Add Scheduling docs for 3.1

versioned_docs/version-3.1/concepts/scheduling/exception.mdx

@@ -0,0 +1,45 @@
+---
+sidebar_position: 4
+---
+
+# Schedule Exception
+
+## Definition
+
+A **schedule exception** in Care records a period when a resource is not available, even though a schedule makes it available. The resource is a practitioner, a location, or a healthcare service.
+
+An exception overrides the regular schedule. Care does not offer slots for booking during the period of the exception.
+
+## Key Attributes
+
+| Components | What it captures |
+| --- | --- |
+| Reason | The reason for the unavailability, for example leave or a holiday. This is required. |
+| Valid From | The first date of the unavailability. This is required. |
+| Valid Till | The last date of the unavailability. This is required. |
+| Full day unavailable | Whether the resource is unavailable for the whole day. |
+| Start time | The time that the unavailability starts on each day. This is required when the resource is not unavailable for the full day. |
+| End time | The time that the unavailability ends on each day. This is required when the resource is not unavailable for the full day. |
+| Resource | The practitioner, location, or healthcare service that the exception belongs to. |
+
+An exception applies on every day in the period from Valid From to Valid Till. For a part-day exception, the same start time and end time apply on each of those days.
+
+### Validation rules
+
+- The Valid From date must not be in the past. Care shows the message "Schedule exception cannot be created for the past".
+- The Valid Till date must be the same as, or later than, the Valid From date.
+- The start time must be earlier than the end time.
+
+## Permissions
+
+| Permission | What it allows |
+| --- | --- |
+| Can Create on Schedule | Create and remove schedule exceptions. |
+| Can list schedule on Object | See the exceptions of a resource. |
+
+## Related
+
+- Concept: [Schedule & Availability](../../concepts/scheduling/schedule.mdx)
+- Flow: [Create a schedule exception](../../flows/scheduling/exception/create-schedule-exception.mdx)
+- Flow: [View schedule exceptions](../../flows/scheduling/exception/view-schedule-exceptions.mdx)
+- Flow: [Remove a schedule exception](../../flows/scheduling/exception/remove-schedule-exception.mdx)

versioned_docs/version-3.1/concepts/scheduling/schedule.mdx

@@ -4,65 +4,80 @@ sidebar_position: 1
 
 # Schedule & Availability
 
-A **schedule** is a named, date-bounded block of time during which a bookable resource — a practitioner, a location, or a healthcare service — accepts appointments. It is the supply side of scheduling: a schedule declares when care can be booked, so the rest of the platform knows which slots to offer patients.
+## Definition
 
