# Appointments — scheduling for staff

This chapter explains how **reception**, **clinical staff**, and **administrators** use the **Appointment** area of FlowRise (Filament admin and the Clinical workspace). All examples use **fictional placeholders** (no real patient data).

Rollout status: see [Module status](../shared/module-status.md). Patient **self-service** booking through a public portal is **not** covered here unless your organization enables it separately — today’s flows assume staff users inside Filament.

---

## Before you start

- **Branch**: Your user account is tied to a **branch**. Lists and calendars usually show only appointments for **your branch**. If lists look empty, confirm with your administrator that you are on the correct branch (see [Getting started](getting-started.md)).
- **Permissions**: Menu entries such as **Appointment**, Clinical workspace pages, or specific buttons depend on your **role**. If you cannot see something described here, ask an administrator to align your permissions with Shield roles.

---

## Roles at a glance

| Role | Typical tasks |
|------|----------------|
| **Reception / scheduling** | Book and reschedule visits; manage waitlist entries; use calendars and filters; attach participants or booked resources where needed. |
| **Clinical staff** | Quick-create bookings from Clinical workspace pages; review appointments on the patient **Timeline** and today/agenda widgets; record arrivals using allowed actions. |
| **Administrators / leads** | Maintain **schedule blocks** (blocked time); tune waitlist priority fields; monitor integration **sync outbox** rows when external systems are connected. |

---

## Core concepts

- **Appointment**: One scheduled booking with a **patient**, **start** and **end** time, **branch**, optional **location** / **department**, **status** (e.g. Booked, Arrived, Cancelled), and optional **reason** text.
- **Practitioner reference**: The system may store an identifier for the clinician assigned to the slot. Until full Staff-picker workflows cover every screen, your organization might enter a **UUID or stable reference** when instructed — treat this field exactly as your local procedure specifies.
- **Participants**: Extra actors tied to the visit (for example another clinician or interpreter). Useful when FHIR-style **participant** lists matter for reporting — participants do **not** replace the main appointment fields unless your workflow says otherwise.
- **Resources**: Rooms or assets booked for the appointment window (e.g. procedure room). These feed **conflict detection**: overlapping bookings on the same resource can be prevented when configured.
- **Recurrence rules**: Some screens allow storing **recurrence metadata** on an appointment. FlowRise does **not** yet automatically generate future visits from that metadata — treat rules as **documentation / planning only** until expansion is announced.
- **Waitlist**: Patients waiting for an earlier slot; scores help rank who to offer cancellations or new openings to.
- **Schedule blocks**: Times when a clinician (or resource) must **not** be booked — vacations, meetings, maintenance.
- **Sync outbox**: A queue of **outbound events** (for HL7/FHIR/API integrations). Rows are normally created when appointments change; operators typically **monitor** rather than create them by hand.

---

## Mini scenarios (how it fits together)

### Scenario A — Reception books a follow-up

| | |
|--|--|
| **Goal** | Reserve a return visit after lab results. |
| **Who** | Scheduling clerk (Riverdale Clinic — Branch North). |
| **Where** | Sidebar → **Appointment** cluster → **Appointments** → **Create**. |
| **Outcome** | A row appears with status **Booked**, patient **Ada Mensah (MRN DEMO-104382)**, **Thu 12 Jun 2026 09:00–09:30**, department **General Medicine**. Optional location **Main Clinic — Consult Room 3**. |

### Scenario B — Nurse checks the timeline before rounds

| | |
|--|--|
| **Goal** | See upcoming bookings for a patient on caseload. |
| **Who** | Nurse James Okoye. |
| **Where** | Clinical workspace → **Timeline** (patient selected). |
| **Outcome** | Appointment entries appear with status labels and links where allowed; nurse confirms whether today’s visit is **Booked** vs **Arrived**. |

### Scenario C — Lead blocks vacation time for Dr. Chen

| | |
|--|--|
| **Goal** | Prevent bookings while Dr. Chen is away. |
| **Who** | Clinic coordinator (administrator permissions). |
| **Where** | **Appointment** cluster → **Schedule blocks** → **Create**. |
| **Outcome** | **Jul 14–Jul 25 2026** blocked for practitioner linked to Dr. Chen’s Staff record; scheduling tries another slot if reception picks conflicting times. |

### Scenario D — Waitlisted patient offered a cancellation slot

| | |
|--|--|
| **Goal** | Fill a slot freed when another patient cancels. |
| **Who** | Reception (updates waitlist + appointment). |
| **Where** | **Waitlist entries** + **Appointments**. |
| **Outcome** | After bumping **computed priority score** for patient **Sam Okonkwo** on the cardiology waitlist, reception phones Sam and books **Mon 9 Jun 2026 14:00** once confirmed — waitlist status moves toward fulfilled per local policy. |

---

## Worked walkthrough — book via Appointment cluster (numbered)

Use this when reception schedules from the main scheduling screens.

