Workflows

Workflows are triggered journeys that send notifications to your recipients.

Workflows are represented as a set of steps, which are either function or channel steps. Functions apply logic to your workflow run, like batching and branching. Channel steps produce notifications that are delivered via your configured channels.

Workflows in Knock:

• Have a unique key
• Execute for a single recipient at a time
• Contain all of the logic and templates for the notifications you send
• Evaluate recipient preferences automatically
• Are triggered via API calls, events, audience events, or recipient schedules

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.

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.

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.

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.

All changes to workflows, including changes made to the templates inside of a workflow, are version controlled. By default, changes must be made in the development environment and then promoted to your production environment.

If your account has production write access enabled, you can create and edit workflows directly in production.

Read more about environments and versioning in Knock.

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 and no workflow runs will be enqueued.

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.

See the frequently asked questions section below for more information on how in-progress workflow runs are affected when you set a workflow's status to Inactive.

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.

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.

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.

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.

Read more about canceling workflows

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 Observability > 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.

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.

Read more about the properties available

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.

See the Workflow file structure section in the CLI reference for details on how workflow files are organized when working with the CLI.

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