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

2026-07-06T04:20:21Z

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

← Older revision		Revision as of 09:50, 6 July 2026
Line 314:		Line 314:
	* <code>TokenCategory.metadata</code> is an open JSON bag for deployment-specific config; <code>shorthand</code> is capped at 5 characters by the spec.		* <code>TokenCategory.metadata</code> is an open JSON bag for deployment-specific config; <code>shorthand</code> is capped at 5 characters by the spec.
	* <code>booking</code> links a token back to a [[References/Booking\|<code>TokenBooking</code>]]; on retrieve it expands to the booking and its associated [[References/Encounter\|encounter]].		* <code>booking</code> links a token back to a [[References/Booking\|<code>TokenBooking</code>]]; on retrieve it expands to the booking and its associated [[References/Encounter\|encounter]].

			{{Navbox scheduling}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:43Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=scheduling
|title=Token
|order=3
|introduced=3.0
|model=Token
|concept=Concepts/Patient
|reference=References/Encounter
}}

A <code>Token</code> is a numbered ticket a patient holds in a walk-in queue — use it when scheduling runs on first-come flow rather than fixed appointment slots. The patient gets a number against a [[References/Schedule & Availability|schedulable resource]] (practitioner, location, or healthcare service), optionally routed to a sub-queue or room.

The Django models store the data; the rules that make a token correct — status enums, the resource binding, queue progression — live in the Pydantic resource specs and the API viewsets. Both layers are covered here.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/scheduling/token.py <code>care/emr/models/scheduling/token.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/token/spec.py <code>token/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/token_category/spec.py <code>token_category/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/token_queue/spec.py <code>token_queue/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/scheduling/token_sub_queue/spec.py <code>token_sub_queue/spec.py</code>]
* Viewsets: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/scheduling/token.py <code>api/viewsets/scheduling/token.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/scheduling/token_queue.py <code>token_queue.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/scheduling/token_sub_queue.py <code>token_sub_queue.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/scheduling/token_category.py <code>token_category.py</code>]

== Models ==

Four models make up the subsystem.

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>TokenQueue</code>
| A queue of tokens for one schedulable resource on one date
|-
| <code>TokenSubQueue</code>
| A sub-queue splitting a resource's tokens (e.g. multiple rooms)
|-
| <code>TokenCategory</code>
| Reusable token categories per facility / resource type
|-
| <code>Token</code>
| A numbered token issued to a patient within a queue
|}

All four extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that supplies <code>external_id</code>, audit fields <code>created_by</code>/<code>updated_by</code>/<code>created_date</code>/<code>modified_date</code>, and soft-delete via <code>deleted</code>.

<code>TokenQueue</code> and <code>TokenSubQueue</code> both carry a <code>resource</code> FK to <code>emr.SchedulableResource</code>, a polymorphic binding to a practitioner (<code>user</code>), <code>location</code>, or <code>healthcare_service</code>, distinguished by <code>resource_type</code>. See [[References/Schedule & Availability|Schedule]].

== <code>Token</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Token|section=Token fields|name=facility|type=FK → facility.Facility (CASCADE)|notes=yes (server)}}
{{Field|model=Token|section=Token fields|name=patient|type=FK → emr.Patient (CASCADE)|notes=optional}}
{{Field|model=Token|section=Token fields|name=queue|type=FK → TokenQueue (CASCADE)|notes=yes (server)}}
{{Field|model=Token|section=Token fields|name=category|type=FK → TokenCategory (CASCADE)|notes=yes}}
{{Field|model=Token|section=Token fields|name=sub_queue|type=FK → TokenSubQueue (CASCADE)|notes=optional}}
{{Field|model=Token|section=Token fields|name=number|type=IntegerField|notes=yes (server)}}
{{Field|model=Token|section=Token fields|name=status|type=CharField(255)|notes=yes (server)}}
{{Field|model=Token|section=Token fields|name=is_next|type=BooleanField (default False)|notes=server}}
{{Field|model=Token|section=Token fields|name=note|type=TextField|notes=optional}}
{{Field|model=Token|section=Token fields|name=booking|type=FK → emr.TokenBooking (CASCADE)|notes=optional}}
|}

<code>number</code> is unique per category within a queue, not across the whole queue — so one patient can hold several tokens in the same queue, and two categories can both have a token <code>1</code>.

=== <code>TokenStatusOptions</code> values ===

