Trigger 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.
Some examples of triggers you can employ are:
- 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
Trigger conditions are created and edited on each step by selecting the step in the workflow canvas. Each trigger condition is made up of a
A trigger 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)
- Message status: when a
refscondition is selected, we can evaluate the status of one or more messages produced from that step (see Message status trigger conditions for more)
Message status trigger conditions allow you to build triggers that evaluate based on the status of one or more messages sent from a channel step. When selecting a step message status trigger condition you can then 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 seen: triggered if the message status is
- Seen but not read: triggered when a message status is
- Marked as read: triggered 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 trigger 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 trigger 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 trigger 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 trigger 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 trigger conditions were not met.
One common use-case for trigger 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 trigger 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!