Cron expressions repeat on fixed cycles, but many tasks need to run only on specific dates -- business days, days that exclude public holidays, or dates tied to irregular events. Calendars solve this by storing a set of active dates. After you associate a calendar with a scheduled task, the task runs only on the dates the calendar defines.
Use cases
Run tasks on business days only. Exclude weekends and public holidays so that reports, data syncs, or batch jobs run only when your team is working.
Skip maintenance windows. Prevent jobs from running during planned downtime or change-freeze periods.
Schedule around irregular events. Define a custom set of dates for tasks tied to seasonal campaigns, fiscal quarter ends, or other non-recurring schedules.
Prerequisites
Before you begin, ensure that you have:
An MSE XXL-JOB instance
Access to the MSE XXL-JOB console
Create a calendar
Log on to the MSE XXL-JOB console, and select a region in the top navigation bar.
In the left navigation bar, select .
Click the target instance.
In the navigation pane on the left, choose Calendars.
Click Create calendar.
Configure the following parameters, then save the calendar.
Parameters
| Parameter | Description | Example |
|---|---|---|
| Calendar name | A descriptive name for the calendar. Use a name that reflects its purpose, such as the year and schedule type. | Workdays |
| Year | The year the calendar covers. Create a separate entry for each year. | 2026 |
| Month | A JSON array that defines which days are active in each month. See Month JSON format. | See below |
Month JSON format
The Month field accepts a JSON array of objects. Each object represents one month and lists the days on which tasks are allowed to run.
Structure:
[
{ "month": <month-number>, "days": [<day>, <day>, ...] },
{ "month": <month-number>, "days": [<day>, <day>, ...] }
]| Field | Type | Description |
|---|---|---|
month | Integer (1--12) | The month of the year |
days | Array of integers | The active days of the month on which tasks run |
Example -- Business days for January and February 2026:
[
{
"month": 1,
"days": [1, 2, 5, 6, 7, 8, 9, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 26, 27, 28, 29, 30]
},
{
"month": 2,
"days": [2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 16, 17, 18, 19, 20, 23, 24, 25, 26, 27]
}
]Provide all 12 months in a single array to cover the full year.
Full-year business days template (click to expand)
The following template covers standard Monday-through-Friday business days for 2026. Adjust the days arrays to match your organization's holiday schedule.
[
{"month":1,"days":[1,2,5,6,7,8,9,12,13,14,15,16,19,20,21,22,23,26,27,28,29,30]},
{"month":2,"days":[2,3,4,5,6,9,10,11,12,13,16,17,18,19,20,23,24,25,26,27]},
{"month":3,"days":[2,3,4,5,6,9,10,11,12,13,16,17,18,19,20,23,24,25,26,27,30,31]},
{"month":4,"days":[1,2,3,6,7,8,9,10,13,14,15,16,17,20,21,22,23,24,27,28,29,30]},
{"month":5,"days":[1,4,5,6,7,8,11,12,13,14,15,18,19,20,21,22,25,26,27,28,29]},
{"month":6,"days":[1,2,3,4,5,8,9,10,11,12,15,16,17,18,19,22,23,24,25,26,29,30]},
{"month":7,"days":[1,2,3,6,7,8,9,10,13,14,15,16,17,20,21,22,23,24,27,28,29,30,31]},
{"month":8,"days":[3,4,5,6,7,10,11,12,13,14,17,18,19,20,21,24,25,26,27,28,31]},
{"month":9,"days":[1,2,3,4,7,8,9,10,11,14,15,16,17,18,21,22,23,24,25,28,29,30]},
{"month":10,"days":[1,2,5,6,7,8,9,12,13,14,15,16,19,20,21,22,23,26,27,28,29,30]},
{"month":11,"days":[2,3,4,5,6,9,10,11,12,13,16,17,18,19,20,23,24,25,26,27,30]},
{"month":12,"days":[1,2,3,4,7,8,9,10,11,14,15,16,17,18,21,22,23,24,25,28,29,30,31]}
]Verify the calendar
After you save the calendar, it appears in the Calendars list. Confirm that the calendar name, year, and active dates are correct before associating the calendar with a scheduled task.
Associate the calendar with a task
After creating a calendar, associate it with one or more scheduled tasks. When you create or edit a task, select the calendar to restrict execution to the dates defined in the calendar. Tasks run only on the active dates.