Defined in <code>token/spec.py</code>; bound on <code>Token.status</code> through the read and update specs.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>UNFULFILLED</code>
| Token issued but not served
|-
| <code>CREATED</code>
| Default state on creation
|-
| <code>IN_PROGRESS</code>
| Currently being served (set when made the sub-queue's current token)
|-
| <code>FULFILLED</code>
| Service completed
|-
| <code>CANCELLED</code>
| Cancelled
|-
| <code>ENTERED_IN_ERROR</code>
| Set automatically on delete (soft-delete)
|}

== Related models ==

=== <code>TokenQueue</code> ===

One resource, one date, one queue of tokens.

<syntaxhighlight lang="text">facility → FK Facility (CASCADE)
resource → FK SchedulableResource (CASCADE)
name → CharField(255)
is_primary → BooleanField (default True)
date → DateField
system_generated → BooleanField (default False)</syntaxhighlight>
* <code>is_primary</code> is resolved server-side on create: the first queue for a <code>(resource, date)</code> pair becomes primary, later ones do not. The <code>set_primary</code> action re-points it.
* <code>generate_token</code> creates <code>system_generated</code> queues implicitly (name <code>"System Generated"</code>) when no primary queue exists for the date.

=== <code>TokenSubQueue</code> ===

A sub-queue routes one queue's tokens to several physical points — multiple vaccination rooms, say, each pulling from its own sub-queue.

<syntaxhighlight lang="text">facility → FK Facility (CASCADE)
resource → FK SchedulableResource (CASCADE)
name → CharField(255)
status → CharField(255) # TokenSubQueueStatusOptions
current_token → FK Token (CASCADE, nullable)</syntaxhighlight>
The spec binds <code>status</code> to <code>TokenSubQueueStatusOptions</code>:

{| class="wikitable"
|-
! Value
|-
| <code>active</code>
|-
| <code>inactive</code>
|}

<code>current_token</code> is whichever token is being served at that point. The progression actions (<code>set_next</code>, <code>set_next_token_to_subqueue</code>) keep it current server-side.

=== <code>TokenCategory</code> ===

A reusable category scoped to a facility and resource type — "General", "Priority", and so on.

<syntaxhighlight lang="text">facility → FK Facility (CASCADE)
resource_type → CharField(255) # SchedulableResourceTypeOptions
name → CharField(255)
shorthand → CharField(255) # spec limits to max_length 5
metadata → JSONField (default dict)
default → BooleanField (default False)</syntaxhighlight>
* The spec binds <code>resource_type</code> to <code>SchedulableResourceTypeOptions</code> (<code>practitioner</code>, <code>location</code>, <code>healthcare_service</code>).
* <code>shorthand</code> is capped at <code>max_length=5</code> by the spec even though the column allows 255.
* <code>metadata</code> is an open JSON bag for deployment-specific category config, exposed as <code>dict | None</code>.
* <code>default</code> is writable only through the <code>set_default</code> action, which clears <code>default</code> on every other category sharing the facility and resource type. It isn't a field on the create spec.

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

Defined in <code>scheduling/schedule/spec.py</code>; used by <code>TokenCategory.resource_type</code> and every <code>*WithQueue</code> / create spec that binds to a resource.

{| class="wikitable"
|-
! Value
|-
| <code>practitioner</code>
|-
| <code>location</code>
|-
| <code>healthcare_service</code>
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>): <code>serialize</code> builds the read payload from the model (plus <code>perform_extra_serialization</code>), and <code>de_serialize</code> writes a model from the payload (plus <code>perform_extra_deserialization</code>). <code>id</code> is always the model's <code>external_id</code> (UUID).

=== Token ===

