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.
- 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.
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).
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.
|RecipientIdentifier||One or more recipient identifiers, or complete recipients to be upserted.|
|string||The workflow to trigger.|
|ScheduleRepeat||A list of one or more repeats (see below). Required if you're creating a recurring schedule.|
|map||Custom data to pass to every workflow trigger.|
|string||A tenant to pass to the workflow trigger.|
|RecipientIdentifier||An identifier of an actor, or a complete actor to be upserted.|
|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.|
|RepeatFrequency||The frequency in which this repeat schedule should run, one of monthly, weekly, daily, or hourly.|
|number (optional)||The interval in which the rule repeats. Defaults to 1. Setting to 2 with a |
|number (optional)||The exact day of the month that this repeat should run.|
|DaysOfWeek, "weekdays", "weekends"||The days of the week that this repeat rule should run. Can provide "weekdays" or "weekends" as a shorthand.|
|number (optional)||The hour this schedule should run (in the recipient's timezone). Defaults to 00.|
|number (optional)||The minute this repeat should run (in the recipient's timezone). Defaults to 00.|
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:
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
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.
Up to 100 schedules can be deleted at a time, causing any already enqueued schedules to be cancelled for a recipient.
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.
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).
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
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.