Appointments & queues

Schedule & Availability

A schedule is a repeatable block of time during which a resource — a practitioner, location, or healthcare service — can be booked. You attach availabilities to it and exceptions that block out specific dates. Source: - Model:…

3.1 · versioned documentation · 8 min read

A schedule is a repeatable block of time during which a resource — a practitioner, location, or healthcare service — can be booked. You attach availabilities to it (these decide how the block splits into slots) and exceptions that block out specific dates.

Source:

• Model: care/emr/models/scheduling/schedule.py
• Resource specs: schedule/spec.py, availability_exception/spec.py, resource/spec.py

The Django model (care/emr/models/scheduling/schedule.py) is storage only, down to the opaque Availability.availability JSONField. The contract lives in the Pydantic resource specs (care/emr/resources/scheduling/...): the enums, the real shape of that JSON field, the validation rules, and the separate read/write schemas. Everything below ## Models describes the specs.

Models

All four extend EMRBaseModel, which supplies external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

Schedule fields

Billing links

Both charge links are set only through the set_charge_item_definition action (see Resource specs) — never the create/update body.

Enums

SchedulableResourceTypeOptions

Discriminates the kind of entity a schedule or exception attaches to. On write, send it as resource_type; the matching resource_id is that entity's external_id.

The SchedulableResource.resource_type model column defaults to the string "practitioner".

SlotTypeOptions

The type of an individual Availability block (Availability.slot_type on the model, slot_type in the spec).

Related models

SchedulableResource

The bookable entity within a facility, and the join point that booking hangs off. Exactly one of user, location, or healthcare_service points at the underlying resource; resource_type says which. You never create one directly: Schedule and AvailabilityException writes call get_or_create_resource(resource_type, resource_id, facility) server-side, which checks the target belongs to the facility first.

facility            → FK Facility (CASCADE)
resource_type       → CharField(255), default "practitioner"
user                → FK User (CASCADE, nullable)
location            → FK FacilityLocation (CASCADE, nullable)
healthcare_service  → FK HealthcareService (CASCADE, nullable)

Three UniqueConstraints keep one SchedulableResource per facility, resource_type, and target:

On read, serialize_resource(obj) (resource/spec.py) dispatches on resource_type to UserSpec / HealthcareServiceReadSpec / FacilityLocationListSpec.

Availability

Decides how a schedule's time divides into bookable slots. One schedule can carry several availabilities — say, a morning block and an afternoon block.

availability JSON shape — AvailabilityDateTimeSpec

Each entry is one weekly recurrence window. The field stores a list of these objects, not a single dict.

AvailabilityDateTimeSpec {
  day_of_week: int   # 0–6, validated le=6 (Monday=0 … Sunday=6, ISO-style)
  start_time: time   # HH:MM:SS
  end_time:   time   # HH:MM:SS
}

The list is validated by AvailabilityForScheduleSpec.validate_availability + validate_for_slot_type:

• Every entry needs start_time < end_time (strict).
• No two entries on the same day_of_week may overlap (has_overlapping_availability: ranges overlap when a.start ≤ b.end and b.start ≤ a.end). On create, overlap is checked across all availabilities of the same schedule.
• For slot_type == appointment: slot_size_in_minutes and tokens_per_slot are mandatory, each window's duration must be an exact multiple of slot_size_in_minutes, and the resulting slot count must not exceed settings.MAX_SLOTS_PER_AVAILABILITY (default 30).

AvailabilityException

Blocks a resource for a date/time range regardless of its schedules — leave, holidays, one-off closures.

Resource specs (API schema)

Every spec extends EMRResource (base.py), which provides serialize() (DB → pydantic), de_serialize() (pydantic → DB), and the perform_extra_serialization / perform_extra_deserialization hooks. __exclude__ lists fields skipped during (de)serialization.

Server-maintained behaviour (viewset hooks)

• Resource resolution. On schedule or exception create, get_or_create_resource(resource_type, resource_id, facility) checks the target is in the facility (a practitioner must be a FacilityOrganizationUser; a location or healthcare service must belong to the facility), then gets-or-creates the SchedulableResource. facility is injected from the URL via clean_create_data.
• Nested availability create. ScheduleViewSet.perform_create (atomic) sets resource, saves the schedule, then de-serializes and saves each availability linked to it.
• Charge items. revisit_allowed_days, charge_item_definition, and revisit_charge_item_definition move only through the set_charge_item_definition detail action, never the create/update body.
• Locking + slot guards. Update and destroy take a Lock("booking:resource:<id>"). Deleting a schedule or availability is rejected when future allocated TokenSlots exist; otherwise availabilities and slots are soft-deleted (deleted=True).
• Exception slot clearing. Creating an AvailabilityException soft-deletes overlapping TokenSlots, but rejects the request if any are already allocated ("There are bookings during this exception").
• List requires resource. The Schedule and AvailabilityException list endpoints require resource_type and resource_id query params and scope results to that SchedulableResource.

Integration notes

• Slots are computed from Availability at read time, not stored as rows on the schedule.
• When reading a SchedulableResource, dispatch on resource_type to pick the populated relation (user, location, or healthcare_service) — only one is set, and you can't assume which.
• A ChargeItemDefinition referenced by a schedule can't be deleted while the schedule exists (PROTECT).

Related

• Reference: Booking
• Reference: Token
• Reference: Charge item definition
• Reference: Healthcare service
• Reference: Location
• Reference: Facility
• Reference: User
• Source (model): schedule.py
• Source (specs): schedule/spec.py, availability_exception/spec.py, resource/spec.py

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/schedule.mdx:1 · f6e9f05f