> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/run-the-roster/availability-and-extended-leave.md).

# Availability, preferences and extended leave

Practical walk-through of the v1.6.7 features for roster-area admins. Assumes you already have the `admin.extended_leave.*` and `admin.availability_preference.edit` and `admin.availability.view` permissions granted (via RBAC UI or your tenant admin).

***

## Start an extended leave

Use this when a worker is going off for maternity, paternity, adoption, shared parental, sabbatical, long sickness, secondment, or another long absence — anything beyond a standard leave request.

1. Go to **Staff → Staff list** (`/ui/admin/staff`).
2. Find the worker's row. Click the row menu → **Start extended leave…**.
3. In the modal:
   * **Leave type** — pick from the dropdown (8 values, closed set).
   * **Started on** — first day of the absence.
   * **Expected return on** — best guess; not binding.
   * **Notes** — free text (≤500 chars, no PII).
4. Submit.

The platform:

* Truncates the worker's active pattern assignments at `started_on - 1` (so the solver stops treating them as available from day 1 of the leave).
* If the type is `long_sickness`, automatically creates a linked sickness record — no double entry into the sickness workflow.

If the button is greyed out or the modal refuses, either:

* The worker has no open employment spell → open one first via **Reactivate** on the staff-edit page (v1.6.6 feature).
* You lack `admin.extended_leave.start` → ask your tenant admin.

## Record return + confirm onboarding

Two actions on the staff-edit page header (visible once a leave exists):

**Record return** — used when the worker is back.

* Enter the **Returned on** date.
* Optionally tick **Confirm onboarding also**. If you hold both perms (`record_return` + `confirm_onboarding`), this closes the leave AND admits the worker back into the solver in one click.

**Confirm onboarding** — used for the delayed case: worker is back at work but needs an onboarding step (e.g. paperwork, refresher training) before they can be rostered. Until confirmed, the solver refuses to schedule them and diagnostics surface them under "Workers skipped for pending onboarding".

## View a worker's employment history

Staff-edit → **Employment History** tab. Each employment spell now shows:

* The pattern assignments in effect during that spell (v1.6.6).
* **Extended leaves inline** — periods, type pill, onboarding status, notes.

Long-sickness rows carry a `→ P24 sickness` deep-link so you can click through to the auto-created sickness record if you need to.

## Set worker availability preferences

Preferences let you record "worker prefers to be available / unavailable" hints at the granularity of specific dates, weekly patterns, weekends, public holidays, or evenings-and-OOH.

**These are planning-transparency signals only in v1.6.7.** The solver does not schedule against them yet — that's a P33+ enhancement. Today they render as a dashed border overlay on the Availability view so you can plan around them by eye.

Staff-edit → **Preferences** tab (gated on `admin.availability_preference.edit`).

* **Active preferences** render as cards.
* **Previous preferences** collapse into an accordion at the bottom (soft-cleared with `cleared_utc + cleared_by` for audit trail).

Add-preference modal:

* **Polarity** — prefers available / prefers unavailable.
* **Scope kind** — specific dates / weekly pattern / weekends / public holidays / evenings & OOH.
* **Slot mask** — AM / PM / OOH; at least one required.
* **Date range** — optional; both dates or neither (paired-null validation).
* **Notes** — free text (≤500 chars, no PII).

Click **Clear** on any active card to soft-clear (it moves to the accordion, doesn't delete). History is preserved.

## The Availability view

New nav group **Availability → Availability view**. Read-only across a department.

### Filter form

* **Department** — active departments in your tenant, alphabetical.
* **View** — Week (7 days) / Month (\~28 days) / Quarter (13 weeks compressed).
* **From date** — snaps to the containing Monday.
* **Previous / Next** — steps by the view span (7 / 28 / 91 days).
* **Show preference overlay** — toggle off to hide the dashed borders when preferences aren't relevant to the planning question.
* **Only workers with preferences** — narrows the grid to just the subset of workers who have expressed any preference.

### Reading the grid

Rows = workers (alphabetical, sticky first column). Columns × 3 sub-rows per date = AM / PM / OOH.

Cell colour follows the status priority (worst first):

1. **Holiday** (slate) — public or tenant-custom holiday.
2. **Extended leave** (light blue) — maternity / sabbatical / long sickness etc.
3. **Sickness** (light red) — reported sickness absence.
4. **Annual leave** (amber) — approved AL request.
5. **Training** (indigo) — reserved for future per-day training tracking.
6. **Rostered** (green) — assigned to a published roster slot.
7. **Off pattern** (neutral) — the working pattern doesn't author this slot.
8. **Available** (white) — free to schedule.

Preference polarity renders as a **dashed border** overlay on top of the status colour: emerald for *prefers available*, rose for *prefers unavailable*.

Month view additionally shades weekend columns and marks public holidays with a `HOL` glyph in the header. Quarter view rolls up each week to its worst status — treat it as a coarse planning aid, not a precise timeline.

Hover any cell for a tooltip: worker name, date, slot, status, and preference polarity if present. Screen readers get the same information via the ARIA label.

### Legend

Right-side collapsible **Legend** panel documents the palette and preference-overlay convention. Every colour swatch carries an ARIA label so screen-reader users get the meaning even when they can't see the colour.

***

## Reversibility summary

| Action                      | Reversible?            | Method                                                                      |
| --------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| Start extended leave        | Yes                    | Cancel leave (soft-clear) — also transitions linked sickness to `cancelled` |
| Record return               | Forward-only in v1.6.7 | Undo needs a separate WP                                                    |
| Confirm onboarding          | Forward-only in v1.6.7 | Undo needs a separate WP                                                    |
| Set preference              | Yes                    | Clear (soft-clear; history preserved)                                       |
| Cancel a cleared preference | Not directly           | Add a new one with the same fields                                          |

## Deferred to v1.7+

* Worker self-service edit of preferences via My ReSouris.
* Solver soft-constraint scoring against preferences.
* Skill / role / band filters on the Availability view. Not scheduled; the view takes no such filter today.
* Per-day training-attendance tracking (the `training` status in the palette is reserved but not populated in v1.6.7).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.resouris.com/run-the-roster/availability-and-extended-leave.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.