Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:19:43Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:49, 6 July 2026
Line 206:		Line 206:
	* <code>tags</code> is stored as an array of integer tag IDs but returned as rendered tag objects on read.		* <code>tags</code> is stored as an array of integer tag IDs but returned as rendered tag objects on read.
	* List requires a <code>resource_type</code> query param and authorization scoped to organizations or resource IDs.		* List requires a <code>resource_type</code> query param and authorization scoped to organizations or resource IDs.

			{{Navbox scheduling}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:39Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=scheduling
|title=Booking
|order=2
|introduced=3.0
|model=Booking
|reference=References/Charge Item
}}

A booking puts a patient into a concrete time slot generated from a [[References/Schedule & Availability|Schedule]]. <code>TokenSlot</code> is a bookable unit of availability; <code>TokenBooking</code> 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: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/scheduling/booking.py <code>care/emr/models/scheduling/booking.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/slot/spec.py <code>care/emr/resources/scheduling/slot/spec.py</code>]
* Viewset (side effects): [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/scheduling/booking.py <code>care/emr/api/viewsets/scheduling/booking.py</code>]

These models live in two layers. The Django model is storage: <code>status</code> is an unconstrained <code>CharField</code> and several relations are opaque at the DB level. The Pydantic resource specs (<code>care/emr/resources/scheduling/slot/</code>) are the API layer — they pin <code>status</code> 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 ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>TokenSlot</code>
| A concrete, bookable time window generated from a schedulable resource's availability
|-
| <code>TokenBooking</code>
| A patient's appointment against a <code>TokenSlot</code>, with status, notes, and optional links to an encounter, token, and charge item
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base providing <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>TokenBooking</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Booking|section=TokenBooking fields|name=token_slot|type=FK → TokenSlot (PROTECT)|notes=The slot this appointment occupies; required. PROTECT prevents deleting a slot that has bookings}}
{{Field|model=Booking|section=TokenBooking fields|name=patient|type=FK → emr.Patient (CASCADE)|notes=The booked patient; required}}
{{Field|model=Booking|section=TokenBooking fields|name=booked_on|type=DateTimeField|notes=<code>auto_now_add</code> — stamped once at creation, never accepted from clients}}
{{Field|model=Booking|section=TokenBooking fields|name=booked_by|type=FK → User (CASCADE)|notes=User who created the booking; nullable for self-service or system-created bookings}}
{{Field|model=Booking|section=TokenBooking fields|name=status|type=CharField (storage) → BookingStatusChoices (API)|notes=Appointment lifecycle status. Unbounded on the model; the write spec restricts it to the [[#bookingstatuschoices-values}}
{{Field|model=Booking|section=TokenBooking fields|name=note|type=TextField|notes=Free-text note; nullable in storage but required (<code>str</code>) on write}}
{{Field|model=Booking|section=TokenBooking fields|name=tags|type=ArrayField[int]|notes=Tag IDs, default empty list. Managed via <code>SingleFacilityTagManager</code>; reads return rendered tag objects, not raw IDs}}
{{Field|model=Booking|section=TokenBooking fields|name=associated_encounter|type=FK → emr.Encounter (PROTECT)|notes=Encounter linked to the appointment; nullable, defaults to <code>None</code>. Surfaced only by <code>TokenBookingRetrieveSpec</code>}}
{{Field|model=Booking|section=TokenBooking fields|name=token|type=FK → emr.Token (PROTECT)|notes=Queue token issued for this booking; nullable, defaults to <code>None</code>, <code>related_name="token_booking"</code>. Created by the <code>generate_token</code> action}}
{{Field|model=Booking|section=TokenBooking fields|name=charge_item|type=FK → emr.ChargeItem (CASCADE)|notes=Billing charge item for the appointment; nullable. Auto-created on booking when the schedule has a <code>charge_item_definition</code>}}
|}

=== <code>BookingStatusChoices</code> values ===

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

{| class="wikitable"
|-
! Value
! Notes
|-
| <code>proposed</code>
|
|-
| <code>pending</code>
|
|-
| <code>booked</code>
| Default applied server-side when a booking is created via <code>lock_create_appointment</code>
|-
| <code>arrived</code>
|
|-
| <code>fulfilled</code>
| Terminal; in <code>COMPLETED_STATUS_CHOICES</code>
|-
| <code>cancelled</code>
| Set only via the <code>cancel</code> endpoint; in <code>CANCELLED_STATUS_CHOICES</code> + <code>COMPLETED_STATUS_CHOICES</code>
|-
| <code>noshow</code>
| Terminal; in <code>COMPLETED_STATUS_CHOICES</code>
|-
| <code>entered_in_error</code>
| Set only via the <code>cancel</code> endpoint; in <code>CANCELLED_STATUS_CHOICES</code> + <code>COMPLETED_STATUS_CHOICES</code>
|-
| <code>checked_in</code>
|
|-
| <code>waitlist</code>
|
|-
| <code>in_consultation</code>
| Cannot be cancelled — the cancel handler rejects it
|-
| <code>rescheduled</code>
| Set only via the <code>reschedule</code> endpoint; in <code>CANCELLED_STATUS_CHOICES</code> + <code>COMPLETED_STATUS_CHOICES</code>
|}

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

{| class="wikitable"
|-
! Set
! Values
|-
| <code>CANCELLED_STATUS_CHOICES</code>
| <code>entered_in_error</code>, <code>cancelled</code>, <code>rescheduled</code>
|-
| <code>COMPLETED_STATUS_CHOICES</code>
| <code>fulfilled</code>, <code>noshow</code>, <code>entered_in_error</code>, <code>cancelled</code>, <code>rescheduled</code>
|}

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

== Related models ==

=== <code>TokenSlot</code> ===

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

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Booking|section=TokenSlot|name=resource|type=FK → SchedulableResource (CASCADE)|notes=The schedulable resource — practitioner, location, or healthcare service — the slot belongs to; required}}
{{Field|model=Booking|section=TokenSlot|name=availability|type=FK → Availability (CASCADE)|notes=The availability rule that generated this slot; nullable}}
{{Field|model=Booking|section=TokenSlot|name=start_datetime|type=DateTimeField|notes=Slot start; required, tz-aware}}
{{Field|model=Booking|section=TokenSlot|name=end_datetime|type=DateTimeField|notes=Slot end; required, tz-aware}}
{{Field|model=Booking|section=TokenSlot|name=allocated|type=IntegerField|notes=Count of bookings currently allocated to the slot, used to enforce capacity. Defaults to <code>0</code>. Platform-maintained — never written by clients}}
|}

