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 methodsCopy
Map data inlineCopy
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.
Sometimes the data from a particular step may not appear to be accessible.
i.e. there may appear to be 'missing' fields.
This is due to the dynamic nature of connector output 'schema'
In this case you will need to trigger a run of your workflow (using a terminate step where necessary) and then manually update the output schema as per the below instructions in 'troubleshooting jsonpaths'
Editing jsonpathsCopy
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-snakeCopy
You can also use the 'connector snake' to get at the data you need:
Sometimes the data from a particular step may not appear to be accessible.
i.e. there may appear to be 'missing' fields.
This is due to the dynamic nature of connector output 'schema'
In this case you will need to trigger a run of your workflow (using a terminate step where necessary) and then manually update the output schema as per the below instructions in 'troubleshooting jsonpaths'
Interpolated modeCopy
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 modeCopy
Pressing the esc
key on your keyboard will cancel interpolated mode.
jsonpaths in detailCopy
Pulling data from a triggerCopy
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:
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)
The Salesforce step uses the Create New Record (Lead) operation to add the lead to Salesforce
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 arraysCopy
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 connectorsCopy
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 connectorsCopy
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 connectorCopy
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 spacesCopy
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 jsonpathsCopy
Common mistakesCopy
Getting the case wrongCopy
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 wrongCopy
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 scenariosCopy
Sometimes the data from a step doesn't seem to be availableCopy
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 logsCopy
Please see our help center article on dealing with this message