Skip to main content
Version: 3.0

Token

A token is a numbered place in a queue — the digital version of pulling a ticket and waiting for your number to be called. It is how Care orders walk-in and queue-based flow: the patient sees where they stand, and staff see who to serve next.

What it represents​

A token is not an appointment. A booking reserves a specific slot ahead of time; a token simply orders the people who show up. The two can connect — a booking can issue a token when the patient arrives — but a token can also stand alone for pure walk-in flow.

Unlike most things in Care, a token doesn't map to a single FHIR resource. It's a queue-management primitive layered on top of scheduling: a number, the queue it belongs to, the category it counts within, its current state, and the patient holding it. Everything else about how tokens behave follows from how those pieces nest together.

How it connects​

Tokens are assembled from a few cooperating pieces, and understanding how they nest is most of the concept:

  • Queue — a list of tokens for one schedulable resource (a doctor, a location, or a healthcare service) on one date. The first queue created for a resource on a date becomes the primary queue; new tokens flow into it by default.
  • Sub-queue — an optional split of one queue across several physical points. A vaccination clinic with three rooms runs one queue but routes patients to three sub-queues, each calling its own current token.
  • Category — a reusable label, with a short code, that separates streams within a queue, so a priority line and a general line each keep their own running count.
  • Token — the numbered ticket itself, issued to a patient inside a queue.

Because numbers are counted per category within a queue, two patients can both hold number 1 if they sit in different categories. The number orders a stream, not the whole queue.

Lifecycle​

A token moves through a small set of states as the patient is served:

CREATED → IN_PROGRESS → FULFILLED
            ↘ CANCELLED / ENTERED_IN_ERROR
  • CREATED — issued and waiting in the queue (the default state)
  • IN_PROGRESS — now being served; set when the token becomes a sub-queue's current token
  • FULFILLED — service complete
  • UNFULFILLED — closed out without being served
  • CANCELLED — withdrawn before service
  • ENTERED_IN_ERROR — set automatically when a token is deleted, so the record closes without erasing history

Staff never pick the next token by hand. Care advances the queue for them — taking the oldest waiting token, marking it in progress, and pointing the sub-queue at it.

Permissions​

Access to tokens is granted at the facility level — the same facility the queue belongs to.

PermissionDescriptionSystem Roles
can_write_tokenIssue, update, and delete tokens, and manage their queues and sub-queues for a schedulable resourceAdmin, Staff, Facility Admin, Doctor, Nurse, Administrator
can_list_tokenView tokens, queues, and sub-queues for a schedulable resourceAdmin, Staff, Facility Admin, Doctor, Nurse, Administrator
can_write_token_categoryCreate, update, and set the default token category for a facilityAdmin, Staff, Facility Admin
can_list_token_categoryView the token categories available in a facilityAdmin, Staff, Facility Admin, Doctor, Nurse, Administrator

Roles come from a user's facility and organization memberships, and permissions cascade down the organization tree — so access granted higher up applies to the facilities beneath it.