Conditions
Knock uses conditions to model checks that determine variations in your workflow runs. They provide a powerful way to create more advanced notification logic flows.
You can use conditions in three areas of the Knock model:
- Step conditions — Used to determine if a single step in one of your workflows should execute during each workflow run. For example, only send an email if the preceding in-app notification has not yet been read or seen.
- Channel conditions — Used to determine if any step using the given channel should execute across all workflow runs. For example, only execute your Postmark email channel steps in your production environment.
- Preference conditions — Used to determine the complete set of preferences available to the current workflow run. For example, allow a recipient to mute notifications for specific resources in your product.
Each of these three cases share the same underlying data model and UI editor, which we outline in detail here.
Condition types
Knock's shared conditions model supports the following types of conditions:
- Data — Evaluates against a property in the workflow trigger data payload.
- Recipient — Evaluates against a property on the workflow run recipient.
- Actor — Evaluates against a property on the workflow run actor.
- Environment variable — Evaluates against one of your environment variables.
- Workflow — Evaluates against a property of the currently executing workflow.
- Workflow run state — Evaluates against a property of the current workflow run.
- Tenant — Evaluates against a property on the tenant associated with the current workflow run.
- Message status — Evaluates against the delivery status or engagement status of a message from a previous step in the current workflow run.
Modeling conditions
Knock models each condition as a combination of three properties: a variable, an operator, and an argument. This will feel familiar to boolean logic with infix operators in many modern programming languages.
In our JSON representation this will look something like:
We also provide a conditions editor that provides some helpful UX abstractions on top of this model for building conditions in the Knock dashboard.
Variables
A condition variable is always a string formatted like "<prefix>.<path>". Knock uses the variable prefix to determine the condition type and the variable path to determine where to look up the data for evaluation.
Knock allows the following variable formats:
| Variable | Description |
|---|---|
data.<path> | A data condition, where <path> is used to select a property from the workflow trigger data payload. |
recipient.<prop> | A recipient condition, where <prop> is used to select a property on the current recipient. |
actor.<prop> | An actor condition, where <prop> is used to select a property on the current actor. |
var.<var> | An environment variable condition, where <var> is the name of one of your environment variables. |
workflow.{id,name,categories} | A workflow condition. |
run.{total_activities,total_actors} | A workflow run condition. |
tenant.<prop> | A tenant condition, where <prop> is used to select a property on the current tenant. |
refs.<ref>.delivery_status | A message status condition that evaluates against a message's delivery status, where <ref> identifies the preceding workflow step that generated the message. |
refs.<ref>.engagement_status | A message status condition that evaluates against a message's engagement status, where <ref> identifies the preceding workflow step that generated the message. |
In cases where data is not found at the path given by the variable, Knock falls back to an empty string as the default value.
Arguments
Knock uses the condition argument as the expected value in the condition evaluation. Arguments can be either static values or dynamic properties.
Static arguments
Static arguments can be any of the following JSON literals:
- Strings (
"foo","bar","baz") - Numbers (
1.0,2,10000) - Booleans (
true,false) null
Plus arrays of any of the above.
Dynamic arguments
Dynamic arguments are nearly identical to variables. Knock will expect a string formatted like "<prefix>.<path>" and use the information within to resolve a value from some runtime data property.
Knock allows the following dynamic argument formats:
| Argument | Description |
|---|---|
data.<path> | <path> is used to select a property from the workflow trigger data payload. |
recipient.<prop> | <prop> is used to select a property on the current recipient. |
actor.<prop> | <prop> is used to select a property on the current actor. |
var.<var> | <var> is the name of one of your environment variables. |
workflow.{id,name,categories} | Selects the id, name, or categories value for the current workflow. |
run.{total_activities,total_actors} | Selects the total_activities or total_actors value for the current workflow run. |
tenant.<prop> | <prop> is used to select a property on the current tenant. |
In cases where data is not found at the path given by the argument, Knock falls back to an empty string as the default value.
Operators
You can use any of the following operators in condition comparisons:
| Operator | Description |
|---|---|
equal_to | == |
not_equal_to | != |
greater_than | > |
greater_than_or_equal_to | >= |
less_than | < |
less_than_or_equal_to | <= |
contains | argument in variable (works with strings and lists) |
contains_all | are all argument in variable (works with single arguments, or lists of arguments) |
not_contains | argument not in variable (works with strings and lists) |
empty | variable in ["", null, []] |
not_empty | variable not in ["", null, []] |
Note: the empty and not_empty operators do not require a companion argument value in the condition, since Knock is checking for the absence of data from the variable path.
The conditions editor
The Knock Dashboard ships with a conditions editor that provides helpful abstractions on top of this data model. Rather than needing to remember how to format variables or name operators, Knock makes the appropriate options available to you.
When creating or modifying a condition, you'll see:
- A dropdown to select the condition type. Knock will use this option to determine the variable
<prefix>value. - An input or dropdown to provide the variable data path.
- A dropdown to select the operator.
- An input or dropdown to provide the argument data path.
Working with the conditions editor to build a recipient data condition.
You can also use the conditions editor to combine multiple conditions together via either 'AND' or 'OR' operators.
ANDcombined conditions require all conditions to be true for the evaluation to pass.ORcombined conditions require at least one condition to be true for the evaluation to pass.
The condition editor is available for use in the workflow step editor and the channel environment settings editor.
Debugging conditions
Knock executes any step, channel, and preference conditions for each step within a workflow run. As part of execution, Knock captures detailed information about each condition evaluation for use in the workflow debugger.
Debugging step and channel conditions
Knock will display step and channel conditions evaluation results together in the step detail panel in the debugger. The overall evaluation result will show whether the step was skipped. For each individual condition within the set, Knock will show either:
- The condition evaluation result. This will include any dynamically resolved variable and argument data captured at workflow run time.
- A "not evaluated" state. This will occur when a preceding condition or group has determined the result, meaning subsequent conditions did not require full evaluation.
Debugging preference conditions
Knock will display any preference conditions evaluations just below the step and channel conditions results. Knock will group each condition evaluation by location within the resolved preference set. The overall evaluation result will show whether the recipient opted-out for the given workflow, category, or channel type.
