This is a guide on how to use and test the Query step in the template builder. To learn about using creating queries in the Integry App Creator, visit this guide.
Query is a step that is used to import data from one app into the other app. This step, when executed at the integration creation, is known as the initial data import. As illustrated in the query activity type document, let’s say you are creating an integration to import and sync your contacts from Mailchimp to Sendinblue. You will need to import all the existing contacts and their details from the Mailchimp account once. This is done through the query step.
As the data that needs to be fetched from another app can be in a large amount, a query usually runs in a loop and fetches records in a page-by-page manner. This is known as Pagination and you can learn more about it here. Pagination saves our systems from getting overwhelmed from importing large amounts of data in a single call.
A paginated query runs like a loop in the template. It fetches a page of records and runs all its child steps one by one. It keeps fetching the data until all the pages are exhausted. The query step usually takes longer to complete than other steps as it is fetching a large number of records from another app.
To use the Query step, create a new template or open an already created template. Add a new step through the Add Step button as shown below.
Whenever we need to run a query at the time of the integration creation, we add it in the Setup App step. The Setup App step runs all its child steps once when the user sets up the integration. So before the query step, you need to add the setup step from the list of steps as shown below.
After adding the setup step, you can add the Query step as its child.
Adding a setup step in the template and adding the query step as its child will look like this:
You can select any app that you want to import records from. For our running example, you need to import subscribers from MailChimp to Sendinblue. So you can select the MailChimp app here. After selecting the app, you will have to select from the queries that are created within that app. You will select a query that imports subscribers from a MailChimp list. Details about creating queries in an app can be found here.
You will then have to provide a few basic details for your query and configure any fields that will get you input from the user at the time of integration.
Apart from the basic details shown above, you can also provide a limit for the number of records that you want to import through the query. For this, you can provide your desired number of records in the Records Limit field as shown below.
Any number that you enter in the above field will take the page size of your target app into account. The records will be imported on a page-by-page basis, just like any paginated query. So your provided number will be rounded off to the nearest page. If you want to import all the records, just leave this field empty, as in the case of the current example.
You can also let the user provide the number of records that they wish to import. For this, you will need to create an activity field in the MailChimp app that will take numeric user input. After adding that, the added field will appear in your template query step as shown below.
Once you toggle on the visibilty of the above field, your user will be able to see it at the integration setup and provide their input.
Finally, the rest of the information you'll need from the user for this query will be in the provided activity fields, as shown below.
The List field will ask the user to select a list from their MailChimp account to import the subscribers from. The user will select the list from the dropdown showing all available lists in their MailChimp account.
The Opt-in Agreement will get the confirmation from the user that they have permission to send campaigns, emails, newsletters, etc. to their contacts. You can edit the text of this field according to your preference.
After the query step that imports subscribers, you can add the action step in the template that creates a contact in Sendinblue. This step will keep creating the contacts that are imported in pages by the query until all the pages are exhausted and all the contacts are imported from MailChimp to Sendinblue. This complete loop of initial importing through a query will look similar to what is shown below.
Testing a Query Step
For a query step, let’s use an example of the Pipedrive app. We now have a query step that imports all the contacts from your Pipedrive account to Integry.
To test this query in the template, you again click on the test button as shown above. This will open a query testing interface in the template.
You’ll need to provide your account creds and fill in any fields that are required. Once done, just click on the Start Test button.
After the test runs, in a few seconds, you’ll get the status of the call. Just like all other tests, this will be a success or an error message, depending on whether all the fields and account information is correct.
Clicking on the View Details button above will show you all the data relating to the imported contacts from your Pipedrive account.
You can see all your imported contact details and attributes in the response fields above.
You can also click on the Next Page button on the bottom right, if your imported data is paginated and exceeds more than one page. See testing a paginated endpoint for more details on this procedure.
Details about creating a query activity type in the Integry App Creator are discussed here.