Action Flow Context Reference
What is Action Flow context data?
Action Flows use and create data from the moment they're triggered, along the way as flow steps run, ending when the Action Flow is completed.
This data is referred to as 'context', because the data involved in each unique instance of an Action Flow is scoped specifically to the context of that unique flow instance and the individual target customer involved.
What's in context data?
Context contains four types of data for each instance of an Action Flow
- Payload data - Data captured from the trigger event that started this instance of the Action Flow
- Flow steps data - Data generated as flow steps are completed
- Profile values - The target users full customer profile dataset
- Resolved variables - The resolved value variables configured in the Action Flow
Payload data
Every time an Action Flow is triggered - data about who is being targeted, optional payload properties (which may be mapped to variables - see Resolved variables), and other metadata is added to the context.
Flow steps data
As each step completes, analytics events are emitted within the platform capturing details of the step and these too are added to the data context for the flow instance, including any outputs from cards, or API requests along the way.
Profile values
The customer profile values for the current target customer are also available in the data context (the latest values are always used, not a snapshot).
Resolved variables
Variables defined in the Action Flow will have their values resolved when each instance of the Action Flow starts. Once resolved, those values are added to the context. Resolved variables are called 'resolved' because their values are locked in at the point the Action Flow instance starts.
When the flow is triggered, Atomic resolves each variable's value in the following order:
- Trigger-supplied value - if the trigger supplies a value for the variable (a mapped property from a webhook or event trigger, a key in an API request payload, or a value from an integration trigger like SFMC or Marketo), that value is used. This step is only performed when the variable has "Allow request payload to overwrite" enabled (see below).
- Default value - the default configured on the variable in the Action Flow editor is used as a fallback.
"Allow request payload to overwrite"
Each variable has an "Allow request payload to overwrite" toggle in the Action Flow editor. Despite the name, the toggle controls all trigger-supplied values for that variable - not just values from an API request payload.
- On (default): the variable accepts values supplied by the trigger - whether from an event mapping, a mapped webhook field, a key in an API request payload, or an integration trigger.
- Off: the variable ignores anything the trigger supplies, and falls through to its default value. Use this when you want the variable's default to be authoritative and not be silently overridden by the trigger.
The toggle is the only gate on whether trigger-supplied values reach a variable. With it off, the variable will always resolve to its default at the start of the flow, regardless of what the trigger sent or mapped to it.
The only time the values of resolved variables update after the Action Flow starts, is in the case of script variables. These will re-evaluate periodically (however, the value of any other variables the scripts reference will not have changed).
Note: Currently, the periodic re-evaluation of script variables only works when the SDK is in WebSocket mode, which is the default mode. They are not updated when the SDK is in HTTP polling mode.
How to use context data in your Action Flows
There are two ways you'll use context data in your Action Flows:
Personalize content and configuration with context data
When adding content elements to a card template, look out for the icon button within the value input field that launches the context placeholder picker, or try typing + to launch it. The context placeholder picker is a simple menu that lists the data from context available to use in the area you're working.
This also works in many configuration inputs, the same icon will be present. In advanced configurations like condition steps (coming soon) you'll be able to access context data using the simple context picker, and when writing JavaScript.
- When you select a context item to insert, you're only adding a placeholder. When Atomic runs the Action Flow and gets to that step, if it finds a placeholder, it will replace it using the relevant value at the time from context, and if none is found, will attempt to you a fallback value, if none is found, Atomic will ignore the placeholder and move on.
- After inserting a context placeholder, you can click the placeholder within your input to optionally set a fallback value. Fallback values are optional (and empty by default).
- If you set a fallback values in one place, that fallback won't be re-used if you add another context placeholder elsewhere, which enables you to set different fallbacks if you need to.
When you're testing your Action Flow, the context values from your test Action Flow instance will be used just like they will when your Action Flow is published. But, if you choose only to send a test card (the option which is shown from inside the card editor) then because you're not testing the entire flow, context placeholders will be resolved to the fallback values. You can read more about this in the testing article.
Pass context data out via request steps
When configuring send a request steps, you can control exactly which data from context is using in the body of the outgoing request. You can choose to pass through the entire context object, or pick and choose the data to pass through.
In the mapping editor the full context object available to this step will be displayed to the left, and you'll be given options to use JavaScript to map what you need into an outgoing payload, or to create your mapping using a basic no-code option.
Any data returned in the response payload of a send a request step will be added into context for downstream steps to use, if you create a response payload mapping.