How to Use Dot Notation to Access Information in a JSON Object

Built.io Flow is a JSON-centric iPaaS. It uses JSON as the data format for all the requests and responses. JSON stores information in a very organized and easy-to-use manner.

Usually, whenever you use an action in a workflow, it returns a JSON object— or JSON array in case it fetches multiple objects—as its output (e.g., Trello – Fetch All Cards, Cisco Webex Teams - Get Message). The object also contains various properties (e.g., name of the Trello card, UID, created by, etc.).

While creating a workflow, you can use the whole output of an action/trigger in another action, or you can pick a particular property from the whole output and use it in subsequent actions. In Built.io Flow, the latter can be done by using dot notation in JSON.

Using dot notation for a single object

There are several actions in Built.io Flow that return a single object (e.g., Cisco Webex Teams - Get Message). If you use the whole output in any subsequent action, the variable usually contains just the internal action code (e.g., {{$a0}}).

4-dot-notation.png


This output contains all of the properties of the message, such as id, roomId, personId, personEmail, and so on. This way when a workflow is executed, it will fetch all of the properties.

There may be times when you want to use only one or a select few properties from the entire output. One of the ways to do this is to select the required property directly from the output structure given on the right of the configuration win.  

Another way is to edit the whole output variable and add .propertyName. For example, {{$a0.id}}, {{$a0.personEmail}}. This will fetch the value of the selected property only, and not the whole output.

Using dot notation for multiple objects (array)

Several actions in Built.io Flow return a JSON array or multiple objects (e.g., Trello – Fetch All Cards). To use the whole output in any subsequent action, you can simply click the ‘insert’ icon given beside ‘cards’ in the input section on the right. You will notice that the variable inserted in the input field is {{$a21.cards}}. When the workflow is executed, it returns multiple card objects, each containing various properties (id, name, url, etc.) of cards.

2.png

If you select the ‘name’ property from the given output, you will notice that the variable inserted in the input field is {{$a21.cards[0].name}}. This means that the workflow will look for the name field given in the first object (0th element). If you wish to fetch the name of the third object, you can manually edit the variable to make it {{$a2.cards[2].name}}.

3.png


If an object contains nested objects within it, you can retrieve the value of the properties of the nested object by adding more dot notations. For example, {{$a2.members[2].address.city}}.

Similarly, you can use multiple properties or a single property of multiple objects in any input field by using dot notation.

If you wish to get the value of a single property of all the objects (e.g., names of all the cards), you need to use the ‘Loop’ action that will iterate an action over all the objects of an array.

Using dot notation in case of custom fields

In the above two cases, picking properties from objects was straightforward, as the property names were visible in the output structure in the subsequent actions. However, there are several triggers/actions in Built.io Flow that let you define custom fields. Fetching these fields in subsequent actions becomes difficult because the property names are not known.

Let’s look at an example to understand this well.

Let’s assume that you have created a form in Wufoo to be filled up by the employees of your organization. The form that you have created contains three fields: ‘name’, ‘age’, and ‘gender’. You want to create a workflow such that whenever a new entry is created for this form, you wish to get notified in Slack via a direct message. Specifically, the notification should also include the name of the user filling the form.

To do this, you will add a trigger ‘Wufoo – New Entry’ that kicks off the workflow whenever a new response is submitted for a given form. But if you look at the output structure of the trigger, you will notice that the default schema does not contain any ‘name’ field. You know that you had created a ‘name’ field while creating the form. However, that too is not visible in the schema. Adding .name directly to the trigger output (i.e., {{$trigger.name}}) may not serve the purpose as the field name defined by you may not be the same as the property name defined by Wufoo for that field.

It is, therefore, always recommended that you test the workflow manually, and have a look at the trigger output to understand the naming conventions followed by the service.

In this case, you can see that Wufoo follows a convention. All the custom fields defined by you are named as ‘Field1’, ‘Field2’, ‘Field3’, and so on.

So, since ‘name’ is the first custom field of our form, we will use ‘Field1’ property to fetch the name. So, in Slack’s action, we will use {{$trigger.Field1}}. Now whenever a new response is added for the specified form, the workflow will fetch the value entered in the ‘name’ field and send it to your Slack messenger.