Payload variables

Introduction

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.

Payload variable syntax

To pass in a variable or parameter value from the incoming payload, use the syntax shown below:

[[payload.<schema notation>]]

...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:

prefix-[[payload.<schema notation>]]-suffix

If necessary, you can combine payload variables with metadata and/or flow variables - for example:

prefix-[[payload.<schema notation>]]-[[meta.unique_key]-suffix

Supported

The [[payload]] variable supports non-JSON payload data types - for example, raw text, CSV, XML - whatever you pass in will be output.

Payload variable examples

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.

Example: single item

At the most basic level, your incoming data might contain items which aren't nested - for example:

{
 "customerID":1000001
}

In this case, our variable would be defined as:

[[payload.customerID]]

...as shown below:

The result for our example would be:

{
 1000001
}

Example: all items in an array

An incoming payload might contain the required element in an array and you want to target all items within it - for example:

{
	"users": [{
			"customerID": "000001",
			"name": "Rita"
		},
		{
			"customerID": "000002",
			"name": "Bob"
		},
		{
			"customerID": "000003",
			"name": "Sue"
		}
	]
}

In this case, we can define a variable to target the required array. For example:

[[payload.*.customerID]]

...will produce a comma separated list of associated customerID values. The result for our example would be:

000001, 000002, 000003

Example: single item in an array

An incoming payload might contain the required element in an array and you only want to target a single item - for example:

{
	"users": [{
			"customerID": "000001",
			"name": "Rita"
		},
		{
			"customerID": "000002",
			"name": "Bob"
		},
		{
			"customerID": "000003",
			"name": "Sue"
		}
	]
}

In this case, we can define a variable to target the required array item. For example:

[[payload.users.0.customerID]]

...will target the first item in the array and return the associated customerID value. The result for our example would be:

000001

Whereas:

[[payload.users.1.customerID]]

...will target the second item in the array and return the customerID value. The result for our example would be:

000002

Example: batched items from an array

Let's take our example below:

{
	"users": [{
			"customerID": "000001",
			"name": "Rita"
		},
		{
			"customerID": "000002",
			"name": "Bob"
		},
		{
			"customerID": "000003",
			"name": "Sue"
		}
	]
}

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:

[{"customerID":"000001","name":"Rita"}] 
[{"customerID":"000002","name":"Bob"}] 
[{"customerID":"000003","name":"Sue"}]

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:

[[payload.*.customerID]]

...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.

Related information

PreviousDynamic variablesNextMetadata variables

Last updated