{| class="wikitable"
|-
! Spec
! Role
! Exposed fields
|-
| <code>TokenBaseSpec</code>
| shared
| <code>id</code>
|-
| <code>TokenGenerateSpec</code>
| write · create (nested under a queue)
| <code>patient?</code> (UUID), <code>category</code> (UUID, required), <code>note?</code>, <code>sub_queue?</code> (UUID)
|-
| <code>TokenGenerateWithQueueSpec</code>
| write · create (queue resolved/created)
| adds <code>resource_type</code> (<code>SchedulableResourceTypeOptions</code>), <code>resource_id</code> (UUID), <code>date</code>
|-
| <code>TokenUpdateSpec</code>
| write · update
| <code>status?</code> (<code>TokenStatusOptions</code>), <code>note?</code>, <code>sub_queue</code> (UUID, nullable)
|-
| <code>TokenMinimalSpec</code>
| read · embedded
| <code>note</code>, <code>number</code>, <code>status</code>, <code>category</code> (serialized via <code>TokenCategoryReadSpec</code>)
|-
| <code>TokenReadSpec</code>
| read · list
| <code>category</code>, <code>sub_queue</code>, <code>note</code>, <code>patient</code>, <code>number</code>, <code>status</code>, <code>queue</code> (<code>TokenQueueReadSpec</code>)
|-
| <code>TokenRetrieveSpec</code>
| read · detail
| extends <code>TokenReadSpec</code> + <code>created_by</code>/<code>updated_by</code> (<code>UserSpec</code>), <code>booking</code>, <code>resource_type</code>, <code>resource</code>, <code>encounter?</code>
|}

What happens on write, from <code>perform_extra_deserialization</code> and the viewset:

* <code>TokenGenerateSpec.perform_extra_deserialization</code> resolves the <code>patient</code>, <code>category</code>, and <code>sub_queue</code> UUIDs to model instances, returning 404 if any is missing.
* <code>TokenUpdateSpec.perform_extra_deserialization</code> resolves the <code>sub_queue</code> UUID, or sets <code>sub_queue = None</code> when it's omitted — so an update can clear it.
* On create (<code>perform_create</code>), <code>queue</code> and <code>facility</code> come from the URL queue, category-vs-queue and sub-queue-vs-queue facility/resource matching is enforced, <code>number</code> is computed under a per-queue lock, and <code>status</code> is forced to <code>CREATED</code>.
* On update, changing the sub-queue clears the old sub-queue's <code>current_token</code> if it pointed at this token. A sub-queue that already has a current token can't be reassigned.
* On delete (<code>perform_destroy</code>), the token is soft-deleted: <code>status = ENTERED_IN_ERROR</code>, <code>deleted = True</code>.
* <code>TokenRetrieveSpec</code> embeds the booking (via <code>TokenBookingMinimumReadSpec</code>), the booking's <code>associated_encounter</code> ([[References/Encounter]]) when present, and the resolved <code>resource</code> (practitioner <code>UserSpec</code> / <code>HealthcareServiceReadSpec</code> / <code>FacilityLocationListSpec</code>) keyed by <code>resource_type</code>.

=== TokenQueue ===

{| class="wikitable"
|-
! Spec
! Role
! Exposed fields
|-
| <code>TokenQueueBaseSpec</code>
| shared
| <code>id</code>, <code>name</code>
|-
| <code>TokenQueueCreateSpec</code>
| write · create
| adds <code>resource_type</code> (<code>SchedulableResourceTypeOptions</code>), <code>resource_id</code> (UUID), <code>date</code>
|-
| <code>TokenQueueUpdateSpec</code>
| write · update
| <code>id</code>, <code>name</code> only
|-
| <code>TokenQueueReadSpec</code>
| read · list
| adds <code>date</code>, <code>is_primary</code>, <code>system_generated</code>
|-
| <code>TokenQueueRetrieveSpec</code>
| read · detail
| adds <code>created_by</code>, <code>updated_by</code>
|}

<code>TokenQueueCreateSpec.perform_extra_deserialization</code> stashes <code>resource_type</code> and <code>resource_id</code> onto the instance. The viewset's <code>perform_create</code> then resolves or creates the <code>SchedulableResource</code>, sets <code>facility</code>, and computes <code>is_primary</code>.

=== TokenSubQueue ===

{| class="wikitable"
|-
! Spec
! Role
! Exposed fields
|-
| <code>TokenSubQueueBaseSpec</code>
| shared / write · update
| <code>id</code>, <code>name</code>, <code>status</code> (<code>TokenSubQueueStatusOptions</code>)
|-
| <code>TokenSubQueueCreateSpec</code>
| write · create
| adds <code>resource_type</code> (<code>SchedulableResourceTypeOptions</code>), <code>resource_id</code> (UUID)
|-
| <code>TokenSubQueueReadSpec</code>
| read
| adds <code>current_token</code> (<code>TokenMinimalSpec</code>, nullable)
|}

<code>TokenSubQueueCreateSpec.perform_extra_deserialization</code> stashes <code>resource_type</code> and <code>resource_id</code>. On create the viewset resolves or creates the resource and validates it. <code>current_token</code> is serialized only when set.

=== TokenCategory ===

{| class="wikitable"
|-
! Spec
! Role
! Exposed fields
|-
| <code>TokenCategoryBaseSpec</code>
| shared
| <code>id</code>, <code>name</code>, <code>resource_type</code> (<code>SchedulableResourceTypeOptions</code>), <code>shorthand</code> (max 5), <code>metadata?</code> (dict)
|-
| <code>TokenCategoryCreateSpec</code>
| write · create
| same as base
|-
| <code>TokenCategoryReadSpec</code>
| read · list
| adds <code>default</code>
|-
| <code>TokenCategoryRetrieveSpec</code>
| read · detail
| adds <code>created_by</code>, <code>updated_by</code>
|}

<code>facility</code> is set from the URL on create. <code>default</code> is read-only here and toggled through the <code>set_default</code> action.

== Methods & save behaviour ==

* '''Number assignment''' — <code>Token.number</code> is <code>count(tokens with same queue + category) + 1</code>, computed inside a <code>Lock("booking:token:{queue.id}")</code> and an atomic transaction so two tokens can't claim the same number.
* '''Status lifecycle''' — create forces <code>CREATED</code>; <code>set_next</code> and <code>set_next_token_to_subqueue</code> set <code>IN_PROGRESS</code>; delete sets <code>ENTERED_IN_ERROR</code>. Status is a single field, with no separate history table.
* '''Queue progression''' — custom actions maintain <code>current_token</code> (on <code>TokenSubQueue</code>) and <code>is_next</code>; clients never write them directly:
** <code>Token</code> action <code>set_next</code> (<code>POST .../{id}/set_next</code>, body <code>{ sub_queue }</code>) points the sub-queue's <code>current_token</code> at this token and marks it <code>IN_PROGRESS</code>.
** <code>TokenQueue</code> action <code>set_next_token_to_subqueue</code> (<code>POST .../{queue}/set_next_token_to_subqueue</code>, body <code>{ sub_queue, category? }</code>) picks the oldest <code>CREATED</code> token (optionally filtered by category), assigns it to the sub-queue as <code>current_token</code>, and sets <code>IN_PROGRESS</code>.
** <code>TokenQueue</code> action <code>set_primary</code> makes one queue primary for its <code>(resource, date)</code>, clearing the flag on siblings.
** <code>TokenCategory</code> action <code>set_default</code> makes one category default per <code>(facility, resource_type)</code>.
* '''Token generation shortcut''' — <code>TokenQueue</code> action <code>generate_token</code> (<code>POST .../generate_token</code>, body = <code>TokenGenerateWithQueueSpec</code>) finds or creates the primary (<code>system_generated</code>) queue for <code>(resource, date)</code> and issues a token in one call.
* '''Queue summary''' — <code>TokenQueue</code> action <code>summary</code> returns per-category, per-status token counts for a queue.

== API integration notes ==

* Create tokens under a queue with <code>TokenGenerateSpec</code> — <code>queue</code>, <code>facility</code>, <code>number</code>, and <code>status</code> are all server-set — or call the queue's <code>generate_token</code> action with <code>TokenGenerateWithQueueSpec</code>, which also resolves or creates the queue.
* Send <code>category</code>, <code>patient</code>, and <code>sub_queue</code> as UUIDs (<code>external_id</code>); the server resolves them to FKs. Cross-facility and cross-resource mismatches return <code>400</code>.
* The update spec accepts only <code>TokenStatusOptions</code> values for <code>status</code>, and <code>TokenSubQueue.status</code> only <code>TokenSubQueueStatusOptions</code>. Both columns are plain <code>CharField</code>s, so the spec layer enforces this, not the database.
* Never set <code>number</code>, <code>is_next</code>, <code>current_token</code>, or <code>is_primary</code> directly — they're queue-progression state owned by the viewset actions above.
* <code>TokenCategory.metadata</code> is an open JSON bag for deployment-specific config; <code>shorthand</code> is capped at 5 characters by the spec.
* <code>booking</code> links a token back to a [[References/Booking|<code>TokenBooking</code>]]; on retrieve it expands to the booking and its associated [[References/Encounter|encounter]].

{{Related}}

References/Token - Revision history

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

Admin: OHC identity seed