Schedules

A schedule allows you to automatically trigger a workflow at a given time for one or more recipients.

You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

Some examples of where you might reach for a schedule:

• A digest notification where your users can select the frequency in which they wish to receive the digest (every day, every week, every month).
• A reminder notification for a specific event or deadline, sent only once at a given date and time.

How schedules work

1. Create a workflow that you wish to run in the future.
2. Using the API, set a repeating schedule or a non-recurring schedule for one or more recipients for the workflow.

Knock will preemptively schedule workflow runs for the recipient(s) that you've provided, and execute those runs at the scheduled time. At the end of the workflow run (and in case of using a recurring schedule), a future scheduled workflow will be enqueued based on the recipient's next schedule.

Scheduling workflows with recurring schedules for Recipients

To schedule a workflow for a recipient using recurring schedules, you must first have a valid, committed workflow in your environment. We can then set a schedule with repeats for one or more recipients (up to 100 at a time).

Scheduling workflows with non-recurring schedules for Recipients

To schedule a workflow for a recipient using a non-recurring schedule, you must also have a valid and committed workflow in your environment. We can then set a schedule with the scheduled_at property, specifying the moment when this workflow should be executed.

Schedule properties

ScheduleRepeat properties

Modeling repeat behavior

Every recurring schedule accepts one or more repeat rules, which allow you to express complex rules like:

• Every Monday at 9am.
• Every weekday at 10.30am.
• Every other Monday, Tuesday, and Friday at 6pm.
• Every year at midnight.

A schedule repeat has the following type structure:

Example repeat rules

To illustrate how to model a repeat rule, here are some common examples:

Every Monday at 9am

Every weekday at 10.30am

Every other Monday, Tuesday, and Friday at 6pm

Updating schedules

Up to 100 recipient schedules can be updated in a single call. Keep in mind that the properties passed in will be applied to all schedules.

Removing schedules

Up to 100 schedules can be deleted at a time, causing any already enqueued schedules to be cancelled for a recipient.

Listing scheduled workflows

Schedules can be listed per recipient (for a user or an object), or for an individual workflow:

Schedules include a next_occurrence_at property which computes the next time that a schedule will be executed. Schedules also incldue a last_occurrence_at property which indicates when was the last time the schedule was executed.`

Workflow data in a scheduled workflow run

Workflows in Knock are triggered either via an API call or via a Source event, both of which will pass the data associated. In the case of a scheduled workflow, the workflow will be triggered with an empty data payload by default.

There are 2 ways in which to get data into each of your scheduled workflow runs:

1. Define static data passed to every triggered workflow on a schedule. We can include an optional data payload when we create our schedule. Any workflow runs triggered by that schedule will include the data payload within their workflow run scope.
2. Fetch data from an HTTP endpoint to use in your workflow. You can use an fetch function step to fetch data for a triggered scheduled workflow to “enrich” the data available with information from a remote server (via HTTP).

Executing schedules in a recipient's timezone

Knock supports a timezone property on the recipient that automatically makes a scheduled workflow run timezone aware, meaning you can express recurring schedules like "every monday at 9am in the recipient's timezone". Recipient timezones must be a valid tz database time zone string, like America/New_York.

Read more about recipient timezone support .

Note: Executing schedules using recipient timezones is only supported by recurring schedules by the moment.

Frequently asked questions

How can I start my repeating schedule at a particular time? You can use the scheduled_at attribute to start your schedule at a particular time in the future.

How can my scheduled workflows use dynamic template data? You can use an HTTP fetch step to fetch data in your workflow as the first step to execute to fetch dynamic template data used in your workflow.

How can I set static data per workflow schedule? When scheduling a workflow for one or more recipients, you can optionally provide a static set of data which will be passed to the invoked workflow.

Can I cancel a scheduled workflow? At any point before the scheduled workflow is invoked you can unschedule the workflow for one or more recipients. If a workflow has already run, then normal workflow cancellation rules take effect.

Can I still debug a scheduled workflow? You’ll see workflow runs that initiated from a scheduled workflow in the list of workflow runs. From there you can select the debugger and debug a given workflow.

Can I model exclusion rules in my repeat logic? Currently, no but we'll be looking to add this feature in the near future.

Can I change a recurring schedule to be a non-recurring? Yes, you can update the schedule to change from a recurring to a non-recurring(or viceversa). This can be done by removing the repeats property and setting the scheduled_at to the desired one-time execution time.