Appointments & queues

Appointment Booking

A booking claims a specific time slot on a practitioner, location, or service's calendar for one patient, and tracks that appointment from the moment it is requested until the patient is seen or the slot is released. It is how published…

3.1 · versioned documentation · 4 min read

A booking claims a specific time slot on a practitioner, location, or service's calendar for one patient, and tracks that appointment from the moment it is requested until the patient is seen or the slot is released. It is how published availability becomes an accountable commitment between a patient and the facility.

What it represents

In MANSOQ's FHIR-aligned model, a booking maps to the Appointment resource, and the time slot it occupies maps to the Slot resource. MANSOQ's field names may differ from the FHIR element names, but the lifecycle maps directly. Together the two capture:

Who and when — the patient, the chosen time slot, and who created the booking
Where it lands — the slot belongs to a schedulable resource: a practitioner, a location, or a healthcare service
Status — where the appointment sits in its lifecycle, from proposed through fulfilled, cancelled, or no-show

The key distinction: a booking is not the schedule it came from. A Schedule defines recurring availability and generates bookable slots; a booking is one patient claiming one of those slots. Each slot has a fixed capacity, so once it fills, no further bookings can be made against it — availability is a shared resource, and a booking is a reservation against it.

Lifecycle

A booking is created as booked — the slot is reserved the moment the appointment exists. From there it advances as the patient arrives and is seen, then settles into a terminal state. Cancelling and rescheduling are deliberate, separate actions, never ordinary edits to the status field.

proposed → pending → booked → arrived → checked_in → in_consultation → fulfilled
                       │
                       ├──→ cancelled / entered_in_error / rescheduled
                       └──→ noshow

proposed / pending — a tentative or unconfirmed request, before the slot is firmly held
booked — the appointment exists and the slot is reserved for the patient (the default on creation)
waitlist — the patient is waiting for a slot to open up
arrived / checked_in — the patient has reached the facility and been registered for the visit
in_consultation — the patient is being seen; a booking in this state cannot be cancelled
fulfilled / noshow — terminal: the visit was completed, or the patient did not turn up
cancelled / entered_in_error / rescheduled — the appointment was called off, logged in error, or moved; these are set only through the dedicated cancel and reschedule actions

Anything that ends a booking early — cancelling, marking an error, or rescheduling — releases the slot's capacity so it can be offered to someone else. Rescheduling does this by closing the original booking and creating a fresh one on the new slot.

How it connects

A booking sits at the centre of several scheduling and clinical primitives:

Patient — every booking belongs to exactly one patient; one patient can hold many bookings over time
Slot and schedule — the booking occupies a slot generated by a Schedule; the slot caps how many patients can book the same window
Encounter — when the patient is seen, the booking links to the Encounter that documents the visit
Token — a queue token can be generated for the booking to manage walk-in and waiting-room flow
Charge item — if the schedule is priced, booking automatically raises a charge item so the appointment can be billed; cancelling the booking aborts it

Permissions

Bookings are governed by the schedule permission set. Access is granted to staff working within the facility that owns the schedule.

Permission	Description	System Roles
`can_write_booking`	Update a booking, and run the cancel, reschedule, and generate-token actions on it	Admin, Staff, Facility Admin, Doctor, Nurse
`can_list_booking`	List and retrieve the bookings on a schedulable resource	Admin, Staff, Facility Admin, Doctor, Nurse, Administrator
`can_write_schedule`	Filter a booking list by organisation (checked when listing bookings scoped to a facility organisation)	Admin, Staff, Facility Admin, Doctor, Nurse
`can_reschedule_booking`	Move a booking to a different slot via the reschedule action	Doctor, Staff, Nurse, Administrator, Facility Admin, Admin

Roles come from a user's facility and organization memberships, and permissions cascade down the organization tree — a role held higher up applies to the facilities and resources beneath it.

Reference: Booking (technical)
Concept: Schedule
Concept: Token
Concept: Encounter
Concept: Patient

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.