Open the scenario editor by going to Campaigns > Scenarios > Create new. Now, you are on the Design tab of the newly created scenario.

Adding, Editing, and Connecting Scenario Nodes

Every scenario is built of components that we call nodes and which are connected to form a scenario flow.

• To add a node, click on the node you want to add, or you can drag & drop it onto the scenario canvas board with your left mouse button.
• To edit a node, double-click the node with your left mouse button. This will open a node-specific edit window. Click "save" after you are done.
• To remove a node, select the node by clicking it with your left mouse button and then click on the trash icon, or hit backspace or delete on your keyboard.
• To connect two nodes, click on the output connector on the right side of the first node and drag the line to the input connector on the left side of the second node, as shown in the animation below. Release your mouse once connected.
  • Now you have created a flow. Customers will pass through this flow starting from a trigger (e.g.,On date) to operators (e.g.,Condition) and finally into actions (e.g.,Email).

📘

Basic Scenario Flow

While in every meaningful scenario there should be at least one trigger, one action and usually also one condition node, there can be multiple flows in a single scenario.

🚧

Scenario size recomendations:

There is a hard limit for how much data can be stored in one scenario (or email campaign) definition.
Following statements are taking into account average size of scenario node.
Using more nodes can quickly lead to internal error about scenario size limit.

• Scenario should not use more than 100 nodes. Ideally, keep their number below 30 to avoid possible lags.
• Scenario should not use more than 25 email nodes. This includes different language versions. The shorter your email is, the more nodes or translations you can use. As a workaround you can move parts of your email into html blocks. Content of such reference will not count towards given scenario size limit.
• Maximum scenario size is 7.9 MB.

Moving, Zooming, and Selecting Multiple Nodes

You can move your position on the canvas by clicking on an empty space and dragging your mouse. To select multiple components, hold shift and do the same. You can delete all selected components by pressing backspace on your keyboard. Zoom in or out using your mouse wheel.

Using a touchpad, you can move by sliding 2 fingers and zoom in/out by pinching 2 fingers.

Keyboard shortcuts available:

• Press 1 to fit the screen
• Press 2 to zoom into the selection
• Press 0 to reset zoom.

You can also click on the minimap in the bottom right corner to navigate your position.

🚧

Saving and executing a scenario

Don't forget to save your scenario by clicking the "Save" button in the top right corner. This will save the scenario for later and will not launch it. If you want to launch the scenario now, click the "Start" button. This means that the triggers in the scenario will now start streaming customers into the flow.

Copy & Paste Nodes

The nodes and their connections can easily be copied within one scenario or among multiple scenarios.

This can be done by selecting the nodes you want to copy, clicking Cmd/Ctrl + c, and then clicking Cmd/Ctrl + v to paste (hold Shift if you want to select multiple nodes).

When copying from one scenario to another for the first time, the browser might ask to allow seeing the nodes copied to the clipboard.

🚧

Copy & pasting between scenarios is not allowed between different versions of the app.

Scenario Nodes Explained

Let's have a look now at how each node works. Remember that you can specify each component by double-clicking on it once it has been placed on the canvas.

How are Nodes Displayed

Node Names

The name of the node displayed in the Scenario contains the following 3 things:

• The Action ID of the node
• The type of the node
• The user-defined name of the node

Search

Search is available to help clients quickly find the node they are looking for. It is possible to search for the node by its action ID, the type of the node, or its name.

Labels Formatting

Labels can be formatted using standard markdown notation. This can be done using either the visual formatting helper bar or by writing markdown directly. The available formatting options are:

• bold
• italic text
• headings (H1-H6)
• unordered lists
• links

Other markdown formatting options are also supported but might not be properly styled in the resulting label.

Triggers

Trigger Limitations

Here's a list of events and nodes with their limitations:

1. Campaign event statuses

Certain campaign event statuses do not trigger scenarios when used in the "On event" node. Therefore, you should not use them as triggers in your scenarios. Those statuses include:

• enqueued
• enqueue_failed
• sent
• failed
• suppressed

Importantly, campaign events that do not have a status attribute altogether, such as A/B tests, will also not trigger a scenario.

2. Other events and nodes

Apart from campaign events, there are other events and nodes that do not trigger scenarios. Those are listed below:

• merge
• consent event that is generated by manual consent update in the web UI. Such consent event will have CRM in the source attribute.
• Add event node doesn't trigger scenarios unless you click on the option "Allow scenario triggering".
• Ad audiencenode (with add_customers and remove_customers operations) is generated internally and not tracked via API; it doesn't trigger scenarios.

3. On-event trigger limitation

If you want to use the event attribute is false in the "On event" trigger, you also need to add an event attribute has value. This way, the system checks the existence of your attribute first and then evaluates it.
If the has value condition is missing in the filter, and non-existing properties will also be evaluated as false.

🚧

You can't use Jinja in an On-event trigger.

For example, you set up two scenarios. You sold your product in the first scenario. In the second scenario with an 'On event' trigger, you want to exclude customers who bought your product with a discount. Set the event discount as false, and the discount has value to exclude these customers.