-## What it represents
+A **[schedule](https://build.fhir.org/schedule.html)** in Care records when a resource can be booked at a facility. The resource is a practitioner, a location, or a healthcare service. Each schedule holds one or more availability sessions. A session states the days of the week, the start time and the end time when the resource is available.
 
-In Care's FHIR-aligned model, a schedule maps to the **Schedule** resource, and the way it produces bookable times mirrors how FHIR derives **Slot**s from a schedule's planning horizon. A schedule captures:
+Care creates bookable slots from the schedule. Staff and patients book appointments against these slots.
 
-- **The resource** — who or what is being booked: a practitioner, a physical location, or a named healthcare service
-- **The effective window** — the dates between which this schedule applies, for example a doctor's roster for one quarter
-- **Availabilities** — one or more recurring time blocks (a morning OPD, an afternoon clinic) that say which days and hours are open and how that time divides into slots
-- **Exceptions** — specific dates and times when the resource is unavailable, such as leave or a public holiday
+## Key Attributes
 
-A schedule is not a list of appointments. It is the rule that *generates* bookable slots; the actual reservations live in [bookings](../scheduling/booking.mdx) and, where queues are used, in [tokens](../scheduling/token.mdx). Slots are never stored as rows — they are computed on demand from a schedule's availabilities with exceptions subtracted, so the schedule is always the single source of truth for what is bookable. Editing a schedule changes what *can* be booked going forward; it does not touch appointments that already exist.
+| Components | What it captures |
+| --- | --- |
+| Template Name | The name of the schedule template. This is required. |
+| Valid From | The first date that the schedule applies. This is required. |
+| Valid Till | The last date that the schedule applies. This is required. |
+| Resource | The practitioner, location, or healthcare service that the schedule belongs to. |
+| Availability sessions | One or more sessions. Each session holds a session title, a slot type, the days of the week, a start time and an end time. |
+| Public | Whether patients can see the schedule and book against it. A private schedule shows the message "This schedule is private". |
 
-## How a schedule is built up
+### Resource types
 
-Three pieces work together. The schedule is the container; availabilities and exceptions shape the slots it offers.
+A schedule belongs to one of these resource types:
 
-- **Schedule** — the named, dated block attached to one resource. Holds the effective window and any billing charge that applies to bookings made against it.
-- **Availability** — a recurring time block inside a schedule. It sets the slot type, how long each slot is, how many people each slot can hold, and which weekdays and hours it repeats on. A schedule can carry several, for example a morning and an afternoon block.
-- **Availability exception** — a one-off date range that blocks the resource regardless of its schedules. Used for leave, holidays, and unplanned closures.
+| Resource type | What it schedules |
+| --- | --- |
+| Practitioner | A user, for example a doctor or a nurse. |
+| Location | A place inside the facility, for example a consultation room. |
+| Healthcare Service | A service that the facility offers. |
 
-## Availability types
+A facility holds only one schedulable resource for each practitioner, each location, and each healthcare service.
 
-Each availability block has a **slot type** that decides how its time behaves:
+### Availability sessions
 
-```text
-appointment → open → closed
-```
+Each session in a schedule holds these values:
 
-- **appointment** — time-precise booking. The block is divided into fixed-length slots (for example, 15-minute slots), each holding a set number of people. Use this when patients book a specific time.
-- **open** — a block with no fixed slot size, suited to walk-in or queue-style flows where order matters more than an exact minute. Often paired with token generation.
-- **closed** — a block that is explicitly not bookable, used to carve a gap out of an otherwise open period.
+| Component | What it captures |
+| --- | --- |
+| Session Title | The name of the session, for example "IP Rounds". This is required. |
+| Slot type | Appointment Slot, Open, or Closed. This is required. |
+| Days of the week | The days that the session repeats. You select at least one day. |
+| Start time and end time | The time range of the session on each selected day. The start time must be earlier than the end time. |
+| Slot size in minutes | The length of one slot. This is required for an appointment slot. |
+| Tokens per slot | The number of patients that Care books into one slot. This is required for an appointment slot. |
+| Reason | Free text that explains the session. This is optional. |
 
-An appointment or open block can also issue a **token** for each booking, feeding the queue and token-display workflows that high-volume, walk-in clinics depend on.
+### Slot types
 
-## How it connects
+| Slot type | What it means |
+| --- | --- |
+| Appointment Slot | Care divides the session into slots of a fixed size. Patients book a specific slot. |
+| Open | The resource is available for the whole session, and Care does not divide the session into slots. |
+| Closed | The resource is not available for booking during the session. |
 
-A schedule sits at the center of the booking flow and links outward to several other primitives:
+### Validation rules
 
-- **Resource** — every schedule attaches to exactly one practitioner ([user](../access-governance/user.mdx)), [location](../facility/location.mdx), or [healthcare service](../facility/healthcare-service.mdx) within a [facility](../facility/facility.mdx).
-- **Bookings** — patients reserve generated slots, creating [bookings](../scheduling/booking.mdx) against the schedule.
-- **Tokens** — in queue-based clinics, a booking can also issue a [token](../scheduling/token.mdx) for the waiting line.
-- **Billing** — a schedule can carry a charge that applies to its bookings, with an optional reduced charge for follow-up visits within a configured window, drawn from a [charge item definition](../definitions/charge-item-definition.mdx).
+- The Valid From date must not be in the past.
+- The Valid From date must not be later than the Valid Till date.
+- The start time of a session must be earlier than its end time.
+- Sessions in a schedule must not overlap.
+- For an appointment slot, the length of the session must be a multiple of the slot size in minutes.
+- For an appointment slot, the number of slots in one session must not be more than the limit that your deployment sets.
 
 ## Permissions
 
-Access to schedules and the bookings made against them is governed by the facility-level permissions below.
+| Permission | What it allows |
+| --- | --- |
+| Can Create on Schedule | Create and change schedules and their sessions. |
+| Can list schedule on Object | See the schedules of a resource. |
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_schedule` | Create, update, and delete schedules and their availabilities for a resource | Admin, Staff, Facility Admin, Doctor, Nurse |
-| `can_list_schedule` | View the schedules and availabilities defined for a resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator |
-| `can_set_charge_item_definition` | Attach a billing charge item definition (and revisit settings) to a schedule | Facility Admin, Admin |
+## Configuration
 
-Roles are granted through a user's facility and organization memberships, and permissions cascade down the organization tree — a role held on a parent organization applies to the facilities and resources beneath it.
+The maximum number of slots in one availability session depends on your deployment's configuration.
 
 ## Related
 
-- Reference: [Schedule & Availability (technical)](../../references/scheduling/schedule.mdx)
-- Concept: [Booking](../scheduling/booking.mdx)
-- Concept: [Token](../scheduling/token.mdx)
-- Concept: [Healthcare service](../facility/healthcare-service.mdx)
+- Flow: [Create a schedule template](../../flows/scheduling/schedule/create-schedule-template.mdx)
+- Flow: [View schedule templates](../../flows/scheduling/schedule/view-schedule-templates.mdx)
+- Flow: [Edit a schedule template](../../flows/scheduling/schedule/edit-schedule-template.mdx)
+- Flow: [Delete a schedule template](../../flows/scheduling/schedule/delete-schedule-template.mdx)

versioned_docs/version-3.1/concepts/scheduling/token.mdx

@@ -4,59 +4,60 @@ sidebar_position: 3
 
 # Token
 
-A **token** is a numbered place in a queue — the digital version of pulling a ticket and waiting for your number to be called. It is how Care orders walk-in and queue-based flow: the patient sees where they stand, and staff see who to serve next.
+## Definition
 
-## What it represents
+A **token** in Care is a numbered place in a queue. Care gives a token to a patient so that staff call the patient in order.
 
-A token is not an appointment. A [booking](../scheduling/booking.mdx) reserves a specific slot ahead of time; a token simply orders the people who show up. The two can connect — a booking can issue a token when the patient arrives — but a token can also stand alone for pure walk-in flow.
+A token belongs to one token queue. The queue holds the tokens for one resource on one date. The resource is a practitioner, a location, or a healthcare service.
 
-Unlike most things in Care, a token doesn't map to a single FHIR resource. It's a queue-management primitive layered on top of scheduling: a number, the queue it belongs to, the category it counts within, its current state, and the patient holding it. Everything else about how tokens behave follows from how those pieces nest together.
+## Key Attributes
 
-## How it connects
+| Components | What it captures |
+| --- | --- |
+| Token Number | The number of the token in its queue. |
+| Patient | The patient that holds the token. |
+| Token Queue | The queue that the token belongs to. |
+| Token Category | The category of the token. This is required. |
+| Sub Queue | The service point that serves the token. This is optional. |
+| Status | The state of the token. |
+| Note | Free text about the token. This is optional. |
+| Booking | The appointment that the token belongs to, when staff generate the token from an appointment. |
 
-Tokens are assembled from a few cooperating pieces, and understanding how they nest is most of the concept:
+### Status values
 
-- **Queue** — a list of tokens for one schedulable resource (a doctor, a location, or a healthcare service) on one date. The first queue created for a resource on a date becomes the *primary* queue; new tokens flow into it by default.
-- **Sub-queue** — an optional split of one queue across several physical points. A vaccination clinic with three rooms runs one queue but routes patients to three sub-queues, each calling its own current token.
-- **Category** — a reusable label, with a short code, that separates streams within a queue, so a priority line and a general line each keep their own running count.
-- **Token** — the numbered ticket itself, issued to a patient inside a queue.
+| Status | What it means |
+| --- | --- |
+| Created | Care created the token, and the patient waits. |
+| In Progress | Staff are serving the patient. |
+| Fulfilled | Staff finished serving the patient. |
+| Unfulfilled | Staff did not serve the patient. |
+| Cancelled | Staff cancelled the token. |
+| Entered in Error | Staff recorded the token by mistake. |
 
-Because numbers are counted *per category within a queue*, two patients can both hold number 1 if they sit in different categories. The number orders a stream, not the whole queue.
+### Token queues
 
-## Lifecycle
+A token queue holds the tokens for one resource on one date. A queue has a name, and one queue for a resource is the primary queue. Care creates some queues automatically.
 
-A token moves through a small set of states as the patient is served:
+### Sub queues
 
-```text
-CREATED → IN_PROGRESS → FULFILLED
-            ↘ CANCELLED / ENTERED_IN_ERROR
-```
+A sub queue is a service point inside a queue. Use sub queues when more than one place serves the same queue, for example more than one room for vaccination. A sub queue is active or inactive, and it records the token that it serves now.
 
-- **CREATED** — issued and waiting in the queue (the default state)
-- **IN_PROGRESS** — now being served; set when the token becomes a sub-queue's current token
-- **FULFILLED** — service complete
-- **UNFULFILLED** — closed out without being served
-- **CANCELLED** — withdrawn before service
-- **ENTERED_IN_ERROR** — set automatically when a token is deleted, so the record closes without erasing history
+### Token categories
 
-Staff never pick the next token by hand. Care advances the queue for them — taking the oldest waiting token, marking it in progress, and pointing the sub-queue at it.
+A token category groups tokens, for example by the kind of visit. Each category has a name and a shorthand. An administrator sets one category as the default for the facility.
 
 ## Permissions
 
-Access to tokens is granted at the facility level — the same facility the queue belongs to.
-
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_token` | Issue, update, and delete tokens, and manage their queues and sub-queues for a schedulable resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator |
-| `can_list_token` | View tokens, queues, and sub-queues for a schedulable resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator |
-| `can_write_token_category` | Create, update, and set the default token category for a facility | Admin, Staff, Facility Admin |
-| `can_list_token_category` | View the token categories available in a facility | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator |
-
-Roles come from a user's facility and organization memberships, and permissions cascade down the organization tree — so access granted higher up applies to the facilities beneath it.
+| Permission | What it allows |
+| --- | --- |
+| Can Create on Token | Create tokens and change them. |
+| Can list token on Object | See tokens and queues. |
+| Can Create on Token Category | Create and change token categories. |
+| Can list token category on Facility | See the token categories of the facility. |
 
 ## Related
 
-- Reference: [Token (technical)](../../references/scheduling/token.mdx)
-- Concept: [Schedule](../scheduling/schedule.mdx)
-- Concept: [Booking](../scheduling/booking.mdx)
-- Concept: [Patient](../clinical/patient)
+- Flow: [Create a token category](../../flows/scheduling/token/create-token-category.mdx)
+- Flow: [Create a token](../../flows/scheduling/token/create-token.mdx)
+- Flow: [Manage a token queue](../../flows/scheduling/token/manage-token-queue.mdx)
+- Flow: [Cancel a token](../../flows/scheduling/token/cancel-token.mdx)

versioned_docs/version-3.1/flows/scheduling/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Scheduling",
+  "position": 4,
+  "key": "scheduling-flows"
+}

