KnockDocs

Trigger conditions

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 == true in the workflow trigger

Building trigger conditions

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 variable, operator, argument triple.

Available variables

A trigger can be set on any of the following variables:

  • data: Target a property within the data payload of the workflow trigger
  • recipient: Target a property of the current recipient of the workflow run
  • actor: Target a property of the current actor of the workflow run
  • refs: Target the message status of a previously executed channel step in the workflow

Available operators

You can use any of the following operators in condition comparisons:

OperatorDescription
equal_to==
not_equal_to!=
greater_than>
greater_than_or_equal_to>=
less_than<
less_than_or_equal_to<=
containsargument in variable
not_containsargument not in variable
emptyvariable in ["", null, []]
not_emptyvariable not in ["", null, []]

Available arguments

Arguments can be static (like fixed strings, numbers, or booleans) or dynamic properties. All of the following are valid arguments:

Static properties

  • Fixed strings (foo, bar, baz)
  • Fixed floats and numbers (1.0, 2, 10000)
  • true, false, null

Dynamic properties

  • 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 refs condition 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

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 sent or delivered but not seen
  • Seen but not read: triggered when a message status is seen
  • Marked as read: triggered when a message status is read but not archived

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 status evaluation order

Message statuses are always evaluated in the following order:

  • sent
  • delivered
  • seen
  • read
  • archived

Multiple message statuses

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 seen.

Combining trigger conditions

One or more trigger conditions can be combined as either 'AND' or 'OR' operators when building conditions on the step.

  • AND combined conditions require all conditions to be true before the step executes
  • OR combined conditions require at least one condition to be true before the step executes

Debugging trigger conditions

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.

Example: conditionally sending an email if an in-app notification was not seen

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.

Setting a trigger condition on the email step
Setting a trigger condition on the email step for when the in-app notification has not been seen

That's all it takes to build intelligent message routing in Knock!