Some apps allow users to create their own fields, like create custom forms in surveys, tickets in customer support services, contact forms in CRMs, mailing lists etc. These data fields are not hard-coded or fixed, rather they can vary from user to user. So, to support this varying behavior we associate Fields List activity fields to an external endpoint, that returns us these custom fields. A user then views these fields while configuring integration using our widget.

Let’s say, your user has two mailing lists in his MailChimp (your app) account. They connect the app to a CRM and creates an integration, “When a contact is added to the CRM, add a subscriber to MailChimp”.

When the user configures the MailChimp account in our widget, they select the list they want to add the subscriber to. As soon as the user selects a list, an API call is sent to MailChimp, that returns us the data fields of the subscription form and the form is rendered in front of the user. This was possible with the help of custom fields. Let us see below how to add Custom Fields to your action or trigger and then how to create the Fields List source endpoint through an example.

Suppose you are creating an action, Create a contact in SendinBlue. The contact created will be added to a list, which is specified by the user when configuring integration. We will fetch the custom data fields from SendinBlue and display them to the user. We cannot pre-define the activity fields that will appear to the user. 

Creating Fields List  Activity Field

Under the Actions tab, we will add a drop-down activity field that will display the lists in the SendinBlue user account. After that, we add a Fields List type activity field from the drop-down menu as shown below. 

We created an activity field by the name Attributes and machine name sendinblue_attributes as shown below. 

This actual Fields List type field does not appear to the user. It is associated with an endpoint that returns us custom fields, which are later displayed to the user.

From the Fields List source endpoint drop-down menu, select Create a new endpoint option. The endpoint creation form will appear. The basic procedure to fill the form is the same for all endpoint types, you can learn about it here. As we are making a call to an external API and requesting data so this is the Outgoing type. 

Some important points about Fields List source endpoint

When we send a request to an external API in case of fields list source endpoint, the response received must be transformed as shown below using the response template. 

[
…..
…...
   "id": "{{ attribute.name }}",
   "type": "{{ (attribute.type == 'Dropdown') ?     'select' : attribute.type }}",
   "title": "{{ attribute.name}}",
   "options": "{{ attribute.enumerations | json_encode  }}"
……
…..
]

The key things you need to keep in mind that we are generating an array of JSON objects with each object having the three properties, id, type, title, and options (in case of select field type). These properties are explained below.

id: The value stored in this property is saved as the machine name of the field

type: This property stores the type of field. Currently, we support two field types, Select and Text

title: This property stores the title of the field

options: This property is valid for select field types only. It stores the drop-down menu options. 

The array below shows the structure of options:

“array1”:
   [
      {
         "value": 1,
         "label": "Men"
      },
      {
         "value": 2,
         "label": "Women"
      },
      {
          "value": 3,
         "label": "Kid"
      }
   ]

It is mandatory that while transforming the response through Response Template you use the same properties names, otherwise, the data will not be processed properly by our widget and displayed. 

A step-by-step example to Fields List Source Endpoint

We know for this particular endpoint, we need to retrieve the contact attributes. We will fetch all those attributes with this endpoint.

Request URL

From the SendinBlue API Docs, we know the following URL needs to be called to get the attributes. 

GET "https://api.sendinblue.com/v3/contacts/attributes 

{
  "attributes": [
    {
      "name": "LASTNAME",
      "category": "normal",
      "type": "text"
    },
    {
      "name": "FIRSTNAME",
      "category": "normal",
      "type": "text"
    },
    {
      "name": "DOB",
      "category": "normal",
      "type": "date"
    },
    {
      "name": "GENDER",
      "category": "category",
      "type": "text",
      "enumeration": [
        {
          "value": 1,
          "label": "Men"
        },
        {
          "value": 2,
          "label": "Women"
        },
        {
          "value": 3,
          "label": "Kid"
        }
      ]
    }
  ]
}

Response Template

We need to transform the response in a form that can be understood by our widget. We will do so by writing the Twig code. Using this template, we will extract the id (machine name), type and title of the fields from the attributes array.

We will receive an array attributes that holds the information we need. See the response below.

[
   {% for attribute in  response.attributes%}
      {% if attribute.category != 'global' %}
         {
             "id": "{{ attribute.name }}",
             "type": "{{ (attribute.type == 'Dropdown') ? 'select' : attribute.type }}",
            "title": "{{ attribute.name}}",
            "options": "{{ attribute.enumerations | json_encode  }}"
         }
      {% if not loop.last %} , {% endif %}
      {% endif %}
   {% endfor %}
]
{% endfor %}
]

The code above iterates through the list of attributes using the response object. The response object returns us the data received in response. A new JSON array is generated in the format required by the Integry widget.

A few points about the code above:

  "options": "{{ attribute.enumerations | json_encode  }}"
  • This line iterates through the select-menu-options. The name of the array is enumerations, and we save the items of the array in the options array. We will apply the filter json_encode to convert data into proper JSON. 

These values are stored in the sendinblue_attributes, do you remember? sendinblue_attributes is the machine name of the fields list activity field we created in the Create a Contact action above.

Learn how to access the custom fields in the action endpoint, here

Did this answer your question?