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
- Create a workflow that you wish to run in the future.
- 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 representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule. |
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:
- Define static data passed to every triggered workflow on a schedule. We can include an optional
datapayload when we create our schedule. Any workflow runs triggered by that schedule will include the data payload within their workflow run scope. - 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.