Workflows

Learn more about what a workflow in Knock is, and how to think about grouping together your cross-channel notifications into different workflows.

In Knock, all notifications are sent via a workflow. Each workflow acts as a container for the logic and templates that are associated with a kind of notification in your system.

Workflows are represented as a set of steps, which are either function or channel steps. Functions apply logic to your workflow run, like batching to collapse multiple calls into single notifications or delays to pause the execution of a workflow for some duration. Channel steps produce a notification that will be delivered via a configured channel. All steps can also have conditions to determine if and when they should run.

Workflows in Knock:

Always have a unique key associated
Are always executed for a single recipient at a time
Contain all of the logic and templates for the notifications you send
Can have recipient preferences attached
Can be triggered via the API, an event, or on a schedule for a recipient

Thinking in workflows

A workflow groups together cross-channel notifications and the business logic that governs those notifications into a single entity. Workflows are always executed on behalf of a single recipient and can have other properties associated with them, like the "actor" of who performed the action that triggered the notification.

It's most common to group notifications about the same "topic" or "entity" in your system into individual workflows. As an example, if we're building a document collaboration app where users can comment on specific documents we might group all of the logic about the cross-channel comment notifications we have into a single new-comment workflow.

💡

Note: remember that in Knock all notifications sent are via a workflow. There's no other way to send notifications to your recipients, so every notification you want to send must be represented in a workflow.

You can read more about how to build your workflows and the features available within the workflow builder under the designing workflows section of the documentation.

Workflows and notification templates

Each workflow you build will contain one or more channel steps. It's these channel steps that contain the templates that will be rendered to produce a notification sent to the recipient of the workflow run.

The templates associated with a channel step only exist in the context of that channel step. That means that templates cannot currently be shared across workflows, or even across other channel steps within the same workflow.

Managing workflows

Knock workflows can be managed either via the Knock Dashboard or programmatically via the Management API. The Knock CLI offers a convenient way to work with the management API locally to make updates to workflows and their templates.

💡

Note: remember that workflows and other resources in Knock can only ever be edited in the development environment.Learn more about versioning and environments.

Workflow categories

Each workflow can have one or more categories associated with it. Categories are useful for grouping related types of workflows together and offer a way to apply a set of recipient preferences across many workflows.

💡

Note: workflow categories are case sensitive.

Version control for workflows

All changes to workflows, including changes made to the templates inside of a workflow, are version controlled. Changes must be made in the development environment and are then "committed" and then "promoted" between environments for that version to be live within an environment. This allows you to confidently make changes to workflows, without affecting any running in production.

Running workflows

Workflows defined in Knock are executed via trigger, which starts a workflow run for the recipients specified using the data passed to the workflow trigger.

💡

Note: it's important to know that in Knock a workflow run is always executed against a single recipient. Workflows can always be invoked for multiple recipients, but each run will only be for a single recipient.

Triggering a workflow

In Knock, workflows can be triggered in three different ways:

API call: workflows can be triggered directly via an API call to our workflow trigger endpoint. This is the most common form of integration and means that Knock is integrated into your backend codebase, usually alongside your application logic.
Events: using different event sources, you can connect Knock to CDPs such as Segment and Rudderstack and map the events those systems produce to workflows that should be triggered.
Schedules: workflows can be scheduled to be run for one or more recipients, in a recipient's local timezone on a one-off, or recurring basis.

Canceling a workflow run

Any triggered workflow that has an active delay or batch step can also be canceled to halt the execution of that workflow run. Workflow cancellations today must happen through the cancellation API and can only occur when a cancellation_key has been specified on the workflow trigger.

Workflow runs and recipients

When a workflow is triggered via the API we return a workflow_run_id via the API response. This ID represents the workflow run for all of the recipients that the workflow was triggered against.

For each recipient included in the workflow trigger or that the workflow should fan out to via subscriptions, a new workflow run is enqueued. We call this the recipient workflow run.

Recipient runs are visible within the Knock dashboard by going to "Developers > Logs". Each run can be inspected to view its current state as well as the steps executed for the workflow. It's also possible from a workflow run log to see the messages (notifications) produced by the run.

Workflow run scope

When a workflow run is executed, associated state is loaded to be used within the templates and conditions defined in the workflow. This state is known as the workflow run scope. The run scope can be modified during the duration of the workflow run by fetching additional data via the fetch function.

Per-workflow preferences

Workflows can have preferences associated, either via individual workflow preferences (specified via the workflow key) or via workflow-category preferences (matched against the categories set).

Frequently asked questions

Is there a limit to the number of workflows I can have in Knock?

No, there's no limit to the number of workflows you can have within your Knock environment.

Can I create per-tenant/per-customer workflows?

While it's possible to create per-customer workflows using the management API, we recommend avoiding doing this in favor of using per-tenant overrides and preferences to control individual workflows.

←Overview

Channels→