Skip to main content

Schedules & the Calendar

The Schedules page (On-Call → Configure → Schedules) is where you see and shape who is on call, when. Opening a schedule shows an interactive swimlane calendar — a Grafana OnCall-style layered timeline — as the primary surface. The calendar is the read view for coverage and the place you manage overrides directly, by dragging. Recurring rotation rules stay in a demoted Advanced section below the calendar.

For who a schedule pages and how it interacts with escalation and cutover, see On-call & Escalation Management. For who may see and edit a schedule, see Access & Roles.

The calendar at a glance​

The calendar draws time left-to-right across the window you're viewing, with one row (lane) per kind of coverage, stacked top-to-bottom:

  • Overrides — the interactive lane. Each override is a colored block badged override; you create, move, resize, and delete overrides here (see Managing overrides).
  • One lane per rotation — each rotation gets its own lane, labelled with the rotation name and a layer badge (L0, L1, …). These show each rotation's own bands in isolation, so you can see how the layers stack before they're resolved.
  • Final — below a divider, the resolved lane: the single winning person at every moment, after layering and overrides are applied. This is what actually pages. Stretches of the Final lane where nobody is on call are drawn as a hatched warning band — a coverage gap.
  • Now-line — a thin vertical rule marks the current instant whenever it falls inside the window.

Every band shows the covering user's name, tinted with a deterministic per-user color (the same person is always the same color across the calendar). Hovering — or focusing — a band reveals a card with the user, whether it's a rotation or override shift, and the exact start–end in the displayed time zone.

The calendar never does the time math itself

Shift geometry — rotations, DST, masked weekdays — is computed server-side by the on-call resolver and returned as one layered envelope per window (GET /api/v1/oncall/schedules/{id}/calendar). The calendar only draws what the backend resolved, so the lanes can never drift from what actually pages. The single thing you can draw on the calendar is an override; recurring changes go through the rotation form in Advanced.

The controls​

Across the top of the calendar:

  • Date navigation — ‹ / Today / › move the window back and forward by one span (a week, two weeks, or a month, depending on the view).
  • View — a selector for Week, 2 weeks, or Month. Week and 2-week are the hour-band swimlane views; Month is a zoomed-out day grid (see Month view).
  • Time zone — a display time-zone switcher. It offers the schedule's own time zone, your browser's time zone, and a curated list of major zones. Changing it re-labels every timestamp and re-draws the day gridlines in that zone — it is display-only and never moves any shift, because the geometry is anchored to absolute instants.
  • Color legend — the per-user color key, one swatch + name per person on the calendar.

Month view​

The Month view trades the hour bands for a compact day grid: one cell per day of the month, each listing the resolved on-call person (or people) for that local day, with a small warning dot on any day a coverage gap touches. It's the at-a-glance "who's got which day this month" summary; use Week or 2-week when you need to see or edit exact times.

Managing overrides​

An override assigns a specific person to a specific time range, and it always wins over the underlying rotations for that range — the way you cover a swap, a holiday, or a one-off. Overrides are managed entirely on the Overrides lane.

With the mouse (drag)​

  • Create — drag across empty space on the Overrides lane. A dashed ghost band tracks your drag (snapped to a 15-minute grid); on release, an editor opens prefilled with that range so you just pick the person and save.
  • Move — drag an override block's body left or right to shift it to a new time.
  • Resize — drag an override block's left or right edge to change when it starts or ends.
  • Delete — click the × on a block (or use Delete in the editor).

Move and resize update the override in place (via PATCH /api/v1/oncall/overrides/{id}) — the override keeps its identity rather than being deleted and re-created. Every change refetches the calendar, so the Final lane and the "who's on call now" reads immediately reflect it.

With the keyboard (no drag required)​

Every drag has an exact-input equivalent, so you never need a pixel-perfect mouse gesture:

  • Add override — the ＋ "Add override" button next to the lane label opens the editor blank.
  • Edit an existing override — each override block is a focusable button; Enter (or click) opens the editor prefilled with that override's user and times.
  • Delete — the × on each block is keyboard-reachable, with an accessible label (Remove override for <name>).

The editor is a dialog with a labelled user picker and Start / End datetime-local inputs. Save is enabled only once a user is chosen and the end is strictly after the start (otherwise it shows "End must be after start."). The dialog traps focus, closes on Escape, and carries a description explaining that overrides win over the underlying rotations.

Rotations (the Advanced section)​

The recurring on-call pattern — layers, cadence (hourly / daily / weekly), the weekday mask, interval count, the ordered roster, and priority — lives in the Advanced disclosure beneath the calendar, collapsed by default so the calendar leads. Expand it to edit rotations with the existing form; those changes reshape the rotation lanes and the resolved Final lane the next time the calendar loads. Recurring changes belong here, not on the calendar — the calendar's drag is deliberately scoped to one-off overrides so there's never a "this occurrence or the whole rotation?" ambiguity.

Read-only for non-managers​

The calendar respects the on-call permission model (full detail in Access & Roles):

  • If you can manage the owning team's schedules (a member of the owning team holding schedules:write, or a super-admin), the Overrides lane is fully interactive — the Add override button, drag-to-manage, block editing, and the delete × are all live.
  • If you can view but not manage the schedule, the whole calendar renders read-only: no add button, no drag, and override blocks become plain, non-interactive chips. Hovering, the hover cards, the view/tz/date controls, and the color legend all still work — you get the full picture, just without the write affordances.

The read-only rendering is advisory; the backend gate is authoritative, so an attempt to mutate a schedule you don't manage is refused (403) regardless of what the UI shows.