Step conditions

Step conditions allow you to apply control flow to your workflow runs on a per-step basis. You can use the Knock conditions editor to associate one or more conditions with any step in your workflow. Then, for each workflow run, Knock will evaluate these conditions to determine if the step should execute.

Some examples of the kinds of step conditions you can design include:

• Only execute a workflow if shouldExecute == true.
• 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.
• Only send an email in your development environment if the recipient's email matches a particular domain.

See our guide on the Knock conditions model for more information about how conditions work across Knock and how to debug your conditions within your workflow runs.

In this guide, we cover features specific to step conditions, most importantly message status conditions.

Types of step conditions

Trigger step conditions

A trigger step can have one or more step conditions, which will be evaluated on the trigger of the workflow for the recipient. When the conditions evaluate to false then the workflow will be halted and no other steps will be executed.

Other step conditions

For all function and channel steps, step conditions will be evaluated when the step is executed. If the conditions on the step evaluate to false, then the step will be skipped and the subsequent step will be invoked, or the workflow will terminate if there are no other steps to execute.

Message status conditions

Message status conditions allow you to build a check for one workflow step that evaluates against the delivery or engagement status of a message sent from a preceding step. When building a step message status condition, you'll use the conditions editor to select:

• Any preceding channel step that may produce a message, using it's ref.
• An asserting ("has") or negating ("has not") condition operator.
• The expected delivery or engagement status case.

Status cases

Evaluation timing

Knock evaluates message status conditions, like all conditions, immediately when executing a workflow step. This means that you may need to account for time between steps when building these conditions, especially those that require some amount of recipient engagement or delivery confirmation. See below for an example of using a delay step for this purpose.

Multiple messages

In certain cases, such as when using a channel group, a single channel step can produce multiple messages. In these cases, Knock uses the message with the highest status for the condition evaluation.

To determine each message's highest status, Knock looks at both its delivery status plus each of its engagement statuses, choosing the highest value status from the group. Knock uses the following combined delivery and engagement status hierarchy (ordered from lowest to highest):

• undelivered
• bounced
• delivery_attempted
• queued
• not_sent
• sent
• delivered
• seen
• read
• interacted + link_clicked
• archived

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

One common use-case for step conditions is conditionally sending a notification based on whether the recipient has seen a preceding notification delivered 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 tell Knock to only send the email if the in-app notification has not yet been seen. To do this you will:

1. Select a "Step message status" condition type.
2. Select the ref of the in-app step (by default named in_app_feed_1).
3. Select the negating "has not" operator.
4. And finally, select the "been seen" status case option.

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

Advanced: How Knock models status conditions

The message status condition editor provides some useful abstractions on top of Knock's conditions model. Under the hood, Knock stores each status condition using our standard variable, operator, and argument trio, with some special caveats:

• The variable will always be either refs.<ref>.delivery_status or refs.<ref>.engagement_status.
• The operator will be a hierarchical comparison operator for a delivery status condition or an inclusionary operator for an engagement status condition.
• The argument will be a reserved status case string.

Below we provide example models for each of the status conditions made available in the editor.

Skipped cases

Failed delivery cases

Bounced cases

Sent cases

Delivered cases

Seen cases

Read cases

Interacted cases

Link clicked cases

Archived cases