Cron

This class will be available from release v89 - Look & Feel on

The Cron class provides a powerful and convenient way to schedule tasks that run automatically at specific times or intervals. It is a wrapper around the popular node-cron library, allowing you to define schedules using the standard cron expression format.

This is useful for automating recurring jobs, such as generating daily reports, performing nightly backups, or sending out scheduled notifications.

Understanding Cron Expressions

A cron expression is a string that consists of five or six fields separated by spaces, representing a time schedule. Each field specifies a different unit of time.

┌─────────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌─────────── day of month (1 - 31)
│ │ │ ┌───────── month (1 - 12)
│ │ │ │ ┌─────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Special Characters:

• *: Asterisk. Represents "every". For example, * in the hour field means "every hour".

• ,: Comma. Specifies a list of values. For example, 1,15,30 in the minute field means "at minutes 1, 15, and 30".

• -: Hyphen. Defines a range of values. For example, 9-17 in the hour field means "every hour from 9 AM to 5 PM".

• /: Slash. Specifies step values. For example, */15 in the minute field means "every 15 minutes".

Static Functions

These functions are called directly on the Cron class and do not require you to create an instance.

validate

Checks if a cron expression string is syntactically valid.

Parameters

• expression: The cron expression to validate.

Example

# expression
'0 9 * * 1-5'

Output

Returns true if the expression is valid, false otherwise.

Instance Functions

You must create an instance of the Cron class to use these functions.

create

Creates a new, empty cron scheduler instance. The task itself is defined and started using the schedule method.

schedule

Defines a task and schedules it to run based on a cron expression. The scheduler starts automatically when this function is called.

Parameters

• expression: A string containing a valid cron expression.

• listener: The function that will be executed each time the schedule is triggered.

• options: An optional object for advanced control.

  • timezone: A string specifying the timezone for the schedule (e.g., "America/New_York", "Europe/Berlin"). If not set, it uses the server's local timezone.

  • noOverlap: A boolean. If true, it prevents the task from starting a new execution if the previous one is still running.

  • maxExecutions: An integer that limits the total number of times the task will run before it is automatically destroyed.

Example 1: Run a task every 15 minutes

# expression
*/15 * * * *
# listener
<callback>

Example 2: Run a task at 9:00 AM and 5:00 PM every day

# expression
0 9,17 * * *
# listener
<callback>

Example 3: Run a cleanup job at 1:30 AM every Saturday and Sunday

# expression
30 1 * * 6,0
# listener
<callback>

Output

Returns the string 'scheduled'.

start

Starts the task scheduler. Note: You only need to call this if you have previously called stop(). The schedule method starts the task automatically.

stop

Stops the task scheduler. The scheduled task will not run again until start() is called.

getStatus

Provides the current lifecycle state of the task. This is useful for monitoring.

Output

A string representing the current state, such as stopped, idle (running but not executing), or running (actively executing).

destroy

Permanently deactivates the task and cleans up all internal resources. A destroyed task cannot be restarted.

execute

Manually executes the task's function immediately, outside of its regular schedule. This is useful for testing or for triggering on-demand runs.

getNextRun

Returns the date and time of the next scheduled execution.

Output

A JavaScript Date object representing the next run time, or null if the task is stopped or destroyed.