Calendars
- Synopsis
- Full Details
In briefA calendar is a named list of dates, shared across workspaces. A frequency uses one to exclude dates, an Annual Plan frequency uses one as the dates it runs on, and a workflow uses one as its Additional Holiday Calendar. The Master Holiday Calendar is the one holiday list your whole organization shares, applied to every workflow that has Use Master Holiday Calendar on.
WhereDesign › Toolkit › the Calendars tab. New Calendar opens the editor; a row's menu has Edit (or View), Cross Reference and Delete. The Master Holiday Calendar button is at the right of the same toolbar. A workflow picks its calendars in the workflow editor's Workflow Settings panel, as Additional Holidays and Use Master Holiday Calendar.
When
- You need a set of holidays or blackout days that one or more workflows or frequencies should skip.
- You want a job to run on a fixed, hand-picked list of dates, through an Annual Plan frequency.
- You keep the organization's bank holidays once, for every workflow, in the Master Holiday Calendar — and, through an Annual Plan, run a job on those holidays.
To change which days of the week count as working days, use the workflow's Working Days instead; see Scheduling and the run.
How
- Open the Calendars tab of the Toolkit and select New Calendar.
- Give it a name, pick dates from the grid or Upload JSON, and save.
- Name it on a frequency or a workflow, then check the dates it removes in the workflow editor's Forecast view.
The full steps are on Manage properties, calendars, and tags.
- A calendar needs a name of 3–255 characters and at least one date. The Master Holiday Calendar may be empty and holds up to 3,660 dates.
- Upload JSON takes a bare array of
YYYY-MM-DDstrings or an object with adatesarray. iCal files are not accepted. - A change to a calendar applies to the next forecast or build. A run already built keeps the dates it was built with.
- A calendar in use cannot be deleted. Delete lists the workflows and frequencies that refer to it; change those first.
- If a holiday or exclusion calendar cannot be resolved, the build fails rather than running with it left out.
- The preview in the Frequencies dialog applies a frequency's exclusion calendar, an Annual Plan's calendar and, when its Use Master Holiday Calendar switch is on, the Master Holiday Calendar, but never a workflow's Additional Holiday Calendar. Check a workflow's holiday effects in the workflow editor's Forecast view.
Calendars are global (not workspace-scoped).
Task walkthrough: Manage properties, calendars, and tags. This page is the full configuration and troubleshooting reference.
A calendar is a named set of dates — typically holidays or blackout days. Calendars are used to exclude days from scheduling.
- Calendar List
- Calendar Editor
- Master Holiday Calendar
- Where Calendars Are Used
- Renaming and Deleting
Calendar List
Working with the calendar list
The Calendars tab of the Toolkit is a single list, and a calendar is created, edited and viewed in one dialog over it. There is no separate detail page to open — the pattern every Toolkit type now follows.
| Where | What it does |
|---|---|
| New Calendar | Opens the editor for a new calendar. |
| Master Holiday Calendar | At the right of the toolbar. Opens the one holiday calendar your whole organization shares — see The Master Holiday Calendar. |
| Row menu → Edit | Opens the same editor on that calendar. Reads View instead when you don't have permission to change calendars; the editor still opens, but Save is unavailable. |
| Row menu → Cross Reference | Shows what refers to this calendar — see What refers to a calendar. |
| Row menu → Delete | Deletes the calendar, once it has checked that nothing refers to it — see Renaming and deleting. |
| Double-clicking a row | The same as Edit. |
The list opens in name order. Filter it by typing in the Name column's search box, and sort it by Date Count, Created or Updated. Date count is the number of dates the calendar holds, which is the quickest way to spot a calendar that was never filled in.
Calendar Editor
Fields
| Field | Notes |
|---|---|
| Name | Unique calendar name. 3–255 characters, following the platform naming rules. |
| Description | Optional. |
| Dates | The dates you pick on the calendar grid, listed beside it. At least one date is required, and each date appears once. Save stays unavailable until the calendar has a name and a date. |
The calendar editor
Name, description and dates are all edited in one dialog.
- Pick dates from the calendar grid. It is a scrollable, multi-month picker that opens on January of the current year, with arrows to move a year at a time. Selecting a day adds it; selecting it again removes it.
- The selected dates are listed alongside, with a running count. Remove one from its own row, or tick several and delete them together.
- Upload dates from a file with Upload JSON. The file is read in your browser and merged into
the dates you already have — nothing is saved until you save the calendar. The file is either a
bare array of
YYYY-MM-DDstrings, or an object with adatesarray of them. iCal (.ics) files are not accepted.
After an upload you're told how many dates were added and, when there were any, how many entries
were skipped because they were not valid YYYY-MM-DD dates.
When you open an existing calendar the form appears only once its dates have loaded, so a save can never replace a stored date set with an empty one. If loading fails you get an error instead of an editable form.
If a save is refused — a name another calendar already uses, or a date that is not valid — the reason appears in the dialog, under the dates, and the dialog stays open with your edits so you can correct them and save again.
Master Holiday Calendar
The Master Holiday Calendar
The Master Holiday Calendar is the one holiday calendar your organization keeps for every workflow — the bank holidays your core is closed on, entered once rather than copied into each workflow. There is exactly one. It is not in the calendar list: open it with the Master Holiday Calendar button at the right of the Calendars toolbar. The dialog has its own address, so you can share a link to it.
It applies across every environment, to every workflow whose schedule has Use Master Holiday Calendar on (see Scheduling and the run). An Annual Plan frequency can also take it as its plan: choose Master Holiday Calendar (system) as the frequency's Plan calendar, and the job runs on its dates. See Annual Plan.
| Rule | Master Holiday Calendar |
|---|---|
| Dates | Picked, listed and uploaded exactly as in the calendar editor. There is no name, no description, and no delete. |
| Empty | Allowed. A Master Holiday Calendar nobody has filled in contributes no dates, and saving it with every date removed clears it. |
| Duplicates | Dropped. The same date twice is kept once. |
| Size | Up to 3,660 dates. |
| Who can open it | Anyone with permission to view calendars. |
| Who can change it | Anyone with permission to change calendars. Without it the dialog is read-only: Save is unavailable and the button reads Close. |
A change takes effect at the next forecast or build. Nothing is held over from an earlier read, so the next Forecast view you open and the next build — started by hand or by the automatic daily build — use the dates as saved. A run that is already built keeps the dates it was built with.
Two people editing at once cannot overwrite each other. If someone else saved the Master Holiday Calendar after you opened it, your save is refused with The Master Holiday Calendar was changed by someone else. Reload to see their changes. Your edits stay on screen until you choose Reload, which replaces them with the saved dates — so note anything you want to keep first.
Closing the dialog with unsaved changes asks whether to discard them.
Where Calendars Are Used
How calendars are used
- As an exclusion calendar on a frequency — matched dates that fall on a calendar date are excluded.
- As an Annual Plan frequency's own calendar, where its dates are the days the job runs on.
- As an additional holiday calendar on a workflow's schedule (see Scheduling and the run).
- The Master Holiday Calendar, on every workflow whose schedule uses it. When a workflow uses both, the dates of the two are combined. An Annual Plan frequency can also run on its dates, as Master Holiday Calendar (system).
What refers to a calendar
Nothing that references a calendar is a job. A calendar is set on a workflow's schedule, or named by a frequency's pattern — so Cross Reference shows two sections, and neither is the Jobs list you see for a tag or a threshold:
| Section | What it lists |
|---|---|
| Workflows | Workflows whose schedule sets this calendar as its Additional Holiday Calendar (the Additional Holidays field). |
| Frequencies | Frequencies whose pattern names it — as an exclusion calendar, or as an Annual Plan's own calendar. |
When there are more references than the dialog shows, it says Showing N of M references rather than presenting part of the list as the whole set.
Renaming and Deleting
Renaming and deleting
A reference is stored as an id plus a name, and the id is what identifies the calendar. So:
- Renaming a calendar does not break anything that uses it. A workflow's Additional Holidays field and a frequency's calendar fields show the new name as soon as you open them, and exports carry it. The name stored beside the id is refreshed the next time the referring workflow or frequency is saved; an earlier version keeps the old name.
- A calendar that is in use cannot be deleted. Selecting Delete checks the references first: if it finds any, the confirmation lists what refers to the calendar and the delete cannot go ahead, rather than being attempted and refused. References are counted the same way the save path resolves them. If the check itself fails you are told so, and the delete is unavailable until it succeeds — a failed lookup is never read as "nothing refers to it".
- A reference whose stored id names no calendar in your tenant falls back to its name — an id carried in from another environment, for instance — and that fallback is counted too.
- A reference to a deleted calendar is never moved to a new calendar of the same name. Deleting a calendar and creating another under its name does not hand the old one's references to the new one, and those references do not count against it when you delete it.
An additional holiday calendar and a frequency's exclusion calendar are optional settings, so a workflow or frequency whose stored reference no longer resolves — including one to a deleted calendar — still saves normally; the reference is left as stored. An Annual Plan is different — the calendar is the schedule, so there the reference must resolve: a save whose Annual Plan calendar has been deleted is refused with Calendar 'X' is deleted. Restore it or use a different calendar., and the build takes no dates from a calendar that has since taken its name. See Renaming or replacing an object a workflow uses.
- Calendars are shared across workspaces.
- To see calendars applied before a run, use the workflow editor's Forecast view: the exclusion calendars on its frequencies and the workflow's holiday calendars — its Additional Holiday Calendar and, when it uses it, the Master Holiday Calendar — are resolved before the dates are calculated, the same as in the build. The preview in the Frequencies dialog applies the frequency's own exclusion calendar and an Annual Plan's calendar, plus the Working Days and Use Master Holiday Calendar setting shown above the preview (on by default, and remembered in your browser). It applies no Additional Holiday Calendar, because a frequency belongs to no workflow — see Frequencies.
- An Additional Holiday Calendar on a workflow now takes effect at all. Earlier builds stored the setting and never applied it — to the Forecast view or to the real build. If you set one before and concluded it did nothing, it works now, so re-check the dates it removes.
- A holiday calendar date — from the Additional Holiday Calendar or the Master Holiday Calendar — is what makes a day non-working for a workflow that applies it, which is what the working-day rules in Frequencies count. An exclusion calendar date is different: it removes the occurrence outright, with no move to another day.
- A cleared description is saved as cleared — emptying the field removes the text rather than leaving the old value in place.