# 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) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/payload-variables.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.