This is a guide on how to use the Query activity type in app creation. To learn about using queries in the template builder, visit this guide.
In most of the integrations, a big chunk of data from one app needs to be imported to the other app once at the time of the integration creation. For example, if you are creating an integration to import and sync your contacts from Mailchimp, you will need to import all the existing contacts and their details from the Mailchimp account once. Integry has created the Query activity type to serve this purpose of fetching records from another app.
Query is a special type of activity and differs from a trigger or an action. A trigger can run at any time after the integration is created. An action is always executed in response to a trigger. A query usually runs only once at the time of the integration creation, when the initial importing of data takes place.
Query is a step that usually takes longer to complete than other steps as it is fetching a large number of records from another app. Queries are usually Paginated and run as a loop in our templates. Details on how queries are implemented and executed in templates can be found here.
Creating a query
Consider you want to get a list of subscribers from MailChimp. To create a query for this, you will need to go to your Apps section in Integry and open the details of the MailChimp app. Select the Queries tab in the application settings menu.
The Queries page shows the existing queries in your app and a button “Create Query” as shown below. Create a new query by clicking this button.
Basic Query Information
Once you click on Create Query, you will need to set it up just like Actions and Triggers. Start with the basic information, query name and its description.
Query Authorization
After giving the basic information, you need to select the Authorization method of your query. This comes in handy if your app supports multiple authorization types. In most of the cases, the query authorization type is the same as the app authorization type being used for all other activities. In this case, you will select the authorization type from the drop-down menu. If not, select Create new Authorization from the menu. The details of creating an authorization endpoint can be viewed here.
Input Object
A query can consume an object as Input. These objects are defined by Integry, which are mostly generic such as Contact, Tasks, User, Event, etc. Using the input object, you can perform actions on these objects, such as Import. Learn more about Input Objects and how to set them up.
Activity Fields
Activity Fields are where you define the data that is collected from the user when the integration is created. A field can also collect data when an activity is added to a template.
We can see from the MailChimp Api documentation, for getting information about members in a list, a request has to be sent to the following URL:
GET https://u15.api.mailchimp.com/3.0/lists/{list_id}/members
The {list_id} variable in the above URL is the unique id for the list. This list information is provided by the user when they create the integration and is collected through activity fields. So you can create the activity field for the list ID and give it the machine name ‘mailchimp_list’.
Learn more about configuring activity fields.
Query Endpoint
Next step is adding the query endpoint. To perform a query activity, your app needs to execute an endpoint in the third-party app. This endpoint is executed by sending a request to the external API. Every query needs an endpoint to be configured with it.
The endpoint for our current example is the one mentioned above and will be paginated. It is discussed in detail here.
You can also read more about endpoints and how they work.
Query Output
This field shapes the output of the query. The response of this query’s endpoint will return a page of members in the list in the form of an array. Data from one object of this array can be entered in the query output. The records for all the subscribers in the list will then be returned in that format.
Adding Hooks
Your query can have a requirement to perform certain API operations at different points in the lifecycle of an integration. Hooks are the endpoints that are executed when a user saves, deletes or updates an integration that uses the query. The associated hooks are configured while setting up the query. To learn about these and how to add them to your activities, click here.
As a query normally runs in the start of the integration, we don’t normally add any hooks for this activity type.
Saving a Query
After configuring your query, you can proceed to saving it. You can view three buttons at the end of the page as shown below.
Cancel: Will cancel your query and no settings will be saved.
Create Query: This will create your query and save it as a draft. You can edit it and test it thoroughly. As the query will still not be published, other users will not be able to view it while creating templates.
Submit for Approval: Submitting a query for approval will send it to our team for review. Our team will test it and make sure there are no associated problems. We will then publish your query and it will become available to be used in templates and other apps.
Once the query is published, it will have limited modification availability. Not all parts of the activity can be edited. Details about this can be learned here. You can cancel the request for approval to make changes to your query configurations. As soon as you submit the request for approval, you can view a Cancel Review and Edit Query button.
Details about using queries in templates can be found here.