Step conditions allow you to specify if a given step will execute at workflow execution time. They provide a powerful way to create more advanced notification workflow logic.
Here are a few examples of step conditions you can build:
- Only send an email if an in-app notification was not previously read or seen
- Only send an in-app notification if the
recipient.plan == "pro"
- Only execute a delay step if
delay == truein the workflow trigger
- Only send an email in your development environment if the recipient's email matches a particular domain
To add a condition to a channel's environment configuration, navigate to that channel under "Integrations > Channels" and then edit the configuration for the channel-environment to which you want to add a condition.
Conditions are created and edited on each step by selecting the step in the workflow canvas. Each condition is made up of a
A condition can be set on any of the following variables:
- data: Target a property within the
datapayload of the workflow trigger
- recipient: Target a property of the current
recipientof the workflow run
- actor: Target a property of the current
actorof the workflow run
- refs: Target the message status of a previously executed channel step in the workflow
You can use any of the following operators in condition comparisons:
Arguments can be static (like fixed strings, numbers, or booleans) or dynamic properties. All of the following are valid arguments:
- Fixed strings (
- Fixed floats and numbers (
data.*: Selects a property within the data payload of the workflow trigger (falling back to an empty string)
recipient.*: Selects a property on the current
recipient(falling back to an empty string)
actor.*: Selects a property on the current
actor(falling back to an empty string)
vars.*: Selects an environment variable (falls back to an empty string)
tenant.*: Selects a property on the current
tenant(falling back to an empty string)
categoriesof the current workflow
total_actorsof the current workflow run
- Message status: when a
refscondition is selected, we can evaluate the status of one or more messages produced from that step (see Message status step conditions for more)
Message status conditions allow you to build conditions that evaluate the status of one or more messages sent from a channel step. When building a step message status condition you can select any proceeding channel steps that have produced messages to evaluate against (by the
ref of the step).
The statuses you can evaluate against are:
- Not sent: evaluates to true if the message status is not
- Sent: evaluates to true if the message status is
- Not seen: evaluates to true if the message status is
- Seen but not read: evaluates to true when a message status is
- Marked as read: evaluates to true when a message status is
Note: the message status is evaluated immediately as the step is executed, meaning that you will need to account for time between steps when building conditions that rely on message status. See below for an example of using a delay step for this purpose.
Message statuses are always evaluated in the following order:
In certain cases channel steps can produce one or more messages (like when a channel group is used).
In the case where multiple messages are produced from a step the lowest message status is selected to be used when evaluating a condition. As an example, if you have one seen and one read message from
step_1 then the status that will be evaluated is
One or more conditions can be combined as either 'AND' or 'OR' operators when building conditions on the step.
ANDcombined conditions require all conditions to be true before the step executes
ORcombined conditions require at least one condition to be true before the step executes
You can debug conditions on each step in the workflow debugger. You'll see a log line that indicates that the step did not execute because one or more conditions were not met.
One common use-case for conditions is conditionally sending a notification based on whether the recipient has seen a notification on another channel. You can think of this concept as channel escalation, or intelligent routing.
In order to implement this, your workflow will need:
- An in-app notification channel step to send the initial message
- A delay step so that we wait a period of time before executing the email step
- An email channel step to send the escalated message
Next, we'll add a condition to our email channel step that will say "only execute this step if the in-app notification has not been seen".
We'll do that by selecting the
ref of the in-app step (by default named
in_app_feed_1) and then applying the "Not seen" message status as a condition.
That's all it takes to build intelligent message routing in Knock!