Skip to main content
A schedule queues a task or workflow on a cron expression: a nightly report, an hourly sync, a weekly digest. A schedule only queues jobs. Two things must also be running:
  1. Something that handles schedules, which queues each due job.
  2. A runner that runs the schedule’s queue.
A worker started with --handle-schedules and --all-queues does both.

Add a schedule

Add schedule to a task or workflow:
A task or workflow can have several schedules, each with its own cron and queue.

Handle schedules

Use one of these, covering the schedule’s queue: Handle schedules often, every minute or faster. The cron decides when a job runs; the handling interval only needs to be shorter than the gap between occurrences. Run schedule handling in one place, such as a single scheduler process. If web replicas also autorun, see Disable web autorun.

How scheduling works

Each time schedules are handled, for every schedule in the selected queues, FrogBot:
  1. Works out the next cron time after the schedule last queued a job. It keeps that time in the payload-jobs-stats global.
  2. Calls beforeSchedule. By default, it skips while a scheduled job of the same task or workflow in that queue is still unfinished, so runs don’t pile up or overlap.
  3. Queues the job with waitUntil set to that cron time and meta: { scheduled: true }. The job is queued ahead of time and waits until then.
  4. Calls afterSchedule, which by default records the time in payload-jobs-stats.
Cron expressions are read in the server process’s local timezone. Set TZ on the process to pin it.

Cron format

Use five fields, or six with a leading seconds field:

Set the input of a scheduled job

Scheduled jobs get {} as input. To compute input when the job is queued, wrap the default check in beforeSchedule:
Keep the default’s shouldSchedule and waitUntil. Without waitUntil, the job runs as soon as a runner sees it, not at the cron time. A hook that always returns shouldSchedule: true queues another job on every scheduling tick.

Schedule options