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" who performed the action that triggered the notification.

It's highly recommended to group notifications about the same "topic" or "entity" in your system into individual workflows. While it might be tempting to build a single workflow with conditional logic for all of your notification use cases that can be triggered from anywhere within your application with the same workflow key, modularizing your workflows by topic and use case allows you to offer the highest level of configurability to your users via Preferences. Our customers also find that concise, topic-specific workflows are easier to maintain and iterate on.

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 user's preferences across many workflows.

To set a category for a given workflow, go to that workflow's page in the dashboard, click the "..." menu, and select "Manage workflow." From there, you'll be able to add categories.

💡

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.

Read more about environments and versioning in Knock.

Workflow status

Each workflow has an Active/Inactive status that is displayed in your dashboard's Workflows section. The status defaults to Active and can be set by clicking on the workflow and using the "Status" selector.

This is your kill switch for a given workflow should you need it; any attempt to trigger an Inactive workflow will result in a workflow_inactive error. The status setting operates independently from the commit model so that you can immediately enable or disable a workflow in any environment without needing to go through environment promotion. It is environment-specific and will only be applied to the current environment.

Archiving workflows

Archiving a workflow allows you to permanently remove a workflow from Knock. When you archive a workflow it will be removed from all environments and cannot be called via API. Once a workflow is archived, it cannot be undone. If you have delayed runs for a workflow that is archived, when the workflow run resumes after the delay it will immediately terminate.

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.

Automate workflow management with the Knock CLI

In addition to working with workflows in the Knock dashboard, you can programmatically create and update workflows using the Knock CLI or our Management API.

If you manage your own workflow files within your application, you can automate the creation and management of Knock workflows so that they always reflect the state of the workflow files you keep in your application code.

The Knock CLI can also be used to commit changes and promote them to production, which means you can automate Knock workflow management as part of your CI/CD workflow.

Workflow files structure

When workflows are pulled from Knock, they are stored in directories named by their workflow key. In addition to a workflow.json file that describes all of a given workflow's steps, each workflow directory also contains individual folders for each of the channel steps in the workflow that hold additional content and formatting data.

If you're migrating your local workflow files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using knock workflow push --all. Each workflow.json file should follow the structure defined here.

You can learn more about automating workflow management in the Knock CLI reference. Feel free to contact us if you have questions.

Frequently asked questions

←Overview

Channels→