If required, you can reference (and therefore manipulate) flow variables in custom scripts. The possibilities here are only as limited as your development expertise however, a simple example might be where you want to generate a running count of order lines, to be output to a total field in a target system.
To achieve this, you would:
Add a flow variable named running_total to your process flow settings.
Write a custom script which loops over each received order line and updates the running_total variable as it goes.
Add the custom script to your process flow via a script shape.
Add a map shape to your process flow and include a rule which maps a custom string transform for {{flow.variables.running_total}}, to the total field in the target system.
To reference flow variables in a custom script, the required syntax is as follows:
In all cases, the variableName element should be replaced with the actual flow variable name. For example:
The example script below takes a flow variable named customerID and sets the value to 1234567:
So, wherever the customerID flow variable is referenced in a process flow, its value would be set to 1234567 when the process flow runs.
When you update flow variables via a script, those updates persist for the duration of the flow run. Once the process flow has completed, default values are restored.
The steps required to reference flow variables in a process flow can be summarised in two stages:
Any flow variables that you want to reference from process flow shapes should be added as variables within the process flow settings. To do this, follow the steps below.
Step 1 Access the process flow that you want to update and make sure that you're switched to the required version.
Typically, you would update the draft version, then deploy changes when you are ready.
Step 2 Select settings (the cog icon) from the actions bar:
Step 3 Look for the variables section in the flow settings panel - for example:
Step 4 Click the add new variable button:
Step 5
In the name field, enter the name (i.e. the API parameter name) of this variable. For our example, the variable is named customerID:
Step 6 Click in the select a type field and select the data type for this variable:
Step 7 Enter the required value to be used wherever this variable is found in the process flow - for example:
Step 8 Add all required flow variables in the same way, then save changes.
Having defined your required flow variables, they can be referenced from process flow connection shapes, wherever a variable field is present. So, if your connection shape is set to use an endpoint which requires/allows variables to be applied, you will see corresponding variable fields in the connection shape settings.
The example below shows how this works. A GET single order endpoint has been configured to expect a customerID variable, and then how this variable is surfaced in connection shape settings when this endpoint is used:
When defining variable values for a connection shape, you can enter a static value, or obtain values dynamically from a payload, or reference an existing flow variable. The steps below show how to reference a flow variable.
You can also reference flow variables in custom scripts (which means you can manipulate these values however you need) and also in field mapping transformations.
Step 1 In your process flow, access settings for the connection shape that you want to update with a flow variable:
Step 2 Look for the variables section in the settings panel - for example:
To use a flow variable here, the expected variable must correlate with a variable that you added in stage 1. Notice that the example above is expecting a Customer ID variable, which correlates with the customerID flow variable that we added in step 5 of stage 1.
Step 3 Use the syntax below to reference a flow variable:
...where the variable element should be replaced with the name of the flow variable defined in process flow settings (stage 1). Using our example, this would be:
Step 4 Save changes. Now when this process flow runs, the value defined in process flow settings will be passed in for this variable.
Flow variable values can also be updated by custom scripts. For further information please see Referencing flow variables in custom scripts.
If your process flow includes a connection shape that's configured for an endpoint where a variable can be entered, you'll probably be used to entering a static value to be applied for that step - for example:
You might also be familiar with obtaining variable values dynamically, from a payload. However, flow variables provide another level of flexibility.
Flow variables provide the ability to define variables at the process flow level, and then reference these values throughout the entire process flow. You set a flow variable once, and it is applied throughout the entire process flow, wherever it is referenced.
When flow variables are modified - either manually or via a script - those updates are applied anywhere in the process flow where they are referenced, automatically.
You can also reference flow variables in custom scripts (which means you can manipulate these values however you need) and also in field mapping transformations.
Before you start working with flow variables, there are a couple of important points to understand regarding process flow versions and update persistence.
Flow variables are version-specific. For example, if you add flow variables to the current draft version and later restore an inactive version to draft, any defined flow variables won't be present. So, make sure you're updating the correct version of a process flow. For more information, please see our Process flow versioning page.
If you update a flow variable via a script, those updates persist for the duration of the flow run. Once the process flow has been completed, default values are restored.
Please see the following pages:
You can reference flow variables in field mapping transformations, using a custom string transformation in the map shape.
Most typically, the custom string transformation type is used to specify some custom text to be applied in a target field. For example, you might choose to add a particular sales rep's name to a reference field for all orders being synced.
However, if your process flow is using flow variables, you can reference these in custom string transformations, instead of static text. When the process flow runs, the flow variable value is mapped to your given target field. If you later decide to update flow variables (either manually or via a custom script), those updates are mapped next time the process flow runs.
The steps required to achieve this can be summarised in two stages:
Any flow variables that you want to reference in field transformations should be added as variables within the process flow settings. To do this, follow the steps below.
Step 1 Access the process flow that you want to update and make sure that you've switched to the required version.
Typically, you would update the draft version, and then deploy changes when you are ready.
Step 2 Select settings (the cog icon) from the actions bar:
Step 3 Look for the variables section in the flow settings panel - for example:
Step 4 Click the add new variable button:
Step 5
In the name field, enter the name (i.e. the API parameter name) of this variable. For our example, the variable is named rep:
Step 6 Click in the select a type field and select the data type for this variable:
Step 7 Enter the required value to be used wherever this variable is found in the process flow - for example:
Step 8 Save changes.
Having defined your required flow variables, they can be referenced in custom string field mapping transformations. Typically, this will be for scenarios where you want to map the output from a flow variable into a target field.
If you've added/updated a map shape before, you'll be used to selecting a source field and a target field. However, when we map a flow variable value to a target field, we don't select a source field - the custom string transformation is our data source.
Step 1 In your process flow, access settings for the map shape that you want to update with a flow variable:
Step 2 Click the add mapping rule option - for example:
Step 3 Click the add transform button:
Step 4 Click the add transform button:
Step 5 Click in the name field to access a list of all available transform functions, then select custom string:
Step 6 Move down to the custom string field and enter the following value:
...where the variable element should be replaced with the name of the flow variable defined in process flow settings (stage 1) that you want to reference. Using our example, this would be:
For example:
You can also reference metadata variables in the same way, using the meta syntax:
[[meta.unique_key]]
Step 7 Accept your changes:
...then save the transformation:
Step 8 Now you can select a target field in the usual way - for example:
...then:
...then:
Step 9 Once your mapping is complete, the row should be displayed without a source field - for example:
From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the value of this flow variable will be mapped to the target field.
