Mapping data between steps

As discussed in Basic data concepts, data in the Tray platform is returned in JSON format.

Tray has a set of tools that allow you to 'map' data from one service to another - i.e. 'pull' data from one service in order to 'push' it into another.

While these tools make this as simple and visually intuitive as possible, it is important to understand the concept of 'jsonpaths'.

A jsonpath is a standardized way of writing a single line of text which can extract values from fields, objects and arrays contained in JSON data.

All jsonpaths will begin as follows:

• If the data is coming from the trigger step of your workflow it will begin with $.steps.trigger

• If the data is coming from a service connector step in your workflow it will begin with a path which names the service such as $.steps.slack-1 or $.steps.marketo-2

• If the data is coming from a core connector step it will be something similar to $.steps.script-2 or $.steps.loop-3

• If the data is coming from a helpers connector step it will be something similar to $.steps.text-helpers-1 or $.steps.list-helpers-1

The following illustration shows how you can determine the prefix for a jsonpath by looking at the connector name and number under the step title for the connector you are wishing to pull data from:

The complete jsonpath will depend on exactly what you are retrieving from the workflow step.

It might be something relatively complex like:

$.steps.hubspot-1.results[0].properties.email

Or something very simple like:

$.steps.storage-3.value

Tray.io has built-in simple auto-mapping methods to make the process of extracting data as easy as possible.

However, for troubleshooting and advanced use cases, you should still have a knowledge of how jsonpaths work in detail. So it is recommended that you familiarize yourself with all the information on this page.

Simple auto-mapping methods

Copy

Map data inline

Copy

The builder has an easy-to-use visual tool to search through all available jsonpaths from all of the 'output schemas' attached to each connector step in your workflow.

When you select any field to insert data, you will automatically be presented with a list of all jsonpaths from previous steps, which are filtered as you type:

In the above case we are searching through all the 'leads' data that has been received by the webhook trigger.

You can see that by searching for 'name' the tool saves us the trouble of having to work out and manually type the $.steps.trigger.body.firstName jsonpath.

Editing jsonpaths

Copy

The end result is a selected jsonpath which can be edited manually, copied, deleted or have a fallback value set in order to deal with occasionally missing data.

To fully understand how data and jsonpaths are structured, please be sure to read through the rest of this page!

The connector-snake

Copy

You can also use the 'connector snake' to get at the data you need:

Interpolated mode

Copy

It's also possible to do more advanced mapping using interpolated mode. Interpolated mode is used when the destination input requires a string and can do things like:

• Concatenate multiple variables into one input, for example "first name" and "last name" both into a single "name" field

• Construct sentences which mix arbitrary text and data pulled in from previous workflow steps

• Converting other types into a string, for example numbers and booleans can be converted into a string by setting the input to just the interpolated variable.

The following example shows using interpolated mode to send a new lead notification to a Slack channel:

As you can see there is mixture of arbitrary text and data pulled in 'programatically' each time a lead is created:

There are 2 ways of using interpolated mode:

• Use / to open up a list of all available jsonpaths:

  

• Copy the jsonpath from the output tab in the properties panel.

  

Cancelling interpolated mode

Copy

Pressing the esc key on your keyboard will cancel interpolated mode.

jsonpaths in detail

Copy

Pulling data from a trigger

Copy

While the above tools make it very easy to get at data from other connectors in your workflow, it is still important to understand how the jsonpaths are formed.

To show you how jsonpaths are constructed we can use an example workflow:

In this workflow, we have data about an individual which has been received via a webhook trigger:

1. The workflow is triggered by data being received about a new lead which needs added to Salesforce (in this case it is a webhook trigger)

2. The Salesforce step uses the Create New Record (Lead) operation to add the lead to Salesforce

3. To populate the First Name, Last Name and City values the Salesforce step uses jsonpaths to extract the relevant data from the trigger step

From the screenshot you can see that the details of the individual are contained within a body object, and that to access:

• firstName we use $.steps.trigger.body.firstName

• lastName we use $.steps.trigger.body.lastName

• city we use $.steps.trigger.body.address.city

Accessing data in arrays

Copy

