Ana içeriğe geç
Bu sayfa henüz Türkçeye çevrilmedi; İngilizce sürümü gösteriliyor.
Versiyon: 1.0.1

Exclusion Calendars

An exclusion calendar is a named list of days on which jobs should not run: public holidays, maintenance days, a company shutdown, weekends. You create a calendar once and reference it from as many jobs as you like.

What a calendar holds​

A calendar can combine three kinds of rule. A day is excluded when any of them matches.

RuleExample
Single dates2027-01-01, 2027-04-23
Date ranges, both ends inclusive, with an optional label2027-12-24 to 2027-12-31, "Year-end shutdown"
Days of the weekSaturday and Sunday

Dates are plain calendar dates without a time or a zone. Each job compares them with the local date of its run in its own time zone, so a single "Public holidays" calendar works for jobs in Istanbul and in New York alike.

What happens on an excluded day​

When a job's run falls on an excluded day:

  1. The run is not sent to a worker.
  2. An occurrence is recorded with the status Skipped, not Failed. Its result and its log say which calendar excluded which date.
  3. The job continues at its first run on a day that is not excluded. A job that runs every 5 minutes on a calendar that excludes weekends records one skipped occurrence for the weekend, not one per run.

A one-time job whose time falls on an excluded day is skipped and recorded the same way, and does not run later.

Upcoming Executions leaves excluded days out: if a job's next run falls on one, the list shows the first run after it, marked "after excluded day".

Calendars are read on every dispatcher cycle, so changes to a calendar apply from the next run on.

Managing calendars​

Dashboard​

Open Calendars in the sidebar. From there you can create, edit and delete calendars. The edit dialog lists the jobs that use the calendar.

To use a calendar, open a job's edit form and tick it under Exclusion Calendars in the settings panel.

A calendar that is still used by a job cannot be deleted. Remove it from those jobs first. This keeps a job from silently starting to run on days someone chose to exclude.

API​

MethodEndpointPermission
PATCH/api/v1/exclusionCalendars (list; supports searchTerm and paging)ExclusionCalendarManagement.List
GET/api/v1/exclusionCalendars/calendar?calendarId={id}ExclusionCalendarManagement.Detail
POST/api/v1/exclusionCalendars/calendarExclusionCalendarManagement.Create
PUT/api/v1/exclusionCalendars/calendarExclusionCalendarManagement.Update
DELETE/api/v1/exclusionCalendars/calendar?calendarId={id}ExclusionCalendarManagement.Delete

Create a calendar:

POST /api/v1/exclusionCalendars/calendar
{
"name": "Public holidays 2027",
"description": "National holidays",
"dates": ["2027-01-01", "2027-04-23", "2027-05-01"],
"dateRanges": [{ "start": "2027-12-24", "end": "2027-12-26", "label": "Christmas" }],
"weekdays": []
}

weekdays uses 0 for Sunday through 6 for Saturday. PUT replaces the whole calendar, so send every field, including id.

Reference calendars from a job with exclusionCalendarIds:

POST /api/v1/jobs/job
{
"displayName": "Daily settlement",
"selectedJobName": "SettlementJob",
"cronExpression": "0 0 18 * * *",
"timeZoneId": "Europe/Istanbul",
"exclusionCalendarIds": ["01a1d700-548a-7fd1-9f68-b01b6027b982"]
}

On PUT /api/v1/jobs/job, exclusionCalendarIds replaces the job's whole list.

MCP​

The MCP server has list_exclusion_calendars, get_exclusion_calendar, create_exclusion_calendar, update_exclusion_calendar and delete_exclusion_calendar, and create_job and update_job accept exclusionCalendarIds.

Permissions​

The five ExclusionCalendarManagement permissions are added to the permission list automatically when the API starts. Grant them to roles the same way as any other permission. A user who can edit jobs but cannot list calendars sees no calendars on the job form.

Limits​

  • A calendar can hold up to 1,000 single dates and 1,000 ranges.
  • A range can span at most 3,660 days.
  • A job can reference up to 20 calendars.