<code>SchedulableResource</code> and <code>Availability</code> live in the [[References/Schedule & Availability|Schedule]] module. <code>SchedulableResource.resource_type</code> is one of <code>SchedulableResourceTypeOptions</code>: <code>practitioner</code>, <code>location</code>, <code>healthcare_service</code>.

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>]): <code>serialize</code> (DB → pydantic, read) and <code>de_serialize</code> (pydantic → DB, write), with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks.

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / behaviour
|-
| <code>TokenBookingBaseSpec</code>
| shared
| <code>__model__ = TokenBooking</code>, <code>__exclude__ = ["token_slot", "patient"]</code>
|-
| <code>TokenBookingWriteSpec</code>
| write · create + update
| Fields: <code>status: BookingStatusChoices</code>, <code>note: str</code>. Rejects <code>status</code> in <code>CANCELLED_STATUS_CHOICES</code> (use the cancel/reschedule endpoints). Serves as both <code>pydantic_model</code> and <code>pydantic_update_model</code>
|-
| <code>TokenBookingMinimumReadSpec</code>
| read · embed
| Lightweight read for when a booking is embedded in another resource, such as a token. Fields: <code>id</code>, <code>token_slot</code> (embedded <code>TokenSlotBaseSpec</code>), <code>booked_on</code>, <code>status: str</code>, <code>note</code>, <code>created_date</code>, <code>modified_date</code>
|-
| <code>TokenBookingBaseReadSpec</code>
| read · shared
| Adds <code>booked_by: UserSpec</code>, <code>resource_type</code>, <code>resource</code> (serialized resource), <code>facility</code>, <code>created_by</code>/<code>updated_by</code>, <code>token: TokenReadSpec</code>, <code>tags: list[dict]</code> (rendered), <code>charge_item: dict</code>
|-
| <code>TokenBookingReadSpec</code>
| read · list/default
| <code>TokenBookingBaseReadSpec</code> + <code>patient: PatientRetrieveSpec</code>. The viewset's <code>pydantic_read_model</code> for list responses
|-
| <code>TokenBookingOTPReadSpec</code>
| read · OTP flow
| <code>TokenBookingBaseReadSpec</code> + <code>patient: PatientOTPReadSpec</code> for the public/OTP booking flow
|-
| <code>TokenBookingRetrieveSpec</code>
| read · detail
| <code>TokenBookingReadSpec</code> + <code>associated_encounter: dict</code> (serialized <code>EncounterListSpec</code>). The viewset's <code>pydantic_retrieve_model</code>
|-
| <code>TokenSlotBaseSpec</code>
| read · embed
| <code>__model__ = TokenSlot</code>, <code>__exclude__ = ["resource", "availability"]</code>. Fields: <code>id</code>, <code>availability</code> (embedded as <code>{name, tokens_per_slot, id, schedule:{name,id}}</code>), <code>start_datetime</code>, <code>end_datetime</code>, <code>allocated</code>
|}

=== Read serialization details (<code>perform_extra_serialization</code>) ===

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

== Methods & save behaviour ==

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

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

== API integration notes ==

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

{{Related}}

References/Booking - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed