Frequencies
Frequencies are global (not workspace-scoped).
Task walkthrough: Define a frequency. This page is the full configuration and troubleshooting reference.
A frequency is a named scheduling rule (a pattern) that decides which calendar dates a job is eligible to run on. Jobs reference frequencies; the per-job runtime settings (build status, timing, retries) live with the job (see Scheduling and the run).
Pattern model
A pattern is defined by a time period and, for most, a type:
- Time period:
daily,weekly,monthly,yearly,onRequest,annualPlan. - Type:
byDate,byWeekday, orbyPeriod. Daily, On Request, and Annual Plan have no type — and On Request and Annual Plan have no interval either.
| Pattern | Key fields |
|---|---|
| Daily | interval (every N days), startDate |
| Weekly · byWeekday | interval, daysOfWeek (e.g. Mon/Wed/Fri) |
| Weekly · byPeriod | interval, anchor (start/end), offsetDays (0…30) |
| Monthly · byDate | interval, dayOfMonth (1–31, clamped to month length) |
| Monthly · byWeekday | interval, weekOrdinal (first…fifth/last), daysOfWeek — e.g. "second Tuesday" |
| Monthly · byPeriod | interval, anchor (start/middle/end), offsetDays (−30…30) — e.g. "last working day" |
| Yearly · byDate | interval, month (1–12), dayOfMonth, nonWorkingDayAction (required) |
| Yearly · byWeekday | interval, weekOrdinal, daysOfWeek |
| Yearly · byPeriod | interval, anchor (start/middle/end), offsetDays (−30…30) |
| On Request | (none) |
| Annual Plan | calendar (required), offsetDays (−30…30) |
On Request and Annual Plan
These two periods do not describe a recurrence. Each replaces the pattern with something simpler, and neither takes an interval, a day type, or a non-working-day action.
On Request
On Request takes no parameters at all. Its summary reads Runs on request.
Every day qualifies for it, but the build never picks it up. A job whose only frequency is On Request is excluded from every scheduled build; an operator adds it to an instance that already exists, using Add Job. That exclusion is deliberate, not a gap.
One consequence is worth planning around: because the build skips On Request work, a workflow whose only eligible work is On Request has nothing to build, and the build fails rather than creating an empty instance. Give the workflow at least one job on a scheduling frequency if you need an instance to exist for On Request jobs to be added into.
Annual Plan
Annual Plan takes a required calendar reference and an optional offset. The calendar's dates are the qualified days — there is no recurrence rule to evaluate. Its summary reads Annual plan: followed by the calendar's name.
Save is blocked until you pick a calendar, because a plan with no calendar has no dates.
An Annual Plan carries no day type and no non-working-day action — the pattern has no such field at all. A plan date that falls on a Saturday, a Sunday, or any other non-working day still runs. That is decided behavior, not an oversight: you put the date in the calendar, so the plan takes you at your word.
A workflow-level holiday calendar is the one exception, and it applies subtractively: a plan date that is also a holiday is omitted, not shifted to a nearby day.
Offset days shifts each run relative to its own plan date, counting working days —
negative for before, positive for after, up to 30 either way. It does not reindex the plan: with
an offset of 1, plan dates 5 January, 10 February and 15 March each run one working day after
their own date, not on the next plan entry. Because every offset step lands on a working day, an
offset result is never removed by the holiday subtraction above.
The plan's calendar reference is now stored by id as well as name, and it is what protects the schedule from ordinary maintenance:
- Renaming the calendar is safe. The id identifies it, and the name stored beside it is refreshed the next time the frequency is saved.
- Deleting it is refused. A calendar an Annual Plan is built on counts as in use, so the delete is blocked rather than quietly emptying the schedule. See Calendars.
- A reference that arrived from another environment heals. An imported frequency carries the source environment's calendar id, which means nothing here; saving repairs it from the name. Only a reference whose name is also gone is an error, and that error blocks the save rather than letting the frequency stand with no dates.
If the reference resolves to nothing — a calendar removed directly, or a plan that never had one — the pattern qualifies no dates and the job simply never builds. Nothing on the frequency itself says why. If an Annual Plan job goes quiet, check its calendar first.
Shared options
These apply to the four recurrence periods (daily, weekly, monthly, yearly). On Request takes none of them, and Annual Plan takes only its own offset.
| Option | Values | Notes |
|---|---|---|
dayType | working / any | Whether the pattern counts only working days. |
nonWorkingDayAction | skipToNext / skipToPrevious / keep / omit | What to do when a working-day match lands on a non-working day. Consulted only when dayType is working, and only on the selections listed below. |
exclusionCalendar | a Calendar reference | Dates to exclude (see Calendars). |
Working days and non-working days
What counts as a working day is the workflow's decision, not a fixed Monday-to-Friday. Each
workflow sets its own workingDays (see Scheduling and the run), so under a
Tuesday-to-Saturday week, Saturday is a working day and Monday is not. A working day is a day in
that set that is not on a holiday calendar the workflow applies.
dayType decides whether the pattern cares:
dayType | What it means |
|---|---|
any | The configured calendar date, full stop. It runs there whether or not that day is a working day, and nonWorkingDayAction is never consulted. |
working | The pattern counts working days, and the emitted date is always a working day. |
When a working-day match lands on a non-working day
nonWorkingDayAction decides, and the default is to move back to the previous working day:
| Action | Result |
|---|---|
| (not set) | Move to the previous working day — the run is preserved rather than lost. This is the default. |
skipToPrevious | The same, said explicitly. |
skipToNext | Move to the next working day. |
keep | Run on the original date even though it is non-working. |
omit | Drop this occurrence — the run does not happen. |
A working pattern with no action configured used to silently produce no run for that
occurrence: the date failed the working-day filter and disappeared. It now shifts back. If you were
relying on that silence to suppress a run, say so explicitly with omit — otherwise the run you
never saw will now appear on the previous working day.
Where the action is offered
If date is non-working day appears only on the selections where the action can actually change the date:
| Selection | Action offered | Why |
|---|---|---|
Daily, dayType: working | Yes | A daily match can land on a non-working day. |
Any byWeekday selection (weekly, monthly, yearly), dayType: working | Yes | "Second Tuesday" can land on a holiday. |
| Yearly · byDate | Yes — and it is required, so the pattern always names one | A fixed date such as 31 December can fall on a weekend. |
| Monthly · byDate | No | A working pattern counts working days, so the date it produces already is one; an any pattern never consults the action. |
| Any byPeriod selection | No | The anchor resolves to a working day, and each offset step lands on one, so there is nothing to shift. |
| On Request, Annual Plan | No | The pattern has no such field. |
Any selection with dayType: any | No | The action is never consulted. |
There is no "None" choice. A working pattern always has an action: the field shows
skipToPrevious when the pattern names none, because that is what the build will do, and the
editor records it explicitly when you switch the day type to Working Day. Switching back to
Any clears it.
- Setting the action on a monthly Day N / Working Day pattern was offered and then rejected on save with Validation failed. The control is no longer offered there, and a stale value carried over from an older pattern is dropped when you switch the day type, so the save goes through.
- The action was offered on the byPeriod selections, where it was accepted and then never applied — a setting that silently did nothing. It is no longer offered there.
- The list's None choice read as "do nothing" and behaved as "move to the previous working day". A pattern saved with None has not changed behavior; it now displays what it does.
The search for a working day is bounded at 30 days in either direction. A pattern whose match cannot reach a working day within 30 days keeps the original date rather than searching forever.
A period that contains no working day at all produces no occurrence — "the fifth working day of this month" simply does not exist in a month with four, and nothing is substituted for it.
Offsets
The byPeriod selections anchor to a period boundary — start, end, and for monthly and yearly
also middle — and offsetDays steps away from that anchor.
Offsets count working days, not calendar days. Each step lands on a working day, so the result is always a working day too. Two things follow:
- A non-working-day action can never fire on an offset result. There is nothing for it to rescue.
- A day is skipped only if it is non-working for that workflow. Saturday is not inherently skipped: under a Tuesday-to-Saturday week the step counts it.
| Selection | Offset range |
|---|---|
| Weekly · byPeriod | 0 … 30 — forward only |
| Monthly · byPeriod | −30 … 30 |
| Yearly · byPeriod | −30 … 30 |
| Annual Plan | −30 … 30 |
Because the offset traverses working days, the offset control appears only when dayType is
working. On an any-day pattern there is no working-day sequence to step along and the engine
ignores the value, so offering the field would let you configure something that silently does
nothing. Switching the day type back to Any clears the offset.
Weekly · byPeriod now has an Offset days field. Earlier builds applied a weekly offset if one was
stored but gave you nowhere to enter it, so the capability was reachable only through the API. Unlike
monthly and yearly, weekly takes no negative offset — the field is clamped to 0–30 and the
editor says so, because it is the one selection whose range is one-sided.
For a working pattern the anchors are working days too: start is the period's first working
day, end its last, and middle its middle working day — not the middle calendar day
nudged onto a working one.
A calendar-day offset landed wherever it landed, and if that was a Saturday the working-day filter dropped the occurrence — so in a month whose first working day was a Thursday, the job silently never ran. Counting working days is what makes the pattern mean what it reads like.
Working with the frequency list
The Frequencies tab of the Toolkit is a single list, and a frequency is created, edited and viewed in one dialog over it. There is no frequency detail page.
| Column | Notes |
|---|---|
| Name | The list's search box sits on this column. |
| Description | — |
| Type | The recurrence period — daily, weekly, monthly, yearly, On Request or Annual Plan. Sorts. |
| Interval | The repeat, read in the units the type implies (every 2 weeks, and so on). Blank for a type that has no interval. |
| Created / Updated | Sort. |
The dialog puts the form on the left — Name, Description and the Recurrence Pattern — and the forecast alongside it. Save turns on only once you have changed something and the pattern is complete, and closing with unsaved edits asks first. Delete sits in the dialog's own footer, so you can reach it from a link straight to the frequency without finding its row.
Every editor action keeps the list's search, sort and page, so closing the dialog puts you back where you were.
What refers to a frequency
The frequency list's Cross Reference action shows both places a frequency can be used:
| Section | What it lists |
|---|---|
| Workflows | Workflows whose schedule carries this frequency, outside any job. |
| Jobs | Jobs whose own frequency list names it, shown as workflow: job. |
Earlier builds listed only the jobs, so a frequency used at the workflow level looked unused. When there are more references than the dialog was given it says Showing N of M references rather than presenting a first page as the whole set.
Forecast
The frequency dialog shows the forecast beside the pattern you are editing: twelve month grids for one year, with the dates the pattern matches highlighted, and arrows to step a year at a time. It recalculates as you change the pattern, so you can see its shape as you edit. It is a simplified preview, not the build — see The dialog's forecast is a quick preview. The forecast is read-only — selecting a day does nothing.
This one answers which dates does this pattern match? — one frequency, many dates. The workflow editor's Forecast view answers the other direction: on one date, which jobs would build, and when would each start? The Forecast view uses the same calculation as the build, with the workflow's working days and calendars applied; this one does not. Use this to see a pattern's shape, and the Forecast view to confirm what a workflow will build.
Earlier builds put it on a separate frequency detail page, which no longer exists; see Working with the frequency list.
The dialog's forecast is a quick preview, not the build
The forecast in the Frequencies dialog is calculated in your browser by a simpler calculation of its own. It is not the calculation the build uses, and it can highlight dates the build will not run on, or miss dates it will. It differs from the build in these ways:
| The dialog's forecast | The build |
|---|---|
| Treats Monday to Friday as the working days. A frequency belongs to no workflow, so there is no workflow week to use. | Uses the workflow's own workingDays. |
| Ignores the pattern's exclusion calendar and any holiday calendar. | Applies both. |
Applies no non-working-day action. A working match that lands on a weekend is dropped rather than moved, and a Yearly · byDate date is shown even when it falls on a weekend. | Applies the action — moving the run to the previous working day by default. |
| Counts offsets in calendar days, and reads the middle anchor as the middle calendar day. | Counts offsets in working days, and uses the middle working day. |
| Shows an Annual Plan calendar's dates exactly as stored — without the pattern's offset, and with no holidays removed. | Shifts each plan date by the offset and omits plan dates that are holidays. |
So the dialog is a fast way to see the shape of a pattern as you edit it. To see what will actually build — calendars, working days and all — use the workflow editor's Forecast view, which asks the same calculation the build uses.
Two periods read differently in the dialog's forecast:
- On Request highlights every day, because every day qualifies for the pattern. It is not telling you the job runs daily — the build never selects an On Request frequency at all.
- Annual Plan highlights the referenced calendar's dates for the selected year. An empty forecast for an Annual Plan means the calendar has no dates that year, or that the reference no longer resolves.
Limits on a forecast
These limits belong to the forecast calculation the build and the workflow editor's Forecast view use, and they bound each request so a single pattern cannot monopolise it. (The Frequencies dialog's own preview runs in your browser and sends no request.)
| Limit | Value |
|---|---|
| Date range | The end date at most 366 days after the start date |
| Calendar year of any date asked about | 1900–2999 |
offsetDays, any pattern | ±30 |
| Days named by a weekly, monthly or yearly by-weekday pattern | at most the seven day names, each named once |
| Working days on a schedule | at most the seven day names |
| Annual Plan dates supplied directly in a request | 1,000 |
| Holiday dates supplied directly in a request | 1,000 |
The two 1,000-date caps apply only to dates written into a request itself. A calendar the platform looks up for you — every calendar a workflow or frequency names, which is how the build works — is not capped, and neither are exclusion dates.
A request beyond these is refused with an error rather than calculated slowly. The same ±30 offset bound is enforced when you save the frequency, so a pattern that forecasts will also save.
The year window is shared with the build, so a workflow cannot be built for a schedule date
outside 1900–2999 either — the date is refused where you enter it rather than failing later in the
build. Dates are held as YYYY-MM-DD throughout, and a four-digit year is what makes them sort and
step correctly; the window is where that holds.
A by-weekday pattern that names the same day twice is refused rather than quietly deduplicated, and so is one naming something that is not a day of the week. Both were previously accepted without comment, which meant a typo'd day name simply had no effect on the dates instead of being reported.
- A frequency is the pattern; when within the day and retry/rerun behavior are the job's per-frequency runtime settings, not the frequency itself.
- The Frequencies dialog's forecast does not apply calendars, a workflow's working days, or the non-working-day action, so it can disagree with the build. The workflow editor's Forecast view applies all three — check a workflow there before relying on a date. See The dialog's forecast is a quick preview.
- In the build, a daily every-N-days pattern no longer repeats a date across a daylight-saving change. The cadence is recomputed from each date rather than advanced by a fixed number of hours, so the 23-hour day that used to emit the same date twice no longer can.
- New frequencies default to a daily, interval 1, any-day pattern, with a start date of 1 January of the current year rather than today. That fixed anchor is what makes an every N days pattern land on predictable dates — with a start date of "today" the same interval produced a different set of dates depending on when you created it — and it means the forecast for a new pattern covers the whole year rather than only the part of it still to come.