There may be times when you need to define variables or parameters for a process flow shape which resolve dynamically, based on given values from the incoming payload.
For example, you might have a list of customer IDs coming in from a source (for example, an inbound API job), and need to match these IDs with payload data for a subsequent connection shape, in order to create customer records. This would be achieved using a specific payload syntax when defining variables in the connection shape.
To pass in a variable or parameter value from the incoming payload, use the syntax shown below:
...where schema notation should be replaced with the relevant notation path for the required field in the incoming schema. A payload variable can be defined on its own, or combined with static text. For example:
If necessary, you can combine payload variables with metadata and/or flow variables - for example:
The [[payload]] variable supports non-JSON payload data types - for example, raw text, CSV, XML - whatever you pass in will be output.
To show how this works in principle, some examples are detailed below:
However, it's important to note that the required settings will depend on the data schemas used for your selected connection endpoints.
At the most basic level, your incoming data might contain items which aren't nested - for example:
In this case, our variable would be defined as:
...as shown below:
The result for our example would be:
An incoming payload might contain the required element in an array and you want to target all items within it - for example:
In this case, we can define a variable to target the required array. For example:
...will produce a comma separated list of associated customerID values. The result for our example would be:
An incoming payload might contain the required element in an array and you only want to target a single item - for example:
In this case, we can define a variable to target the required array item. For example:
...will target the first item in the array and return the associated customerID value. The result for our example would be:
Whereas:
...will target the second item in the array and return the customerID value. The result for our example would be:
Let's take our example below:
We've seen how we can target specific items in an array, and how we can list all items in an array - but what if we wanted to target all array items individually?
In this case, we would add a flow control shape to split the incoming payload into batches of 1 at the required data element level (in the case of our example this would ne users :
This will result in three payloads, each with a single customerID and name. For example:
In the following connection step (where the variable/parameter is defined), we can add our payload syntax for the variable/parameter. For our example this would be:
...as shown below:
Here, we need to specify the * because each of our batched payloads is wrapped in an array. For each payload generated from our example, the result is that the associated customerID is taken as the variable value.
