Appointments & queues

Booking

A booking puts a patient into a concrete time slot generated from a Schedule. TokenSlot is a bookable unit of availability; TokenBooking is a patient's appointment against that slot, carrying its status through the lifecycle. You touch both…

3.1 · versioned documentation · 7 min read

A booking puts a patient into a concrete time slot generated from a Schedule. TokenSlot is a bookable unit of availability; TokenBooking is a patient's appointment against that slot, carrying its status through the lifecycle. You touch both whenever an integration creates, cancels, reschedules, or reads an appointment.

Source:

• Model: care/emr/models/scheduling/booking.py
• Resource spec: care/emr/resources/scheduling/slot/spec.py
• Viewset (side effects): care/emr/api/viewsets/scheduling/booking.py

These models live in two layers. The Django model is storage: status is an unconstrained CharField and several relations are opaque at the DB level. The Pydantic resource specs (care/emr/resources/scheduling/slot/) are the API layer — they pin status to a fixed enum, validate writes, and define the read schemas that embed slot, resource, facility, token, charge item, encounter, and patient sub-objects.

Models

Both extend EMRBaseModel, the shared MANSOQ EMR base providing external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

TokenBooking fields

BookingStatusChoices values

BookingStatusChoices (str, Enum) is the full set of status values the write spec accepts:

Two derived sets (from slot/spec.py) drive the lifecycle rules:

TokenBookingWriteSpec.perform_extra_deserialization rejects any write whose status is in CANCELLED_STATUS_CHOICES with "Cannot cancel a booking. Use the cancel endpoint". Cancellation and rescheduling go through dedicated endpoints (see below), never a plain update.

Related models

TokenSlot

A bookable window derived from a resource's availability. Bookings reference it via PROTECT, so a slot with active bookings cannot be deleted.

SchedulableResource and Availability live in the Schedule module. SchedulableResource.resource_type is one of SchedulableResourceTypeOptions: practitioner, location, healthcare_service.

Resource specs (API schema)

Every spec extends EMRResource (base.py): serialize (DB → pydantic, read) and de_serialize (pydantic → DB, write), with perform_extra_serialization / perform_extra_deserialization hooks.

Read serialization details (perform_extra_serialization)

• id always comes from obj.external_id (UUID), not the integer PK.
• token_slot is embedded via TokenSlotBaseSpec.serialize(...).
• resource_type comes from token_slot.resource.resource_type; resource is built by serialize_resource() — a UserSpec for practitioner, HealthcareServiceReadSpec for healthcare_service, FacilityLocationListSpec for location.
• facility is a cached FacilityBareMinimumSpec; booked_by / created_by / updated_by are cached UserSpecs.
• tags are rendered through SingleFacilityTagManager().render_tags(obj) as objects, not raw IDs.
• token (TokenReadSpec), charge_item (ChargeItemReadSpec), and associated_encounter (EncounterListSpec) appear only when present.

Methods & save behaviour

status has no model-level choices; the lifecycle lives entirely in the spec/viewset layer (TokenBookingViewSet). The server-maintained behaviour:

• Creation (lock_create_appointment) — runs under a per-resource lock and a transaction. Rejects past slots (end_datetime < now) and full slots (allocated >= availability.tokens_per_slot), rejects a duplicate active booking for the same patient/slot (any status not in COMPLETED_STATUS_CHOICES), then increments token_slot.allocated, creates the booking with status="booked", and — if the schedule has a charge_item_definition — auto-creates the linked charge_item.
• Cancel (cancel action) — accepts CancelBookingSpec { reason: cancelled | entered_in_error | rescheduled, note?: str }. Rejects cancelling an in_consultation booking. Decrements token_slot.allocated (unless already cancelled), sets status = reason, optionally overwrites note, sets updated_by, and aborts any linked charge_item (handle_charge_item_cancel + status aborted).
• Reschedule (reschedule action) — accepts RescheduleBookingSpec { new_slot: UUID, new_booking_note: str, previous_booking_note?: str, tags: list[UUID] } and requires can_reschedule_booking. Cancels the existing booking with reason rescheduled, then runs lock_create_appointment to create a fresh booking on new_slot for the same patient. Rejects rescheduling to the same slot.
• Generate token (generate_token action) — accepts TokenGenerationSpec { category: UUID, note?: str, queue?: UUID }. Rejects if a token already exists. Resolves or creates a TokenQueue for the slot's date and resource, allocates the next number under a queue lock, creates a Token (status="CREATED"), and links it to booking.token.
• booked_on is auto_now_add — never set by clients.

API integration notes

• TokenSlot and TokenBooking are exposed through MANSOQ's scheduling REST API and align with the FHIR Slot and Appointment resources; payload field names may differ from Django model names.
• Writes use TokenBookingWriteSpec (status constrained to BookingStatusChoices, note required). cancelled / entered_in_error / rescheduled cannot be set through a plain update — use the cancel / reschedule actions.
• List responses use TokenBookingReadSpec; detail responses use TokenBookingRetrieveSpec, which adds associated_encounter.
• allocated on TokenSlot is a capacity counter maintained by lock_create_appointment and cancel; do not write it directly.
• tags is stored as an array of integer tag IDs but returned as rendered tag objects on read.
• List requires a resource_type query param and authorization scoped to organizations or resource IDs.

Related

• Reference: Schedule
• Reference: Token
• Reference: Encounter
• Reference: Patient
• Reference: Charge item
• Source: booking.py (model)
• Source: slot/spec.py (resource spec)
• Source: booking.py (viewset)

Source evidence

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

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/scheduling/booking.mdx:1 · f6e9f05f