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

2026-07-06T04:19:19Z

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

← Older revision		Revision as of 09:49, 6 July 2026
Line 328:		Line 328:
	* When reading a <code>SchedulableResource</code>, dispatch on <code>resource_type</code> to pick the populated relation (<code>user</code>, <code>location</code>, or <code>healthcare_service</code>) — only one is set, and you can't assume which.		* When reading a <code>SchedulableResource</code>, dispatch on <code>resource_type</code> to pick the populated relation (<code>user</code>, <code>location</code>, or <code>healthcare_service</code>) — only one is set, and you can't assume which.
	* A <code>ChargeItemDefinition</code> referenced by a schedule can't be deleted while the schedule exists (<code>PROTECT</code>).		* A <code>ChargeItemDefinition</code> referenced by a schedule can't be deleted while the schedule exists (<code>PROTECT</code>).

			{{Navbox scheduling}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:40Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=scheduling
|title=Schedule & Availability
|order=1
|introduced=3.0
|model=Schedule&Availability
|reference=References/User & Skills
}}

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: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/scheduling/schedule.py <code>care/emr/models/scheduling/schedule.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/schedule/spec.py <code>schedule/spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/availability_exception/spec.py <code>availability_exception/spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/resource/spec.py <code>resource/spec.py</code>]

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

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>SchedulableResource</code>
| A bookable resource (a user, location, or healthcare service) within a facility
|-
| <code>Schedule</code>
| A named, date-bounded block of availability attached to a resource
|-
| <code>Availability</code>
| Slot configuration for a schedule (slot size, tokens, weekly recurrence)
|-
| <code>AvailabilityException</code>
| A date/time range that blocks a resource (leave, holidays)
|}

All four extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <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>Schedule</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Req.
! Notes
{{Field|model=Schedule&Availability|section=Schedule fields|name=resource|type=FK → SchedulableResource (CASCADE)|notes=server}}
{{Field|model=Schedule&Availability|section=Schedule fields|name=name|type=CharField(255)|notes=yes}}
{{Field|model=Schedule&Availability|section=Schedule fields|name=valid_from|type=DateTimeField|notes=yes}}
{{Field|model=Schedule&Availability|section=Schedule fields|name=valid_to|type=DateTimeField|notes=yes}}
{{Field|model=Schedule&Availability|section=Schedule fields|name=revisit_allowed_days|type=IntegerField|notes=no}}
{{Field|model=Schedule&Availability|section=Schedule fields|name=is_public|type=BooleanField|notes=yes}}
|}

=== Billing links ===

Both charge links are set only through the <code>set_charge_item_definition</code> action (see [[#resource-specs-api-schema|Resource specs]]) — never the create/update body.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Schedule&Availability|section=Billing links|name=charge_item_definition|type=FK → ChargeItemDefinition (PROTECT)|notes=Nullable; charge applied to bookings against this schedule. <code>related_name="schedule_charge_item_definition"</code>}}
{{Field|model=Schedule&Availability|section=Billing links|name=revisit_charge_item_definition|type=FK → ChargeItemDefinition (PROTECT)|notes=Nullable; charge applied when a booking falls within <code>revisit_allowed_days</code>. <code>related_name="schedule_revisit_charge_item_definition"</code>}}
|}

== Enums ==

=== <code>SchedulableResourceTypeOptions</code> ===

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

{| class="wikitable"
|-
! Value
! Resolves to
|-
| <code>practitioner</code>
| A [[References/User & Skills
|-
| <code>location</code>
| A <code>FacilityLocation</code> in the facility (serialized via <code>FacilityLocationListSpec</code>)
|-
| <code>healthcare_service</code>
| A [[References/Healthcare Service
|}

The <code>SchedulableResource.resource_type</code> model column defaults to the string <code>"practitioner"</code>.

=== <code>SlotTypeOptions</code> ===

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

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>open</code>
| Open block; <code>slot_size_in_minutes</code> / <code>tokens_per_slot</code> are cleared to <code>null</code> on save
|-
| <code>appointment</code>
| Time-precise appointment block; requires both <code>slot_size_in_minutes</code> and <code>tokens_per_slot</code>
|-
| <code>closed</code>
| Closed block; <code>slot_size_in_minutes</code> / <code>tokens_per_slot</code> are cleared to <code>null</code> on save
|}

== Related models ==

=== <code>SchedulableResource</code> ===

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

<syntaxhighlight lang="text">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)</syntaxhighlight>
Three <code>UniqueConstraint</code>s keep one <code>SchedulableResource</code> per facility, <code>resource_type</code>, and target:

{| class="wikitable"
|-
! Constraint
! Fields
|-
| <code>unique_facility_resource_user</code>
| <code>facility</code>, <code>resource_type</code>, <code>user</code>
|-
| <code>unique_facility_resource_location</code>
| <code>facility</code>, <code>resource_type</code>, <code>location</code>
|-
| <code>unique_facility_resource_healthcare_service</code>
| <code>facility</code>, <code>resource_type</code>, <code>healthcare_service</code>
|}

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

=== <code>Availability</code> ===

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

{| class="wikitable"
|-
! Field
! Type
! Req.
! Spec detail
|-
| <code>schedule</code>
| <code>FK Schedule</code> (CASCADE)
| server
| Excluded from the availability spec; set from the URL / parent schedule
|-
| <code>name</code>
| <code>CharField(255)</code>
| yes
| Block name
|-
| <code>slot_type</code>
| <code>CharField</code>
| yes
| One of [[#slottypeoptions
|-
| <code>slot_size_in_minutes</code>
| <code>IntegerField</code> (nullable)
| conditional
| <code>int | None</code>, <code>ge=1</code>. Required when <code>slot_type == appointment</code>; forced to <code>null</code> otherwise
|-
| <code>tokens_per_slot</code>
| <code>IntegerField</code> (nullable)
| conditional
| <code>int | None</code>, <code>ge=1</code>. Capacity per slot. Required when <code>slot_type == appointment</code>; forced to <code>null</code> otherwise
|-
| <code>create_tokens</code>
| <code>BooleanField</code>
| no
| Default <code>False</code>. When <code>True</code>, each booking gets a token (queue/token workflows)
|-
| <code>reason</code>
| <code>TextField</code> (nullable)
| no
| Spec default <code>""</code>
|-
| <code>availability</code>
| <code>JSONField</code>, default <code>dict</code>
| yes
| Despite the <code>dict</code> default, the spec models it as a <code>list[AvailabilityDateTimeSpec]</code> (weekly recurrence). See below
|}

==== <code>availability</code> JSON shape — <code>AvailabilityDateTimeSpec</code> ====

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

<syntaxhighlight lang="text">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
}</syntaxhighlight>
The list is validated by <code>AvailabilityForScheduleSpec.validate_availability</code> + <code>validate_for_slot_type</code>:

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

=== <code>AvailabilityException</code> ===

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

{| class="wikitable"
|-
! Field
! Type
! Req.
! Spec detail
|-
| <code>resource</code>
| <code>FK SchedulableResource</code> (CASCADE)
| server
| Resolved from <code>resource_type</code> + <code>resource_id</code> (get-or-create); excluded from the spec body
|-
| <code>name</code>
| <code>CharField(255)</code>
| yes
| Exception name
|-
| <code>reason</code>
| <code>TextField</code> (nullable)
| no
| <code>str | None</code>
|-
| <code>valid_from</code>
| <code>DateField</code>
| yes
| <code>date</code>. Must be ≥ today and ≤ <code>valid_to</code>
|-
| <code>valid_to</code>
| <code>DateField</code>
| yes
| <code>date</code>. Must be ≥ today
|-
| <code>start_time</code>
| <code>TimeField</code>
| yes
| <code>time</code>
|-
| <code>end_time</code>
| <code>TimeField</code>
| yes
| <code>time</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>]), which provides <code>serialize()</code> (DB → pydantic), <code>de_serialize()</code> (pydantic → DB), and the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>__exclude__</code> lists fields skipped during (de)serialization.

{| class="wikitable"
|-
! Spec
! Role
! Exposes / behaviour
|-
| <code>ScheduleBaseSpec</code>
| shared
| <code>id</code>, <code>is_public</code>. <code>__exclude__ = ["resource", "facility"]</code>
|-
| <code>ScheduleCreateSpec</code>
| write · create
| <code>facility</code>, <code>name</code>, <code>valid_from</code>, <code>valid_to</code>, <code>availabilities: list[AvailabilityForScheduleSpec]</code>, <code>resource_type</code>, <code>resource_id</code>, <code>is_public</code>. Validates dates ≥ now, <code>valid_from ≤ valid_to</code>, and cross-availability non-overlap. <code>perform_extra_deserialization</code> stashes <code>facility</code>, <code>_resource_id</code>, <code>_resource_type</code>, and <code>availabilities</code> on the instance for the viewset
|-
| <code>ScheduleUpdateSpec</code>
| write · update
| <code>name</code>, <code>valid_from</code>, <code>valid_to</code>, <code>is_public</code>. <code>perform_extra_deserialization</code> blocks narrowing validity that would drop allocated slots — it compares <code>Sum(TokenSlot.allocated)</code> across the old vs new range and raises if they differ
|-
| <code>ScheduleReadSpec</code>
| read · list + detail
| All of the above plus <code>availabilities</code> (re-serialized from <code>Availability</code> rows), <code>resource_type</code>, <code>charge_item_definition</code> / <code>revisit_charge_item_definition</code> (full <code>ChargeItemDefinitionReadSpec</code> or <code>null</code>), <code>revisit_allowed_days</code>, <code>created_by</code>, <code>updated_by</code>
|-
| <code>AvailabilityBaseSpec</code>
| shared
| <code>id</code>. <code>__exclude__ = ["schedule"]</code>
|-
| <code>AvailabilityForScheduleSpec</code>
| write/read (nested in schedule)
| <code>name</code>, <code>slot_type</code>, <code>slot_size_in_minutes</code>, <code>tokens_per_slot</code>, <code>create_tokens</code>, <code>reason</code>, <code>availability: list[AvailabilityDateTimeSpec]</code>. Carries the availability + slot-type validators
|-
| <code>AvailabilityCreateSpec</code>
| write · create (standalone)
| Adds <code>schedule: UUID4</code>; on create, re-checks overlap against all existing availabilities of that schedule
|-
| <code>AvailabilityDateTimeSpec</code>
| nested
| <code>day_of_week</code> (le=6), <code>start_time</code>, <code>end_time</code> — the shape of the <code>availability</code> JSON field
|-
| <code>AvailabilityExceptionBaseSpec</code>
| shared
| <code>id</code>, <code>reason</code>, <code>valid_from</code>, <code>valid_to</code>, <code>start_time</code>, <code>end_time</code>. <code>__exclude__ = ["resource", "facility"]</code>
|-
| <code>AvailabilityExceptionWriteSpec</code>
| write · create/upsert
| Adds <code>facility</code>, <code>resource_type</code>, <code>resource_id</code>. Validates dates ≥ today and <code>valid_from ≤ valid_to</code>; stashes <code>_resource_type</code>/<code>_resource_id</code>
|-
| <code>AvailabilityExceptionReadSpec</code>
| read · list + detail
| Base fields; <code>perform_extra_serialization</code> maps <code>id</code> → <code>external_id</code>
|-
| <code>ChargeItemDefinitionSetSpec</code>
| write (action body)
| <code>charge_item_definition: str | None</code>, <code>re_visit_allowed_days: int</code>, <code>re_visit_charge_item_definition: str | None</code> — body for <code>POST .../set_charge_item_definition</code> (charge fields resolved by <code>slug</code> within the facility)
|}

=== Server-maintained behaviour (viewset hooks) ===

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

== Integration notes ==

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

{{Related}}

References/Schedule & Availability - Revision history

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

Admin: OHC identity seed