Scheduling

Jobs may be created automatically based on a cron expression. As with other cron-based systems, at least one instance needs to be running for scheduling to work. In order to reduce the amount of evaluations, schedules are checked every 30 seconds, which means the 6-placeholder format should be discouraged in favor of the minute-level precision 5-placeholder format.

For example, use this format, which implies "any second during 3:30 am every day"

30 3 * * *

but not this format which is parsed as "only run exactly at 3:30:30 am every day"

30 30 3 * * *

To change how often schedules are checked, you can set cronMonitorIntervalSeconds. To change how often cron jobs are run, you can set cronWorkerIntervalSeconds.

In order mitigate clock skew and drift, every 10 minutes the clocks of each instance are compared to the database server's clock. The skew, if any, is stored and used as an offset during cron evaluation to ensure all instances are synchronized. Internally, job throttling options are then used to make sure only 1 job is sent even if multiple instances are running.

If needed, the default clock monitoring interval can be adjusted using clockMonitorIntervalSeconds. Additionally, to disable scheduling on an instance completely, use the following in the constructor options.

{
  schedule: false
}

For more cron documentation and examples see the docs for the cron-parser package.

schedule(name, cron, data, options)

Schedules a job to be sent to the specified queue based on a cron expression. If the schedule already exists, it's updated to the new cron expression.

Arguments

• name: string, required
• cron: string, required
• data: object
• options: object

options supports all properties in send() as well as the following additional options.

• tz

  An optional time zone name. If not specified, the default is UTC.

• key

  An optional unique key if more than schedule is needed for this queue.

For example, the following code will send a job at 3:00am in the US central time zone into the queue notification-abc.

await boss.schedule('notification-abc', `0 3 * * *`, null, { tz: 'America/Chicago' })

unschedule(name)

Removes all scheduled jobs for the specified queue name.

unschedule(name, key)

Removes a schedule by queue name and unique key.

getSchedules()

Returns all scheduled jobs.

getSchedules(name)

Returns all scheduled jobs by queue name.

getSchedules(name, key)

Returns all scheduled jobs by queue name and unique key.