> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/app-builder/build-backend/functions/utilities/cron.md). # Cron With cron, you schedule tasks that run automatically at specific times or intervals, defined in the standard cron expression format of the underlying `node-cron` library. This is useful for recurring jobs such as generating daily reports, performing nightly backups, or sending scheduled notifications. The code class name is `Cron`. This class requires an instance to schedule tasks, though it includes a static utility function for verification. ## Understanding cron expressions A cron expression is a string of five or six fields separated by spaces that represents 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) (0 is Sunday) │ │ │ │ │ * * * * * ``` ### Special characters * `*` represents "every" (such as every hour when used in the hour field). * `,` specifies a list of values (such as `1,15,30` to trigger at minutes 1, 15, and 30). * `-` defines a range of values (such as `9-17` to trigger every hour from 9 AM to 5 PM). * `/` specifies step values (such as `*/15` to trigger every 15 minutes). ## Static functions These functions are called directly on the class and do not require you to create an instance. ### `validate` Checks if a cron expression string is syntactically valid. #### Parameters
InputDescriptionType
expressionThe cron expression string to validate.string
#### Output Returns `true` if the expression is valid, or `false` if invalid. #### Example ```yaml # expression 0 9 * * 1-5 ``` ## Instance functions You must create an instance to use these functions. All functions except `create`, `delete`, and `schedule` require a previously scheduled task. ### `create` Creates a new, empty cron scheduler instance. The task itself is defined and started using the `schedule` function. #### Parameters None. #### Output Returns the name of the created instance. ### `delete` Deletes a cron instance. #### Parameters None. #### Output Returns `true` upon removal. {% hint style="danger" %} #### Irreversible action Deleting removes the instance configuration. {% endhint %} ### `schedule` Defines a task and schedules it to run based on a cron expression. The scheduler starts automatically when you call this function. #### Parameters
InputKeyDescriptionType
expressionA valid cron expression string.string
listenerThe callback function that executes each time the schedule triggers.callback
optionstimezoneThe timezone for the schedule (such as America/New_York or Europe/Berlin). If omitted, the system uses the server's local timezone.string
noOverlapPrevents the task from starting a new execution while the previous execution is still running. Default false.boolean
maxExecutionsLimits the total number of times the task runs before it is automatically destroyed.integer
#### Output Returns the string `scheduled`. #### Examples **Example 1: Run a task every 15 minutes** ```yaml # expression */15 * * * * # listener ``` **Example 2: Run a task at 9:00 AM and 5:00 PM every day** ```yaml # expression 0 9,17 * * * # listener ``` **Example 3: Run a cleanup job at 1:30 AM every Saturday and Sunday** ```yaml # expression 30 1 * * 6,0 # listener ``` ### `start` Starts the task scheduler. You only need to call this if you have previously stopped the scheduler using `stop`, since `schedule` starts the task automatically. This function does nothing if the scheduler is already running. #### Parameters None. #### Output Returns `true`. ### `stop` Stops the task scheduler. The scheduled task does not run again until you call `start`. #### Parameters None. #### Output Returns `true`. ### `execute` Manually executes the task's function immediately, outside of its regular schedule. This is useful for testing or triggering on-demand runs. #### Parameters None. #### Output Returns the return value of the task function. ### `getStatus` Retrieves the current lifecycle state of the task. #### Parameters None. #### Output Returns a string representing the current state: * `stopped`: The scheduler is not running. * `idle`: The scheduler is running, but the task is not executing. * `running`: The task is actively executing. * `destroyed`: The task is permanently removed. ### `getNextRun` Retrieves the next scheduled run time for the task. #### Parameters None. #### Output Returns a date object representing the next run time, or `null` if the task is stopped or destroyed. ### `destroy` Permanently deactivates the task and cleans up all internal resources. You cannot restart a destroyed task. {% hint style="danger" %} #### Irreversible action Destroying a task removes its configuration permanently. {% endhint %} #### Parameters None. #### Output Returns `true`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heisenware.com/app-builder/build-backend/functions/utilities/cron.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.