1. Sign in and confirm your **branch** matches where the patient will be seen (see [Getting started](getting-started.md)).
2. Open **Appointment** in the sidebar, then **Appointments**.
3. Choose **Create** (or equivalent control).
4. Select **Patient** — search by **MRN** or name (example: **DEMO-104382**, Ada Mensah).
5. Set **Branch** (example: **Riverdale — North Wing**) if not defaulted.
6. Optionally pick **Location** (example: **Main Clinic — Consult Room 3**) and **Department** (example: **General Medicine**).
7. Enter **Practitioner reference** only if your site requires it (may be a Staff UUID from IT).
8. Set **Start** and **End** (example: **2026-06-12 09:00** → **2026-06-12 09:30**); ensure **End** is after **Start**.
9. Confirm **Status** matches workflow (**Booked** is typical for a confirmed slot).
10. Enter **Reason** text so clinicians see context (example: *Follow-up HbA1c review*).
11. Save the record.
12. **Verify**: Return to **Appointments** list or open the **Calendar** view (if enabled); confirm the new row appears at the correct time and filters such as **Today** include it when applicable.

---

## Other workflows (with examples)

### Book or reschedule from the Appointment cluster

- **Reschedule**: Open the appointment → **Edit** → change times or location → save.
- **Example**: **Before** — Tue 10 Jun 11:00 cardiology. **After** — Wed 11 Jun 08:30 same branch because the cath lab slot opened.

### Clinical workspace quick booking

From Clinical workspace pages such as **Patients**, **My Agenda**, or context-aware headers (when enabled), use **Quick schedule** / slide-over booking where available: fewer fields than the full form, focused on **patient**, **branch**, **times**, and a **required reason**. After save, widgets such as **today’s appointments** refresh automatically where configured.

- **Example**: Dr. Ndiaye opens **Patients**, taps schedule next week for **MRN DEMO-551902**, enters reason *Dressing change*, saves — the booking appears on list views tied to that branch.

### Check-in and cancel from the appointments table

On the **Appointments** table, **row actions** may include:

- **Check-in** — visible when the current status allows check-in; marks the patient **Arrived** and records check-in time (confirm button when prompted).
- **Cancel** — visible when cancellation is allowed; marks **Cancelled** (confirm button when prompted).

Bulk actions may include **Bulk cancel** for administrators clearing multiple rows — use only per policy.

- **If** you need reason codes beyond simple cancellation **then** use **Edit** on the appointment after cancelling or follow local procedure — some environments capture structured cancellation reasons on edit screens.

---

## Waitlist (examples)

Waitlist entries capture:

- Patient and branch (required).
- Preferred practitioner / location / department when known.
- Score components (**urgency**, wait time, referral, manual override) and an overall **computed priority score**.

**Operational pattern**: reception periodically sorts by priority, contacts patients when slots open, then creates or moves appointments accordingly.

**Example**: Cardiology wait — patient **Zara Ibrahim**, preferred department **Cardiology**, urgency bumped after symptom escalation → coordinator raises **manual override score** → **computed priority score** rises → patient contacted first when a Wed slot cancels.

---

## Schedule blocks (examples)

Blocks reserve calendar time so appointments cannot overlap that window for the chosen practitioner (and optionally linked resource references).

**Example — vacation**: Block **May 1–May 14** for Dr. Kim → reception receives conflicts when attempting overlapping bookings → reception chooses another clinician or date.

**Example — room maintenance**: Block **Resource reference ROOM-MRI-01** Friday afternoon → MRI bookings must avoid that window.

---

## Sync outbox (administrators & integrations)

When integrations are enabled, creating or changing appointments through **central scheduling services** can enqueue **sync outbox** rows for downstream systems.

**Typical pattern**:

1. Reception **reschedules** an appointment (save succeeds).
2. A **new queue row** appears under Appointment sync outbox screens (names vary by configuration).
3. Background processing (scheduled jobs/commands run by your operations team) marks rows **completed** after delivery — stuck rows with errors may require IT review.

**Operator rule**: **Do not** routinely create outbox rows manually; use **View / Edit** only for troubleshooting when IT asks.

Technical event names and payloads: see [Appointment module README](../../Modules/Appointment/README.md).

---

## Status lifecycle (plain language)

| Label | Meaning for staff |
|-------|-------------------|
| **Proposed / Pending** | Not fully confirmed — clarify before telling the patient the slot is final. |
| **Booked** | Confirmed reservation — normal operating state for upcoming visits. |
| **Arrived** | Patient checked in / present for service. |
| **Fulfilled** | Visit completed from scheduling perspective. |
| **Cancelled** | Appointment called off. |
| **No-show** | Patient did not attend without timely cancellation. |

Exact transitions depend on your permissions and which buttons your screens expose.

---

## Permissions

Access is **role-based**. If you lack **Appointment** menus or Clinical workspace actions:

1. Confirm login and branch with [Getting started](getting-started.md).
2. Ask an administrator to review Shield roles and policies.

---

## Related documentation

- [Clinical workflows](clinical-workflows.md) — encounters, vitals, notes, orders  
- [Patient management](patient-management.md) — registration and lookup  
- [Staff management](staff-management.md) — directory context for practitioners (planned features vary)  
- [Admin troubleshooting](../admin-guide/troubleshooting.md) — connectivity and access issues  

---

*Examples use fictional identifiers (MRN DEMO-* , placeholder names). Replace with your organization’s conventions.*