This is a detailed guide on the adapter activity type as used in the app creator. For details on how to use the adapter step in templates, visit here

An Adapter is an activity that takes an input array of data and transforms it into a shape that is required to perform a specific operation on it. The transformation is done using a Twig syntax.

We use Adapters to take a list of objects from an API endpoint, that might contain custom attributes as well and allow the end-user to specify their own mapping. Effectively, an adapter maps the input data based upon what the user selects in the mapping step of the integration.

Suppose that you want to import the data of multiple contacts for a user from MailChimp. This action is known as bulk import. When creating the integration, the user will provide a basic mapping to match the attributes of his app with the external MailChimp attributes. From the user’s end, this will look similar to what is shown below.  The user could decide to map SMS with the Phone field, might skip mapping the FIRSTNAME field and map the LASTNAME with LAST NAME field. This user-defined mapping is applied using the adapter step. So typically, in the template, an adapter is applied to the Query step to transform it to the user's needs

This mapping information is collected by an adapter which then maps these attributes with the actual data stored inside the corresponding MailChimp attributes. The input JSON array and the mapping of corresponding data on the back-end will be shown for this example later in this document.

Adapters usually take a list of Objects as input and map them with the attributes coming in from another app. Adapters are similar to filters in nature. The difference is that adapters are used for the initial mapping of objects between two apps, while filters are used for mapping in the opposite direction as well as for applying other basic data transformations.

Creating an adapter

To create an adapter for the example mentioned above, you will need to go to your Apps section in Integry and open the details of your specific app. Select the adapter tab in the application settings menu. 

The Adapters page shows the existing adapters in your app and a button “Create Adapter” as shown below. Create a new adapter by clicking this button.

Basic Adapter Information

Once you click on Create Adapter, you will need to set it up just like Actions and Triggers. Start with the basic information, adapter name and its description. 

Adapter Authorization

After giving the basic information, you need to select the Authorization method of your adapter. This comes in handy if your app supports multiple authorization types. In most of the cases, the adapter authorization type is the same as the app authorization type being used for all other activities. If that is the 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

An adapter 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.

For the current example, you need an input array where the values of the MailChimp attributes for the imported contacts are stored. These values will later be mapped with the attributes in Sendinblue. The input array will be in the form of objects. You can configure this activity field as shown below.

 

 

An input array for this activity field will be provided in the template. That array containing the values of the MailChimp attributes will be similar to the one shown below.

[ 

{

"id":"111",

"email":"user50@example.com",

      "custom_fields":{

         "FNAME":"User",

         "LNAME":"Fifty",

         "PHONENUMBER":""

      }

   },

   {

      "id":"112",

      "email": "user51@example.com",

      "custom_fields":{

         "FNAME":"Fifty",

         "LNAME":"One",

         "PHONENUMBER":""

      }

   }

]

You will also need a field list activity field where the mapping data will be collected by the user. This mapping step is shown at the start of this document where the user provides the MailChimp attribute names for contacts corresponding to the attributes in his app. 

You can also receive the email and contact list from the user through activity fields depending on your requirement. Learn more about configuring activity fields.

 

Adapter Output

This field shapes the output of the adapter. The output of this adapter’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 into the adapter output. The records for all the mapped contacts in the list will then be returned in that format

Adapter Template

This is the field where you can provide a Twig template string to transform the data collected through the activity fields into a specific shape. For the current example, the mapping of attribute names have been collected from the user in the “sendinblue_attributes” activity field shown above (Sendinblue is your app in this example). You can write the following code to arrange the contact attribute names of Sendinblue with the mapped attribute names in MailChimp.

{

"email":"{{email}}"

{% for property_name, property_value in sendinblue_attributes %}

 ,"{{ property_name }}":"{{ property_value }}"

{% endfor %}

}

The above code iterates over all the attribute names and their values in the “sendinblue_attributes” activity field step that were taken from the user mapping. It then arranges them in the following manner.

{

“email” : ”{email}”,

“first_name” : “{custom_fields.FNAME}”,

“last_name” : “{custom_fields.LNAME}”

}

In the above JSON text, the field names on the left side are the Sendinblue attributes and the variables on the right side are the corresponding attribute names in MailChimp. These variables will get their values from the input array that is collected through the “input_array” activity field. This will create a final output of the adapter in the form of an array that will have as many objects as present in the input array. Fetching the values from the example array that was provided in that section, the above mapping will change to:

Output

[

{

“email” : “user50@example.com”,

“first_name” : "User",

“last_name” : "Fifty"

},

{

“email” : “user51@example.com”,

“first_name” : "Fifty",

“last_name” : "One"

}

]

The above is the required output for creating the imported contacts in your app. The contact attributes in your app are shaped and mapped with the values of the corresponding attributes in MailChimp.

 

Saving an Adapter

After configuring your adapter, you can proceed to saving it. You can view three buttons at the end of the page as shown below.

Cancel: Will cancel your adapter and no settings will be saved.

Create Adapter: This will create your adapter and save it as a draft. You can edit it and test it thoroughly. As the adapter will still not be published, other users will not be able to view it while creating templates.

Submit for Approval: Submitting the adapter 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 adapter and it will become available to be used in templates and other apps.

 Once the adapter 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 adapter configurations. As soon as you submit the request for approval, you can view a Cancel Review and Edit Adapter button.

We have discussed the adapter activity type in the app creation in this article. Details about using adapters in templates can be found here.

Did this answer your question?