Action Flow Steps Reference
This article is focussed on steps you can add to an Action Flow after the 'start' point. It covers:
Triggers, which cause your Action Flow to start, are described in the triggers article.
How steps run within Action Flow
Steps are run as soon as possible
Atomic always tries to run steps as soon as possible. After an Action Flow instance starts, the system immediately looks for the one (or more) steps directly connected to the start node, queues the tasks, then attempts to run them as quickly as possible.
-
If the step is a 'Send a card' step, the instruction will be processed immediately. The card will be created, respecting the delivery settings set configured for the step, and once created, the step will be marked as completed. Atomic will then immediately look for steps directly connected to the Send a card step and attempt to run them.
-
If the step being run is a wait step, Atomic will wait, respecting the configuration on the step. Wait steps can pause and listen to a card sent by a parent step, only proceeding with a specific action has been tracked, or a wait step can pause for a period of time.
Prior to Action Flows, using a fixed embargo date/time was the only way to delay when a card was visible to a customer. Action Flow wait steps now provide more options.
All Action Flow activities are queued before processing, so ensure the scalability and resilience of the system. This can mean the elapsed time between steps being processed slows during times of heavy system load and may be worth bearing in mind as you design your flows.
Customers flow through all possible branches
To have more than one step run when the parent step has completed, you can simply add multiple steps directly connected to that parent step. Once the parent step is completed, all directly connected children steps will be run.
- If you need to daisy-chain events so they happen one after the other, you can achieve this by only adding one child per step.
- In cases where you're sending a card, and only want a second card to be sent after the first card has been published, you can add a wait step in between two send card step and configure if to wait for the first card to be published.
We are working on releasing a conditional branching step, designed so that you can route customers to a specific branch using context data and rules, instead of having them flow down all applicable branches. When released this type will be an exception to the 'flow through all branches' behavior that is normally applied, giving you greater control and flexibility. If you need early access to the preview of this step, let us know.
If a step fails, that instance of the Action Flow will stop
Each time an Action Flow is triggered for customer we create an unique instance of the Action Flow for them. This means, while more than one customer may be targeted in the original trigger event, we still send each individual customer through the Action Flow alone.
- If any step fails to complete (for example if a send API request receives an error when running) then this unique instance of the Action Flow will be completely stopped.
- Any cards already created by the Action Flow will still be live (these can be canceled via the Cancel Cards tool)
- Error events will be tracked in analytics, so you can be alerted.
We've designed this initial behavior to be conservative, and intend to support more error-handling options. If you have a use case, or idea for how you'd like this to work, we'd love to hear about it
Each step can only run once per Action Flow instance
When Atomic evaluates a step, it will look for the first opportunity to complete the step, then move on. For example, if you configure a 'wait for card event' step to wait for a card sent in the previous step to be snoozed or completed or dismissed, then when Atomic detects the first one of these, it will complete the step and move on.
If for example, you want to listen for card events independently, you can achieve this by adding multiple wait steps as children of the send card step. This way, each branch will wait independently of the others.
Steps can access Context data from steps before them
The data available to a running Action Flow instance builds as the flow steps are run.
- When the Action Flow starts, a snapshot of the data from the originating trigger event (if any) is added to the data context.
- Any variables defined in the Action Flow will have their values resolved when the flow starts, and those resolved variables are added to the data context.
- 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).
- 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.
The Action Flow context article explains how context works and how to use it, but the headline is that each step in an Action Flow can access the full context data from the steps above it (not in adjacent branches).
Action Flow Step Types
Send a card
Sends your customer an in-app action card.
- Configure delivery settings, including which streams it will be visible in, priority and card lifecycle details by selecting the step from the canvas
- When you add this step, a blank card template will be automatically created an connected, you can edit this card, or switch the setup to connect to a different card template within the same action flow (you can delete unlinked card templates in the left side menu)
- If you want Atomic to also a send a push notification when this card is created, you can configure this alongside the card template
If you are migrating legacy cards to Action Flows, we strongly recommend updating any trigger events to no longer send card delivery metadata in the event payload. Read the migration guide for more information.
Send a notification
Sends your customers a mobile push notification (without sending an in-app action card).
- Configure the notification by selecting the step from the canvas
When delivering push notifications, any push notification that would normally be sent during a customer's do not disturb windows (if set by your apps) will be automatically rescheduled to go out after the do-no-disturb window ends.
Send a request
Sends an API request to a third-party system.
- The destination URL can be static, or contain context placeholders to construct some all of the URL dynamically with context data
- The send a request step supports making
POST,PUT,GET,PATCHandDELETErequests - You can provide static header values for the request
- credentials can be used to authenticate the outgoing requests
- The body of the request can be a static payload, or a dynamic payload you define using either JavaScript or a no-code mapping, that can customize each request using some or all of the data available to this step in context.
- Data from the responses can be added back into the context of the flow, to be used downstream by child steps. To do this, you'll create a mapping, providing an example of a typical response, then define a mapping which outputs key/value pairs.
- Responses to the outgoing request need to be successful, otherwise the Send a request step will error, causing an action flow instance to stop
When testing or debugging your action flow, having Atomic send flow context data to a webhook provided by a service like webhook.site can help save time. We don't recommend using these types of services for sending live data, but those choices are ultimately up to you.
Wait for a period of time
Pauses the current branch for a set amount of time.
- This step provides a way to prevent Atomic from moving immediately from a completed step to a child step, by making it pause for a set time.
- You can use these steps to pace out a complex multi-step interaction, add delays to allow others systems to be updated, or any other situation where you need to wait for a predetermined time before continuing.
- After Atomic starts a wait for a period of time step it will pause, then resume and complete at the end of the specified time.
Wait for a card event
Pauses the current branch until a specific card-event is detected.
- This step can only be added to your flow immediately following a send a card step, and it will only listen for card events relating to the card instance created by that parent step.
- It provides a way to prevent Atomic from moving immediately from a completed step to a child step, by making it pause until it detects a specific event relating to the action card sent by its parent step.
- The events this step can listen for include are published, displayed, completed, dismissed and more (the full list of card events this step can listen for is below).
- You can configure the step to listen for one or more events, but the first event detected will satisfy the wait rule and complete the step.
- After Atomic starts a wait for a card event step it will pause, then resume and complete when the first event it is listening for occurs.
Full list of card events the wait for a card event steps can listen for
- card-canceled
- card-dismissed
- card-completed
- card-expired
- card-published
- card-embargoed
- card-snoozed
- card-unsnoozed
- notification-sent
- notifications-not-sent
- card-displayed
- card-subview-displayed
- card-subview-exited
- user-redirected
- runtime-vars-updated
- notification-received
- card-voted-up
- card-voted-down
- snooze-options-displayed
- snooze-options-canceled
- card-error
Because customers will flow through all branches you may choose to add more than one of these wait for a card steps to the same parent step, in situations where you want to independently respond to create different branches for different events. For example, you may want to create a branch to send customers down if they complete the card, and a separate branch if they dismiss it. In that example it would be impossible for one customers to go down both branches, but not all card events are mutually exclusive.
Track a goal
Records that a customer has made it to this point in the Action Flow.
- This step enables you to explicitly track when users reach key moments in your Action Flow
- When configuring the step, you'll provide a name for the goal, and optionally assign a value to each conversion event
- Goal values can be recorded as points, currency, or time and the values can be static, or set dynamically based on context data
- When track a goal steps complete, the action-flow-step-completed analytics event is generated. Within this analytic event there are two attributes which you can use in your analysis and system outside of Atomic -
properties.goalValueandproperties.goalValueMeasure. - Tracked goal values can also be used when making a send a request step, if you want to use an action flow step to pass this information out after the goal step is completed
- Action Flow reports in the Workbench will also use goal data to show you how your Action Flows are performing
We recommend always assigning values to your track a goal steps, to make the most of the reporting in Atomic, and to assist in capturing and communicating the business impact of your Action Flows
Action a card
Complete or cancel one of the cards created by a previous step
- This step lets you cancel or complete a card that you send in an earlier step
- This can be used to dynamically recall other cards if the user has completed certain actions or its no longer desirable to show the card
Branch flow
Conditionally branch your flow based on input from previous steps
- The branch step allows you to configure different branches that your Action Flow can traverse
- When setting up a branch step you provide the criteria for a user to enter one of the branches, this can be done through simple comparisons or complex scripts
- This step type can be used to set up A/B testing or conditionally send a user different cards based on their input in previous ones - among many other possibilities