Resetting Triggers

Once used in a live scenario, both Now and On date triggers will become inactive. If you want to re-activate them, use the Reset trigger. In the picture below, you can see the triggers as active on the left and inactive on the right:

🚧

Specifying events using derived attributes

It is not possible to specify events using derived attributes (running aggregates, expressions, event segmentations).

❗️

Parallel triggers overload in a single scenario

As the triggered actions will be processed in the order as requested, a single Scenario with parallel triggers might not work as expected. For example, if both 'On event' and 'On date' triggers are pulled simultaneously the 'On event' trigger would need to wait until the 'On date' trigger is fully processed despite the expectation that it would go into action right after a particular event is tracked. If there are multiple parallel triggers it is recommended to divide them across multiple Scenarios.

Actions

When a customer enters an action component, an action is executed. Each type of action has a unique 'action_id'. Read more about this in the System events article.

📘

Locating action ID

To see a particular action ID, go to the Evaluation tab, hover your mouse over the node and the ID will be shown in the format of "#(number)".

🚧

Emailing a manually-chosen recipient

If the recipient is used in the scenario's email node is chosen manually, then the campaign policy for the frequency of delivery will be ignored.

Operators

Operators are generally used to change the way customers move through the flow. There are the following types of Operators:

📘

Relative time filters use the UTC timezone while absolute time filters use your custom timezone from Settings > User Settings > Timezone. Note that the relative filters apply only to scenarios, not to your whole project.

See Also: Flexible Operators in Advanced Features in Scenarios

Customer Limit

🚧

You can only have up to 1000 distinct groups in a limit node, before it starts failing.

The customer limit allows you to set the maximum number of customers passing through the node. This can be very useful when your scenario leads your customers to a channel with a limited capacity. For example, you might have limited capacity for the number of calls your call center can handle within a day.

The customer limit node creates two outputs: a successful one for the customers within the limit and an unsuccessful one for the customers over the limit. At the moment when a particular customer arrives at the customer limit node in the scenario, it is decided which output they will go to. At first, all customers go to the successful output, but once the threshold is reached, all the rest go to the unsuccessful output. Since then, all customers will fall into the unsuccessful output even for the next campaign runs until the number of customers passing through the node is reset back to zero. You can set a period reset of this number in the Specify customer limit reset period.

You can set the limit by filling in the value of the Limit to # of customers. This value can either be an absolute number or a number referenced by Jinja (references to the following can be used: metrics, reports, report_value_by_key, catalogs). Read more on jinja references.

You can also Allow drill-down group which lets you use Jinja to add multiple limits per node based on the group - a separate limit on each segment of customers using the scenario. You might want to do this if you send out a competition that would be decided on a 'first come, first serve' basis, but where you also want to have a specific number of winners from different segments of customers. You can use the same variables as in webhooks, like customer attributes, trigger event properties, or webhook response. If you want to use the drill-down group as a parameter in the jinja of the limit, the parameter is called limit_group.

📘

Example of the limit with a limit group

To look into catalog subsidiaries and look for an item that was used as a drill-down group, and reference limit attribute from the catalog item, use:
{{ catalogs.subsidiaries.item_by_id(limit_group).limit }}

Using Optimal Send Time

Based on your customer's past behavior, the optimal send time option in the wait node allows you to automatically send out email campaigns to individual customers at a time, rounded to an hour, when they are most likely to click/open your email. Learn more about Optimal send time

📘

Interactive tour

Learn how trigger email and SMS with real-time data and let AI determine which channel to engage customers on.

View tour 23 steps, 4 minutes

Using Dynamic Time

Using Jinja, you can use the dynamic wait time to set a custom wait period. You can use some project metrics, aggregates, trigger event attributes, or any type of personalization.

Common usage of the dynamic wait time is to spread or throttle the campaign execution over some time period using the random number generator. E.g. to spread the send approximately within 60 minutes, you can use the{{ range(0,60) | random }}.

If the Wait time is set to hours, the number is rounded down (to an integer). For example, when you calculate 1.8 hours wait, The ait node waits only 1 hour. If you want to round up, you can use the Jinja function round (can accept "ceil," "floor," or "common" parameter):

Wait {{ ((event.departure_time - time) / 3600) | round("ceil") }} hours

Wait node does not wait at all if the wait value is zero or lower (executes the following node right away).

Using Silent Hours

You can use Silent hours to temporarily pause the sending of your campaigns to the customer during times when you do not want to disturb them, such as at night or on a Sunday. If this node is entered during silent hours, the scenario will wait under their end and only then send the campaign. Silent hours can be set up for a specific time repeated daily or as Silent days, which will silence the whole selected day, or both options can be used together. A specific timezone can also be selected for the silent hours to be evaluated against.

Silent hours can also be set up globally in Project settings > Campaigns > General Campaigns settings. This will pre-fill a Silent hour Wait node when it is selected in a scenario. The setting can be overridden in a specific node if needed.

📘

Note

Read Scenario best practices to get helpful tips for building effective scenarios.