The above examples are quite straightforward. However, if we want to access the correct value to populate Mobile Phone in Salesforce, it is slightly different, as John's phones are stored in an array within phoneNumbers, as indicated by the use of [ ] in the output data.

From the above screenshot you will see that the correct jsonpath for this is $.steps.trigger.body.phoneNumbers[0].number

This is because we have identified that, in order to populate Mobile Phone in the Salesforce record, the correct phone number from the list is type iPhone (i.e. not 'home').

In order to pick the first item from an array we use [0] as in the above jsonpath.

Why do we use [0]? Because arrays returned in Tray platform data are always zero-indexed!

So in this case, if we wanted to access the second item in this list (i.e. the 'home' phone number) we would use $.steps.trigger.body.phoneNumbers[1].number

So when accessing data / objects in arrays, you use:

• [0] to get item number 1

• [1] to get item number 2

• [2] to get item number 3

• etc.

Pulling data from service connectors

Copy

The following example shows how you can use jsonpaths to pull data from a service connector:

In this case we have used Salesforce to return the Email of a lead, which we would like to pass into a Clearbit connector step.

From the output on the left side of the screen you can see that the lead is the first (and only!) result in a records array of results (indicated by the [ ]).

Therefore (remembering the rules on accessing data from arrays) the jsonpath we use to pull the email which is needed for the Clearbit Enrichment operation is:

$.steps.salesforce-1.records[0].Email

Note that the exact path for this might change depending on the position of your Salesforce connector in your workflow. For example, it could be $.steps.salesforce-3.records[0].Email if it was the third Salesforce connector you added to the workflow.

Pulling data from core / helper connectors

Copy

You can also pull data from Tray platform core and helper connectors.

For example, we could use $.steps.script-1.result.messages[0].body to get at the output of a script connector step such as:

Or we could use $.steps.storage-1.value to pull data from a data storage connector step.

Pulling data from a loop connector

Copy

When building workflows, it is very common that you will need to use the Loop Connector to go through a list of results one-by-one. In this case you will then be adding further connector steps within the loop which will pull the data from each result using jsonpaths which begin with e.g. $.steps.loop-1.value

For detailed instructions on how to do this please see the Loop Connector documentation page.

Passing variables with spaces

Copy

If a variable contains spaces then it must be passed inside ['']

For example a body response such as:

1
{
2
  "body": {
3
    "Primary User Email": "email_address"
4
  }
5
}

Would be passed as $.steps.trigger.body['Primary User Email'] if the body had come from the output of the workflow trigger.

Troubleshooting jsonpaths

Copy

Common mistakes

Copy

Getting the case wrong

Copy

Jsonpaths are case-sensitive!

So if the piece of data you are after is firstName and you enter $.steps.asana-2.person.firstname the connector step will fail!

Getting the number of the connector step wrong

Copy

Remember that the prefix of your jsonpath must match the name of the connector/service and the number of the step - e.g. $.steps.slack-1 or $.steps.salesforce-3 or $.steps.loop-2

This is explained in working with data and jsonpaths.

Variables with spaces in them can cause an error!

Copy

If the variable you are trying to access is called e.g. Primary User Email then you will need to pass it inside [''] as explained here

FAQs / other scenarios

Copy

Sometimes the data from a step doesn't seem to be available

Copy

You may find that you need to go to 'Debug' and click 'use output' for certain steps if it appears that the output is not available when using visual jsonpaths or the connector snake:

You will also be notified in the 'Output' panel for any step when a new version of its schema is available:

Clicking on 'preview' will allow you to update the schema:

I have an array of results, how do I access a result which is not the first in the list?

Copy

In this scenario, you would use certain identifying criteria to pull the correct item from the list (for example pull the item where lastName equals Robinson)

This can be done using the List Helpers 'filter' operation

I have an array of results, how do I access the last result in the list?

Copy

You can use the List Helpers 'last' operation

How do I check if a piece of data matches a certain value?

Copy

Use the Text Helpers 'contains' operation.

How do I put several pieces of data into a single box?

Copy

You can use Interpolated mode to combine pieces of data, and e.g. compose a long message which contains those pieces of data.

"Data is too large to be displayed" message in logs

Copy

Please see our help center article on dealing with this message