Import a custom calendar for scheduled tasks

Standard cron expressions cannot account for business-specific schedules. For example, 0 0 * * 1-5 runs a task every weekday but cannot skip public holidays or include makeup workdays. Use a custom calendar to define exact execution dates for workday schedules, financial trading days, or promotional blackout periods.

Prerequisites

Before you begin, make sure that you have:

An XXL-JOB instance
An application

Import a custom calendar

Import a calendar by calling the ImportCalendar API through the OpenAPI Portal.

Open the ImportCalendar page in the OpenAPI Portal.
Set Region to the region of your XXL-JOB instance.

Configure the following parameters:

Parameter	Description	Example
`ClusterId`	The ID of your XXL-JOB cluster instance	`xxljob-b6ec1xxxx`
`Name`	A descriptive calendar name, such as `workday` or `trading-day`	`workday`
`Year`	The calendar year	`2025`
`Months`	A JSON array that defines execution dates for each month. See Months parameter format.	See below

Click Initiate Call.

Months parameter format

The Months parameter is a JSON array of objects, one per month. Each object contains:

month: The month number (1--12).
days: An array of day numbers on which the task runs.

Example: Full-year workday calendar (2025, excluding weekends and Chinese public holidays):

[
  {"month": 1, "days": [3, 4, 5, 6, 9, 10, 11, 12, 13, 16, 17, 18, 19, 20, 28, 29, 30, 31]},
  {"month": 2, "days": [1, 2, 3, 6, 7, 8, 9, 10, 13, 14, 15, 16, 17, 20, 21, 22, 23, 24, 27, 28]},
  {"month": 3, "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": 4, "days": [3, 4, 6, 7, 10, 11, 12, 13, 14, 17, 18, 19, 20, 21, 23, 24, 25, 26, 27, 28]},
  {"month": 5, "days": [4, 5, 6, 8, 9, 10, 11, 12, 15, 16, 17, 18, 19, 22, 23, 24, 25, 26, 29, 30, 31]},
  {"month": 6, "days": [1, 2, 5, 6, 7, 8, 9, 12, 13, 14, 15, 16, 19, 20, 21, 25, 26, 27, 28, 29, 30]},
  {"month": 7, "days": [3, 4, 5, 6, 7, 10, 11, 12, 13, 14, 17, 18, 19, 20, 21, 24, 25, 26, 27, 28, 31]},
  {"month": 8, "days": [1, 2, 3, 4, 7, 8, 9, 10, 11, 14, 15, 16, 17, 18, 21, 22, 23, 24, 25, 28, 29, 30, 31]},
  {"month": 9, "days": [1, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 25, 26, 27, 28]},
  {"month": 10, "days": [7, 8, 9, 10, 11, 12, 13, 16, 17, 18, 19, 20, 23, 24, 25, 26, 27, 30, 31]},
  {"month": 11, "days": [1, 2, 3, 6, 7, 8, 9, 10, 13, 14, 15, 16, 17, 20, 21, 22, 23, 24, 27, 28, 29, 30]},
  {"month": 12, "days": [1, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 25, 26, 27, 28, 29]}
]

Create a calendar-based scheduled task

After importing the calendar, associate it with a scheduled task in the Microservices Engine (MSE) console.

Log on to the MSE XXL-JOB console and select the region of your instance in the top navigation bar.
In the left-side navigation pane, choose Task Scheduling > XXL-JOB Edition.
Click the instance ID to open the instance details page.
In the left-side navigation pane, click Task Management, and then click Create Task.
Configure the basic settings. In the Timing Configuration section, set Time Type to cron.
In the advanced configuration section, select Specify Calendar and choose the calendar you imported.
Click Next, configure the notification settings, and then click Complete.

The task now runs only on the dates defined in your custom calendar.

Update a calendar

To update the dates in an existing calendar, repeat the Import a custom calendar procedure and import a new calendar with the same name. The new calendar overwrites the previous one automatically.