versioned_docs/version-3.1/flows/scheduling/exception/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Schedule Exception",
+  "position": 2,
+  "key": "scheduling-exception-flows"
+}

versioned_docs/version-3.1/flows/scheduling/exception/create-schedule-exception.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+---
+
+# Create a schedule exception
+
+## Overview
+
+This flow describes how to record a period when a resource is not available in Care. The exception overrides the regular schedule, and Care does not offer slots during that period. See [Schedule Exception](../../../concepts/scheduling/exception.mdx).
+
+## Pre-requisites
+
+- The resource is available in the facility.
+- You can open the schedule of the resource.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Create on Schedule | Lets you create a schedule exception. |
+| Can list schedule on Object | Lets you see the schedules of the resource. |
+
+## Steps
+
+### 1. Open the schedule of the resource
+
+Open the facility. Go to the scheduling section and select the resource.
+
+### 2. Open the exceptions panel
+
+Select **Add Exception**. Care opens the **Add Schedule Exceptions** panel. The panel shows the text "Configure absences by adding unavailability beyond the regular schedule."
+
+### 3. Enter the reason
+
+Enter the **Reason** for the unavailability, for example leave or a holiday.
+
+### 4. Set the period
+
+Enter **Valid From** and **Valid Till**.
+
+The Valid From date must not be in the past. The Valid Till date must be the same as, or later than, the Valid From date.
+
+### 5. Set the times
+
+To make the resource unavailable for the whole day, select **Full day unavailable**.
+
+For a part of the day, leave that option clear and enter the start time and the end time. The start time must be earlier than the end time.
+
+### 6. Confirm the unavailability
+
+Select **Confirm Unavailability**. Care shows a message that the exception is created.
+
+## Expected Outcome
+
+- The exception appears in the list of schedule exceptions for the resource.
+- Care does not offer slots for booking during the period of the exception.
+
+## Related
+
+Concepts:
+
+- [Schedule Exception](../../../concepts/scheduling/exception.mdx)
+- [Schedule & Availability](../../../concepts/scheduling/schedule.mdx)
+
+Flows:
+
+- [View schedule exceptions](./view-schedule-exceptions.mdx)
+- [Remove a schedule exception](./remove-schedule-exception.mdx)