Scheduler

Configure BoxLang's built-in task scheduler

BoxLang includes a powerful built-in task scheduler that allows you to schedule and manage tasks at the runtime level. The scheduler is managed by the SchedulerService and can be configured globally or programmatically.

Configuration Structure

The scheduler configuration is located in the scheduler section of your boxlang.json file:

{
  "scheduler": {
    "executor": "scheduled-tasks",
    "cacheName": "default",
    "schedulers": [],
    "tasks": {},
    "tasksFile": "${boxlang-home}/config/tasks.json"
  }
}

Configuration Properties

executor

Type: string Default: "scheduled-tasks" Description: The name of the executor to use for running scheduled tasks. This must reference a valid executor defined in the executors section.

"executor": "scheduled-tasks"

cacheName

Type: string Default: "default" Description: The cache to leverage for server fixation or distribution. This is useful when running BoxLang in clustered environments to coordinate scheduled tasks across multiple instances.

"cacheName": "default"

schedulers

Type: array Default: [] Description: An array of absolute paths to BoxLang scheduler files (.bx) that should be registered upon runtime startup. You can use variable substitutions like ${user-dir} or ${boxlang-home}.

"schedulers": [
  "${user-dir}/schedulers/MainScheduler.bx",
  "/path/to/custom/MyScheduler.bx"
]

tasks

Type: object Default: {}

A map of scheduled tasks keyed by unique task name. Tasks defined here are registered on startup in addition to any tasks persisted by the bx:schedule component. In most cases you will not edit this block directly — instead, use bx:schedule (or cfschedule) to create and manage tasks at runtime; BoxLang writes the resulting task definitions to the file configured by tasksFile and reloads them automatically.

Each task entry supports the following properties:

Property	Type	Description
url	string	URL to GET on each execution
crontime	string	Cron expression (5-field Unix or 6-field Quartz)
interval	string	once, daily, weekly, monthly, or seconds ≥ 60
startDate	string	Date on which the task becomes active
endDate	string	Date on which the task is deactivated
exclude	string	Comma-separated dates or ranges to skip
group	string	Group label for organising tasks
eventHandler	string	Path to BoxLang file called on exception (when onException="invokeHandler")
file	string	Filename for published HTTP response output

tasksFile

Type: string Default: ${boxlang-home}/config/tasks.json

Path to the JSON file where the bx:schedule component persists task definitions. Tasks are written to this file on every create, update, or delete operation and reloaded from it on runtime startup.

"tasksFile": "${boxlang-home}/config/tasks.json"

Override this path when you want multiple BoxLang instances to share a common task store (for example, via a shared mounted volume in a cluster).

Programmatic Scheduling

You can create and manage scheduled tasks at runtime using:

• bx:schedule component — tag/script API for HTTP-driven tasks; changes persist automatically to tasksFile

• Scheduler DSL — fluent class-based API for running arbitrary BoxLang code on a schedule

The configuration above provides the foundation and default settings for the scheduler service.

Related Configuration

• Executors - Configure the thread pools used by the scheduler

• Caches - Configure caches used for task coordination

• Logging - Configure logging for scheduler operations