> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/payload-variables.md). # 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](#payload-variable-syntax) when defining variables in the [connection shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md). ## Payload variable syntax To pass in a variable or parameter value from the incoming payload, use the syntax shown below: ``` [[payload.]] ``` ...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.]]-suffix ``` If necessary, you can combine payload variables with metadata and/or flow variables - for example: ``` prefix-[[payload.]]-[[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: * [Single item](#example-single-item) * [Single item in an array](#example-single-item-in-an-array) * [All items in an array](#example-all-items-in-an-array) * [Batched items from an array](#example-batched-items-from-an-array) 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: ```json { "customerID":1000001 } ``` In this case, our variable would be defined as: ``` [[payload.customerID]] ``` ...as shown below:
The result for our example would be: ```json { 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: ```json 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: ```json 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: ```json 000002 ``` ### Example: batched items from an array Let's take our example below: ```json { "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](#example-single-item), and how we can [list all items in an array](#example-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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/flow-control-shape.md) 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: ```json [{"customerID":"000001","name":"Rita"}] ``` ```json [{"customerID":"000002","name":"Bob"}] ``` ```json [{"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: ```json [[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 * [Metadata variables](/product-documentation/process-flows/building-process-flows/dynamic-variables/metadata-variables.md) * [Flow variables](/product-documentation/process-flows/building-process-flows/dynamic-variables/flow-variables.md) * [Generating dynamic cache keys with variables](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/add-to-cache-shape/generating-dynamic-cache-keys-with-variables.md)