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.
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.
Knock models each condition as a combination of three properties: a
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.
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:
|A data condition, where |
|A recipient condition, where |
|An actor condition, where |
|An environment variable condition, where |
|A workflow condition.|
|A workflow run condition.|
|A tenant condition, where |
|A message status condition that evaluates against a message's delivery status, where |
|A message status condition that evaluates against a message's engagement status, where |
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.
Knock uses the condition argument as the expected value in the condition evaluation. Arguments can be either static values or dynamic properties.
Static arguments can be any of the following JSON literals:
- Strings (
- Numbers (
- Booleans (
Plus arrays of any of the above.
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:
|Selects the |
|Selects the |
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.
You can use any of the following operators in condition comparisons:
|are all |
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 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
- 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.
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.
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.
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.
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.