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 one-off, 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

Variable	Type	Description
recipients	RecipientIdentifier[]	One or more recipient identifiers, or complete recipients to be upserted.
workflow	string	The workflow to trigger.
repeats	ScheduleRepeat[]	A list of one or more repeats (see below). Required if you're creating a recurring schedule.
data	map	Custom data to pass to every workflow trigger.
tenant	string	A tenant to pass to the workflow trigger.
actor	RecipientIdentifier	An identifier of an actor, or a complete actor to be upserted.
scheduled_at	utc_datetime	A UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule.
ending_at	utc_datetime	A UTC datetime in ISO-8601 format that indicates when the schedule should end. Once the current schedule time passes ending_at, no further occurrences will be scheduled.

ScheduleRepeat properties

Variable	Type	Description
frequency	RepeatFrequency	The frequency in which this repeat schedule should run, one of monthly, weekly, daily, or hourly.
interval	number (optional)	The interval in which the rule repeats. Defaults to 1. Setting to 2 with a weekly frequency would mean running every other week.
day_of_month	number (optional)	The exact day of the month that this repeat should run.
days	DaysOfWeek[], "weekdays", "weekends"	The days of the week that this repeat rule should run. Can provide "weekdays" or "weekends" as a shorthand.
hours	number (optional)	The hour this schedule should run (in the recipient's timezone). Defaults to 00.
minutes	number (optional)	The minute this repeat should run (in the recipient's timezone). Defaults to 00.

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

Frequently asked questions