From 4f29fabf4e654a20fbc3119720c38a9bd5777305 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 17 Jun 2026 02:47:37 +0530 Subject: [PATCH 1/2] Add concept docs for all Care domains, with real permission model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build the Concepts layer ("What is…?") to match the References layer: 23 plain-language concept docs across 8 domains (clinical, medications, scheduling, billing, supply, facility, forms, access), each distilled from its technical reference doc. - Every concept has a Permissions section grounded in the real care/security/permissions/* enums and roles (care/security/roles). - A dedicated "Roles & Permissions" concept documents the full RBAC model: roles, permission contexts, org-tree cascade, memberships. - Concepts sidebar switched to autogenerated via per-domain _category_.json (positioned, generated-index landing pages). - Links follow the repo convention: .mdx for siblings/references, extensionless for the translated patient/create-patient docs (keeps the Malayalam locale build green). - Mirrored to 3.0 & 3.1; full `npm run build` (en + ml) passes clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../concepts/access/_category_.json | 10 ++ .../concepts/access/access-control.mdx | 101 ++++++++++++++++++ .../version-3.0/concepts/access/user.mdx | 64 +++++++++++ .../concepts/billing/_category_.json | 10 ++ .../version-3.0/concepts/billing/billing.mdx | 100 +++++++++++++++++ .../concepts/clinical/_category_.json | 7 +- .../concepts/clinical/allergy-intolerance.mdx | 71 ++++++++++++ .../concepts/clinical/condition.mdx | 83 ++++++++++++++ .../version-3.0/concepts/clinical/consent.mdx | 85 +++++++++++++++ .../concepts/clinical/diagnostic-report.mdx | 65 +++++++++++ .../concepts/clinical/encounter.mdx | 92 ++++++++++++++++ .../version-3.0/concepts/clinical/notes.mdx | 59 ++++++++++ .../concepts/clinical/observation.mdx | 77 +++++++++++++ .../concepts/clinical/service-request.mdx | 73 +++++++++++++ .../concepts/clinical/specimen.mdx | 71 ++++++++++++ .../concepts/facility/_category_.json | 10 ++ .../version-3.0/concepts/facility/device.mdx | 69 ++++++++++++ .../concepts/facility/facility.mdx | 64 +++++++++++ .../concepts/facility/healthcare-service.mdx | 65 +++++++++++ .../concepts/facility/location.mdx | 73 +++++++++++++ .../concepts/facility/organization.mdx | 94 ++++++++++++++++ .../concepts/forms/_category_.json | 10 ++ .../concepts/forms/questionnaire.mdx | 73 +++++++++++++ .../version-3.0/concepts/forms/valueset.mdx | 70 ++++++++++++ .../concepts/medications/_category_.json | 10 ++ .../concepts/medications/medication.mdx | 87 +++++++++++++++ .../concepts/scheduling/_category_.json | 10 ++ .../concepts/scheduling/scheduling.mdx | 74 +++++++++++++ .../version-3.0/concepts/scheduling/token.mdx | 71 ++++++++++++ .../concepts/supply/_category_.json | 10 ++ .../version-3.0/concepts/supply/supply.mdx | 93 ++++++++++++++++ .../concepts/access/_category_.json | 10 ++ .../concepts/access/access-control.mdx | 101 ++++++++++++++++++ .../version-3.1/concepts/access/user.mdx | 64 +++++++++++ .../concepts/billing/_category_.json | 10 ++ .../version-3.1/concepts/billing/billing.mdx | 100 +++++++++++++++++ .../concepts/clinical/_category_.json | 7 +- .../concepts/clinical/allergy-intolerance.mdx | 71 ++++++++++++ .../concepts/clinical/condition.mdx | 83 ++++++++++++++ .../version-3.1/concepts/clinical/consent.mdx | 85 +++++++++++++++ .../concepts/clinical/diagnostic-report.mdx | 65 +++++++++++ .../concepts/clinical/encounter.mdx | 92 ++++++++++++++++ .../version-3.1/concepts/clinical/notes.mdx | 59 ++++++++++ .../concepts/clinical/observation.mdx | 77 +++++++++++++ .../concepts/clinical/service-request.mdx | 73 +++++++++++++ .../concepts/clinical/specimen.mdx | 71 ++++++++++++ .../concepts/facility/_category_.json | 10 ++ .../version-3.1/concepts/facility/device.mdx | 69 ++++++++++++ .../concepts/facility/facility.mdx | 64 +++++++++++ .../concepts/facility/healthcare-service.mdx | 65 +++++++++++ .../concepts/facility/location.mdx | 73 +++++++++++++ .../concepts/facility/organization.mdx | 94 ++++++++++++++++ .../concepts/forms/_category_.json | 10 ++ .../concepts/forms/questionnaire.mdx | 73 +++++++++++++ .../version-3.1/concepts/forms/valueset.mdx | 70 ++++++++++++ .../concepts/medications/_category_.json | 10 ++ .../concepts/medications/medication.mdx | 87 +++++++++++++++ .../concepts/scheduling/_category_.json | 10 ++ .../concepts/scheduling/scheduling.mdx | 74 +++++++++++++ .../version-3.1/concepts/scheduling/token.mdx | 71 ++++++++++++ .../concepts/supply/_category_.json | 10 ++ .../version-3.1/concepts/supply/supply.mdx | 93 ++++++++++++++++ versioned_sidebars/version-3.0-sidebars.json | 6 +- versioned_sidebars/version-3.1-sidebars.json | 6 +- 64 files changed, 3704 insertions(+), 10 deletions(-) create mode 100644 versioned_docs/version-3.0/concepts/access/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/access/access-control.mdx create mode 100644 versioned_docs/version-3.0/concepts/access/user.mdx create mode 100644 versioned_docs/version-3.0/concepts/billing/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/billing/billing.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/condition.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/consent.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/encounter.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/notes.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/observation.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/service-request.mdx create mode 100644 versioned_docs/version-3.0/concepts/clinical/specimen.mdx create mode 100644 versioned_docs/version-3.0/concepts/facility/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/facility/device.mdx create mode 100644 versioned_docs/version-3.0/concepts/facility/facility.mdx create mode 100644 versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx create mode 100644 versioned_docs/version-3.0/concepts/facility/location.mdx create mode 100644 versioned_docs/version-3.0/concepts/facility/organization.mdx create mode 100644 versioned_docs/version-3.0/concepts/forms/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/forms/questionnaire.mdx create mode 100644 versioned_docs/version-3.0/concepts/forms/valueset.mdx create mode 100644 versioned_docs/version-3.0/concepts/medications/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/medications/medication.mdx create mode 100644 versioned_docs/version-3.0/concepts/scheduling/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx create mode 100644 versioned_docs/version-3.0/concepts/scheduling/token.mdx create mode 100644 versioned_docs/version-3.0/concepts/supply/_category_.json create mode 100644 versioned_docs/version-3.0/concepts/supply/supply.mdx create mode 100644 versioned_docs/version-3.1/concepts/access/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/access/access-control.mdx create mode 100644 versioned_docs/version-3.1/concepts/access/user.mdx create mode 100644 versioned_docs/version-3.1/concepts/billing/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/billing/billing.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/condition.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/consent.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/encounter.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/notes.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/observation.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/service-request.mdx create mode 100644 versioned_docs/version-3.1/concepts/clinical/specimen.mdx create mode 100644 versioned_docs/version-3.1/concepts/facility/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/facility/device.mdx create mode 100644 versioned_docs/version-3.1/concepts/facility/facility.mdx create mode 100644 versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx create mode 100644 versioned_docs/version-3.1/concepts/facility/location.mdx create mode 100644 versioned_docs/version-3.1/concepts/facility/organization.mdx create mode 100644 versioned_docs/version-3.1/concepts/forms/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/forms/questionnaire.mdx create mode 100644 versioned_docs/version-3.1/concepts/forms/valueset.mdx create mode 100644 versioned_docs/version-3.1/concepts/medications/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/medications/medication.mdx create mode 100644 versioned_docs/version-3.1/concepts/scheduling/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx create mode 100644 versioned_docs/version-3.1/concepts/scheduling/token.mdx create mode 100644 versioned_docs/version-3.1/concepts/supply/_category_.json create mode 100644 versioned_docs/version-3.1/concepts/supply/supply.mdx diff --git a/versioned_docs/version-3.0/concepts/access/_category_.json b/versioned_docs/version-3.0/concepts/access/_category_.json new file mode 100644 index 0000000..dd92a2c --- /dev/null +++ b/versioned_docs/version-3.0/concepts/access/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Access & Identity", + "position": 8, + "key": "access-concepts", + "link": { + "type": "generated-index", + "title": "Access & Identity", + "description": "Who can do what in Care — users, roles, and the permission model that governs access." + } +} diff --git a/versioned_docs/version-3.0/concepts/access/access-control.mdx b/versioned_docs/version-3.0/concepts/access/access-control.mdx new file mode 100644 index 0000000..d2328d5 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/access/access-control.mdx @@ -0,0 +1,101 @@ +--- +sidebar_position: 1 +--- + +# Roles & Permissions + +Care decides what each person can see and do using **role-based access control (RBAC)**. A **permission** is the right to perform one action (for example, "Can Create Patient"); a **role** is a named bundle of permissions; and a role is granted to a user *within a boundary* — a facility, an organization, or a single patient. Access is never assigned to a user directly: it always flows permission → role → membership. + +## What it represents + +The access-control model captures three things working together: + +- **Permissions** — the smallest unit of access, one per action, each tagged with a **context** (the kind of resource it governs). Permissions are defined in code, not edited by users. +- **Roles** — flat, named collections of permissions (for example, *Doctor* or *Nurse*). A role is not a job title or a type; it is just "this set of permissions." Built-in roles ship with Care; deployments can add their own. +- **Memberships** — the link that grants a role to a user inside a specific boundary. The same user can hold *Nurse* in one facility and *Administrator* in an organization at the same time. + +A user's effective access in any context is the **union** of all permissions from every role they hold that reaches that context. + +## Standard roles + +Care seeds a set of built-in (system) roles. These cannot be edited or deleted, and they apply within the boundaries shown below. + +| Role | Applies in | What it is for | +| --- | --- | --- | +| Doctor | Facility, Government org | Clinicians who create encounters and read/write clinical data | +| Nurse | Facility, Government org | Bedside care staff with clinical read/write access | +| Staff | Facility, Government org | Front-desk and operational staff: registration, scheduling, non-clinical work | +| Pharmacist | Facility | Medication and pharmacy workflows | +| Volunteer | Facility, Government org | Limited helpers — can list patients and view responses, but not full clinical data | +| Administrator | Facility, Government org | Operational admin within a boundary: manages users, facilities, and organizations | +| Facility Admin | Facility | Full administrator of a single facility (assigned to whoever creates it) | +| Admin | Facility, Government org | The broadest administrative role, including creating and deleting organizations | +| Admin (role org) | Role organization | Administers a user-group ("role") organization and its connected groups | +| Manager (role org) | Role organization | Manages members within a role organization | +| Member (role org) | Role organization | Plain membership in a role organization | + +Deployments can also define **custom roles** with any chosen set of permissions — for example "Doctor (Read Only)" or "Scheduler." A custom role is just a different bundle; the system treats it exactly like a built-in one. + +## Boundaries and the organization tree + +A role is always granted *inside a boundary*, and the boundary type is one of three **role contexts**: + +``` +FACILITY → role applies within a facility +GOVT_ORG → role applies within a government organization +ROLE_ORG → role applies within a role (user-group) organization +``` + +Memberships are recorded by boundary type: + +- **OrganizationUser** — a user holds a role in a government or role organization. +- **FacilityOrganizationUser** — a user holds a role in a facility (or one of its sub-departments). +- **PatientUser** — a user holds a role scoped to a single patient. + +Organizations form a **tree**: a government organization can contain sub-organizations, and a facility can contain departments. A role granted at a parent **cascades to every descendant** — if you are an Administrator of a district, you hold that access in all facilities and units beneath it, without a membership at each one. When Care checks access, it looks at the target plus all of its ancestors and collects every permission you hold along that chain. + +## How a permission is decided + +Each permission carries a **permission context** describing the resource it governs. When Care serializes a resource for a user, it only counts permissions in the relevant contexts: + +| Context | Governs | +| --- | --- | +| `GENERIC` | Not tied to a specific resource type | +| `FACILITY` | Facility-level actions | +| `PATIENT` | A patient record and its data | +| `ENCOUNTER` | A single encounter | +| `ORGANIZATION` | A government or role organization | +| `FACILITY_ORGANIZATION` | A facility organization (department) | +| `QUESTIONNAIRE` | Questionnaires | + +So a request to read a patient resolves to "which roles do I hold that reach this patient, and do any of them carry a `PATIENT`/`FACILITY` permission for this action?" The answer is computed live from the user's memberships and the organization tree. + +## Permissions + +Permissions are declared in code with a display name, a context, and the default roles that hold them. A few representative examples: + +| Permission | Roles | +| --- | --- | +| Can Create Patient | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Create encounter | Doctor, Nurse, Admin, Facility Admin | +| Can create User in care | Admin, Facility Admin, Administrator | +| Can View Organizations | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | +| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | +| Can Create Organizations | Admin | +| Can Delete Organizations | Admin | + +Roles are granted to users through organization, facility-organization, or patient memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective permissions in any context are the union of all roles that reach it. Permissions themselves are platform-maintained reference data — administrators assign roles, not individual permissions. + +## Related + +- Reference: [Role (technical)](../../references/access/role.mdx) +- Reference: [Permission (technical)](../../references/access/permission.mdx) +- Reference: [Permission association (technical)](../../references/access/permission-association.mdx) +- Concept: [User](./user.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Facility](../facility/facility.mdx) + +## FHIR reference + +Care's roles and permissions are an internal authorization model rather than a clinical resource, so they do not map to a single FHIR resource. They align in spirit with FHIR's access-control concepts (such as the `Permission` and `Role`/`PractitionerRole` resources), but enforcement is Care-specific. diff --git a/versioned_docs/version-3.0/concepts/access/user.mdx b/versioned_docs/version-3.0/concepts/access/user.mdx new file mode 100644 index 0000000..5bd951f --- /dev/null +++ b/versioned_docs/version-3.0/concepts/access/user.mdx @@ -0,0 +1,64 @@ +--- +sidebar_position: 2 +--- + +# Users + +A **user** in Care is an account that a person — or a machine integration — uses to sign in and act in the system. Users are the *who* behind every record: a user creates a patient, documents an encounter, or places an order, and the system tracks what each account is allowed to do through roles and organizations. + +## What it represents + +A user account captures: + +- **Identity & profile** — name (with prefix and suffix), username, gender, date of birth, and profile picture +- **Contact** — phone number, alternate phone, and email +- **Clinician credentials** — qualification, medical council registration, experience, and weekly working hours (for staff who deliver care) +- **Authentication & security** — password, multi-factor authentication (TOTP and backup codes), and web-push notification keys +- **Placement** — the geographic organization and facility a user belongs to, plus the roles they hold in each +- **Account type** — whether the account is a real person or a service account used by an integration + +A user is *not* the same as a role. The account is the identity; the roles attached to it (in one or more organizations) decide what that identity can do. + +## Types of accounts + +| Type | Purpose | +| --- | --- | +| Human user | A person who signs in — clinicians, nurses, registration staff, administrators | +| Service account | A non-human account used by an integration or automation to talk to Care's API | + +Clinician fields such as qualification and council registration are only meaningful for staff who provide care; administrative and service accounts leave them blank. + +## Relationships + +- **Organizations & facilities** — a user is placed in a geographic organization and can be assigned roles across many organizations and facilities. This placement is what grants access. +- **Patients & encounters** — when a user creates or updates a clinical record, the account is recorded as the actor; clinical history stays auditable to the user who entered it. +- **Skills** — users can be tagged with skills (competencies) for scheduling and discovery. + +## Identifiers + +Each user has a stable public identifier (surfaced as `id` in the API) that is separate from the username. Usernames, phone numbers, and emails must each be unique across the system, so they can also locate an account during sign-in and administration. + +## Permissions + +User administration is governed by the user permission set. The two key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can create User in care | Admin, Facility Admin, Administrator | +| Can list Users in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | + +Creating users is reserved for administrators, while most clinical and support roles can list and view other users in their facility. Roles are granted to a user through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A superuser bypasses these checks entirely. + +For the broader model of how roles, permissions, and organizations combine to decide access, see [Access control](./access-control.mdx). + +## Related + +- Reference: [User & Skills (technical)](../../references/access/user.mdx) +- Concept: [Access control](./access-control.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Facility](../facility/facility.mdx) +- Concept: [Patient](../clinical/patient) + +## FHIR reference + +A care-providing user aligns with FHIR's **Practitioner** resource, and a user's role within an organization aligns with **PractitionerRole**. Care keeps the account identity and its organization-scoped roles as related but distinct ideas, mirroring that separation. diff --git a/versioned_docs/version-3.0/concepts/billing/_category_.json b/versioned_docs/version-3.0/concepts/billing/_category_.json new file mode 100644 index 0000000..0dce028 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/billing/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Billing", + "position": 4, + "key": "billing-concepts", + "link": { + "type": "generated-index", + "title": "Billing", + "description": "How charges, accounts, invoices, and payments come together to bill for care." + } +} diff --git a/versioned_docs/version-3.0/concepts/billing/billing.mdx b/versioned_docs/version-3.0/concepts/billing/billing.mdx new file mode 100644 index 0000000..b316d08 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/billing/billing.mdx @@ -0,0 +1,100 @@ +--- +sidebar_position: 1 +--- + +# Billing & Accounts + +**Billing** in Care is how the cost of care is recorded, grouped, invoiced, and settled. Its anchor is the **account** — a financial bucket that aggregates everything charged to a patient within a facility — so that charges, invoices, and payments all hang together as one coherent financial history. + +## What it represents + +Billing is not a single resource but a small family of resources that work together: + +- **Account** — a per-patient, per-facility bucket that aggregates charges and tracks running balances. One open account is created automatically for a patient when the first charge is raised; it can be balanced and closed once care is complete. +- **Charge item** — a single billable line for a service or product (a consultation, a dispensed medication, a bed-day). It records what was charged, the quantity, and the resolved price. +- **Charge item definition** — the reusable pricing template that answers "how much does this cost", binding a service to its base rate, surcharges, discounts, and taxes. +- **Invoice** — a billable grouping of charge items for one account, with snapshotted line items and computed totals, issued to the patient or payer. +- **Payment reconciliation** — a record of a payment, advance, or credit note made against an account (and optionally a specific invoice), capturing how, when, and how much was paid. + +Together these answer: what was charged, what it costs, what was billed, and what was paid. + +## How the pieces fit + +``` +Charge item definition ──(applied to)──▶ Charge item ──(placed on)──▶ Account + │ ▲ + (grouped into) (settled by) + ▼ │ + Invoice ◀──(paid via)── Payment reconciliation +``` + +A charge item is usually built from a **definition**, placed on the patient's default **account**, then grouped into an **invoice**. A **payment reconciliation** records money received against the account or invoice. Prices, totals, and balances are computed by the platform — clients record the facts, the system does the arithmetic. + +## Lifecycle + +Each billing resource has its own status, and the invoice status drives the charge item lifecycle. + +Account billing status: + +``` +open → billing → closed (completed / voided / bad debt / combined) +``` + +Charge item: + +``` +billable → billed → paid (or → not_billable / aborted / entered_in_error) +``` + +Invoice: + +``` +draft → issued → balanced (or → cancelled / entered_in_error) +``` + +A new account opens as `active` / `open` and keeps accruing charges until billing begins and it is eventually closed. A charge starts `billable`, becomes `billed` when it lands on an invoice, and `paid` once settled. An invoice begins as a `draft` (still editable), is `issued` to the payer, and is marked `balanced` when fully settled. Totals are recomputed automatically as charges, invoices, and payments change. + +## Relationships + +- Every account and charge item belongs to a **patient** and a **facility**; a charge item and an account may optionally reference an **encounter**. +- A charge item can originate from another resource — a service request, a medication dispense, an appointment, or a bed association — recorded as its service source. +- Invoices and payment reconciliations are always created against an **account**, and a payment may additionally be allocated to a single invoice. + +## Permissions + +Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The key permissions: + +| Permission | Roles | +| --- | --- | +| Can Read Account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Account / Can Update Account | Facility Admin, Admin | +| Can Create Charge Item | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Update Charge Item / Can Cancel Charge Item | Facility Admin, Admin | +| Can Create Negative Charge Item | Facility Admin, Admin | +| Can Read Charge Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Read Charge Item Definition | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Charge Item Definition on Facility / Can Set Charge Item Definition on Facility | Facility Admin, Admin | +| Can Write Invoice | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Invoice | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Invoice / Can Manage Locked Invoice | Facility Admin, Admin | +| Can Write Payment Reconciliation | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Payment Reconciliation | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Payment Reconciliation | Facility Admin, Admin | + +A broad set of clinical roles can read billing and raise charges, invoices, and payments, while creating or editing accounts, editing or cancelling charges, defining prices, and destroying or unlocking invoices are reserved for administrators. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendant facilities and locations. + +## Related + +- Reference: [Account](../../references/billing/account.mdx) +- Reference: [Charge item](../../references/billing/charge-item.mdx) +- Reference: [Charge item definition](../../references/billing/charge-item-definition.mdx) +- Reference: [Invoice](../../references/billing/invoice.mdx) +- Reference: [Payment reconciliation](../../references/billing/payment-reconciliation.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Facility](../facility/facility.mdx) +- Concept: [Supply](../supply/supply.mdx) + +## FHIR reference + +The billing resources are FHIR-aligned: the account maps to the FHIR **Account** resource, charge items and their definitions to **ChargeItem** and **ChargeItemDefinition**, the invoice to **Invoice**, and payments to **PaymentReconciliation**. Care's enum values use underscores (e.g. `entered_in_error`) rather than the FHIR-style hyphenated forms, and some field names differ from the FHIR spec. diff --git a/versioned_docs/version-3.0/concepts/clinical/_category_.json b/versioned_docs/version-3.0/concepts/clinical/_category_.json index 0e9fee9..db8262a 100644 --- a/versioned_docs/version-3.0/concepts/clinical/_category_.json +++ b/versioned_docs/version-3.0/concepts/clinical/_category_.json @@ -1,5 +1,10 @@ { "label": "Clinical", "position": 1, - "key": "clinical-concepts" + "key": "clinical-concepts", + "link": { + "type": "generated-index", + "title": "Clinical", + "description": "The clinical primitives a patient record is built from — encounters, conditions, allergies, observations, diagnostics, specimens, orders, consent, and notes." + } } diff --git a/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx b/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx new file mode 100644 index 0000000..25a27af --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 4 +--- + +# Allergy & Intolerance + +An **allergy or intolerance** records a patient's known risk of an adverse reaction to a substance — a food, a medication, an environmental trigger, or a biologic. It is part of the patient's longitudinal record and is meant to be checked before prescribing, ordering, or administering anything that could cause harm. + +## What it represents + +Each allergy or intolerance entry captures: + +- **The substance** — a coded allergen drawn from a curated SNOMED CT list, so the record can be matched against medications rather than read as free text +- **Whether it is an allergy or an intolerance** — an immune-mediated allergy versus a non-immune intolerance +- **Category** — food, medication, environment, or biologic +- **How certain and how serious it is** — a verification level (how confirmed the report is) and a criticality (the potential for harm) +- **Clinical state** — whether the allergy is currently active, inactive, or resolved +- **Timing** — when it started, when it was first recorded, and the most recent known reaction +- **Context** — the encounter it was recorded in and an optional free-text clinical note + +An entry is always recorded in the context of an encounter, and the patient is derived from that encounter — you do not attach an allergy to a patient directly. + +## Lifecycle + +The clinical state of an allergy moves through three values: + +``` +active → inactive → resolved +``` + +- **Active** — the allergy is currently relevant and should be considered during care +- **Inactive** — no longer thought to be relevant, but kept on the record +- **Resolved** — the patient is no longer believed to have this allergy + +Alongside the clinical state, a **verification status** (unconfirmed, presumed, confirmed, refuted, or entered-in-error) records how trustworthy the assertion is — for example, a self-reported allergy may sit as `unconfirmed` until a clinician confirms it. + +## Types & classification + +- **Type** — `allergy` (an immune response) or `intolerance` (a non-immune adverse reaction) +- **Category** — `food`, `medication`, `environment`, or `biologic` +- **Criticality** — `low`, `high`, or `unable_to_assess`, signalling the potential clinical harm of a future reaction + +## Relationships + +- Every allergy belongs to a **patient** and is anchored to the **encounter** in which it was recorded. +- The substance is a coded **value set** concept, which is what lets medication ordering and other business logic flag potential conflicts. +- Because an allergy is tied to its patient and encounter, it never outlives them; moving an entry to a different encounter is handled by the platform as a maintained copy. + +## Permissions + +Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient clinical-data** and **encounter clinical-data** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Doctor, Nurse, Staff, Administrator, Facility Admin | +| Can Update a Patient's data | Doctor, Nurse, Staff, Administrator, Facility Admin | +| Update Encounter related clinical data | Doctor, Nurse, Administrator, Facility Admin | + +Reading allergies requires "Can view clinical data about patients"; creating an entry requires "Can Update a Patient's data"; updating one requires "Update Encounter related clinical data" on its encounter. These roles are granted to users through organization, facility-organization, or direct patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants, so a user with the right role on a facility automatically reaches the patients and encounters beneath it. + +## Related + +- Reference: [Allergy & Intolerance (technical)](../../references/clinical/allergy-intolerance.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Condition](../clinical/condition.mdx) +- Concept: [Medication](../medications/medication.mdx) + +## FHIR reference + +Care aligns this resource to the FHIR `AllergyIntolerance` resource, and the clinical state, verification, category, and criticality values follow the corresponding FHIR code systems. diff --git a/versioned_docs/version-3.0/concepts/clinical/condition.mdx b/versioned_docs/version-3.0/concepts/clinical/condition.mdx new file mode 100644 index 0000000..3cde8ff --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/condition.mdx @@ -0,0 +1,83 @@ +--- +sidebar_position: 3 +--- + +# Condition + +A **condition** in Care records a clinical problem, diagnosis, or symptom for a patient — for example a chronic illness on the problem list, a diagnosis made during a visit, or a presenting complaint. It is part of the patient's longitudinal clinical record and is always captured in the context of an encounter. In the Care product UI conditions are surfaced as **Symptoms**. + +## What it represents + +A condition captures, in plain terms: + +- **What the problem is** — a coded clinical finding (drawn from SNOMED CT), not free text, so it can be searched, summarized, and exchanged +- **How certain it is** — whether the condition is confirmed, provisional, suspected, or refuted +- **What kind of problem it is** — a problem-list item, an encounter diagnosis, or a chronic condition +- **How serious it is** — an optional severity (mild, moderate, severe) +- **When it started and stopped** — onset and abatement, given as a date, an age, or a description +- **Where it belongs** — the patient it concerns and the encounter it was recorded in, plus an optional clinical note + +A condition is distinct from an allergy or an observation: it is a problem the patient *has*, recorded and tracked over time, rather than a measurement or a reaction. + +## Classification + +Every condition is classified so it shows up in the right place in the record: + +| Category | What it means | +| --- | --- | +| Problem list item | An ongoing problem tracked on the patient's problem list | +| Encounter diagnosis | A diagnosis made during a specific visit | +| Chronic condition | A long-term condition carried across encounters | + +## Lifecycle + +A condition's **clinical status** describes where the problem stands now, and its **verification status** describes how sure the clinician is. These move independently. + +Clinical status: + +``` +active → inactive → resolved +active → remission +active → recurrence / relapse +(unknown when not yet established) +``` + +Verification status: + +``` +unconfirmed → provisional → differential → confirmed +(refuted or entered_in_error when ruled out or mistaken) +``` + +Verification status must always be set; a condition is never recorded without saying how certain it is. + +## Relationships + +- **Patient** — every condition belongs to one patient and forms part of their clinical history. +- **Encounter** — a condition is always recorded within an encounter; Care derives the patient from that encounter, so clinicians never attach a condition to a patient directly. + +Because the patient is taken from the encounter, conditions stay tied to the visit where they were documented while still rolling up into the patient's overall record. + +## Permissions + +Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** clinical-data permission and the **encounter** clinical-data permissions, since every condition lives inside an encounter for a patient. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective roles on a patient are resolved across their organization, the patient's encounters and locations, and any direct patient assignment. Reading or writing a condition therefore requires the right clinical-data permission on the patient or the encounter it belongs to. + +## Related + +- Reference: [Condition (technical)](../../references/clinical/condition.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Allergy / intolerance](../clinical/allergy-intolerance.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +A condition aligns with the FHIR **Condition** resource. Its coded `code` is bound to a SNOMED CT clinical-finding value set, and its clinical-status, verification-status, category, and severity values follow the corresponding FHIR concepts. diff --git a/versioned_docs/version-3.0/concepts/clinical/consent.mdx b/versioned_docs/version-3.0/concepts/clinical/consent.mdx new file mode 100644 index 0000000..c803707 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/consent.mdx @@ -0,0 +1,85 @@ +--- +sidebar_position: 9 +--- + +# Consent + +A **consent** in Care records a patient's decision — to permit or deny — for a defined category of activity, such as treatment, research participation, or sharing of their information. It captures what the patient agreed to, when it applies, and who verified it, so that care teams have an auditable record of the patient's wishes. + +## What it represents + +Consent maps to the FHIR **Consent** resource. Each record captures: + +- **Decision** — whether the patient permits or denies the activity +- **Category** — what the consent is about (treatment, privacy, research, advance directives, and so on) +- **Validity** — the date it was recorded and the period during which it applies +- **Verification** — who confirmed the consent and how (for example, by a family member) +- **Supporting documents** — scanned or uploaded consent forms attached to the record +- **Encounter linkage** — the visit the consent was captured during + +A consent is always anchored to an encounter, and the owning patient is reached through that encounter. The patient's history is the container that makes their consents coherent over time. + +## Decision + +Every consent states one of two outcomes: + +- **Permit** — the patient grants consent for the activity +- **Deny** — the patient refuses consent for the activity + +## Types + +The category describes what kind of activity the consent governs: + +| Category | Meaning | +| --- | --- | +| Treatment | Consent to receive treatment | +| Patient privacy | Disclosure or sharing of patient information | +| Research | Participation in research | +| DNR | Do-not-resuscitate directive | +| Comfort care | Comfort / palliative care directive | +| Advance care directive | A patient's advance care directive | +| Advance directive (other) | Other advance directive | + +## Lifecycle + +A consent moves through a small set of statuses that describe whether it is in force: + +``` +draft → active → inactive + ↘ not_done + ↘ entered_in_error +``` + +- **draft** — being prepared, not yet in force +- **active** — currently in force +- **inactive** — no longer in force +- **not_done** — the consent activity did not take place +- **entered_in_error** — recorded by mistake; kept for audit but disregarded + +Status is recorded directly on the consent; there is no automatic state machine, so a record can be marked `entered_in_error` or `inactive` as a plain update while the history remains auditable. + +## Relationships + +A consent belongs to a single **encounter**, and an encounter can carry many consents. The **patient** is reached through that encounter, so a consent is part of the patient's longitudinal record. Verification entries reference the **user** who confirmed the consent, and uploaded consent forms are linked as supporting attachments. + +## Permissions + +Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the patient permissions defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access to a specific consent is decided by the roles a user holds on its patient — gathered through the patient's encounters, locations, owning organizations, and any direct patient association. Because access is scoped by the organization tree, a permission held at a parent organization cascades to its descendants. + +## Related + +- Reference: [Consent (technical)](../../references/clinical/consent.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [User](../access/user.mdx) + +## FHIR reference + +Consent aligns with the FHIR **Consent** resource: `status`, `category`, `decision`, and `period` map to their FHIR counterparts. diff --git a/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx b/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx new file mode 100644 index 0000000..d76bd81 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 6 +--- + +# Diagnostic Report + +A **diagnostic report** in Care holds the results and interpretation of a diagnostic test or investigation — a lab panel, an imaging study, or a similar workup. It is the answer that closes the loop on an order: every report fulfils exactly one [service request](./service-request.mdx) and is anchored to the patient and encounter the order was raised under. + +## What it represents + +In Care's FHIR-aligned model, a diagnostic report maps to the **DiagnosticReport** resource. It captures: + +- **What was tested** — a coded category (the diagnostic service section, e.g. laboratory, radiology) and an optional coded report name or panel +- **The results** — the individual measurements and findings, recorded as observations linked to the report +- **The interpretation** — a free-text conclusion summarising what the results mean, plus optional notes +- **Provenance** — the service request it fulfils, and the patient and encounter it belongs to + +A report is not the order itself. The order (service request) asks for the work; the diagnostic report is the verified outcome that comes back. + +## Lifecycle + +A report moves through statuses as results are produced and verified: + +``` +registered → partial → preliminary → final +``` + +- **registered** — the report exists but no results are attached yet +- **partial** — some results are in; the report is still incomplete +- **preliminary** — provisional results are available but not yet verified +- **final** — the report is verified and complete + +Not every report passes through every step; a straightforward result can move from `registered` to `final` directly. + +## Relationships + +A diagnostic report sits downstream of an order and pulls together the data around it: + +- **Service request** — the order being fulfilled; a report belongs to exactly one request, chosen when the report is created +- **Patient** and **encounter** — set from the context of the originating order, not entered by hand +- **Observations** — the individual result rows (values, findings) collected under the report +- **Specimen** — when a sample is involved, it is collected against the service request that this report fulfils + +## Permissions + +Access to diagnostic reports is governed by a dedicated permission enum: + +| Permission | Roles | +| --- | --- | +| Can Create Diagnostic Report on Facility | Facility Admin, Admin, Doctor, Nurse | +| Can Read Diagnostic Report | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is then scoped by the organization tree: a permission held at a parent organization cascades to its descendants. In practice, Care decides report access via the originating service request — a user can act on a report if they hold the matching permission on the encounter (or on a facility organization tied to the request's locations) that the report belongs to. + +## Related + +- Reference: [Diagnostic Report (technical)](../../references/clinical/diagnostic-report.mdx) +- Concept: [Service Request](./service-request.mdx) +- Concept: [Observation](./observation.mdx) +- Concept: [Specimen](./specimen.mdx) +- Concept: [Encounter](./encounter.mdx) + +## FHIR reference + +Care's diagnostic report aligns with the FHIR **DiagnosticReport** resource. The coded `category` and `code` fields are bound value sets (HL7 diagnostic service sections and LOINC), and `status` follows the FHIR report-status vocabulary. diff --git a/versioned_docs/version-3.0/concepts/clinical/encounter.mdx b/versioned_docs/version-3.0/concepts/clinical/encounter.mdx new file mode 100644 index 0000000..09e5c1a --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/encounter.mdx @@ -0,0 +1,92 @@ +--- +sidebar_position: 2 +--- + +# Encounter + +An **encounter** in Care is a single interaction between a patient and a facility — a clinic visit, an admission, an emergency presentation, or a tele-consult. It is the episode that clinical work happens inside: observations, conditions, orders, medications, and notes are all recorded against an encounter, which in turn belongs to a [patient](../clinical/patient). + +## What it represents + +In Care's FHIR-aligned model, an encounter maps to the **Encounter** resource. It captures: + +- **The interaction** — which patient, at which facility, and over what time period +- **Classification** — the kind of contact (inpatient, ambulatory, emergency, virtual, and so on) and its priority +- **Status** — where the visit sits in its lifecycle, with a full history of changes +- **Hospitalization detail** — admit source, discharge disposition, and diet preference when the patient is admitted +- **Care team** — the practitioners and their roles for this episode +- **Context links** — the originating appointment, the patient's current location, and the organizations responsible for the encounter + +A patient is the long-lived record; an encounter is one chapter in it. One patient accumulates many encounters over time, and each encounter is the container that ties a specific episode of care together. + +## Classification + +Every encounter is tagged with a **class** that describes the kind of contact: + +| Class | Meaning | +| --- | --- | +| Inpatient | Admitted to the facility | +| Ambulatory | Outpatient / walk-in | +| Observation | Short-stay observation | +| Emergency | Emergency department | +| Virtual | Tele-consultation | +| Home health | Care delivered at home | + +A **priority** (such as routine, urgent, emergency, or elective) records how time-sensitive the interaction is. + +## Lifecycle + +An encounter moves through a status that reflects where the episode stands. The status history is preserved each time it changes: + +``` +planned → in_progress → on_hold → discharged → completed + ↘ cancelled + ↘ discontinued + ↘ entered_in_error +``` + +- **planned** — the visit is scheduled but has not started +- **in_progress** — the patient is actively being seen +- **on_hold** — temporarily paused +- **discharged** — the patient has been discharged but paperwork may remain +- **completed**, **cancelled**, **discontinued**, **entered_in_error** — terminal states that close the encounter + +Once an encounter reaches a terminal (closed) state, clinical data can no longer be written to it; reopening requires the appropriate permission. + +## Relationships + +An encounter sits at the centre of an episode of care and connects to: + +- **Patient** — the person the encounter is for, set when the encounter is created +- **Facility** — where the interaction takes place +- **Appointment** — the originating [scheduling](../scheduling/scheduling.mdx) booking, when one exists +- **Location** — the patient's current [location](../facility/location.mdx) within the facility, with a full location history +- **Organizations** — the facility [organizations](../facility/organization.mdx) responsible for the encounter, which drive who can access it + +## Permissions + +Access to encounters is governed by the encounter permission set. The core permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create encounter | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Staff, Doctor, Nurse, Admin, Facility Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendant organizations. A user can reach an encounter when they hold the relevant permission in any organization linked to that encounter — either through the encounter's responsible organizations or through the patient's current location. Writes are additionally blocked once an encounter is in a closed (terminal) state. + +## Related + +- Reference: [Encounter (technical)](../../references/clinical/encounter.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Service request](../clinical/service-request.mdx) +- Concept: [Scheduling](../scheduling/scheduling.mdx) + +## FHIR reference + +The encounter aligns with the FHIR **Encounter** resource, including its status, class, and hospitalization concepts, so episodes of care interoperate with other FHIR-based systems. diff --git a/versioned_docs/version-3.0/concepts/clinical/notes.mdx b/versioned_docs/version-3.0/concepts/clinical/notes.mdx new file mode 100644 index 0000000..e425e57 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/notes.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 10 +--- + +# Clinical Notes + +**Clinical notes** are threaded discussions attached to a patient's record. They let care teams capture narrative context — handover notes, observations, and coordination — that does not fit into structured fields, and keep that conversation tied to the right patient and, when relevant, the right visit. + +## What it represents + +A note is a conversation, not a single entry. It captures: + +- **Threads** — a titled discussion attached to a patient, optionally scoped to one encounter +- **Messages** — the individual posts within a thread, each authored by a user +- **Authorship and timing** — who wrote each message and when, carried by the standard audit fields +- **Edit history** — when a message is edited, the previous version and its author are preserved automatically + +Notes are free-text by design. They complement structured clinical data (conditions, observations, orders) rather than replace it. + +## Relationships + +Every thread is anchored to a [patient](../clinical/patient). A thread may also be scoped to a single [encounter](../clinical/encounter.mdx): + +- **Patient-level threads** — no encounter; visible across the patient's whole record +- **Encounter-scoped threads** — tied to one visit, for conversation about that episode of care + +Within a thread, every message belongs to that thread and inherits the same patient (and encounter) anchoring. Deleting a patient removes their threads; deleting a thread removes its messages. + +## Edit history + +Messages can be edited, but earlier versions are never lost. On each edit, the platform appends the previous message body and its author to the message's history automatically — clients cannot set or overwrite this. The current text shows in the thread; the prior versions remain auditable. + +Editing is also restricted to the original author: a user can revise their own messages, but not someone else's. + +## Permissions + +Notes do not have a dedicated permission set — access is governed by the same **patient** and **encounter** clinical-data permissions that protect the rest of the record. Whether a thread is patient-level or encounter-scoped decides which one applies. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Administrator (admin), Facility Admin | +| Can Read encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | +| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Administrator (admin), Facility Admin | +| Update Encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | + +In practice: reading notes requires clinical-data read access on the patient (or, for encounter-scoped threads, on the encounter). Posting or editing a message in a patient-level thread requires permission to update the patient's data; in an encounter-scoped thread it requires permission to update the encounter's clinical data, and is blocked once the encounter is closed. + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — so a user sees and edits notes only for patients and encounters within their reach. + +## Related + +- Reference: [Notes (technical)](../../references/clinical/notes.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +Care's clinical resources are FHIR-aligned, but free-text notes are modeled as Care's own `NoteThread` and `NoteMessage` resources rather than a single FHIR resource. Narrative content elsewhere in the record maps to FHIR's `Annotation` and narrative elements; notes here are a Care-native threading layer over that idea. diff --git a/versioned_docs/version-3.0/concepts/clinical/observation.mdx b/versioned_docs/version-3.0/concepts/clinical/observation.mdx new file mode 100644 index 0000000..67b6539 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/observation.mdx @@ -0,0 +1,77 @@ +--- +sidebar_position: 5 +--- + +# Observation + +An **observation** in Care is a single named, coded data point recorded about a patient — a blood pressure reading, a temperature, a lab result, or a coded answer captured through a questionnaire. Each observation says *what* was measured and holds the recorded *value*, anchored to a patient and the encounter in which it was taken. + +## What it represents + +In Care's FHIR-aligned model, an observation maps to the **Observation** resource. It captures: + +- **What was observed** — a primary code (typically LOINC) describing the measurement, finding, or question +- **The result** — the recorded value, with a unit for quantities or a coded answer for choices +- **When and by whom** — the effective time of the measurement and who performed or entered it +- **Clinical qualifiers** — body site, collection method, reference range, and interpretation (high / low / normal) +- **Context** — links to the patient, the encounter, and the questionnaire response that produced it + +Observations are the granular clinical readings that build up a patient's record over time. Care favours **structured** observations — coded, machine-readable values — because downstream logic such as allergy and medication checks relies on them rather than on free text. + +## Types and structure + +A single observation usually holds one value, but observations can be composed: + +- **Grouped (panel) observations** mark a parent that holds several child observations sharing a context — for example, a vitals panel or a lab panel. +- **Components** are sub-readings recorded together under one observation, each with its own code and value (for example, the systolic and diastolic parts of a blood pressure). + +Most observations are created automatically when a questionnaire is submitted, so the value and its type mirror the questionnaire answer, and the originating questionnaire response is recorded for provenance. + +## Lifecycle + +An observation's status reflects how trustworthy the recorded value is: + +``` +final → amended +final → entered_in_error +``` + +- **final** — recorded, complete, and verified; the default for questionnaire-sourced observations +- **amended** — a previously final observation that was later corrected +- **entered_in_error** — recorded by mistake and should be disregarded + +Observations are not deleted to "undo" them; marking an entry as `entered_in_error` keeps the history auditable. + +## Relationships + +An observation always belongs to a **patient** and is normally recorded within an **encounter**. It may also link to: + +- the **questionnaire response** that produced it (provenance for questionnaire-sourced data) +- a **diagnostic report** it forms part of, such as a lab or imaging report +- an **observation definition** — a facility-level template that standardises codes, units, and reference ranges for a kind of observation + +## Permissions + +Observations are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can submit questionnaire about patients | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | +| Can view questionnaire responses on patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | + +Separately, the **observation definitions** that template these readings are governed at the facility level: "Can Read Observation Definition" is held by most clinical and admin roles, while "Can Create Observation Definition on Facility" is restricted to Facility Admin and Admin. + +Roles are granted to users through organization, facility-organization, encounter, and direct patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a role granted at a facility flows down to the patients and encounters beneath it. + +## Related + +- Reference: [Observation (technical)](../../references/clinical/observation.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Diagnostic report](../clinical/diagnostic-report.mdx) +- Concept: [Questionnaire](../forms/questionnaire.mdx) + +## FHIR reference + +Care's observation aligns with the FHIR **Observation** resource. Codes bind to standard terminologies — primary codes to LOINC, and body site and collection method to SNOMED CT — though API and FHIR field names may differ from Care's internal model. diff --git a/versioned_docs/version-3.0/concepts/clinical/service-request.mdx b/versioned_docs/version-3.0/concepts/clinical/service-request.mdx new file mode 100644 index 0000000..55dbfe0 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/service-request.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 7 +--- + +# Service Request + +A **service request** in Care is an order or proposal to perform an action — a lab test, an imaging study, a procedure, counselling — for a patient. It is the instruction that sets clinical work in motion: the specimens collected, the reports produced, and the observations recorded all trace back to the request that asked for them. + +## What it represents + +In Care's FHIR-aligned model, a service request maps to the **ServiceRequest** resource. It captures: + +- **What is being asked for** — a human-readable title and a coded service or procedure +- **Why and how** — its category (laboratory, imaging, counselling, surgical, education), priority, and whether it is a firm order or just a proposal +- **Clinical context** — the patient and encounter it belongs to, optional notes, patient instructions, and a target body site +- **Who and where** — the requesting clinician, the healthcare service expected to fulfil it, and the facility locations it applies to +- **Downstream linkage** — the specimens and diagnostic reports generated in response to it + +A service request is not the result — it is the ask. The findings it produces live in separate observation, specimen, and diagnostic report records that point back to it. + +## Lifecycle + +A request moves through a small set of statuses from draft to a terminal state: + +``` +draft → active → on_hold → completed + ↘ ended / revoked / entered_in_error +``` + +- **draft** — being prepared, not yet actionable +- **active** — placed and in progress +- **on_hold** — temporarily paused +- **completed** — fulfilled +- **ended**, **revoked**, **entered_in_error** — terminal closures (ended, cancelled, or logged as a mistake) + +## Intent and priority + +Two fields shape how a request is read and acted on: + +- **Intent** — how binding the request is: `proposal`, `plan`, `directive`, or `order`. A proposal is a suggestion; an order is a committed instruction. +- **Priority** — how urgently it should be handled: `routine`, `urgent`, `asap`, or `stat`. + +## Relationships + +A service request never stands alone. It is always created within an **encounter**, and the patient is taken from that encounter rather than set directly — you cannot file a request without a clinical context. From there it connects outward: + +- The **encounter** supplies the patient and the clinical setting. +- A **healthcare service** and one or more **locations** describe who fulfils the request and where. +- **Specimens** and **diagnostic reports** are produced in response and reference the request as their origin. +- A request can be created from an activity-definition template that supplies its category and the value set its code is drawn from. + +## Permissions + +Access to service requests is governed by a dedicated permission set: + +| Permission | Roles | +| --- | --- | +| Can Read Service Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Write Service Request on Facility | Facility Admin, Admin, Doctor, Nurse | + +Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A user reaches a specific request either through their membership in the encounter's facility organization (and its current location) or through the facility organizations of the locations the request is attached to. + +## Related + +- Reference: [Service Request (technical)](../../references/clinical/service-request.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Specimen](../clinical/specimen.mdx) +- Concept: [Diagnostic Report](../clinical/diagnostic-report.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +The service request aligns with the FHIR **ServiceRequest** resource, implementing a focused subset. Care follows its own conventions for some values — statuses, intents, and priorities are snake_case rather than the hyphenated FHIR codes. diff --git a/versioned_docs/version-3.0/concepts/clinical/specimen.mdx b/versioned_docs/version-3.0/concepts/clinical/specimen.mdx new file mode 100644 index 0000000..e4d8d2c --- /dev/null +++ b/versioned_docs/version-3.0/concepts/clinical/specimen.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 8 +--- + +# Specimen + +A **specimen** is a physical sample — blood, tissue, a swab, urine, and so on — collected from a patient for laboratory analysis. It is the bridge between an order for a test and the result that comes back, recording what was collected, how, and the state it reached the lab in. + +## What it represents + +In Care's FHIR-aligned model, a specimen maps to the **Specimen** resource. It captures: + +- **What was collected** — the kind of material (e.g. blood, swab, tissue), identified by a coded specimen type +- **How it was collected** — the collector, method, body site, quantity, and the patient's fasting status at collection +- **Where it came from** — the patient it belongs to and the encounter during which it was taken +- **Its journey through the lab** — when it was received, its condition on arrival, and any processing steps applied +- **Identification** — an accession identifier or barcode used to find the sample quickly + +A specimen is not the test result itself. It is the sample; the findings derived from it are reported separately. + +## Lifecycle + +A specimen moves through these statuses as it travels from collection to the lab: + +``` +draft → available → unavailable + → unsatisfactory +(any) → entered_in_error +``` + +- **draft** — a placeholder record before the sample is confirmed (Care-specific) +- **available** — the specimen is in hand and available for testing +- **unavailable** — the specimen is no longer available (consumed, lost, or disposed of) +- **unsatisfactory** — the specimen is unsuitable for testing (e.g. clotted, insufficient, contaminated) +- **entered_in_error** — the record was created in error and should be disregarded + +## Relationships + +A specimen sits between an order and a result, and is always tied to the patient it came from: + +- It is usually collected to fulfill a **service request** (a lab order); one service request may yield several specimens. +- It may be shaped by a **specimen definition** — a template describing the expected sample for a given test. +- It links to the **patient** it was collected from and the **encounter** during which collection happened. +- Findings derived from it are communicated through a **diagnostic report**. + +## Identifiers + +Each specimen carries an **accession identifier** — the lab accession number or barcode used to track the physical sample. This identifier is indexed so a specimen can be looked up quickly by scanning or searching, for example to match a tube on the bench back to the right patient and order. + +## Permissions + +Access to specimens is controlled by role-based permissions, scoped to the facility: + +| Permission | Roles | +| --- | --- | +| Can Read Specimen | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Create Specimen on Facility | Facility Admin, Admin, Doctor, Nurse | + +In practice, viewing and creating a specimen are also gated by access to the linked service request, so a user must be able to reach the underlying order. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. + +## Related + +- Reference: [Specimen (technical)](../../references/clinical/specimen.mdx) +- Concept: [Service Request](../clinical/service-request.mdx) +- Concept: [Diagnostic Report](../clinical/diagnostic-report.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's specimen aligns with the FHIR **Specimen** resource. Some Care field names differ (for example, the patient and encounter are set on creation via `subject_patient` and `subject_encounter`), and Care adds a `draft` status not present in FHIR. diff --git a/versioned_docs/version-3.0/concepts/facility/_category_.json b/versioned_docs/version-3.0/concepts/facility/_category_.json new file mode 100644 index 0000000..b250052 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Facility & Administration", + "position": 6, + "key": "facility-concepts", + "link": { + "type": "generated-index", + "title": "Facility & Administration", + "description": "Facilities, organizations, locations, services, and devices — the administrative structure care is delivered within." + } +} diff --git a/versioned_docs/version-3.0/concepts/facility/device.mdx b/versioned_docs/version-3.0/concepts/facility/device.mdx new file mode 100644 index 0000000..560ba15 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/device.mdx @@ -0,0 +1,69 @@ +--- +sidebar_position: 5 +--- + +# Device + +A **device** in Care is a physical or logical piece of equipment tracked within a facility — a monitor, pump, camera, or any asset a clinical team relies on. The device record anchors where that equipment lives, which encounter it is attached to, and the history of how it has moved and been serviced over time. + +## What it represents + +In Care's FHIR-aligned model, a device maps to the **Device** resource. It captures: + +- **Identity** — registered name, a friendly display name, and identifiers such as serial number, lot number, model number, and part number +- **Provenance** — manufacturer, manufacture date, and expiration date +- **Status** — both its lifecycle state and its physical availability +- **Contact** — structured contact points (phone, email, and similar) for the device or its vendor +- **Placement** — the facility that owns it, the organization responsible for it, and the location and encounter it is currently associated with +- **Type-specific data** — optional plugin-driven configuration when the device is a known care type (for example, a camera) + +A device is owned by exactly one facility, but it is not tied to a single location or encounter forever. It can be moved between locations and attached to or detached from encounters, and Care keeps an audit trail of each of those associations. + +## Lifecycle + +A device carries two independent status fields. Its **lifecycle status** describes whether it is in service: + +``` +active → inactive → entered_in_error +``` + +- **active** — the device is in service +- **inactive** — the device is not currently in service +- **entered_in_error** — the record was created by mistake + +Separately, its **availability status** describes its physical condition: `available`, `lost`, `damaged`, or `destroyed`. A device can be `active` in the system while its availability reflects that it is, say, out for repair. + +## Relationships + +Devices connect to the rest of Care through a few associations, each managed through its own action rather than edited directly on the device: + +- **Facility** — the owning facility, set when the device is registered. A device always belongs to one facility. +- **Managing organization** — the facility organization accountable for the device. This scopes who can see and manage it. +- **Location** — where the device is currently placed. Moving a device opens a new entry in its location history and closes the previous one. +- **Encounter** — the [encounter](../clinical/encounter.mdx) the device is currently attached to. Attaching or detaching is recorded in encounter history; when an encounter is completed, attached devices are released automatically. + +Care also keeps a **service history** — a log of maintenance and servicing events — so the upkeep of each device stays auditable alongside its movements. + +## Permissions + +Access to devices is governed by the device permissions, granted to users through their roles: + +| Permission | Roles | +| --- | --- | +| Can List Devices on Facility | Staff, Administrator, Doctor, Nurse, Facility Admin, Pharmacist | +| Can Manage Devices on Facility | Staff, Administrator, Facility Admin, Pharmacist | +| Can Manage Device Associations to Encounters | Staff, Administrator, Doctor, Nurse, Facility Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. A device is visible to users whose memberships overlap its managing organization (or the organization of the location it currently sits in), so listing and management follow the facility's organization hierarchy rather than being open to everyone in the facility. + +## Related + +- Reference: [Device (technical)](../../references/facility/device.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's device model aligns with the FHIR **Device** resource, including its lifecycle status, availability status, and structured contact points. The encounter, location, and service associations are tracked as Care-specific history records layered on top of that resource. diff --git a/versioned_docs/version-3.0/concepts/facility/facility.mdx b/versioned_docs/version-3.0/concepts/facility/facility.mdx new file mode 100644 index 0000000..e1b4e20 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/facility.mdx @@ -0,0 +1,64 @@ +--- +sidebar_position: 1 +--- + +# Facility + +A **facility** in Care is a care site — a hospital, clinic, lab, or telemedicine endpoint — and the root of a deployment's administrative hierarchy. It is where users, locations, patients, and clinical activity are anchored: nearly everything in Care happens inside the context of a facility. + +## What it represents + +In Care's FHIR-aligned model, a facility holds: + +- **Identity & classification** — name, description, and a facility type (for example, Private Hospital, Primary Health Centre, or Govt Labs) +- **Location & contact** — address, pincode, geo-coordinates, and phone number +- **Capabilities** — a set of features the site offers, such as CT scan, maternity care, X-ray, neonatal care, operation theater, or blood bank +- **Geographic placement** — a link to a government organization in the geographic hierarchy (state → district → ward) +- **Presentation & billing config** — a cover image, print templates, and per-facility discount, tax, and invoice-numbering rules + +A facility is not just a name on a map. When one is created, Care automatically provisions its root **Administration** organization and makes the creator a facility administrator, giving the site an internal structure to attach teams, departments, locations, and users to. + +## Types & classification + +Every facility has a single **facility type** drawn from a fixed list, spanning private and government hospitals, primary/community/family health centres, labs, telemedicine, NGOs, and community-based organizations. The type is descriptive — it categorizes the site for reporting and discovery but does not by itself change behaviour. + +Separately, a facility advertises zero or more **features** (CT scan, maternity care, X-ray, neonatal care, operation theater, blood bank) so that referrals and search can find sites with the right capabilities. + +## Relationships + +A facility sits at the centre of a deployment's structure: + +- **Organizations** — each facility has an internal facility-organization tree (rooted at its auto-created Administration org) for teams and departments, and a link out to the geographic organization tree for administrative placement +- **Locations** — physical places inside the facility (wards, beds, rooms) live under it +- **Users** — staff gain access by being given roles within a facility's organizations +- **Patients & encounters** — registration and care activity are scoped to the facility +- **Healthcare services & devices** — services offered and equipment are registered against the facility + +## Billing configuration + +Each facility can carry its own monetary configuration: facility-defined discount codes, selectable discount line items, a rule for how discounts stack, and an expression that generates invoice numbers. These layer on top of instance-wide catalogs, so a site can add its own discounts without redefining the ones shared across the deployment. + +## Permissions + +Access to facilities is governed by the `FacilityPermissions` enum. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create on Facility | Administrator, Admin, Facility Admin | +| Can Read on Facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Can Update on Facility | Facility Admin, Administrator, Admin, Staff | + +Roles are granted to users through organization memberships — a user holds a role within a facility's root organization, a facility sub-organization (team or department), or the geographic organization tree. Access is then scoped by that tree: a permission held at a parent organization cascades to its descendants, so a role granted high in the geographic hierarchy can authorize action on the facilities beneath it, while a role on a facility's own root org governs that site directly. + +## Related + +- Reference: [Facility (technical)](../../references/facility/facility.mdx) +- Reference: [Facility config (technical)](../../references/facility/facility-config.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Location](./location.mdx) +- Concept: [User](../access/user.mdx) +- Concept: [Access control](../access/access-control.mdx) + +## FHIR reference + +Care's facility model is aligned with FHIR. A facility broadly corresponds to a combination of the FHIR **Organization** and **Location** resources — it names the care provider and anchors the physical and administrative structure beneath it. diff --git a/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx b/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx new file mode 100644 index 0000000..917b977 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 4 +--- + +# Healthcare Service + +A **healthcare service** in Care is a specific service a facility offers — cardiology, a laboratory, radiology, a pharmacy, or a store. It names what is on offer, where it is delivered, and which department runs it, so the rest of Care can route work to the right place. + +## What it represents + +A healthcare service captures, in plain terms: + +- **What the service is** — a display name and a coded service type (for example, a cardiology or radiology code) +- **Where it is delivered** — the locations within the facility where the service is provided +- **Who runs it** — the managing organization (the department or team responsible for it) +- **What it behaves like internally** — an optional internal type that tells Care how the service is used (pharmacy, lab, scheduling, or store) +- **How it appears** — optional presentation hints (such as colours or icons) used by the interface + +A healthcare service belongs to one facility. The facility is set from context, not chosen on the form, so a service is always tied to the facility it lives in. + +## Types + +Beyond its clinical service type, a healthcare service can carry an **internal type** that tells Care how to treat it operationally: + +| Internal type | Used for | +| --- | --- | +| `pharmacy` | Dispensing and medication supply | +| `lab` | Laboratory and diagnostic ordering | +| `scheduling` | Appointment and resource scheduling | +| `store` | Inventory and supply stores | + +The internal type is optional. A service without one is simply an offered service with no special operational handling. + +## Relationships + +A healthcare service is the connective tissue between a facility's structure and the work that happens in it: + +- **Facility** — every service belongs to exactly one facility, assigned from context. +- **Locations** — a service points to the locations where it is delivered; one service can span several locations. +- **Organization** — a managing organization (a facility department or team) owns the service and is responsible for it. + +Because of these links, a healthcare service is what scheduling, ordering, and supply workflows reference when they need to know *what* is being offered and *where*. + +## Permissions + +Access to healthcare services is governed by the `HealthcareService` permissions: + +| Permission | Roles | +| --- | --- | +| Can Read Healthcare Service | Facility Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Healthcare Service on Facility | Facility Admin, Administrator | + +Reading the catalogue of services is broadly available to clinical and support staff, while creating or changing services is restricted to facility administrators. Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. Creating a service additionally requires the permission at the facility root. + +## Related + +- Reference: [Healthcare Service (technical)](../../references/facility/healthcare-service.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Scheduling](../scheduling/scheduling.mdx) + +## FHIR reference + +Care's healthcare service is aligned with the FHIR **HealthcareService** resource, and its service type is coded against the HL7 Healthcare Service Type Code value set. diff --git a/versioned_docs/version-3.0/concepts/facility/location.mdx b/versioned_docs/version-3.0/concepts/facility/location.mdx new file mode 100644 index 0000000..119301f --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/location.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 3 +--- + +# Location + +A **location** in Care is a physical place where care happens or where resources sit — a building, a wing, a ward, a room, or a single bed. Locations form a hierarchy inside a facility, and encounters attach to them so you always know where a patient is. + +## What it represents + +In Care's FHIR-aligned model, a location maps to the **Location** resource. It captures: + +- **Identity** — a name and description for the place +- **Physical form** — what kind of place it is (site, building, wing, ward, room, bed, vehicle, and so on) +- **Where it sits** — its parent location and the tree it belongs to, so a bed knows it lives in a room, inside a ward, inside a building +- **Occupancy** — the encounter currently associated with it, used for bed and room management +- **Operational state** — whether it is occupied, unoccupied, closed, being cleaned, contaminated, or isolated + +Locations are nested without limit: every location may have a parent and children, letting a deployment model its real-world geography as deep as it needs. + +## Mode: kind vs instance + +Every location is one of two modes, fixed when it is created: + +- **kind** — a class or type of place, such as "a ward" or "a building". A kind can contain child locations. +- **instance** — a single, concrete place, such as "Bed 1". Instances are leaf nodes and **cannot have children**. + +This is why beds are just locations in `instance` mode, not a separate concept. + +## Lifecycle + +A location's administrative status moves between a small set of values: + +``` +active → inactive → unknown +``` + +- **active** — the location is in use +- **inactive** — retained but no longer in service +- **unknown** — status is not known + +Separately, an **operational status** describes the live state of a bed or room — closed, housekeeping, occupied, unoccupied, contaminated, or isolated — and a server-maintained **availability** flag marks whether the location is currently tied to an encounter (reserved) or free (available). + +## Relationships + +- **Facility** — every location belongs to exactly one [facility](./facility.mdx). +- **Parent and children** — locations form a tree; a permission or organization grant at a parent cascades down to its descendants. +- **Organization** — a [facility organization](./organization.mdx) can be granted access to a location, which is how users gain access to it and the encounters within. +- **Encounter** — an [encounter](../clinical/encounter.mdx) is associated with a location over a time window (for example, a bed assignment), and the location surfaces its current encounter for occupancy views. + +## Permissions + +Access to locations is governed by the facility-location permissions: + +| Permission | Roles | +| --- | --- | +| Can List Facility Locations | Administrator, Doctor, Nurse, Staff, Pharmacist, Facility Admin, Admin | +| Can Create/Update Facility Locations | Facility Admin, Staff, Admin | +| Can List Facility Location Organizations | Facility Admin, Staff, Admin | +| Can Create/Update Facility Location Organizations | Facility Admin, Staff, Admin | + +Roles are granted to users through facility-organization membership, and access is scoped by the organization tree: a permission held on an organization applies to the locations that organization can reach, and grants at a parent location cascade to its children. Because that cascade is computed asynchronously, newly granted access settles a moment after the change is made. + +## Related + +- Reference: [Location (technical)](../../references/facility/location.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's location is modelled on the [FHIR Location](https://build.fhir.org/location.html) resource, including its `mode` (kind/instance), physical form, and operational status concepts. API field names may differ from the internal model. diff --git a/versioned_docs/version-3.0/concepts/facility/organization.mdx b/versioned_docs/version-3.0/concepts/facility/organization.mdx new file mode 100644 index 0000000..60f2c85 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/facility/organization.mdx @@ -0,0 +1,94 @@ +--- +sidebar_position: 2 +--- + +# Organizations + +An **organization** in Care is a grouping used to structure people and resources into a nested tree. It is how Care decides who can do what: roles are granted to users on an organization, and the permissions that come with those roles flow down to everything inside that branch of the tree. + +## What it represents + +In Care's FHIR-aligned model, an organization maps to the **Organization** resource. It captures: + +- **Identity** — a display name, description, and an open `metadata` bag for deployment-specific data +- **Classification** — a type that says what kind of grouping it is (a team, a governance unit, a role group, a supplier) +- **Tree position** — a parent organization, so groups nest into a hierarchy with roots, branches, and descendants +- **Membership** — links between users and the organization, each carrying a role that defines what those users can do + +An organization is not a single person or a single facility. It is the container that groups them, and the place where access is anchored. + +## Two kinds of organization + +Care has two organization trees that work the same way but live at different scopes: + +- **Organization** — instance-wide. This is the governance and permissions backbone for the whole deployment: geography, administrative units, supplier groups, and role groups that exist independently of any one facility. +- **Facility organization** — scoped to a single facility. This is how a facility is divided internally into departments and teams (for example, `Cardiology` or an emergency ward) with their own staff and access. + +Every facility has a single **root** facility organization at the top of its internal tree; departments and teams hang off it. + +## Types and classification + +An organization's type describes what the grouping is for: + +| Type | Meaning | +| --- | --- | +| `team` | A team or department-style grouping | +| `govt` | A governance or governmental unit, typically managed by a superadmin | +| `role` | A role group — a set of users who share a role across the deployment | +| `product_supplier` | A supplier organization, linked to the supply chain | + +Governance, role, and root organizations are restricted to superadmin management; ordinary teams are managed by facility and organization admins. + +## The tree and how access cascades + +Organizations nest into a tree. The key idea is **inheritance**: a permission held on an organization applies not just there but to every organization beneath it. If a user is an admin of a region, they are effectively an admin of every district, facility group, and team inside that region — without being added to each one individually. + +``` +Root organization + └─ Branch organization + └─ Child organization + └─ Team +``` + +A user added near the top of the tree carries their role's permissions all the way down. A user added to a single team has access only within that team. This makes the tree the natural unit for delegating administration as a deployment grows. + +Membership is also deliberate: belonging to an organization does not automatically grant access to everything it owns — only to the resources actually assigned to it and to what the user's role allows. + +## Permissions + +Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. + +Key instance-wide organization permissions: + +| Permission | Roles | +| --- | --- | +| Can View Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | +| Can Create Organizations | Admin | +| Can Delete Organizations | Admin | +| Can Manage Organizations | Admin, role-org Admin | +| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | +| Can List Users in an Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager | + +Key facility-organization permissions: + +| Permission | Roles | +| --- | --- | +| Can View Facility Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer | +| Can Create Facility Organizations | Facility Admin | +| Can Delete Facility Organizations | Facility Admin | +| Can Manage Facility Organizations | Facility Admin, Administrator | +| Can Manage Users in a Facility Organization | Facility Admin, Administrator | + +Roles are granted to users through organization and facility-organization memberships. Access is then scoped by the tree: a permission held at a parent organization cascades to all of its descendants, so checks walk the chain of ancestors above a given organization. Geo admins are a special case — they can manage and view facility organizations within the geography they administer, regardless of facility membership. When assigning a role to another user, an admin can only grant a role whose permissions are a subset of their own. + +## Related + +- Reference: [Organization (technical)](../../references/facility/organization.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Access control](../access/access-control.mdx) +- Concept: [User](../access/user.mdx) + +## FHIR reference + +Organizations align with the FHIR **Organization** resource — a nested grouping used to organize people and resources and to anchor permissions. Both the instance-wide and facility-scoped trees follow this model. diff --git a/versioned_docs/version-3.0/concepts/forms/_category_.json b/versioned_docs/version-3.0/concepts/forms/_category_.json new file mode 100644 index 0000000..f114257 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/forms/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Forms & Terminology", + "position": 7, + "key": "forms-concepts", + "link": { + "type": "generated-index", + "title": "Forms & Terminology", + "description": "Questionnaires that capture structured data, and the coded value sets that keep it consistent." + } +} diff --git a/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx b/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx new file mode 100644 index 0000000..23faf64 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 1 +--- + +# Questionnaires & Structured Data + +A **questionnaire** (also called a **form**) is a reusable, versioned definition of questions that Care presents to capture structured data about a patient or an encounter. It is how Care turns clinical and operational data entry — vitals, intake forms, assessments, checklists — into consistent, query-friendly records instead of free text. + +## What it represents + +A questionnaire and its answers together capture: + +- **The form definition** — a titled, versioned tree of questions (groups, text, numbers, dates, choices, quantities) with display rules and validation +- **The subject** — whether the form is answered about a **patient** or an **encounter** +- **The answers** — a stored set of responses for a subject, recorded when someone fills out and submits the form +- **Derived clinical data** — coded answers can automatically become [observations](../clinical/observation.mdx) on the encounter, so a vitals form populates the clinical record directly +- **Reusable templates** — saved "favourites" or order sets that pre-fill a response, optionally bundling medication requests and service orders + +A questionnaire is the blueprint; a response is one filled-out copy. One questionnaire can be answered many times, by many people, for many subjects. + +## Lifecycle + +A questionnaire definition moves through a small set of publication states: + +``` +draft → active → retired +``` + +- **draft** — being authored; not yet available for data entry +- **active** — published and accepting submissions. Active forms should not be edited in place +- **retired** — withdrawn from use; existing responses remain readable + +Only **active** questionnaires accept submissions. A submitted response is normally **completed**, and can later be marked **entered in error** to void it without deleting the history. Forms that support a save-then-finalise flow carry a submission envelope that moves from **draft** to **submitted**. + +## Types of question + +Questions are typed, which is what makes the captured data structured. Common types include groups (containers), text, numbers (integer, decimal), booleans, dates and times, single- or multi-select **choices**, **quantities** with units, and display-only notes. Choice and quantity questions draw their allowed answers from a [value set](./valueset.mdx), and conditional rules can show or hide a question based on earlier answers. + +## Relationships + +- **Patient / encounter** — every response is anchored to a [patient](../clinical/patient), and to an [encounter](../clinical/encounter.mdx) when answered during a visit +- **Observations** — coded answers materialise as [observations](../clinical/observation.mdx) linked back to the response +- **Value sets** — choice and quantity questions reference a [value set](./valueset.mdx) for their allowed answers +- **Organizations** — a questionnaire is scoped to one or more [organizations](../facility/organization.mdx), which controls who can see and submit it + +## Permissions + +Access to questionnaires is governed by a dedicated permission set; response templates have their own. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Read Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin, Organization Admin/Manager/Member | +| Can Submit Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Facility Admin, Organization Admin/Manager/Member | +| Can Create/Update Questionnaires | Administrator, Facility Admin | +| Can Archive Questionnaires | Administrator, Facility Admin | +| Can Manage Questionnaires | Administrator, Facility Admin, Organization Admin | +| Can Read Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | +| Can Create/Update Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. A questionnaire is attached to organizations, and access is decided by checking the user's roles against those organizations. Because permissions cascade down the organization tree, a role held at a parent organization also applies to the questionnaires scoped to its descendants. + +## Related + +- Reference: [Questionnaire (technical)](../../references/forms/questionnaire.mdx) +- Reference: [Questionnaire Response (technical)](../../references/forms/questionnaire-response.mdx) +- Reference: [Questionnaire Response Template (technical)](../../references/forms/questionnaire-response-template.mdx) +- Concept: [Value sets](./valueset.mdx) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's questionnaires are inspired by the FHIR **Questionnaire** resource, and stored answers align loosely with **QuestionnaireResponse**. The publication states (draft, active, retired) mirror FHIR's publication-status model, so forms map cleanly onto FHIR-based exchange. diff --git a/versioned_docs/version-3.0/concepts/forms/valueset.mdx b/versioned_docs/version-3.0/concepts/forms/valueset.mdx new file mode 100644 index 0000000..dc3368f --- /dev/null +++ b/versioned_docs/version-3.0/concepts/forms/valueset.mdx @@ -0,0 +1,70 @@ +--- +sidebar_position: 2 +--- + +# Value Sets & Coded Data + +A **value set** is a named, curated list of coded answers — the menu of valid options a form question can offer. It is how Care keeps coded data consistent: instead of free text, a question draws its allowed answers from a value set, so everyone records the same concept the same way and the data stays query-friendly. + +## What it represents + +A value set captures the *rules* for which coded concepts are valid, not a frozen list: + +- **A named collection** — a slug, display name, and description that questionnaires and clinical fields reference by name +- **Composition rules** — `include` and `exclude` clauses that pull concepts from one or more code systems (such as SNOMED CT, LOINC, or ICD), either by pinning specific codes or by filtering a system (for example, "all descendants of this code") +- **Coded answers** — each member concept is a code plus a human-readable display, drawn live from terminology servers rather than copied in +- **Provenance** — whether the value set is shipped and maintained by the platform or authored locally by a deployment + +A value set is not a list of codes stored in one place. It stores the *rules* for membership, and the actual codes are resolved in real time when a picker is searched or a submitted code is validated. Editing the rules immediately changes which codes the value set yields — there is nothing to rebuild. + +## Lifecycle + +A value set moves through a small set of publication states: + +``` +draft → active → retired +``` + +- **draft** — authored but not yet in use +- **active** — published and available to questionnaires and coded fields +- **retired** — no longer recommended for use; existing data that used it stays readable + +A fourth state, **unknown**, exists for value sets whose status is not established. + +## System vs. local value sets + +Value sets come in two flavours: + +- **System-defined** — shipped and maintained by the platform as shared terminology. Deployments should treat these as read-only. Their slugs use a reserved `system-` prefix. +- **Locally authored** — created by a deployment for its own terminology needs, using any non-reserved slug. + +This split lets the platform ship sensible defaults while still letting each site extend coded data for local workflows. + +## Relationships + +- **Questionnaires** — choice and quantity questions in a [questionnaire](./questionnaire.mdx) reference a value set for their allowed answers, which is the main place coded data is captured +- **Clinical fields** — coded fields on resources such as [conditions](../clinical/condition.mdx), [allergies](../clinical/allergy-intolerance.mdx), and [observations](../clinical/observation.mdx) bind to value sets so their codes stay consistent +- **Personalization** — individual users can favourite codes within a value set and see recently used codes surfaced in pickers; this is per-user convenience, not part of the value set definition + +## Permissions + +Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. Any authenticated user can read and search them — that is what powers the code pickers throughout the product. Authoring is gated to administrators. + +| Permission | Roles | +| --- | --- | +| Read / search value sets | Any authenticated user (shared reference data) | +| Create / update value sets | Administrator, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a role held at a parent organization cascades to its descendants. Because value sets are global reference data rather than patient- or encounter-scoped, read access is universal; the administrative roles above are what control who may author or change them, and system-defined value sets are read-only for everyone. + +## Related + +- Reference: [Value Set (technical)](../../references/forms/valueset.mdx) +- Concept: [Questionnaires & Structured Data](./questionnaire.mdx) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Condition](../clinical/condition.mdx) +- Concept: [Access control](../access/access-control.mdx) + +## FHIR reference + +Value sets align with the FHIR **ValueSet** resource: a composition of coded concepts drawn from one or more code systems, expressed as `include` / `exclude` clauses against those systems. This makes Care's coded data interoperable with external terminology services and FHIR-based systems. diff --git a/versioned_docs/version-3.0/concepts/medications/_category_.json b/versioned_docs/version-3.0/concepts/medications/_category_.json new file mode 100644 index 0000000..5f2136f --- /dev/null +++ b/versioned_docs/version-3.0/concepts/medications/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Medications", + "position": 2, + "key": "medications-concepts", + "link": { + "type": "generated-index", + "title": "Medications", + "description": "How medications are prescribed, administered, dispensed, and reconciled across a patient's care." + } +} diff --git a/versioned_docs/version-3.0/concepts/medications/medication.mdx b/versioned_docs/version-3.0/concepts/medications/medication.mdx new file mode 100644 index 0000000..0d6335d --- /dev/null +++ b/versioned_docs/version-3.0/concepts/medications/medication.mdx @@ -0,0 +1,87 @@ +--- +sidebar_position: 1 +--- + +# Medication + +A **medication** in Care is how the system tracks a drug across its whole journey for a patient — from the prescriber's intent, through what the pharmacy hands over, to what is actually given at the bedside and what the patient reports taking at home. It is not one record but a small family of related records that together describe the medication story for an encounter. + +## What it represents + +Care models medication as four distinct but connected resources, each answering a different question: + +- **Medication request** — what a prescriber *intends*: the drug, dose, route, timing, and PRN rules, grouped into a prescription for an encounter +- **Medication administration** — what was actually *given* (or attempted) to the patient, fulfilling a request +- **Medication dispense** — what the pharmacy *handed over*, drawing down inventory and optionally raising a charge +- **Medication statement** — what the patient *reports* taking, has taken, or intends to take, as told by the patient, a relative, or a clinician (not actively prescribed) + +Keeping these separate lets Care distinguish "ordered" from "given" from "dispensed" from "reported" — the difference that matters for medication reconciliation and safety. + +## The four resources + +| Resource | Captures | Anchored to | +| --- | --- | --- | +| Request | Prescriber intent (dose, route, timing) | Encounter, grouped in a prescription | +| Administration | The actual give event | A request, on an encounter | +| Dispense | Hand-over of stock | An inventory item at a location | +| Statement | Patient-reported medication use | Patient and encounter | + +A request can lead to many administrations (each scheduled dose) and many dispenses (refills). A statement stands on its own — it documents medication history, not an active order. + +## Lifecycle + +Each resource carries its own status. Drawn from the same plain-language strings the API uses: + +``` +Request: draft → active → on_hold → completed / stopped / cancelled +Administration: in_progress → completed / not_done / stopped +Dispense: preparation → in_progress → completed / declined / cancelled +Statement: active → on_hold → completed / stopped / not_taken / intended +``` + +A few terminal states (`entered_in_error`, plus `stopped` / `cancelled` / `declined` depending on the resource) close a record out. Cancelling a dispense automatically reverses its inventory draw-down and any attached charge, so stock and billing stay consistent. + +## Relationships + +- A **request** belongs to an **encounter** and is grouped under a **prescription**; the **patient** is always derived from the encounter, never set directly +- An **administration** points back to the **request** it fulfils +- A **dispense** consumes an **inventory item** at a **location**, may link to the **authorizing request**, and can raise a **charge item** for billing +- A **statement** links to the **patient** and the **encounter** where it was recorded + +Drugs and dose units are coded against SNOMED CT value sets, so "amoxicillin 500 mg, oral, twice daily" is structured data rather than free text. + +## Permissions + +Medication access splits along two access models. + +**Dispense** has dedicated, location-centric permissions — pharmacists work in the pharmacy and often have no encounter access, so dispensing keys off the dispensing location instead: + +| Permission | Roles | +| --- | --- | +| Pharmacist in Care | Facility Admin, Administrator, Pharmacist | +| Medication Dispense Read | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | +| Write Medication Dispense | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | + +**Requests, administrations, and statements** are clinical data on the encounter, so they are governed by the encounter clinical-data permissions: + +| Permission | Roles | +| --- | --- | +| Can Read encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — and dispense access is checked against the location's facility-organization rather than the encounter. + +## Related + +- Reference: [Medication Request](../../references/medications/medication-request.mdx) +- Reference: [Medication Administration](../../references/medications/medication-administration.mdx) +- Reference: [Medication Dispense](../../references/medications/medication-dispense.mdx) +- Reference: [Medication Statement](../../references/medications/medication-statement.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Supply](../supply/supply.mdx) +- Concept: [Billing](../billing/billing.mdx) + +## FHIR reference + +Care's medication resources align with FHIR: `MedicationRequest`, `MedicationAdministration`, `MedicationDispense`, and `MedicationStatement`. Care uses underscored status values (for example `on_hold`, `entered_in_error`) rather than the hyphenated FHIR spellings, and binds coded fields to SNOMED CT value sets. diff --git a/versioned_docs/version-3.0/concepts/scheduling/_category_.json b/versioned_docs/version-3.0/concepts/scheduling/_category_.json new file mode 100644 index 0000000..0ae9d41 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/scheduling/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Scheduling", + "position": 3, + "key": "scheduling-concepts", + "link": { + "type": "generated-index", + "title": "Scheduling", + "description": "Appointments, practitioner availability, and the token queues that move patients through a facility." + } +} diff --git a/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx b/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx new file mode 100644 index 0000000..da46e83 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 1 +--- + +# Scheduling & Appointments + +**Scheduling** in Care defines when a resource — a practitioner, a location, or a healthcare service — is available, and **appointments** record a patient being booked into a concrete time within that availability. Together they answer "who is free, when?" and "who is coming in, and at what time?" — the backbone of front-desk and clinic operations. + +## What it represents + +Scheduling spans a few related building blocks, in plain terms: + +- **Schedule** — a named, date-bounded block of availability attached to a bookable resource (for example, "Morning OPD", valid for the next quarter) +- **Availability** — how a schedule's time is divided: recurring weekly windows, slot length, and how many people each slot can hold +- **Exception** — a date range that blocks a resource regardless of its schedules (leave, holidays, one-off closures) +- **Slot** — a concrete, bookable time window generated from a schedule's availability +- **Booking (appointment)** — a patient placed into a slot, with a status that tracks them from proposed through to seen or cancelled + +A schedule describes *potential* availability; a booking is an *actual* appointment. One schedule produces many slots, and each slot can hold one or more bookings up to its capacity. + +## Bookable resources + +A schedule is never attached to a patient — it is attached to whatever the patient comes to see. Care supports three kinds of bookable resource: + +| Resource type | What gets booked | +| --- | --- | +| Practitioner | A clinician or staff member who is a part of the facility | +| Location | A room, bed, or area within the facility | +| Healthcare service | A named service offering (for example, a vaccination clinic) | + +When booking, clients name the resource by its type and id; Care resolves the underlying practitioner, location, or service behind the scenes. + +## Appointment lifecycle + +A booking moves through a status as the patient progresses. The common path is: + +``` +proposed → pending → booked → arrived → checked_in → in_consultation → fulfilled +``` + +Other terminal or branch states include `noshow` (patient did not arrive), `waitlist`, and the cancellation states `cancelled`, `rescheduled`, and `entered_in_error`. Cancelling and rescheduling do not happen through a plain status edit — they go through dedicated cancel and reschedule actions, which also free up the slot's capacity. A booking already `in_consultation` cannot be cancelled. + +## Relationships + +- A **booking** links a **patient** to a **slot**, and can carry an associated [encounter](../clinical/encounter.mdx), a queue [token](./token.mdx), and a billing charge. +- A **schedule** lives inside a **facility** and points at one bookable resource. +- When a schedule defines a charge, a booking made against it can automatically raise the matching [billing](../billing/billing.mdx) charge; queue-style workflows issue a [token](./token.mdx) so patients can be called in order. + +## Permissions + +Access to schedules and bookings is governed by the schedule permission set. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create on Schedule | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can list schedule on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can update bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can reschedule bookings on Object | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. For practitioner schedules, access is decided against the organizations the practitioner belongs to within the facility; for locations and healthcare services, against that resource's managing organization. + +## Related + +- Reference: [Schedule & availability (technical)](../../references/scheduling/schedule.mdx) +- Reference: [Booking (technical)](../../references/scheduling/booking.mdx) +- Concept: [Token](./token.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Healthcare service](../facility/healthcare-service.mdx) +- Concept: [Location](../facility/location.mdx) + +## FHIR reference + +Scheduling is FHIR-aligned: a schedule's slots map to the FHIR **Slot** resource, and a booking maps to the FHIR **Appointment** resource. Care's API field names may differ from the FHIR element names. diff --git a/versioned_docs/version-3.0/concepts/scheduling/token.mdx b/versioned_docs/version-3.0/concepts/scheduling/token.mdx new file mode 100644 index 0000000..b3e8731 --- /dev/null +++ b/versioned_docs/version-3.0/concepts/scheduling/token.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# Tokens & Queues + +A **token** in Care is a numbered place in a queue for a walk-in or queue-based visit. Tokens let a facility manage flow when patients are not booked into specific appointment slots — each patient draws a numbered token in a queue tied to a practitioner, location, or service, and is called in turn. + +## What it represents + +A token captures one patient's position in a queue, and the queue structures the waiting line around a resource: + +- **The token** — a number issued to a patient, its category (e.g. General, Priority), an optional note, and its current status +- **The queue** — the waiting line for one schedulable resource (practitioner, location, or healthcare service) on one date +- **Sub-queues** — optional splits of a queue so the same resource can serve from several physical points (e.g. multiple vaccination rooms, each drawing its own tokens) +- **Categories** — reusable labels per facility that group and prioritize tokens, each with a short code shown on displays + +A token is for managing the live waiting line. It is distinct from a booked appointment, though a token can be linked to a booking when one exists. + +## Lifecycle + +A token moves through these states as it is served: + +``` +CREATED → IN_PROGRESS → FULFILLED + ↘ CANCELLED + ↘ ENTERED_IN_ERROR (on delete) +``` + +- **CREATED** — the token has been issued and is waiting to be served +- **IN_PROGRESS** — the patient is being served (set when the token becomes a point's current token) +- **FULFILLED** — service is complete +- **CANCELLED** — the token was cancelled +- **ENTERED_IN_ERROR** — applied automatically when a token is deleted (a soft delete; the record is retained) + +Queue progression — which token is current and who is next — is maintained by the platform as staff advance the line, not set directly by the person issuing the token. + +## Classification + +- **By category** — every token belongs to a category (such as General or Priority). Numbering runs per category within a queue, so two categories in the same queue each count from 1. +- **By resource type** — a queue is bound to one of three schedulable resource types: a **practitioner**, a **location**, or a **healthcare service**. This binding determines who can manage and see the queue. + +## Relationships + +- **Patient** — a token can belong to a [patient](../clinical/patient); one patient may hold more than one token. +- **Resource** — every queue is tied to a schedulable resource through [Scheduling](./scheduling.mdx). +- **Booking** — a token may link to a booking, and through it to the associated [encounter](../clinical/encounter.mdx) when one exists. + +## Permissions + +Token access is governed by facility-scoped permissions. Whether a user can see or manage a queue is decided by their membership in the facility organization that owns the resource the queue is bound to. + +| Permission | Roles | +| --- | --- | +| Can Create on Token | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Can list token on Object | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Can Create on Token Category | Administrator, Staff, Facility Admin | +| Can list token category on Facility | Administrator, Staff, Facility Admin, Doctor, Nurse | + +Roles are granted to users through facility-organization memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a user's reach over a queue follows the organization that manages the queue's practitioner, location, or healthcare service. + +## Related + +- Reference: [Token (technical)](../../references/scheduling/token.mdx) +- Concept: [Scheduling](./scheduling.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Tokens and queues are Care's model for walk-in flow and do not map to a single FHIR resource. They build on Care's FHIR-aligned scheduling primitives — the schedulable resource and booking — to manage the live waiting line. diff --git a/versioned_docs/version-3.0/concepts/supply/_category_.json b/versioned_docs/version-3.0/concepts/supply/_category_.json new file mode 100644 index 0000000..bed362b --- /dev/null +++ b/versioned_docs/version-3.0/concepts/supply/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Supply & Inventory", + "position": 5, + "key": "supply-concepts", + "link": { + "type": "generated-index", + "title": "Supply & Inventory", + "description": "Products, stock, and the requests and deliveries that keep a facility supplied." + } +} diff --git a/versioned_docs/version-3.0/concepts/supply/supply.mdx b/versioned_docs/version-3.0/concepts/supply/supply.mdx new file mode 100644 index 0000000..dc615da --- /dev/null +++ b/versioned_docs/version-3.0/concepts/supply/supply.mdx @@ -0,0 +1,93 @@ +--- +sidebar_position: 1 +--- + +# Inventory & Supply + +**Inventory & supply** is how Care tracks what physical items a facility stocks, how much of each is on hand, and how items move between stores, wards, suppliers, and patients. It is the operational backbone behind medications, nutritional products, and consumables — keeping stock counts accurate as goods are received, transferred, and dispensed. + +## What it represents + +Care models supply as a small set of connected resources, each answering a different question: + +- **Product knowledge** — the reusable catalogue definition of an item (its name, codes, base unit, ingredients or nutrients, and storage guidelines). It is the "what is this item" record, defined once per instance or per facility. +- **Product** — a concrete, batch-level instance of a catalogue item at a facility, carrying batch-specific detail like lot number, expiry, and purchase price. +- **Inventory item** — the current on-hand quantity of one product at one facility location (for example, a ward pharmacy or central store). +- **Supply request** — a request to move a quantity of a catalogue item into a destination location, grouped under an order. +- **Supply delivery** — a record of items actually moving — into a facility from a supplier, between locations, or out to a patient — grouped under a delivery order. + +Stock balances are not entered by hand. Care derives the on-hand quantity for each location from the deliveries that bring stock in and the dispenses that take it out, so availability stays consistent with what actually happened. + +## Catalogue vs. stock + +It helps to separate the *idea* of an item from the *thing on the shelf*: + +- **Catalogue** (product knowledge) describes an item in the abstract — paracetamol 500 mg tablets, defined once and reused everywhere. +- **Stock** (product, then inventory item) is a specific batch of that item sitting in a specific location, with a real quantity that goes up and down. + +A catalogue entry can be defined instance-wide (shared across all facilities) or scoped to a single facility. Each product references exactly one catalogue entry, so naming and coding live in one place rather than being copied onto every batch. + +## How stock moves + +Stock changes through two ordered workflows. A **request** signals intent ("we need this here"); a **delivery** records the actual movement. + +``` +Supply request: draft → active → processed → completed + ↘ suspended / cancelled +Supply delivery: in_progress → completed + ↘ abandoned +``` + +Both flows are grouped under orders. A **request order** describes items wanted at a destination location, optionally from a supplier organization or an origin location. A **delivery order** records the matching shipment and starts in `draft` or `pending` before progressing. + +A delivery has two shapes depending on where stock comes from: + +- **External delivery** — the order has no origin location, so goods arrive from a supplier. The delivery names the product received. +- **Intra-facility move** — the order has an origin location, so stock transfers between two locations within the facility. The delivery draws from a specific inventory item (batch). + +A delivery order can also dispense directly to a patient. When a delivery completes — or a dispense changes — Care recomputes the affected inventory item so its on-hand quantity reflects everything that has moved in and out. + +## Relationships + +Supply ties together several other parts of Care: + +- **Location** — every inventory item, request, and delivery is anchored to a [facility location](../facility/location.mdx); access is scoped through it. +- **Facility** — products and catalogue entries belong to a [facility](../facility/facility.mdx), and stock is counted per facility location. +- **Organization** — suppliers are [organizations](../facility/organization.mdx) marked as product suppliers. +- **Medication** — dispensing a [medication](../medications/medication.mdx) draws down inventory, keeping clinical and stock records in sync. +- **Billing** — products can link to a charge definition and delivery orders to an invoice, so issued items can be billed. + +## Permissions + +Access to supply resources is governed by facility-scoped permissions. The main ones, with the roles that hold them by default: + +| Permission | Roles | +| --- | --- | +| Can Read Product | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product on Facility | Facility Admin, Admin | +| Can Read Product Knowledge | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product Knowledge on Facility | Facility Admin, Admin | +| Can Read Inventory Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Read Supply Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Request on Facility | Facility Admin, Admin, Staff, Doctor, Nurse | +| Can Read Supply Delivery | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Delivery on Facility | Facility Admin, Admin | +| Can Create External Supply Delivery on Facility | Facility Admin, Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access to a location's inventory, requests, and deliveries is checked against the facility organizations that own that location, and a permission held at a parent organization cascades to its descendants in the organization tree. In practice, clinical and pharmacy staff can read stock and raise supply requests, while creating catalogue items and recording deliveries is reserved for facility administrators. + +## Related + +- Reference: [Product](../../references/supply/product.mdx) +- Reference: [Product knowledge](../../references/supply/product-knowledge.mdx) +- Reference: [Inventory item](../../references/supply/inventory-item.mdx) +- Reference: [Supply request](../../references/supply/supply-request.mdx) +- Reference: [Supply delivery](../../references/supply/supply-delivery.mdx) +- Concept: [Medication](../medications/medication.mdx) +- Concept: [Location](../facility/location.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Billing](../billing/billing.mdx) + +## FHIR reference + +These resources are FHIR-aligned: product knowledge maps to FHIR `MedicationKnowledge` / `NutritionProduct`, and the request and delivery records align with FHIR `SupplyRequest` and `SupplyDelivery`. Coded fields use Care's own snake_case status and category values rather than FHIR URIs. diff --git a/versioned_docs/version-3.1/concepts/access/_category_.json b/versioned_docs/version-3.1/concepts/access/_category_.json new file mode 100644 index 0000000..dd92a2c --- /dev/null +++ b/versioned_docs/version-3.1/concepts/access/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Access & Identity", + "position": 8, + "key": "access-concepts", + "link": { + "type": "generated-index", + "title": "Access & Identity", + "description": "Who can do what in Care — users, roles, and the permission model that governs access." + } +} diff --git a/versioned_docs/version-3.1/concepts/access/access-control.mdx b/versioned_docs/version-3.1/concepts/access/access-control.mdx new file mode 100644 index 0000000..d2328d5 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/access/access-control.mdx @@ -0,0 +1,101 @@ +--- +sidebar_position: 1 +--- + +# Roles & Permissions + +Care decides what each person can see and do using **role-based access control (RBAC)**. A **permission** is the right to perform one action (for example, "Can Create Patient"); a **role** is a named bundle of permissions; and a role is granted to a user *within a boundary* — a facility, an organization, or a single patient. Access is never assigned to a user directly: it always flows permission → role → membership. + +## What it represents + +The access-control model captures three things working together: + +- **Permissions** — the smallest unit of access, one per action, each tagged with a **context** (the kind of resource it governs). Permissions are defined in code, not edited by users. +- **Roles** — flat, named collections of permissions (for example, *Doctor* or *Nurse*). A role is not a job title or a type; it is just "this set of permissions." Built-in roles ship with Care; deployments can add their own. +- **Memberships** — the link that grants a role to a user inside a specific boundary. The same user can hold *Nurse* in one facility and *Administrator* in an organization at the same time. + +A user's effective access in any context is the **union** of all permissions from every role they hold that reaches that context. + +## Standard roles + +Care seeds a set of built-in (system) roles. These cannot be edited or deleted, and they apply within the boundaries shown below. + +| Role | Applies in | What it is for | +| --- | --- | --- | +| Doctor | Facility, Government org | Clinicians who create encounters and read/write clinical data | +| Nurse | Facility, Government org | Bedside care staff with clinical read/write access | +| Staff | Facility, Government org | Front-desk and operational staff: registration, scheduling, non-clinical work | +| Pharmacist | Facility | Medication and pharmacy workflows | +| Volunteer | Facility, Government org | Limited helpers — can list patients and view responses, but not full clinical data | +| Administrator | Facility, Government org | Operational admin within a boundary: manages users, facilities, and organizations | +| Facility Admin | Facility | Full administrator of a single facility (assigned to whoever creates it) | +| Admin | Facility, Government org | The broadest administrative role, including creating and deleting organizations | +| Admin (role org) | Role organization | Administers a user-group ("role") organization and its connected groups | +| Manager (role org) | Role organization | Manages members within a role organization | +| Member (role org) | Role organization | Plain membership in a role organization | + +Deployments can also define **custom roles** with any chosen set of permissions — for example "Doctor (Read Only)" or "Scheduler." A custom role is just a different bundle; the system treats it exactly like a built-in one. + +## Boundaries and the organization tree + +A role is always granted *inside a boundary*, and the boundary type is one of three **role contexts**: + +``` +FACILITY → role applies within a facility +GOVT_ORG → role applies within a government organization +ROLE_ORG → role applies within a role (user-group) organization +``` + +Memberships are recorded by boundary type: + +- **OrganizationUser** — a user holds a role in a government or role organization. +- **FacilityOrganizationUser** — a user holds a role in a facility (or one of its sub-departments). +- **PatientUser** — a user holds a role scoped to a single patient. + +Organizations form a **tree**: a government organization can contain sub-organizations, and a facility can contain departments. A role granted at a parent **cascades to every descendant** — if you are an Administrator of a district, you hold that access in all facilities and units beneath it, without a membership at each one. When Care checks access, it looks at the target plus all of its ancestors and collects every permission you hold along that chain. + +## How a permission is decided + +Each permission carries a **permission context** describing the resource it governs. When Care serializes a resource for a user, it only counts permissions in the relevant contexts: + +| Context | Governs | +| --- | --- | +| `GENERIC` | Not tied to a specific resource type | +| `FACILITY` | Facility-level actions | +| `PATIENT` | A patient record and its data | +| `ENCOUNTER` | A single encounter | +| `ORGANIZATION` | A government or role organization | +| `FACILITY_ORGANIZATION` | A facility organization (department) | +| `QUESTIONNAIRE` | Questionnaires | + +So a request to read a patient resolves to "which roles do I hold that reach this patient, and do any of them carry a `PATIENT`/`FACILITY` permission for this action?" The answer is computed live from the user's memberships and the organization tree. + +## Permissions + +Permissions are declared in code with a display name, a context, and the default roles that hold them. A few representative examples: + +| Permission | Roles | +| --- | --- | +| Can Create Patient | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Create encounter | Doctor, Nurse, Admin, Facility Admin | +| Can create User in care | Admin, Facility Admin, Administrator | +| Can View Organizations | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | +| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | +| Can Create Organizations | Admin | +| Can Delete Organizations | Admin | + +Roles are granted to users through organization, facility-organization, or patient memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective permissions in any context are the union of all roles that reach it. Permissions themselves are platform-maintained reference data — administrators assign roles, not individual permissions. + +## Related + +- Reference: [Role (technical)](../../references/access/role.mdx) +- Reference: [Permission (technical)](../../references/access/permission.mdx) +- Reference: [Permission association (technical)](../../references/access/permission-association.mdx) +- Concept: [User](./user.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Facility](../facility/facility.mdx) + +## FHIR reference + +Care's roles and permissions are an internal authorization model rather than a clinical resource, so they do not map to a single FHIR resource. They align in spirit with FHIR's access-control concepts (such as the `Permission` and `Role`/`PractitionerRole` resources), but enforcement is Care-specific. diff --git a/versioned_docs/version-3.1/concepts/access/user.mdx b/versioned_docs/version-3.1/concepts/access/user.mdx new file mode 100644 index 0000000..5bd951f --- /dev/null +++ b/versioned_docs/version-3.1/concepts/access/user.mdx @@ -0,0 +1,64 @@ +--- +sidebar_position: 2 +--- + +# Users + +A **user** in Care is an account that a person — or a machine integration — uses to sign in and act in the system. Users are the *who* behind every record: a user creates a patient, documents an encounter, or places an order, and the system tracks what each account is allowed to do through roles and organizations. + +## What it represents + +A user account captures: + +- **Identity & profile** — name (with prefix and suffix), username, gender, date of birth, and profile picture +- **Contact** — phone number, alternate phone, and email +- **Clinician credentials** — qualification, medical council registration, experience, and weekly working hours (for staff who deliver care) +- **Authentication & security** — password, multi-factor authentication (TOTP and backup codes), and web-push notification keys +- **Placement** — the geographic organization and facility a user belongs to, plus the roles they hold in each +- **Account type** — whether the account is a real person or a service account used by an integration + +A user is *not* the same as a role. The account is the identity; the roles attached to it (in one or more organizations) decide what that identity can do. + +## Types of accounts + +| Type | Purpose | +| --- | --- | +| Human user | A person who signs in — clinicians, nurses, registration staff, administrators | +| Service account | A non-human account used by an integration or automation to talk to Care's API | + +Clinician fields such as qualification and council registration are only meaningful for staff who provide care; administrative and service accounts leave them blank. + +## Relationships + +- **Organizations & facilities** — a user is placed in a geographic organization and can be assigned roles across many organizations and facilities. This placement is what grants access. +- **Patients & encounters** — when a user creates or updates a clinical record, the account is recorded as the actor; clinical history stays auditable to the user who entered it. +- **Skills** — users can be tagged with skills (competencies) for scheduling and discovery. + +## Identifiers + +Each user has a stable public identifier (surfaced as `id` in the API) that is separate from the username. Usernames, phone numbers, and emails must each be unique across the system, so they can also locate an account during sign-in and administration. + +## Permissions + +User administration is governed by the user permission set. The two key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can create User in care | Admin, Facility Admin, Administrator | +| Can list Users in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | + +Creating users is reserved for administrators, while most clinical and support roles can list and view other users in their facility. Roles are granted to a user through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A superuser bypasses these checks entirely. + +For the broader model of how roles, permissions, and organizations combine to decide access, see [Access control](./access-control.mdx). + +## Related + +- Reference: [User & Skills (technical)](../../references/access/user.mdx) +- Concept: [Access control](./access-control.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Facility](../facility/facility.mdx) +- Concept: [Patient](../clinical/patient) + +## FHIR reference + +A care-providing user aligns with FHIR's **Practitioner** resource, and a user's role within an organization aligns with **PractitionerRole**. Care keeps the account identity and its organization-scoped roles as related but distinct ideas, mirroring that separation. diff --git a/versioned_docs/version-3.1/concepts/billing/_category_.json b/versioned_docs/version-3.1/concepts/billing/_category_.json new file mode 100644 index 0000000..0dce028 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/billing/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Billing", + "position": 4, + "key": "billing-concepts", + "link": { + "type": "generated-index", + "title": "Billing", + "description": "How charges, accounts, invoices, and payments come together to bill for care." + } +} diff --git a/versioned_docs/version-3.1/concepts/billing/billing.mdx b/versioned_docs/version-3.1/concepts/billing/billing.mdx new file mode 100644 index 0000000..b316d08 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/billing/billing.mdx @@ -0,0 +1,100 @@ +--- +sidebar_position: 1 +--- + +# Billing & Accounts + +**Billing** in Care is how the cost of care is recorded, grouped, invoiced, and settled. Its anchor is the **account** — a financial bucket that aggregates everything charged to a patient within a facility — so that charges, invoices, and payments all hang together as one coherent financial history. + +## What it represents + +Billing is not a single resource but a small family of resources that work together: + +- **Account** — a per-patient, per-facility bucket that aggregates charges and tracks running balances. One open account is created automatically for a patient when the first charge is raised; it can be balanced and closed once care is complete. +- **Charge item** — a single billable line for a service or product (a consultation, a dispensed medication, a bed-day). It records what was charged, the quantity, and the resolved price. +- **Charge item definition** — the reusable pricing template that answers "how much does this cost", binding a service to its base rate, surcharges, discounts, and taxes. +- **Invoice** — a billable grouping of charge items for one account, with snapshotted line items and computed totals, issued to the patient or payer. +- **Payment reconciliation** — a record of a payment, advance, or credit note made against an account (and optionally a specific invoice), capturing how, when, and how much was paid. + +Together these answer: what was charged, what it costs, what was billed, and what was paid. + +## How the pieces fit + +``` +Charge item definition ──(applied to)──▶ Charge item ──(placed on)──▶ Account + │ ▲ + (grouped into) (settled by) + ▼ │ + Invoice ◀──(paid via)── Payment reconciliation +``` + +A charge item is usually built from a **definition**, placed on the patient's default **account**, then grouped into an **invoice**. A **payment reconciliation** records money received against the account or invoice. Prices, totals, and balances are computed by the platform — clients record the facts, the system does the arithmetic. + +## Lifecycle + +Each billing resource has its own status, and the invoice status drives the charge item lifecycle. + +Account billing status: + +``` +open → billing → closed (completed / voided / bad debt / combined) +``` + +Charge item: + +``` +billable → billed → paid (or → not_billable / aborted / entered_in_error) +``` + +Invoice: + +``` +draft → issued → balanced (or → cancelled / entered_in_error) +``` + +A new account opens as `active` / `open` and keeps accruing charges until billing begins and it is eventually closed. A charge starts `billable`, becomes `billed` when it lands on an invoice, and `paid` once settled. An invoice begins as a `draft` (still editable), is `issued` to the payer, and is marked `balanced` when fully settled. Totals are recomputed automatically as charges, invoices, and payments change. + +## Relationships + +- Every account and charge item belongs to a **patient** and a **facility**; a charge item and an account may optionally reference an **encounter**. +- A charge item can originate from another resource — a service request, a medication dispense, an appointment, or a bed association — recorded as its service source. +- Invoices and payment reconciliations are always created against an **account**, and a payment may additionally be allocated to a single invoice. + +## Permissions + +Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The key permissions: + +| Permission | Roles | +| --- | --- | +| Can Read Account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Account / Can Update Account | Facility Admin, Admin | +| Can Create Charge Item | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Update Charge Item / Can Cancel Charge Item | Facility Admin, Admin | +| Can Create Negative Charge Item | Facility Admin, Admin | +| Can Read Charge Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Read Charge Item Definition | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Charge Item Definition on Facility / Can Set Charge Item Definition on Facility | Facility Admin, Admin | +| Can Write Invoice | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Invoice | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Invoice / Can Manage Locked Invoice | Facility Admin, Admin | +| Can Write Payment Reconciliation | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Payment Reconciliation | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Payment Reconciliation | Facility Admin, Admin | + +A broad set of clinical roles can read billing and raise charges, invoices, and payments, while creating or editing accounts, editing or cancelling charges, defining prices, and destroying or unlocking invoices are reserved for administrators. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendant facilities and locations. + +## Related + +- Reference: [Account](../../references/billing/account.mdx) +- Reference: [Charge item](../../references/billing/charge-item.mdx) +- Reference: [Charge item definition](../../references/billing/charge-item-definition.mdx) +- Reference: [Invoice](../../references/billing/invoice.mdx) +- Reference: [Payment reconciliation](../../references/billing/payment-reconciliation.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Facility](../facility/facility.mdx) +- Concept: [Supply](../supply/supply.mdx) + +## FHIR reference + +The billing resources are FHIR-aligned: the account maps to the FHIR **Account** resource, charge items and their definitions to **ChargeItem** and **ChargeItemDefinition**, the invoice to **Invoice**, and payments to **PaymentReconciliation**. Care's enum values use underscores (e.g. `entered_in_error`) rather than the FHIR-style hyphenated forms, and some field names differ from the FHIR spec. diff --git a/versioned_docs/version-3.1/concepts/clinical/_category_.json b/versioned_docs/version-3.1/concepts/clinical/_category_.json index 0e9fee9..db8262a 100644 --- a/versioned_docs/version-3.1/concepts/clinical/_category_.json +++ b/versioned_docs/version-3.1/concepts/clinical/_category_.json @@ -1,5 +1,10 @@ { "label": "Clinical", "position": 1, - "key": "clinical-concepts" + "key": "clinical-concepts", + "link": { + "type": "generated-index", + "title": "Clinical", + "description": "The clinical primitives a patient record is built from — encounters, conditions, allergies, observations, diagnostics, specimens, orders, consent, and notes." + } } diff --git a/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx b/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx new file mode 100644 index 0000000..25a27af --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 4 +--- + +# Allergy & Intolerance + +An **allergy or intolerance** records a patient's known risk of an adverse reaction to a substance — a food, a medication, an environmental trigger, or a biologic. It is part of the patient's longitudinal record and is meant to be checked before prescribing, ordering, or administering anything that could cause harm. + +## What it represents + +Each allergy or intolerance entry captures: + +- **The substance** — a coded allergen drawn from a curated SNOMED CT list, so the record can be matched against medications rather than read as free text +- **Whether it is an allergy or an intolerance** — an immune-mediated allergy versus a non-immune intolerance +- **Category** — food, medication, environment, or biologic +- **How certain and how serious it is** — a verification level (how confirmed the report is) and a criticality (the potential for harm) +- **Clinical state** — whether the allergy is currently active, inactive, or resolved +- **Timing** — when it started, when it was first recorded, and the most recent known reaction +- **Context** — the encounter it was recorded in and an optional free-text clinical note + +An entry is always recorded in the context of an encounter, and the patient is derived from that encounter — you do not attach an allergy to a patient directly. + +## Lifecycle + +The clinical state of an allergy moves through three values: + +``` +active → inactive → resolved +``` + +- **Active** — the allergy is currently relevant and should be considered during care +- **Inactive** — no longer thought to be relevant, but kept on the record +- **Resolved** — the patient is no longer believed to have this allergy + +Alongside the clinical state, a **verification status** (unconfirmed, presumed, confirmed, refuted, or entered-in-error) records how trustworthy the assertion is — for example, a self-reported allergy may sit as `unconfirmed` until a clinician confirms it. + +## Types & classification + +- **Type** — `allergy` (an immune response) or `intolerance` (a non-immune adverse reaction) +- **Category** — `food`, `medication`, `environment`, or `biologic` +- **Criticality** — `low`, `high`, or `unable_to_assess`, signalling the potential clinical harm of a future reaction + +## Relationships + +- Every allergy belongs to a **patient** and is anchored to the **encounter** in which it was recorded. +- The substance is a coded **value set** concept, which is what lets medication ordering and other business logic flag potential conflicts. +- Because an allergy is tied to its patient and encounter, it never outlives them; moving an entry to a different encounter is handled by the platform as a maintained copy. + +## Permissions + +Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient clinical-data** and **encounter clinical-data** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Doctor, Nurse, Staff, Administrator, Facility Admin | +| Can Update a Patient's data | Doctor, Nurse, Staff, Administrator, Facility Admin | +| Update Encounter related clinical data | Doctor, Nurse, Administrator, Facility Admin | + +Reading allergies requires "Can view clinical data about patients"; creating an entry requires "Can Update a Patient's data"; updating one requires "Update Encounter related clinical data" on its encounter. These roles are granted to users through organization, facility-organization, or direct patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants, so a user with the right role on a facility automatically reaches the patients and encounters beneath it. + +## Related + +- Reference: [Allergy & Intolerance (technical)](../../references/clinical/allergy-intolerance.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Condition](../clinical/condition.mdx) +- Concept: [Medication](../medications/medication.mdx) + +## FHIR reference + +Care aligns this resource to the FHIR `AllergyIntolerance` resource, and the clinical state, verification, category, and criticality values follow the corresponding FHIR code systems. diff --git a/versioned_docs/version-3.1/concepts/clinical/condition.mdx b/versioned_docs/version-3.1/concepts/clinical/condition.mdx new file mode 100644 index 0000000..3cde8ff --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/condition.mdx @@ -0,0 +1,83 @@ +--- +sidebar_position: 3 +--- + +# Condition + +A **condition** in Care records a clinical problem, diagnosis, or symptom for a patient — for example a chronic illness on the problem list, a diagnosis made during a visit, or a presenting complaint. It is part of the patient's longitudinal clinical record and is always captured in the context of an encounter. In the Care product UI conditions are surfaced as **Symptoms**. + +## What it represents + +A condition captures, in plain terms: + +- **What the problem is** — a coded clinical finding (drawn from SNOMED CT), not free text, so it can be searched, summarized, and exchanged +- **How certain it is** — whether the condition is confirmed, provisional, suspected, or refuted +- **What kind of problem it is** — a problem-list item, an encounter diagnosis, or a chronic condition +- **How serious it is** — an optional severity (mild, moderate, severe) +- **When it started and stopped** — onset and abatement, given as a date, an age, or a description +- **Where it belongs** — the patient it concerns and the encounter it was recorded in, plus an optional clinical note + +A condition is distinct from an allergy or an observation: it is a problem the patient *has*, recorded and tracked over time, rather than a measurement or a reaction. + +## Classification + +Every condition is classified so it shows up in the right place in the record: + +| Category | What it means | +| --- | --- | +| Problem list item | An ongoing problem tracked on the patient's problem list | +| Encounter diagnosis | A diagnosis made during a specific visit | +| Chronic condition | A long-term condition carried across encounters | + +## Lifecycle + +A condition's **clinical status** describes where the problem stands now, and its **verification status** describes how sure the clinician is. These move independently. + +Clinical status: + +``` +active → inactive → resolved +active → remission +active → recurrence / relapse +(unknown when not yet established) +``` + +Verification status: + +``` +unconfirmed → provisional → differential → confirmed +(refuted or entered_in_error when ruled out or mistaken) +``` + +Verification status must always be set; a condition is never recorded without saying how certain it is. + +## Relationships + +- **Patient** — every condition belongs to one patient and forms part of their clinical history. +- **Encounter** — a condition is always recorded within an encounter; Care derives the patient from that encounter, so clinicians never attach a condition to a patient directly. + +Because the patient is taken from the encounter, conditions stay tied to the visit where they were documented while still rolling up into the patient's overall record. + +## Permissions + +Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** clinical-data permission and the **encounter** clinical-data permissions, since every condition lives inside an encounter for a patient. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective roles on a patient are resolved across their organization, the patient's encounters and locations, and any direct patient assignment. Reading or writing a condition therefore requires the right clinical-data permission on the patient or the encounter it belongs to. + +## Related + +- Reference: [Condition (technical)](../../references/clinical/condition.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Allergy / intolerance](../clinical/allergy-intolerance.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +A condition aligns with the FHIR **Condition** resource. Its coded `code` is bound to a SNOMED CT clinical-finding value set, and its clinical-status, verification-status, category, and severity values follow the corresponding FHIR concepts. diff --git a/versioned_docs/version-3.1/concepts/clinical/consent.mdx b/versioned_docs/version-3.1/concepts/clinical/consent.mdx new file mode 100644 index 0000000..c803707 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/consent.mdx @@ -0,0 +1,85 @@ +--- +sidebar_position: 9 +--- + +# Consent + +A **consent** in Care records a patient's decision — to permit or deny — for a defined category of activity, such as treatment, research participation, or sharing of their information. It captures what the patient agreed to, when it applies, and who verified it, so that care teams have an auditable record of the patient's wishes. + +## What it represents + +Consent maps to the FHIR **Consent** resource. Each record captures: + +- **Decision** — whether the patient permits or denies the activity +- **Category** — what the consent is about (treatment, privacy, research, advance directives, and so on) +- **Validity** — the date it was recorded and the period during which it applies +- **Verification** — who confirmed the consent and how (for example, by a family member) +- **Supporting documents** — scanned or uploaded consent forms attached to the record +- **Encounter linkage** — the visit the consent was captured during + +A consent is always anchored to an encounter, and the owning patient is reached through that encounter. The patient's history is the container that makes their consents coherent over time. + +## Decision + +Every consent states one of two outcomes: + +- **Permit** — the patient grants consent for the activity +- **Deny** — the patient refuses consent for the activity + +## Types + +The category describes what kind of activity the consent governs: + +| Category | Meaning | +| --- | --- | +| Treatment | Consent to receive treatment | +| Patient privacy | Disclosure or sharing of patient information | +| Research | Participation in research | +| DNR | Do-not-resuscitate directive | +| Comfort care | Comfort / palliative care directive | +| Advance care directive | A patient's advance care directive | +| Advance directive (other) | Other advance directive | + +## Lifecycle + +A consent moves through a small set of statuses that describe whether it is in force: + +``` +draft → active → inactive + ↘ not_done + ↘ entered_in_error +``` + +- **draft** — being prepared, not yet in force +- **active** — currently in force +- **inactive** — no longer in force +- **not_done** — the consent activity did not take place +- **entered_in_error** — recorded by mistake; kept for audit but disregarded + +Status is recorded directly on the consent; there is no automatic state machine, so a record can be marked `entered_in_error` or `inactive` as a plain update while the history remains auditable. + +## Relationships + +A consent belongs to a single **encounter**, and an encounter can carry many consents. The **patient** is reached through that encounter, so a consent is part of the patient's longitudinal record. Verification entries reference the **user** who confirmed the consent, and uploaded consent forms are linked as supporting attachments. + +## Permissions + +Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the patient permissions defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access to a specific consent is decided by the roles a user holds on its patient — gathered through the patient's encounters, locations, owning organizations, and any direct patient association. Because access is scoped by the organization tree, a permission held at a parent organization cascades to its descendants. + +## Related + +- Reference: [Consent (technical)](../../references/clinical/consent.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [User](../access/user.mdx) + +## FHIR reference + +Consent aligns with the FHIR **Consent** resource: `status`, `category`, `decision`, and `period` map to their FHIR counterparts. diff --git a/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx b/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx new file mode 100644 index 0000000..d76bd81 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 6 +--- + +# Diagnostic Report + +A **diagnostic report** in Care holds the results and interpretation of a diagnostic test or investigation — a lab panel, an imaging study, or a similar workup. It is the answer that closes the loop on an order: every report fulfils exactly one [service request](./service-request.mdx) and is anchored to the patient and encounter the order was raised under. + +## What it represents + +In Care's FHIR-aligned model, a diagnostic report maps to the **DiagnosticReport** resource. It captures: + +- **What was tested** — a coded category (the diagnostic service section, e.g. laboratory, radiology) and an optional coded report name or panel +- **The results** — the individual measurements and findings, recorded as observations linked to the report +- **The interpretation** — a free-text conclusion summarising what the results mean, plus optional notes +- **Provenance** — the service request it fulfils, and the patient and encounter it belongs to + +A report is not the order itself. The order (service request) asks for the work; the diagnostic report is the verified outcome that comes back. + +## Lifecycle + +A report moves through statuses as results are produced and verified: + +``` +registered → partial → preliminary → final +``` + +- **registered** — the report exists but no results are attached yet +- **partial** — some results are in; the report is still incomplete +- **preliminary** — provisional results are available but not yet verified +- **final** — the report is verified and complete + +Not every report passes through every step; a straightforward result can move from `registered` to `final` directly. + +## Relationships + +A diagnostic report sits downstream of an order and pulls together the data around it: + +- **Service request** — the order being fulfilled; a report belongs to exactly one request, chosen when the report is created +- **Patient** and **encounter** — set from the context of the originating order, not entered by hand +- **Observations** — the individual result rows (values, findings) collected under the report +- **Specimen** — when a sample is involved, it is collected against the service request that this report fulfils + +## Permissions + +Access to diagnostic reports is governed by a dedicated permission enum: + +| Permission | Roles | +| --- | --- | +| Can Create Diagnostic Report on Facility | Facility Admin, Admin, Doctor, Nurse | +| Can Read Diagnostic Report | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is then scoped by the organization tree: a permission held at a parent organization cascades to its descendants. In practice, Care decides report access via the originating service request — a user can act on a report if they hold the matching permission on the encounter (or on a facility organization tied to the request's locations) that the report belongs to. + +## Related + +- Reference: [Diagnostic Report (technical)](../../references/clinical/diagnostic-report.mdx) +- Concept: [Service Request](./service-request.mdx) +- Concept: [Observation](./observation.mdx) +- Concept: [Specimen](./specimen.mdx) +- Concept: [Encounter](./encounter.mdx) + +## FHIR reference + +Care's diagnostic report aligns with the FHIR **DiagnosticReport** resource. The coded `category` and `code` fields are bound value sets (HL7 diagnostic service sections and LOINC), and `status` follows the FHIR report-status vocabulary. diff --git a/versioned_docs/version-3.1/concepts/clinical/encounter.mdx b/versioned_docs/version-3.1/concepts/clinical/encounter.mdx new file mode 100644 index 0000000..09e5c1a --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/encounter.mdx @@ -0,0 +1,92 @@ +--- +sidebar_position: 2 +--- + +# Encounter + +An **encounter** in Care is a single interaction between a patient and a facility — a clinic visit, an admission, an emergency presentation, or a tele-consult. It is the episode that clinical work happens inside: observations, conditions, orders, medications, and notes are all recorded against an encounter, which in turn belongs to a [patient](../clinical/patient). + +## What it represents + +In Care's FHIR-aligned model, an encounter maps to the **Encounter** resource. It captures: + +- **The interaction** — which patient, at which facility, and over what time period +- **Classification** — the kind of contact (inpatient, ambulatory, emergency, virtual, and so on) and its priority +- **Status** — where the visit sits in its lifecycle, with a full history of changes +- **Hospitalization detail** — admit source, discharge disposition, and diet preference when the patient is admitted +- **Care team** — the practitioners and their roles for this episode +- **Context links** — the originating appointment, the patient's current location, and the organizations responsible for the encounter + +A patient is the long-lived record; an encounter is one chapter in it. One patient accumulates many encounters over time, and each encounter is the container that ties a specific episode of care together. + +## Classification + +Every encounter is tagged with a **class** that describes the kind of contact: + +| Class | Meaning | +| --- | --- | +| Inpatient | Admitted to the facility | +| Ambulatory | Outpatient / walk-in | +| Observation | Short-stay observation | +| Emergency | Emergency department | +| Virtual | Tele-consultation | +| Home health | Care delivered at home | + +A **priority** (such as routine, urgent, emergency, or elective) records how time-sensitive the interaction is. + +## Lifecycle + +An encounter moves through a status that reflects where the episode stands. The status history is preserved each time it changes: + +``` +planned → in_progress → on_hold → discharged → completed + ↘ cancelled + ↘ discontinued + ↘ entered_in_error +``` + +- **planned** — the visit is scheduled but has not started +- **in_progress** — the patient is actively being seen +- **on_hold** — temporarily paused +- **discharged** — the patient has been discharged but paperwork may remain +- **completed**, **cancelled**, **discontinued**, **entered_in_error** — terminal states that close the encounter + +Once an encounter reaches a terminal (closed) state, clinical data can no longer be written to it; reopening requires the appropriate permission. + +## Relationships + +An encounter sits at the centre of an episode of care and connects to: + +- **Patient** — the person the encounter is for, set when the encounter is created +- **Facility** — where the interaction takes place +- **Appointment** — the originating [scheduling](../scheduling/scheduling.mdx) booking, when one exists +- **Location** — the patient's current [location](../facility/location.mdx) within the facility, with a full location history +- **Organizations** — the facility [organizations](../facility/organization.mdx) responsible for the encounter, which drive who can access it + +## Permissions + +Access to encounters is governed by the encounter permission set. The core permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create encounter | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Staff, Doctor, Nurse, Admin, Facility Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendant organizations. A user can reach an encounter when they hold the relevant permission in any organization linked to that encounter — either through the encounter's responsible organizations or through the patient's current location. Writes are additionally blocked once an encounter is in a closed (terminal) state. + +## Related + +- Reference: [Encounter (technical)](../../references/clinical/encounter.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Service request](../clinical/service-request.mdx) +- Concept: [Scheduling](../scheduling/scheduling.mdx) + +## FHIR reference + +The encounter aligns with the FHIR **Encounter** resource, including its status, class, and hospitalization concepts, so episodes of care interoperate with other FHIR-based systems. diff --git a/versioned_docs/version-3.1/concepts/clinical/notes.mdx b/versioned_docs/version-3.1/concepts/clinical/notes.mdx new file mode 100644 index 0000000..e425e57 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/notes.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 10 +--- + +# Clinical Notes + +**Clinical notes** are threaded discussions attached to a patient's record. They let care teams capture narrative context — handover notes, observations, and coordination — that does not fit into structured fields, and keep that conversation tied to the right patient and, when relevant, the right visit. + +## What it represents + +A note is a conversation, not a single entry. It captures: + +- **Threads** — a titled discussion attached to a patient, optionally scoped to one encounter +- **Messages** — the individual posts within a thread, each authored by a user +- **Authorship and timing** — who wrote each message and when, carried by the standard audit fields +- **Edit history** — when a message is edited, the previous version and its author are preserved automatically + +Notes are free-text by design. They complement structured clinical data (conditions, observations, orders) rather than replace it. + +## Relationships + +Every thread is anchored to a [patient](../clinical/patient). A thread may also be scoped to a single [encounter](../clinical/encounter.mdx): + +- **Patient-level threads** — no encounter; visible across the patient's whole record +- **Encounter-scoped threads** — tied to one visit, for conversation about that episode of care + +Within a thread, every message belongs to that thread and inherits the same patient (and encounter) anchoring. Deleting a patient removes their threads; deleting a thread removes its messages. + +## Edit history + +Messages can be edited, but earlier versions are never lost. On each edit, the platform appends the previous message body and its author to the message's history automatically — clients cannot set or overwrite this. The current text shows in the thread; the prior versions remain auditable. + +Editing is also restricted to the original author: a user can revise their own messages, but not someone else's. + +## Permissions + +Notes do not have a dedicated permission set — access is governed by the same **patient** and **encounter** clinical-data permissions that protect the rest of the record. Whether a thread is patient-level or encounter-scoped decides which one applies. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Administrator (admin), Facility Admin | +| Can Read encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | +| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Administrator (admin), Facility Admin | +| Update Encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | + +In practice: reading notes requires clinical-data read access on the patient (or, for encounter-scoped threads, on the encounter). Posting or editing a message in a patient-level thread requires permission to update the patient's data; in an encounter-scoped thread it requires permission to update the encounter's clinical data, and is blocked once the encounter is closed. + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — so a user sees and edits notes only for patients and encounters within their reach. + +## Related + +- Reference: [Notes (technical)](../../references/clinical/notes.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +Care's clinical resources are FHIR-aligned, but free-text notes are modeled as Care's own `NoteThread` and `NoteMessage` resources rather than a single FHIR resource. Narrative content elsewhere in the record maps to FHIR's `Annotation` and narrative elements; notes here are a Care-native threading layer over that idea. diff --git a/versioned_docs/version-3.1/concepts/clinical/observation.mdx b/versioned_docs/version-3.1/concepts/clinical/observation.mdx new file mode 100644 index 0000000..67b6539 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/observation.mdx @@ -0,0 +1,77 @@ +--- +sidebar_position: 5 +--- + +# Observation + +An **observation** in Care is a single named, coded data point recorded about a patient — a blood pressure reading, a temperature, a lab result, or a coded answer captured through a questionnaire. Each observation says *what* was measured and holds the recorded *value*, anchored to a patient and the encounter in which it was taken. + +## What it represents + +In Care's FHIR-aligned model, an observation maps to the **Observation** resource. It captures: + +- **What was observed** — a primary code (typically LOINC) describing the measurement, finding, or question +- **The result** — the recorded value, with a unit for quantities or a coded answer for choices +- **When and by whom** — the effective time of the measurement and who performed or entered it +- **Clinical qualifiers** — body site, collection method, reference range, and interpretation (high / low / normal) +- **Context** — links to the patient, the encounter, and the questionnaire response that produced it + +Observations are the granular clinical readings that build up a patient's record over time. Care favours **structured** observations — coded, machine-readable values — because downstream logic such as allergy and medication checks relies on them rather than on free text. + +## Types and structure + +A single observation usually holds one value, but observations can be composed: + +- **Grouped (panel) observations** mark a parent that holds several child observations sharing a context — for example, a vitals panel or a lab panel. +- **Components** are sub-readings recorded together under one observation, each with its own code and value (for example, the systolic and diastolic parts of a blood pressure). + +Most observations are created automatically when a questionnaire is submitted, so the value and its type mirror the questionnaire answer, and the originating questionnaire response is recorded for provenance. + +## Lifecycle + +An observation's status reflects how trustworthy the recorded value is: + +``` +final → amended +final → entered_in_error +``` + +- **final** — recorded, complete, and verified; the default for questionnaire-sourced observations +- **amended** — a previously final observation that was later corrected +- **entered_in_error** — recorded by mistake and should be disregarded + +Observations are not deleted to "undo" them; marking an entry as `entered_in_error` keeps the history auditable. + +## Relationships + +An observation always belongs to a **patient** and is normally recorded within an **encounter**. It may also link to: + +- the **questionnaire response** that produced it (provenance for questionnaire-sourced data) +- a **diagnostic report** it forms part of, such as a lab or imaging report +- an **observation definition** — a facility-level template that standardises codes, units, and reference ranges for a kind of observation + +## Permissions + +Observations are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. + +| Permission | Roles | +| --- | --- | +| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can submit questionnaire about patients | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | +| Can view questionnaire responses on patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | + +Separately, the **observation definitions** that template these readings are governed at the facility level: "Can Read Observation Definition" is held by most clinical and admin roles, while "Can Create Observation Definition on Facility" is restricted to Facility Admin and Admin. + +Roles are granted to users through organization, facility-organization, encounter, and direct patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a role granted at a facility flows down to the patients and encounters beneath it. + +## Related + +- Reference: [Observation (technical)](../../references/clinical/observation.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Diagnostic report](../clinical/diagnostic-report.mdx) +- Concept: [Questionnaire](../forms/questionnaire.mdx) + +## FHIR reference + +Care's observation aligns with the FHIR **Observation** resource. Codes bind to standard terminologies — primary codes to LOINC, and body site and collection method to SNOMED CT — though API and FHIR field names may differ from Care's internal model. diff --git a/versioned_docs/version-3.1/concepts/clinical/service-request.mdx b/versioned_docs/version-3.1/concepts/clinical/service-request.mdx new file mode 100644 index 0000000..55dbfe0 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/service-request.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 7 +--- + +# Service Request + +A **service request** in Care is an order or proposal to perform an action — a lab test, an imaging study, a procedure, counselling — for a patient. It is the instruction that sets clinical work in motion: the specimens collected, the reports produced, and the observations recorded all trace back to the request that asked for them. + +## What it represents + +In Care's FHIR-aligned model, a service request maps to the **ServiceRequest** resource. It captures: + +- **What is being asked for** — a human-readable title and a coded service or procedure +- **Why and how** — its category (laboratory, imaging, counselling, surgical, education), priority, and whether it is a firm order or just a proposal +- **Clinical context** — the patient and encounter it belongs to, optional notes, patient instructions, and a target body site +- **Who and where** — the requesting clinician, the healthcare service expected to fulfil it, and the facility locations it applies to +- **Downstream linkage** — the specimens and diagnostic reports generated in response to it + +A service request is not the result — it is the ask. The findings it produces live in separate observation, specimen, and diagnostic report records that point back to it. + +## Lifecycle + +A request moves through a small set of statuses from draft to a terminal state: + +``` +draft → active → on_hold → completed + ↘ ended / revoked / entered_in_error +``` + +- **draft** — being prepared, not yet actionable +- **active** — placed and in progress +- **on_hold** — temporarily paused +- **completed** — fulfilled +- **ended**, **revoked**, **entered_in_error** — terminal closures (ended, cancelled, or logged as a mistake) + +## Intent and priority + +Two fields shape how a request is read and acted on: + +- **Intent** — how binding the request is: `proposal`, `plan`, `directive`, or `order`. A proposal is a suggestion; an order is a committed instruction. +- **Priority** — how urgently it should be handled: `routine`, `urgent`, `asap`, or `stat`. + +## Relationships + +A service request never stands alone. It is always created within an **encounter**, and the patient is taken from that encounter rather than set directly — you cannot file a request without a clinical context. From there it connects outward: + +- The **encounter** supplies the patient and the clinical setting. +- A **healthcare service** and one or more **locations** describe who fulfils the request and where. +- **Specimens** and **diagnostic reports** are produced in response and reference the request as their origin. +- A request can be created from an activity-definition template that supplies its category and the value set its code is drawn from. + +## Permissions + +Access to service requests is governed by a dedicated permission set: + +| Permission | Roles | +| --- | --- | +| Can Read Service Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Write Service Request on Facility | Facility Admin, Admin, Doctor, Nurse | + +Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A user reaches a specific request either through their membership in the encounter's facility organization (and its current location) or through the facility organizations of the locations the request is attached to. + +## Related + +- Reference: [Service Request (technical)](../../references/clinical/service-request.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Specimen](../clinical/specimen.mdx) +- Concept: [Diagnostic Report](../clinical/diagnostic-report.mdx) +- Concept: [Observation](../clinical/observation.mdx) + +## FHIR reference + +The service request aligns with the FHIR **ServiceRequest** resource, implementing a focused subset. Care follows its own conventions for some values — statuses, intents, and priorities are snake_case rather than the hyphenated FHIR codes. diff --git a/versioned_docs/version-3.1/concepts/clinical/specimen.mdx b/versioned_docs/version-3.1/concepts/clinical/specimen.mdx new file mode 100644 index 0000000..e4d8d2c --- /dev/null +++ b/versioned_docs/version-3.1/concepts/clinical/specimen.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 8 +--- + +# Specimen + +A **specimen** is a physical sample — blood, tissue, a swab, urine, and so on — collected from a patient for laboratory analysis. It is the bridge between an order for a test and the result that comes back, recording what was collected, how, and the state it reached the lab in. + +## What it represents + +In Care's FHIR-aligned model, a specimen maps to the **Specimen** resource. It captures: + +- **What was collected** — the kind of material (e.g. blood, swab, tissue), identified by a coded specimen type +- **How it was collected** — the collector, method, body site, quantity, and the patient's fasting status at collection +- **Where it came from** — the patient it belongs to and the encounter during which it was taken +- **Its journey through the lab** — when it was received, its condition on arrival, and any processing steps applied +- **Identification** — an accession identifier or barcode used to find the sample quickly + +A specimen is not the test result itself. It is the sample; the findings derived from it are reported separately. + +## Lifecycle + +A specimen moves through these statuses as it travels from collection to the lab: + +``` +draft → available → unavailable + → unsatisfactory +(any) → entered_in_error +``` + +- **draft** — a placeholder record before the sample is confirmed (Care-specific) +- **available** — the specimen is in hand and available for testing +- **unavailable** — the specimen is no longer available (consumed, lost, or disposed of) +- **unsatisfactory** — the specimen is unsuitable for testing (e.g. clotted, insufficient, contaminated) +- **entered_in_error** — the record was created in error and should be disregarded + +## Relationships + +A specimen sits between an order and a result, and is always tied to the patient it came from: + +- It is usually collected to fulfill a **service request** (a lab order); one service request may yield several specimens. +- It may be shaped by a **specimen definition** — a template describing the expected sample for a given test. +- It links to the **patient** it was collected from and the **encounter** during which collection happened. +- Findings derived from it are communicated through a **diagnostic report**. + +## Identifiers + +Each specimen carries an **accession identifier** — the lab accession number or barcode used to track the physical sample. This identifier is indexed so a specimen can be looked up quickly by scanning or searching, for example to match a tube on the bench back to the right patient and order. + +## Permissions + +Access to specimens is controlled by role-based permissions, scoped to the facility: + +| Permission | Roles | +| --- | --- | +| Can Read Specimen | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Create Specimen on Facility | Facility Admin, Admin, Doctor, Nurse | + +In practice, viewing and creating a specimen are also gated by access to the linked service request, so a user must be able to reach the underlying order. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. + +## Related + +- Reference: [Specimen (technical)](../../references/clinical/specimen.mdx) +- Concept: [Service Request](../clinical/service-request.mdx) +- Concept: [Diagnostic Report](../clinical/diagnostic-report.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's specimen aligns with the FHIR **Specimen** resource. Some Care field names differ (for example, the patient and encounter are set on creation via `subject_patient` and `subject_encounter`), and Care adds a `draft` status not present in FHIR. diff --git a/versioned_docs/version-3.1/concepts/facility/_category_.json b/versioned_docs/version-3.1/concepts/facility/_category_.json new file mode 100644 index 0000000..b250052 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Facility & Administration", + "position": 6, + "key": "facility-concepts", + "link": { + "type": "generated-index", + "title": "Facility & Administration", + "description": "Facilities, organizations, locations, services, and devices — the administrative structure care is delivered within." + } +} diff --git a/versioned_docs/version-3.1/concepts/facility/device.mdx b/versioned_docs/version-3.1/concepts/facility/device.mdx new file mode 100644 index 0000000..560ba15 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/device.mdx @@ -0,0 +1,69 @@ +--- +sidebar_position: 5 +--- + +# Device + +A **device** in Care is a physical or logical piece of equipment tracked within a facility — a monitor, pump, camera, or any asset a clinical team relies on. The device record anchors where that equipment lives, which encounter it is attached to, and the history of how it has moved and been serviced over time. + +## What it represents + +In Care's FHIR-aligned model, a device maps to the **Device** resource. It captures: + +- **Identity** — registered name, a friendly display name, and identifiers such as serial number, lot number, model number, and part number +- **Provenance** — manufacturer, manufacture date, and expiration date +- **Status** — both its lifecycle state and its physical availability +- **Contact** — structured contact points (phone, email, and similar) for the device or its vendor +- **Placement** — the facility that owns it, the organization responsible for it, and the location and encounter it is currently associated with +- **Type-specific data** — optional plugin-driven configuration when the device is a known care type (for example, a camera) + +A device is owned by exactly one facility, but it is not tied to a single location or encounter forever. It can be moved between locations and attached to or detached from encounters, and Care keeps an audit trail of each of those associations. + +## Lifecycle + +A device carries two independent status fields. Its **lifecycle status** describes whether it is in service: + +``` +active → inactive → entered_in_error +``` + +- **active** — the device is in service +- **inactive** — the device is not currently in service +- **entered_in_error** — the record was created by mistake + +Separately, its **availability status** describes its physical condition: `available`, `lost`, `damaged`, or `destroyed`. A device can be `active` in the system while its availability reflects that it is, say, out for repair. + +## Relationships + +Devices connect to the rest of Care through a few associations, each managed through its own action rather than edited directly on the device: + +- **Facility** — the owning facility, set when the device is registered. A device always belongs to one facility. +- **Managing organization** — the facility organization accountable for the device. This scopes who can see and manage it. +- **Location** — where the device is currently placed. Moving a device opens a new entry in its location history and closes the previous one. +- **Encounter** — the [encounter](../clinical/encounter.mdx) the device is currently attached to. Attaching or detaching is recorded in encounter history; when an encounter is completed, attached devices are released automatically. + +Care also keeps a **service history** — a log of maintenance and servicing events — so the upkeep of each device stays auditable alongside its movements. + +## Permissions + +Access to devices is governed by the device permissions, granted to users through their roles: + +| Permission | Roles | +| --- | --- | +| Can List Devices on Facility | Staff, Administrator, Doctor, Nurse, Facility Admin, Pharmacist | +| Can Manage Devices on Facility | Staff, Administrator, Facility Admin, Pharmacist | +| Can Manage Device Associations to Encounters | Staff, Administrator, Doctor, Nurse, Facility Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. A device is visible to users whose memberships overlap its managing organization (or the organization of the location it currently sits in), so listing and management follow the facility's organization hierarchy rather than being open to everyone in the facility. + +## Related + +- Reference: [Device (technical)](../../references/facility/device.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's device model aligns with the FHIR **Device** resource, including its lifecycle status, availability status, and structured contact points. The encounter, location, and service associations are tracked as Care-specific history records layered on top of that resource. diff --git a/versioned_docs/version-3.1/concepts/facility/facility.mdx b/versioned_docs/version-3.1/concepts/facility/facility.mdx new file mode 100644 index 0000000..e1b4e20 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/facility.mdx @@ -0,0 +1,64 @@ +--- +sidebar_position: 1 +--- + +# Facility + +A **facility** in Care is a care site — a hospital, clinic, lab, or telemedicine endpoint — and the root of a deployment's administrative hierarchy. It is where users, locations, patients, and clinical activity are anchored: nearly everything in Care happens inside the context of a facility. + +## What it represents + +In Care's FHIR-aligned model, a facility holds: + +- **Identity & classification** — name, description, and a facility type (for example, Private Hospital, Primary Health Centre, or Govt Labs) +- **Location & contact** — address, pincode, geo-coordinates, and phone number +- **Capabilities** — a set of features the site offers, such as CT scan, maternity care, X-ray, neonatal care, operation theater, or blood bank +- **Geographic placement** — a link to a government organization in the geographic hierarchy (state → district → ward) +- **Presentation & billing config** — a cover image, print templates, and per-facility discount, tax, and invoice-numbering rules + +A facility is not just a name on a map. When one is created, Care automatically provisions its root **Administration** organization and makes the creator a facility administrator, giving the site an internal structure to attach teams, departments, locations, and users to. + +## Types & classification + +Every facility has a single **facility type** drawn from a fixed list, spanning private and government hospitals, primary/community/family health centres, labs, telemedicine, NGOs, and community-based organizations. The type is descriptive — it categorizes the site for reporting and discovery but does not by itself change behaviour. + +Separately, a facility advertises zero or more **features** (CT scan, maternity care, X-ray, neonatal care, operation theater, blood bank) so that referrals and search can find sites with the right capabilities. + +## Relationships + +A facility sits at the centre of a deployment's structure: + +- **Organizations** — each facility has an internal facility-organization tree (rooted at its auto-created Administration org) for teams and departments, and a link out to the geographic organization tree for administrative placement +- **Locations** — physical places inside the facility (wards, beds, rooms) live under it +- **Users** — staff gain access by being given roles within a facility's organizations +- **Patients & encounters** — registration and care activity are scoped to the facility +- **Healthcare services & devices** — services offered and equipment are registered against the facility + +## Billing configuration + +Each facility can carry its own monetary configuration: facility-defined discount codes, selectable discount line items, a rule for how discounts stack, and an expression that generates invoice numbers. These layer on top of instance-wide catalogs, so a site can add its own discounts without redefining the ones shared across the deployment. + +## Permissions + +Access to facilities is governed by the `FacilityPermissions` enum. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create on Facility | Administrator, Admin, Facility Admin | +| Can Read on Facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Can Update on Facility | Facility Admin, Administrator, Admin, Staff | + +Roles are granted to users through organization memberships — a user holds a role within a facility's root organization, a facility sub-organization (team or department), or the geographic organization tree. Access is then scoped by that tree: a permission held at a parent organization cascades to its descendants, so a role granted high in the geographic hierarchy can authorize action on the facilities beneath it, while a role on a facility's own root org governs that site directly. + +## Related + +- Reference: [Facility (technical)](../../references/facility/facility.mdx) +- Reference: [Facility config (technical)](../../references/facility/facility-config.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Location](./location.mdx) +- Concept: [User](../access/user.mdx) +- Concept: [Access control](../access/access-control.mdx) + +## FHIR reference + +Care's facility model is aligned with FHIR. A facility broadly corresponds to a combination of the FHIR **Organization** and **Location** resources — it names the care provider and anchors the physical and administrative structure beneath it. diff --git a/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx b/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx new file mode 100644 index 0000000..917b977 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 4 +--- + +# Healthcare Service + +A **healthcare service** in Care is a specific service a facility offers — cardiology, a laboratory, radiology, a pharmacy, or a store. It names what is on offer, where it is delivered, and which department runs it, so the rest of Care can route work to the right place. + +## What it represents + +A healthcare service captures, in plain terms: + +- **What the service is** — a display name and a coded service type (for example, a cardiology or radiology code) +- **Where it is delivered** — the locations within the facility where the service is provided +- **Who runs it** — the managing organization (the department or team responsible for it) +- **What it behaves like internally** — an optional internal type that tells Care how the service is used (pharmacy, lab, scheduling, or store) +- **How it appears** — optional presentation hints (such as colours or icons) used by the interface + +A healthcare service belongs to one facility. The facility is set from context, not chosen on the form, so a service is always tied to the facility it lives in. + +## Types + +Beyond its clinical service type, a healthcare service can carry an **internal type** that tells Care how to treat it operationally: + +| Internal type | Used for | +| --- | --- | +| `pharmacy` | Dispensing and medication supply | +| `lab` | Laboratory and diagnostic ordering | +| `scheduling` | Appointment and resource scheduling | +| `store` | Inventory and supply stores | + +The internal type is optional. A service without one is simply an offered service with no special operational handling. + +## Relationships + +A healthcare service is the connective tissue between a facility's structure and the work that happens in it: + +- **Facility** — every service belongs to exactly one facility, assigned from context. +- **Locations** — a service points to the locations where it is delivered; one service can span several locations. +- **Organization** — a managing organization (a facility department or team) owns the service and is responsible for it. + +Because of these links, a healthcare service is what scheduling, ordering, and supply workflows reference when they need to know *what* is being offered and *where*. + +## Permissions + +Access to healthcare services is governed by the `HealthcareService` permissions: + +| Permission | Roles | +| --- | --- | +| Can Read Healthcare Service | Facility Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Healthcare Service on Facility | Facility Admin, Administrator | + +Reading the catalogue of services is broadly available to clinical and support staff, while creating or changing services is restricted to facility administrators. Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. Creating a service additionally requires the permission at the facility root. + +## Related + +- Reference: [Healthcare Service (technical)](../../references/facility/healthcare-service.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Scheduling](../scheduling/scheduling.mdx) + +## FHIR reference + +Care's healthcare service is aligned with the FHIR **HealthcareService** resource, and its service type is coded against the HL7 Healthcare Service Type Code value set. diff --git a/versioned_docs/version-3.1/concepts/facility/location.mdx b/versioned_docs/version-3.1/concepts/facility/location.mdx new file mode 100644 index 0000000..119301f --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/location.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 3 +--- + +# Location + +A **location** in Care is a physical place where care happens or where resources sit — a building, a wing, a ward, a room, or a single bed. Locations form a hierarchy inside a facility, and encounters attach to them so you always know where a patient is. + +## What it represents + +In Care's FHIR-aligned model, a location maps to the **Location** resource. It captures: + +- **Identity** — a name and description for the place +- **Physical form** — what kind of place it is (site, building, wing, ward, room, bed, vehicle, and so on) +- **Where it sits** — its parent location and the tree it belongs to, so a bed knows it lives in a room, inside a ward, inside a building +- **Occupancy** — the encounter currently associated with it, used for bed and room management +- **Operational state** — whether it is occupied, unoccupied, closed, being cleaned, contaminated, or isolated + +Locations are nested without limit: every location may have a parent and children, letting a deployment model its real-world geography as deep as it needs. + +## Mode: kind vs instance + +Every location is one of two modes, fixed when it is created: + +- **kind** — a class or type of place, such as "a ward" or "a building". A kind can contain child locations. +- **instance** — a single, concrete place, such as "Bed 1". Instances are leaf nodes and **cannot have children**. + +This is why beds are just locations in `instance` mode, not a separate concept. + +## Lifecycle + +A location's administrative status moves between a small set of values: + +``` +active → inactive → unknown +``` + +- **active** — the location is in use +- **inactive** — retained but no longer in service +- **unknown** — status is not known + +Separately, an **operational status** describes the live state of a bed or room — closed, housekeeping, occupied, unoccupied, contaminated, or isolated — and a server-maintained **availability** flag marks whether the location is currently tied to an encounter (reserved) or free (available). + +## Relationships + +- **Facility** — every location belongs to exactly one [facility](./facility.mdx). +- **Parent and children** — locations form a tree; a permission or organization grant at a parent cascades down to its descendants. +- **Organization** — a [facility organization](./organization.mdx) can be granted access to a location, which is how users gain access to it and the encounters within. +- **Encounter** — an [encounter](../clinical/encounter.mdx) is associated with a location over a time window (for example, a bed assignment), and the location surfaces its current encounter for occupancy views. + +## Permissions + +Access to locations is governed by the facility-location permissions: + +| Permission | Roles | +| --- | --- | +| Can List Facility Locations | Administrator, Doctor, Nurse, Staff, Pharmacist, Facility Admin, Admin | +| Can Create/Update Facility Locations | Facility Admin, Staff, Admin | +| Can List Facility Location Organizations | Facility Admin, Staff, Admin | +| Can Create/Update Facility Location Organizations | Facility Admin, Staff, Admin | + +Roles are granted to users through facility-organization membership, and access is scoped by the organization tree: a permission held on an organization applies to the locations that organization can reach, and grants at a parent location cascade to its children. Because that cascade is computed asynchronously, newly granted access settles a moment after the change is made. + +## Related + +- Reference: [Location (technical)](../../references/facility/location.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Organization](./organization.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's location is modelled on the [FHIR Location](https://build.fhir.org/location.html) resource, including its `mode` (kind/instance), physical form, and operational status concepts. API field names may differ from the internal model. diff --git a/versioned_docs/version-3.1/concepts/facility/organization.mdx b/versioned_docs/version-3.1/concepts/facility/organization.mdx new file mode 100644 index 0000000..60f2c85 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/facility/organization.mdx @@ -0,0 +1,94 @@ +--- +sidebar_position: 2 +--- + +# Organizations + +An **organization** in Care is a grouping used to structure people and resources into a nested tree. It is how Care decides who can do what: roles are granted to users on an organization, and the permissions that come with those roles flow down to everything inside that branch of the tree. + +## What it represents + +In Care's FHIR-aligned model, an organization maps to the **Organization** resource. It captures: + +- **Identity** — a display name, description, and an open `metadata` bag for deployment-specific data +- **Classification** — a type that says what kind of grouping it is (a team, a governance unit, a role group, a supplier) +- **Tree position** — a parent organization, so groups nest into a hierarchy with roots, branches, and descendants +- **Membership** — links between users and the organization, each carrying a role that defines what those users can do + +An organization is not a single person or a single facility. It is the container that groups them, and the place where access is anchored. + +## Two kinds of organization + +Care has two organization trees that work the same way but live at different scopes: + +- **Organization** — instance-wide. This is the governance and permissions backbone for the whole deployment: geography, administrative units, supplier groups, and role groups that exist independently of any one facility. +- **Facility organization** — scoped to a single facility. This is how a facility is divided internally into departments and teams (for example, `Cardiology` or an emergency ward) with their own staff and access. + +Every facility has a single **root** facility organization at the top of its internal tree; departments and teams hang off it. + +## Types and classification + +An organization's type describes what the grouping is for: + +| Type | Meaning | +| --- | --- | +| `team` | A team or department-style grouping | +| `govt` | A governance or governmental unit, typically managed by a superadmin | +| `role` | A role group — a set of users who share a role across the deployment | +| `product_supplier` | A supplier organization, linked to the supply chain | + +Governance, role, and root organizations are restricted to superadmin management; ordinary teams are managed by facility and organization admins. + +## The tree and how access cascades + +Organizations nest into a tree. The key idea is **inheritance**: a permission held on an organization applies not just there but to every organization beneath it. If a user is an admin of a region, they are effectively an admin of every district, facility group, and team inside that region — without being added to each one individually. + +``` +Root organization + └─ Branch organization + └─ Child organization + └─ Team +``` + +A user added near the top of the tree carries their role's permissions all the way down. A user added to a single team has access only within that team. This makes the tree the natural unit for delegating administration as a deployment grows. + +Membership is also deliberate: belonging to an organization does not automatically grant access to everything it owns — only to the resources actually assigned to it and to what the user's role allows. + +## Permissions + +Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. + +Key instance-wide organization permissions: + +| Permission | Roles | +| --- | --- | +| Can View Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | +| Can Create Organizations | Admin | +| Can Delete Organizations | Admin | +| Can Manage Organizations | Admin, role-org Admin | +| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | +| Can List Users in an Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager | + +Key facility-organization permissions: + +| Permission | Roles | +| --- | --- | +| Can View Facility Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer | +| Can Create Facility Organizations | Facility Admin | +| Can Delete Facility Organizations | Facility Admin | +| Can Manage Facility Organizations | Facility Admin, Administrator | +| Can Manage Users in a Facility Organization | Facility Admin, Administrator | + +Roles are granted to users through organization and facility-organization memberships. Access is then scoped by the tree: a permission held at a parent organization cascades to all of its descendants, so checks walk the chain of ancestors above a given organization. Geo admins are a special case — they can manage and view facility organizations within the geography they administer, regardless of facility membership. When assigning a role to another user, an admin can only grant a role whose permissions are a subset of their own. + +## Related + +- Reference: [Organization (technical)](../../references/facility/organization.mdx) +- Concept: [Facility](./facility.mdx) +- Concept: [Location](./location.mdx) +- Concept: [Access control](../access/access-control.mdx) +- Concept: [User](../access/user.mdx) + +## FHIR reference + +Organizations align with the FHIR **Organization** resource — a nested grouping used to organize people and resources and to anchor permissions. Both the instance-wide and facility-scoped trees follow this model. diff --git a/versioned_docs/version-3.1/concepts/forms/_category_.json b/versioned_docs/version-3.1/concepts/forms/_category_.json new file mode 100644 index 0000000..f114257 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/forms/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Forms & Terminology", + "position": 7, + "key": "forms-concepts", + "link": { + "type": "generated-index", + "title": "Forms & Terminology", + "description": "Questionnaires that capture structured data, and the coded value sets that keep it consistent." + } +} diff --git a/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx b/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx new file mode 100644 index 0000000..23faf64 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 1 +--- + +# Questionnaires & Structured Data + +A **questionnaire** (also called a **form**) is a reusable, versioned definition of questions that Care presents to capture structured data about a patient or an encounter. It is how Care turns clinical and operational data entry — vitals, intake forms, assessments, checklists — into consistent, query-friendly records instead of free text. + +## What it represents + +A questionnaire and its answers together capture: + +- **The form definition** — a titled, versioned tree of questions (groups, text, numbers, dates, choices, quantities) with display rules and validation +- **The subject** — whether the form is answered about a **patient** or an **encounter** +- **The answers** — a stored set of responses for a subject, recorded when someone fills out and submits the form +- **Derived clinical data** — coded answers can automatically become [observations](../clinical/observation.mdx) on the encounter, so a vitals form populates the clinical record directly +- **Reusable templates** — saved "favourites" or order sets that pre-fill a response, optionally bundling medication requests and service orders + +A questionnaire is the blueprint; a response is one filled-out copy. One questionnaire can be answered many times, by many people, for many subjects. + +## Lifecycle + +A questionnaire definition moves through a small set of publication states: + +``` +draft → active → retired +``` + +- **draft** — being authored; not yet available for data entry +- **active** — published and accepting submissions. Active forms should not be edited in place +- **retired** — withdrawn from use; existing responses remain readable + +Only **active** questionnaires accept submissions. A submitted response is normally **completed**, and can later be marked **entered in error** to void it without deleting the history. Forms that support a save-then-finalise flow carry a submission envelope that moves from **draft** to **submitted**. + +## Types of question + +Questions are typed, which is what makes the captured data structured. Common types include groups (containers), text, numbers (integer, decimal), booleans, dates and times, single- or multi-select **choices**, **quantities** with units, and display-only notes. Choice and quantity questions draw their allowed answers from a [value set](./valueset.mdx), and conditional rules can show or hide a question based on earlier answers. + +## Relationships + +- **Patient / encounter** — every response is anchored to a [patient](../clinical/patient), and to an [encounter](../clinical/encounter.mdx) when answered during a visit +- **Observations** — coded answers materialise as [observations](../clinical/observation.mdx) linked back to the response +- **Value sets** — choice and quantity questions reference a [value set](./valueset.mdx) for their allowed answers +- **Organizations** — a questionnaire is scoped to one or more [organizations](../facility/organization.mdx), which controls who can see and submit it + +## Permissions + +Access to questionnaires is governed by a dedicated permission set; response templates have their own. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Read Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin, Organization Admin/Manager/Member | +| Can Submit Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Facility Admin, Organization Admin/Manager/Member | +| Can Create/Update Questionnaires | Administrator, Facility Admin | +| Can Archive Questionnaires | Administrator, Facility Admin | +| Can Manage Questionnaires | Administrator, Facility Admin, Organization Admin | +| Can Read Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | +| Can Create/Update Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. A questionnaire is attached to organizations, and access is decided by checking the user's roles against those organizations. Because permissions cascade down the organization tree, a role held at a parent organization also applies to the questionnaires scoped to its descendants. + +## Related + +- Reference: [Questionnaire (technical)](../../references/forms/questionnaire.mdx) +- Reference: [Questionnaire Response (technical)](../../references/forms/questionnaire-response.mdx) +- Reference: [Questionnaire Response Template (technical)](../../references/forms/questionnaire-response-template.mdx) +- Concept: [Value sets](./valueset.mdx) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Care's questionnaires are inspired by the FHIR **Questionnaire** resource, and stored answers align loosely with **QuestionnaireResponse**. The publication states (draft, active, retired) mirror FHIR's publication-status model, so forms map cleanly onto FHIR-based exchange. diff --git a/versioned_docs/version-3.1/concepts/forms/valueset.mdx b/versioned_docs/version-3.1/concepts/forms/valueset.mdx new file mode 100644 index 0000000..dc3368f --- /dev/null +++ b/versioned_docs/version-3.1/concepts/forms/valueset.mdx @@ -0,0 +1,70 @@ +--- +sidebar_position: 2 +--- + +# Value Sets & Coded Data + +A **value set** is a named, curated list of coded answers — the menu of valid options a form question can offer. It is how Care keeps coded data consistent: instead of free text, a question draws its allowed answers from a value set, so everyone records the same concept the same way and the data stays query-friendly. + +## What it represents + +A value set captures the *rules* for which coded concepts are valid, not a frozen list: + +- **A named collection** — a slug, display name, and description that questionnaires and clinical fields reference by name +- **Composition rules** — `include` and `exclude` clauses that pull concepts from one or more code systems (such as SNOMED CT, LOINC, or ICD), either by pinning specific codes or by filtering a system (for example, "all descendants of this code") +- **Coded answers** — each member concept is a code plus a human-readable display, drawn live from terminology servers rather than copied in +- **Provenance** — whether the value set is shipped and maintained by the platform or authored locally by a deployment + +A value set is not a list of codes stored in one place. It stores the *rules* for membership, and the actual codes are resolved in real time when a picker is searched or a submitted code is validated. Editing the rules immediately changes which codes the value set yields — there is nothing to rebuild. + +## Lifecycle + +A value set moves through a small set of publication states: + +``` +draft → active → retired +``` + +- **draft** — authored but not yet in use +- **active** — published and available to questionnaires and coded fields +- **retired** — no longer recommended for use; existing data that used it stays readable + +A fourth state, **unknown**, exists for value sets whose status is not established. + +## System vs. local value sets + +Value sets come in two flavours: + +- **System-defined** — shipped and maintained by the platform as shared terminology. Deployments should treat these as read-only. Their slugs use a reserved `system-` prefix. +- **Locally authored** — created by a deployment for its own terminology needs, using any non-reserved slug. + +This split lets the platform ship sensible defaults while still letting each site extend coded data for local workflows. + +## Relationships + +- **Questionnaires** — choice and quantity questions in a [questionnaire](./questionnaire.mdx) reference a value set for their allowed answers, which is the main place coded data is captured +- **Clinical fields** — coded fields on resources such as [conditions](../clinical/condition.mdx), [allergies](../clinical/allergy-intolerance.mdx), and [observations](../clinical/observation.mdx) bind to value sets so their codes stay consistent +- **Personalization** — individual users can favourite codes within a value set and see recently used codes surfaced in pickers; this is per-user convenience, not part of the value set definition + +## Permissions + +Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. Any authenticated user can read and search them — that is what powers the code pickers throughout the product. Authoring is gated to administrators. + +| Permission | Roles | +| --- | --- | +| Read / search value sets | Any authenticated user (shared reference data) | +| Create / update value sets | Administrator, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a role held at a parent organization cascades to its descendants. Because value sets are global reference data rather than patient- or encounter-scoped, read access is universal; the administrative roles above are what control who may author or change them, and system-defined value sets are read-only for everyone. + +## Related + +- Reference: [Value Set (technical)](../../references/forms/valueset.mdx) +- Concept: [Questionnaires & Structured Data](./questionnaire.mdx) +- Concept: [Observation](../clinical/observation.mdx) +- Concept: [Condition](../clinical/condition.mdx) +- Concept: [Access control](../access/access-control.mdx) + +## FHIR reference + +Value sets align with the FHIR **ValueSet** resource: a composition of coded concepts drawn from one or more code systems, expressed as `include` / `exclude` clauses against those systems. This makes Care's coded data interoperable with external terminology services and FHIR-based systems. diff --git a/versioned_docs/version-3.1/concepts/medications/_category_.json b/versioned_docs/version-3.1/concepts/medications/_category_.json new file mode 100644 index 0000000..5f2136f --- /dev/null +++ b/versioned_docs/version-3.1/concepts/medications/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Medications", + "position": 2, + "key": "medications-concepts", + "link": { + "type": "generated-index", + "title": "Medications", + "description": "How medications are prescribed, administered, dispensed, and reconciled across a patient's care." + } +} diff --git a/versioned_docs/version-3.1/concepts/medications/medication.mdx b/versioned_docs/version-3.1/concepts/medications/medication.mdx new file mode 100644 index 0000000..0d6335d --- /dev/null +++ b/versioned_docs/version-3.1/concepts/medications/medication.mdx @@ -0,0 +1,87 @@ +--- +sidebar_position: 1 +--- + +# Medication + +A **medication** in Care is how the system tracks a drug across its whole journey for a patient — from the prescriber's intent, through what the pharmacy hands over, to what is actually given at the bedside and what the patient reports taking at home. It is not one record but a small family of related records that together describe the medication story for an encounter. + +## What it represents + +Care models medication as four distinct but connected resources, each answering a different question: + +- **Medication request** — what a prescriber *intends*: the drug, dose, route, timing, and PRN rules, grouped into a prescription for an encounter +- **Medication administration** — what was actually *given* (or attempted) to the patient, fulfilling a request +- **Medication dispense** — what the pharmacy *handed over*, drawing down inventory and optionally raising a charge +- **Medication statement** — what the patient *reports* taking, has taken, or intends to take, as told by the patient, a relative, or a clinician (not actively prescribed) + +Keeping these separate lets Care distinguish "ordered" from "given" from "dispensed" from "reported" — the difference that matters for medication reconciliation and safety. + +## The four resources + +| Resource | Captures | Anchored to | +| --- | --- | --- | +| Request | Prescriber intent (dose, route, timing) | Encounter, grouped in a prescription | +| Administration | The actual give event | A request, on an encounter | +| Dispense | Hand-over of stock | An inventory item at a location | +| Statement | Patient-reported medication use | Patient and encounter | + +A request can lead to many administrations (each scheduled dose) and many dispenses (refills). A statement stands on its own — it documents medication history, not an active order. + +## Lifecycle + +Each resource carries its own status. Drawn from the same plain-language strings the API uses: + +``` +Request: draft → active → on_hold → completed / stopped / cancelled +Administration: in_progress → completed / not_done / stopped +Dispense: preparation → in_progress → completed / declined / cancelled +Statement: active → on_hold → completed / stopped / not_taken / intended +``` + +A few terminal states (`entered_in_error`, plus `stopped` / `cancelled` / `declined` depending on the resource) close a record out. Cancelling a dispense automatically reverses its inventory draw-down and any attached charge, so stock and billing stay consistent. + +## Relationships + +- A **request** belongs to an **encounter** and is grouped under a **prescription**; the **patient** is always derived from the encounter, never set directly +- An **administration** points back to the **request** it fulfils +- A **dispense** consumes an **inventory item** at a **location**, may link to the **authorizing request**, and can raise a **charge item** for billing +- A **statement** links to the **patient** and the **encounter** where it was recorded + +Drugs and dose units are coded against SNOMED CT value sets, so "amoxicillin 500 mg, oral, twice daily" is structured data rather than free text. + +## Permissions + +Medication access splits along two access models. + +**Dispense** has dedicated, location-centric permissions — pharmacists work in the pharmacy and often have no encounter access, so dispensing keys off the dispensing location instead: + +| Permission | Roles | +| --- | --- | +| Pharmacist in Care | Facility Admin, Administrator, Pharmacist | +| Medication Dispense Read | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | +| Write Medication Dispense | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | + +**Requests, administrations, and statements** are clinical data on the encounter, so they are governed by the encounter clinical-data permissions: + +| Permission | Roles | +| --- | --- | +| Can Read encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — and dispense access is checked against the location's facility-organization rather than the encounter. + +## Related + +- Reference: [Medication Request](../../references/medications/medication-request.mdx) +- Reference: [Medication Administration](../../references/medications/medication-administration.mdx) +- Reference: [Medication Dispense](../../references/medications/medication-dispense.mdx) +- Reference: [Medication Statement](../../references/medications/medication-statement.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Supply](../supply/supply.mdx) +- Concept: [Billing](../billing/billing.mdx) + +## FHIR reference + +Care's medication resources align with FHIR: `MedicationRequest`, `MedicationAdministration`, `MedicationDispense`, and `MedicationStatement`. Care uses underscored status values (for example `on_hold`, `entered_in_error`) rather than the hyphenated FHIR spellings, and binds coded fields to SNOMED CT value sets. diff --git a/versioned_docs/version-3.1/concepts/scheduling/_category_.json b/versioned_docs/version-3.1/concepts/scheduling/_category_.json new file mode 100644 index 0000000..0ae9d41 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/scheduling/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Scheduling", + "position": 3, + "key": "scheduling-concepts", + "link": { + "type": "generated-index", + "title": "Scheduling", + "description": "Appointments, practitioner availability, and the token queues that move patients through a facility." + } +} diff --git a/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx b/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx new file mode 100644 index 0000000..da46e83 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 1 +--- + +# Scheduling & Appointments + +**Scheduling** in Care defines when a resource — a practitioner, a location, or a healthcare service — is available, and **appointments** record a patient being booked into a concrete time within that availability. Together they answer "who is free, when?" and "who is coming in, and at what time?" — the backbone of front-desk and clinic operations. + +## What it represents + +Scheduling spans a few related building blocks, in plain terms: + +- **Schedule** — a named, date-bounded block of availability attached to a bookable resource (for example, "Morning OPD", valid for the next quarter) +- **Availability** — how a schedule's time is divided: recurring weekly windows, slot length, and how many people each slot can hold +- **Exception** — a date range that blocks a resource regardless of its schedules (leave, holidays, one-off closures) +- **Slot** — a concrete, bookable time window generated from a schedule's availability +- **Booking (appointment)** — a patient placed into a slot, with a status that tracks them from proposed through to seen or cancelled + +A schedule describes *potential* availability; a booking is an *actual* appointment. One schedule produces many slots, and each slot can hold one or more bookings up to its capacity. + +## Bookable resources + +A schedule is never attached to a patient — it is attached to whatever the patient comes to see. Care supports three kinds of bookable resource: + +| Resource type | What gets booked | +| --- | --- | +| Practitioner | A clinician or staff member who is a part of the facility | +| Location | A room, bed, or area within the facility | +| Healthcare service | A named service offering (for example, a vaccination clinic) | + +When booking, clients name the resource by its type and id; Care resolves the underlying practitioner, location, or service behind the scenes. + +## Appointment lifecycle + +A booking moves through a status as the patient progresses. The common path is: + +``` +proposed → pending → booked → arrived → checked_in → in_consultation → fulfilled +``` + +Other terminal or branch states include `noshow` (patient did not arrive), `waitlist`, and the cancellation states `cancelled`, `rescheduled`, and `entered_in_error`. Cancelling and rescheduling do not happen through a plain status edit — they go through dedicated cancel and reschedule actions, which also free up the slot's capacity. A booking already `in_consultation` cannot be cancelled. + +## Relationships + +- A **booking** links a **patient** to a **slot**, and can carry an associated [encounter](../clinical/encounter.mdx), a queue [token](./token.mdx), and a billing charge. +- A **schedule** lives inside a **facility** and points at one bookable resource. +- When a schedule defines a charge, a booking made against it can automatically raise the matching [billing](../billing/billing.mdx) charge; queue-style workflows issue a [token](./token.mdx) so patients can be called in order. + +## Permissions + +Access to schedules and bookings is governed by the schedule permission set. The key permissions and the roles that hold them: + +| Permission | Roles | +| --- | --- | +| Can Create on Schedule | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can list schedule on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can update bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can reschedule bookings on Object | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | + +Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. For practitioner schedules, access is decided against the organizations the practitioner belongs to within the facility; for locations and healthcare services, against that resource's managing organization. + +## Related + +- Reference: [Schedule & availability (technical)](../../references/scheduling/schedule.mdx) +- Reference: [Booking (technical)](../../references/scheduling/booking.mdx) +- Concept: [Token](./token.mdx) +- Concept: [Encounter](../clinical/encounter.mdx) +- Concept: [Healthcare service](../facility/healthcare-service.mdx) +- Concept: [Location](../facility/location.mdx) + +## FHIR reference + +Scheduling is FHIR-aligned: a schedule's slots map to the FHIR **Slot** resource, and a booking maps to the FHIR **Appointment** resource. Care's API field names may differ from the FHIR element names. diff --git a/versioned_docs/version-3.1/concepts/scheduling/token.mdx b/versioned_docs/version-3.1/concepts/scheduling/token.mdx new file mode 100644 index 0000000..b3e8731 --- /dev/null +++ b/versioned_docs/version-3.1/concepts/scheduling/token.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# Tokens & Queues + +A **token** in Care is a numbered place in a queue for a walk-in or queue-based visit. Tokens let a facility manage flow when patients are not booked into specific appointment slots — each patient draws a numbered token in a queue tied to a practitioner, location, or service, and is called in turn. + +## What it represents + +A token captures one patient's position in a queue, and the queue structures the waiting line around a resource: + +- **The token** — a number issued to a patient, its category (e.g. General, Priority), an optional note, and its current status +- **The queue** — the waiting line for one schedulable resource (practitioner, location, or healthcare service) on one date +- **Sub-queues** — optional splits of a queue so the same resource can serve from several physical points (e.g. multiple vaccination rooms, each drawing its own tokens) +- **Categories** — reusable labels per facility that group and prioritize tokens, each with a short code shown on displays + +A token is for managing the live waiting line. It is distinct from a booked appointment, though a token can be linked to a booking when one exists. + +## Lifecycle + +A token moves through these states as it is served: + +``` +CREATED → IN_PROGRESS → FULFILLED + ↘ CANCELLED + ↘ ENTERED_IN_ERROR (on delete) +``` + +- **CREATED** — the token has been issued and is waiting to be served +- **IN_PROGRESS** — the patient is being served (set when the token becomes a point's current token) +- **FULFILLED** — service is complete +- **CANCELLED** — the token was cancelled +- **ENTERED_IN_ERROR** — applied automatically when a token is deleted (a soft delete; the record is retained) + +Queue progression — which token is current and who is next — is maintained by the platform as staff advance the line, not set directly by the person issuing the token. + +## Classification + +- **By category** — every token belongs to a category (such as General or Priority). Numbering runs per category within a queue, so two categories in the same queue each count from 1. +- **By resource type** — a queue is bound to one of three schedulable resource types: a **practitioner**, a **location**, or a **healthcare service**. This binding determines who can manage and see the queue. + +## Relationships + +- **Patient** — a token can belong to a [patient](../clinical/patient); one patient may hold more than one token. +- **Resource** — every queue is tied to a schedulable resource through [Scheduling](./scheduling.mdx). +- **Booking** — a token may link to a booking, and through it to the associated [encounter](../clinical/encounter.mdx) when one exists. + +## Permissions + +Token access is governed by facility-scoped permissions. Whether a user can see or manage a queue is decided by their membership in the facility organization that owns the resource the queue is bound to. + +| Permission | Roles | +| --- | --- | +| Can Create on Token | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Can list token on Object | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Can Create on Token Category | Administrator, Staff, Facility Admin | +| Can list token category on Facility | Administrator, Staff, Facility Admin, Doctor, Nurse | + +Roles are granted to users through facility-organization memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a user's reach over a queue follows the organization that manages the queue's practitioner, location, or healthcare service. + +## Related + +- Reference: [Token (technical)](../../references/scheduling/token.mdx) +- Concept: [Scheduling](./scheduling.mdx) +- Concept: [Patient](../clinical/patient) +- Concept: [Encounter](../clinical/encounter.mdx) + +## FHIR reference + +Tokens and queues are Care's model for walk-in flow and do not map to a single FHIR resource. They build on Care's FHIR-aligned scheduling primitives — the schedulable resource and booking — to manage the live waiting line. diff --git a/versioned_docs/version-3.1/concepts/supply/_category_.json b/versioned_docs/version-3.1/concepts/supply/_category_.json new file mode 100644 index 0000000..bed362b --- /dev/null +++ b/versioned_docs/version-3.1/concepts/supply/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Supply & Inventory", + "position": 5, + "key": "supply-concepts", + "link": { + "type": "generated-index", + "title": "Supply & Inventory", + "description": "Products, stock, and the requests and deliveries that keep a facility supplied." + } +} diff --git a/versioned_docs/version-3.1/concepts/supply/supply.mdx b/versioned_docs/version-3.1/concepts/supply/supply.mdx new file mode 100644 index 0000000..dc615da --- /dev/null +++ b/versioned_docs/version-3.1/concepts/supply/supply.mdx @@ -0,0 +1,93 @@ +--- +sidebar_position: 1 +--- + +# Inventory & Supply + +**Inventory & supply** is how Care tracks what physical items a facility stocks, how much of each is on hand, and how items move between stores, wards, suppliers, and patients. It is the operational backbone behind medications, nutritional products, and consumables — keeping stock counts accurate as goods are received, transferred, and dispensed. + +## What it represents + +Care models supply as a small set of connected resources, each answering a different question: + +- **Product knowledge** — the reusable catalogue definition of an item (its name, codes, base unit, ingredients or nutrients, and storage guidelines). It is the "what is this item" record, defined once per instance or per facility. +- **Product** — a concrete, batch-level instance of a catalogue item at a facility, carrying batch-specific detail like lot number, expiry, and purchase price. +- **Inventory item** — the current on-hand quantity of one product at one facility location (for example, a ward pharmacy or central store). +- **Supply request** — a request to move a quantity of a catalogue item into a destination location, grouped under an order. +- **Supply delivery** — a record of items actually moving — into a facility from a supplier, between locations, or out to a patient — grouped under a delivery order. + +Stock balances are not entered by hand. Care derives the on-hand quantity for each location from the deliveries that bring stock in and the dispenses that take it out, so availability stays consistent with what actually happened. + +## Catalogue vs. stock + +It helps to separate the *idea* of an item from the *thing on the shelf*: + +- **Catalogue** (product knowledge) describes an item in the abstract — paracetamol 500 mg tablets, defined once and reused everywhere. +- **Stock** (product, then inventory item) is a specific batch of that item sitting in a specific location, with a real quantity that goes up and down. + +A catalogue entry can be defined instance-wide (shared across all facilities) or scoped to a single facility. Each product references exactly one catalogue entry, so naming and coding live in one place rather than being copied onto every batch. + +## How stock moves + +Stock changes through two ordered workflows. A **request** signals intent ("we need this here"); a **delivery** records the actual movement. + +``` +Supply request: draft → active → processed → completed + ↘ suspended / cancelled +Supply delivery: in_progress → completed + ↘ abandoned +``` + +Both flows are grouped under orders. A **request order** describes items wanted at a destination location, optionally from a supplier organization or an origin location. A **delivery order** records the matching shipment and starts in `draft` or `pending` before progressing. + +A delivery has two shapes depending on where stock comes from: + +- **External delivery** — the order has no origin location, so goods arrive from a supplier. The delivery names the product received. +- **Intra-facility move** — the order has an origin location, so stock transfers between two locations within the facility. The delivery draws from a specific inventory item (batch). + +A delivery order can also dispense directly to a patient. When a delivery completes — or a dispense changes — Care recomputes the affected inventory item so its on-hand quantity reflects everything that has moved in and out. + +## Relationships + +Supply ties together several other parts of Care: + +- **Location** — every inventory item, request, and delivery is anchored to a [facility location](../facility/location.mdx); access is scoped through it. +- **Facility** — products and catalogue entries belong to a [facility](../facility/facility.mdx), and stock is counted per facility location. +- **Organization** — suppliers are [organizations](../facility/organization.mdx) marked as product suppliers. +- **Medication** — dispensing a [medication](../medications/medication.mdx) draws down inventory, keeping clinical and stock records in sync. +- **Billing** — products can link to a charge definition and delivery orders to an invoice, so issued items can be billed. + +## Permissions + +Access to supply resources is governed by facility-scoped permissions. The main ones, with the roles that hold them by default: + +| Permission | Roles | +| --- | --- | +| Can Read Product | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product on Facility | Facility Admin, Admin | +| Can Read Product Knowledge | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product Knowledge on Facility | Facility Admin, Admin | +| Can Read Inventory Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Read Supply Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Request on Facility | Facility Admin, Admin, Staff, Doctor, Nurse | +| Can Read Supply Delivery | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Delivery on Facility | Facility Admin, Admin | +| Can Create External Supply Delivery on Facility | Facility Admin, Admin | + +Roles are granted to users through organization, facility-organization, and patient memberships. Access to a location's inventory, requests, and deliveries is checked against the facility organizations that own that location, and a permission held at a parent organization cascades to its descendants in the organization tree. In practice, clinical and pharmacy staff can read stock and raise supply requests, while creating catalogue items and recording deliveries is reserved for facility administrators. + +## Related + +- Reference: [Product](../../references/supply/product.mdx) +- Reference: [Product knowledge](../../references/supply/product-knowledge.mdx) +- Reference: [Inventory item](../../references/supply/inventory-item.mdx) +- Reference: [Supply request](../../references/supply/supply-request.mdx) +- Reference: [Supply delivery](../../references/supply/supply-delivery.mdx) +- Concept: [Medication](../medications/medication.mdx) +- Concept: [Location](../facility/location.mdx) +- Concept: [Organization](../facility/organization.mdx) +- Concept: [Billing](../billing/billing.mdx) + +## FHIR reference + +These resources are FHIR-aligned: product knowledge maps to FHIR `MedicationKnowledge` / `NutritionProduct`, and the request and delivery records align with FHIR `SupplyRequest` and `SupplyDelivery`. Coded fields use Care's own snake_case status and category values rather than FHIR URIs. diff --git a/versioned_sidebars/version-3.0-sidebars.json b/versioned_sidebars/version-3.0-sidebars.json index 2aaff30..5376f67 100644 --- a/versioned_sidebars/version-3.0-sidebars.json +++ b/versioned_sidebars/version-3.0-sidebars.json @@ -7,10 +7,8 @@ "collapsed": false, "items": [ { - "type": "category", - "label": "Clinical", - "key": "clinical-concepts", - "items": ["concepts/clinical/patient"] + "type": "autogenerated", + "dirName": "concepts" } ] }, diff --git a/versioned_sidebars/version-3.1-sidebars.json b/versioned_sidebars/version-3.1-sidebars.json index 2aaff30..5376f67 100644 --- a/versioned_sidebars/version-3.1-sidebars.json +++ b/versioned_sidebars/version-3.1-sidebars.json @@ -7,10 +7,8 @@ "collapsed": false, "items": [ { - "type": "category", - "label": "Clinical", - "key": "clinical-concepts", - "items": ["concepts/clinical/patient"] + "type": "autogenerated", + "dirName": "concepts" } ] }, From 83060b56e4ea164860921bce23800646b09dcf54 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 17 Jun 2026 02:55:21 +0530 Subject: [PATCH 2/2] Rewrite concept Permissions tables: Permission | Description | System Roles The previous tables were cherry-picked 2-column (Permission | Roles) lists. Replace each concept's table with the complete set, sourced from care/security/permissions/.py: - Every permission in the resource's enum is listed (no cherry-picking). - New Description column: code description where meaningful, otherwise a concise authored explanation of what the permission allows. - System Roles column expands role constants (e.g. CLINICAL_DATA_ACCESS_ROLES) to display names (Doctor, Nurse, Facility Admin, ...). - Multi-resource concepts (billing, supply, organization, questionnaire, specimen, access-control) group rows under per-resource sub-headings. - Surrounding access-model prose preserved. 154 permission rows total. Mirrored to 3.0 & 3.1; full `npm run build` (en + ml) passes clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../concepts/access/access-control.mdx | 31 ++++++---- .../version-3.0/concepts/access/user.mdx | 10 +-- .../version-3.0/concepts/billing/billing.mdx | 62 +++++++++++++------ .../concepts/clinical/allergy-intolerance.mdx | 31 +++++++--- .../concepts/clinical/condition.mdx | 31 +++++++--- .../version-3.0/concepts/clinical/consent.mdx | 18 ++++-- .../concepts/clinical/diagnostic-report.mdx | 8 +-- .../concepts/clinical/encounter.mdx | 22 +++---- .../version-3.0/concepts/clinical/notes.mdx | 30 +++++++-- .../concepts/clinical/observation.mdx | 28 ++++++--- .../concepts/clinical/service-request.mdx | 10 +-- .../concepts/clinical/specimen.mdx | 19 ++++-- .../version-3.0/concepts/facility/device.mdx | 10 +-- .../concepts/facility/facility.mdx | 12 ++-- .../concepts/facility/healthcare-service.mdx | 8 +-- .../concepts/facility/location.mdx | 12 ++-- .../concepts/facility/organization.mdx | 48 +++++++------- .../concepts/forms/questionnaire.mdx | 29 +++++---- .../version-3.0/concepts/forms/valueset.mdx | 7 +-- .../concepts/medications/medication.mdx | 18 +++--- .../concepts/scheduling/scheduling.mdx | 18 +++--- .../version-3.0/concepts/scheduling/token.mdx | 12 ++-- .../version-3.0/concepts/supply/supply.mdx | 50 ++++++++++----- .../concepts/access/access-control.mdx | 31 ++++++---- .../version-3.1/concepts/access/user.mdx | 10 +-- .../version-3.1/concepts/billing/billing.mdx | 62 +++++++++++++------ .../concepts/clinical/allergy-intolerance.mdx | 31 +++++++--- .../concepts/clinical/condition.mdx | 31 +++++++--- .../version-3.1/concepts/clinical/consent.mdx | 18 ++++-- .../concepts/clinical/diagnostic-report.mdx | 8 +-- .../concepts/clinical/encounter.mdx | 22 +++---- .../version-3.1/concepts/clinical/notes.mdx | 30 +++++++-- .../concepts/clinical/observation.mdx | 28 ++++++--- .../concepts/clinical/service-request.mdx | 10 +-- .../concepts/clinical/specimen.mdx | 19 ++++-- .../version-3.1/concepts/facility/device.mdx | 10 +-- .../concepts/facility/facility.mdx | 12 ++-- .../concepts/facility/healthcare-service.mdx | 8 +-- .../concepts/facility/location.mdx | 12 ++-- .../concepts/facility/organization.mdx | 48 +++++++------- .../concepts/forms/questionnaire.mdx | 29 +++++---- .../version-3.1/concepts/forms/valueset.mdx | 7 +-- .../concepts/medications/medication.mdx | 18 +++--- .../concepts/scheduling/scheduling.mdx | 18 +++--- .../version-3.1/concepts/scheduling/token.mdx | 12 ++-- .../version-3.1/concepts/supply/supply.mdx | 50 ++++++++++----- 46 files changed, 668 insertions(+), 380 deletions(-) diff --git a/versioned_docs/version-3.0/concepts/access/access-control.mdx b/versioned_docs/version-3.0/concepts/access/access-control.mdx index d2328d5..ce73fc5 100644 --- a/versioned_docs/version-3.0/concepts/access/access-control.mdx +++ b/versioned_docs/version-3.0/concepts/access/access-control.mdx @@ -72,18 +72,27 @@ So a request to read a patient resolves to "which roles do I hold that reach thi ## Permissions -Permissions are declared in code with a display name, a context, and the default roles that hold them. A few representative examples: +Permissions are declared in code with a display name, a context, and the default roles that hold them. The complete set of organization- and user-related permissions follows. -| Permission | Roles | -| --- | --- | -| Can Create Patient | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Create encounter | Doctor, Nurse, Admin, Facility Admin | -| Can create User in care | Admin, Facility Admin, Administrator | -| Can View Organizations | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | -| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | -| Can Create Organizations | Admin | -| Can Delete Organizations | Admin | +### Organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can View Organizations | View organizations the user can reach | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Create Organizations | Create new organizations in the tree | Admin | +| Can Delete Organizations | Delete existing organizations | Admin | +| Can Manage Organizations | Change an organization's name, description, metadata, etc. | Admin, Admin (role org) | +| Can Manage Users in an Organization | Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) | +| Can Manage Connected Role Organizations | Add, remove, and assign roles to users in connected role organizations | Admin (role org), Manager (role org) | +| Can List Users in an Organizations | List the users who belong to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) | +| Is Geo Admin | Geo Admins can manage facilities in their organization | (no default roles) | + +### User permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can create User in care | Create new user accounts in Care | Admin, Facility Admin, Administrator | +| Can list Users in Care | List user accounts in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, or patient memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective permissions in any context are the union of all roles that reach it. Permissions themselves are platform-maintained reference data — administrators assign roles, not individual permissions. diff --git a/versioned_docs/version-3.0/concepts/access/user.mdx b/versioned_docs/version-3.0/concepts/access/user.mdx index 5bd951f..8c098c9 100644 --- a/versioned_docs/version-3.0/concepts/access/user.mdx +++ b/versioned_docs/version-3.0/concepts/access/user.mdx @@ -40,12 +40,12 @@ Each user has a stable public identifier (surfaced as `id` in the API) that is s ## Permissions -User administration is governed by the user permission set. The two key permissions and the roles that hold them: +User administration is governed by the user permission set. The complete set of user permissions, what each allows, and the system roles that hold it by default: -| Permission | Roles | -| --- | --- | -| Can create User in care | Admin, Facility Admin, Administrator | -| Can list Users in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can create User in care | Create new user accounts within a facility | Admin, Facility Admin, Administrator | +| Can list Users in Care | List and view user accounts in the facility | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Creating users is reserved for administrators, while most clinical and support roles can list and view other users in their facility. Roles are granted to a user through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A superuser bypasses these checks entirely. diff --git a/versioned_docs/version-3.0/concepts/billing/billing.mdx b/versioned_docs/version-3.0/concepts/billing/billing.mdx index b316d08..dd54514 100644 --- a/versioned_docs/version-3.0/concepts/billing/billing.mdx +++ b/versioned_docs/version-3.0/concepts/billing/billing.mdx @@ -62,24 +62,50 @@ A new account opens as `active` / `open` and keeps accruing charges until billin ## Permissions -Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The key permissions: - -| Permission | Roles | -| --- | --- | -| Can Read Account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Account / Can Update Account | Facility Admin, Admin | -| Can Create Charge Item | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Update Charge Item / Can Cancel Charge Item | Facility Admin, Admin | -| Can Create Negative Charge Item | Facility Admin, Admin | -| Can Read Charge Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Read Charge Item Definition | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Charge Item Definition on Facility / Can Set Charge Item Definition on Facility | Facility Admin, Admin | -| Can Write Invoice | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Read Invoice | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Destroy Invoice / Can Manage Locked Invoice | Facility Admin, Admin | -| Can Write Payment Reconciliation | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Read Payment Reconciliation | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Destroy Payment Reconciliation | Facility Admin, Admin | +Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The complete set of billing permissions and the system roles that hold them by default is listed below, grouped by resource. + +### Account + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Account | Open a new financial account for a patient at a facility | Facility Admin, Admin | +| Can Update Account | Edit an existing account, including its billing status | Facility Admin, Admin | +| Can Read Account | View a patient's account and its running balances | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | + +### Charge item + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Negative Charge Item | Raise a charge with a negative amount, such as a refund or adjustment | Facility Admin, Admin | +| Can Create Charge Item | Add a billable line for a service or product to an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Update Charge Item | Edit an existing charge item's details | Facility Admin, Admin | +| Can Read Charge Item | View charge items recorded on an account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Cancel Charge Item | Cancel a charge item so it no longer counts toward billing | Facility Admin, Admin | + +### Charge item definition + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Charge Item Definition on Facility | Create a reusable pricing template for a facility | Facility Admin, Admin | +| Can Read Charge Item Definition | View pricing templates and their rates, surcharges, and taxes | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Set Charge Item Definition on Facility | Assign or activate a pricing template for use at a facility | Facility Admin, Admin | + +### Invoice + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Invoice | Create or edit an invoice grouping charge items for an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Invoice | View invoices, their line items, and computed totals | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Invoice | Delete an invoice from an account | Facility Admin, Admin | +| Can Manage Locked Invoice | Modify or unlock an invoice that has been locked | Facility Admin, Admin | + +### Payment reconciliation + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Payment Reconciliation | Record a payment, advance, or credit note against an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Payment Reconciliation | View payments and credit notes recorded against an account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Payment Reconciliation | Delete a recorded payment reconciliation | Facility Admin, Admin | A broad set of clinical roles can read billing and raise charges, invoices, and payments, while creating or editing accounts, editing or cancelling charges, defining prices, and destroying or unlocking invoices are reserved for administrators. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendant facilities and locations. diff --git a/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx b/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx index 25a27af..0a5cec4 100644 --- a/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/allergy-intolerance.mdx @@ -48,13 +48,30 @@ Alongside the clinical state, a **verification status** (unconfirmed, presumed, ## Permissions -Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient clinical-data** and **encounter clinical-data** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Doctor, Nurse, Staff, Administrator, Facility Admin | -| Can Update a Patient's data | Doctor, Nurse, Staff, Administrator, Facility Admin | -| Update Encounter related clinical data | Doctor, Nurse, Administrator, Facility Admin | +Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient** and **encounter** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. The tables below list the complete set of permissions for both resources. + +### Patient + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient in the system | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | Browse and search the patient list | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical records, including allergies | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Fill and submit questionnaires about a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | Browse encounters; no clinical data is exposed | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Create or modify clinical data on an encounter, including allergies | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data recorded on an encounter, including allergies | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Fill and submit questionnaires about an encounter | Staff, Doctor, Nurse, Admin, Facility Admin | Reading allergies requires "Can view clinical data about patients"; creating an entry requires "Can Update a Patient's data"; updating one requires "Update Encounter related clinical data" on its encounter. These roles are granted to users through organization, facility-organization, or direct patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants, so a user with the right role on a facility automatically reaches the patients and encounters beneath it. diff --git a/versioned_docs/version-3.0/concepts/clinical/condition.mdx b/versioned_docs/version-3.0/concepts/clinical/condition.mdx index 3cde8ff..e6efe37 100644 --- a/versioned_docs/version-3.0/concepts/clinical/condition.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/condition.mdx @@ -60,13 +60,30 @@ Because the patient is taken from the encounter, conditions stay tied to the vis ## Permissions -Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** clinical-data permission and the **encounter** clinical-data permissions, since every condition lives inside an encounter for a patient. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** and **encounter** permission sets, since every condition lives inside an encounter for a patient. The complete set of permissions from both resources is listed below. + +### Patient permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Create a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's demographic and record data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including conditions | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire against a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | View the list of encounters (no clinical data exposed) | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical fields | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Write clinical data on an encounter, including conditions | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data on an encounter, including conditions | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit a questionnaire against a patient encounter | Staff, Doctor, Nurse, Admin, Facility Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective roles on a patient are resolved across their organization, the patient's encounters and locations, and any direct patient assignment. Reading or writing a condition therefore requires the right clinical-data permission on the patient or the encounter it belongs to. diff --git a/versioned_docs/version-3.0/concepts/clinical/consent.mdx b/versioned_docs/version-3.0/concepts/clinical/consent.mdx index c803707..602ce35 100644 --- a/versioned_docs/version-3.0/concepts/clinical/consent.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/consent.mdx @@ -64,12 +64,18 @@ A consent belongs to a single **encounter**, and an encounter can carry many con ## Permissions -Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the patient permissions defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the complete patient permission set defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. The full set of patient permissions is listed below. + +### Patient + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's data, including their consents | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | List and search patient records | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | View a patient's clinical data, including their consents | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | View questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire about a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | Roles are granted to users through organization, facility-organization, and patient memberships. Access to a specific consent is decided by the roles a user holds on its patient — gathered through the patient's encounters, locations, owning organizations, and any direct patient association. Because access is scoped by the organization tree, a permission held at a parent organization cascades to its descendants. diff --git a/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx b/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx index d76bd81..862c6d0 100644 --- a/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/diagnostic-report.mdx @@ -45,10 +45,10 @@ A diagnostic report sits downstream of an order and pulls together the data arou Access to diagnostic reports is governed by a dedicated permission enum: -| Permission | Roles | -| --- | --- | -| Can Create Diagnostic Report on Facility | Facility Admin, Admin, Doctor, Nurse | -| Can Read Diagnostic Report | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Diagnostic Report on Facility | Create diagnostic reports for a facility's patients | Facility Admin, Admin, Doctor, Nurse | +| Can Read Diagnostic Report | View diagnostic reports and their results | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | Roles are granted to users through organization, facility-organization, and patient memberships. Access is then scoped by the organization tree: a permission held at a parent organization cascades to its descendants. In practice, Care decides report access via the originating service request — a user can act on a report if they hold the matching permission on the encounter (or on a facility organization tied to the request's locations) that the report belongs to. diff --git a/versioned_docs/version-3.0/concepts/clinical/encounter.mdx b/versioned_docs/version-3.0/concepts/clinical/encounter.mdx index 09e5c1a..0ba0c31 100644 --- a/versioned_docs/version-3.0/concepts/clinical/encounter.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/encounter.mdx @@ -65,17 +65,17 @@ An encounter sits at the centre of an episode of care and connects to: ## Permissions -Access to encounters is governed by the encounter permission set. The core permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Create encounter | Admin, Doctor, Nurse, Facility Admin | -| Can list encounters | Admin, Doctor, Nurse, Facility Admin | -| Can Read encounter | Admin, Doctor, Nurse, Facility Admin | -| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter non clinical | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Can submit questionnaire about patient encounters | Staff, Doctor, Nurse, Admin, Facility Admin | +Access to encounters is governed by the encounter permission set. The complete set of permissions, what each allows, and the system roles that hold them by default: + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Create a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | List encounters; no clinical data is exposed | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical fields | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Edit clinical data recorded against the encounter | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | View clinical data recorded against the encounter | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit questionnaire responses about a patient's encounters | Staff, Doctor, Nurse, Admin, Facility Admin | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendant organizations. A user can reach an encounter when they hold the relevant permission in any organization linked to that encounter — either through the encounter's responsible organizations or through the patient's current location. Writes are additionally blocked once an encounter is in a closed (terminal) state. diff --git a/versioned_docs/version-3.0/concepts/clinical/notes.mdx b/versioned_docs/version-3.0/concepts/clinical/notes.mdx index e425e57..698a82c 100644 --- a/versioned_docs/version-3.0/concepts/clinical/notes.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/notes.mdx @@ -36,12 +36,30 @@ Editing is also restricted to the original author: a user can revise their own m Notes do not have a dedicated permission set — access is governed by the same **patient** and **encounter** clinical-data permissions that protect the rest of the record. Whether a thread is patient-level or encounter-scoped decides which one applies. -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Administrator (admin), Facility Admin | -| Can Read encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | -| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Administrator (admin), Facility Admin | -| Update Encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | +Because there is no notes-specific permission set, the complete set that can govern note access is the patient and encounter permissions below. + +### Patient permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Edit a patient's data, including patient-level notes | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including notes | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | View questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire response for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | View the list of a patient's encounters (no clinical data) | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Edit clinical data on an encounter, including encounter-scoped notes | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's core details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data on an encounter, including notes | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit a questionnaire response for an encounter | Staff, Doctor, Nurse, Admin, Facility Admin | In practice: reading notes requires clinical-data read access on the patient (or, for encounter-scoped threads, on the encounter). Posting or editing a message in a patient-level thread requires permission to update the patient's data; in an encounter-scoped thread it requires permission to update the encounter's clinical data, and is blocked once the encounter is closed. diff --git a/versioned_docs/version-3.0/concepts/clinical/observation.mdx b/versioned_docs/version-3.0/concepts/clinical/observation.mdx index 67b6539..f432976 100644 --- a/versioned_docs/version-3.0/concepts/clinical/observation.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/observation.mdx @@ -52,15 +52,29 @@ An observation always belongs to a **patient** and is normally recorded within a ## Permissions -Observations are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. +Observation instances are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. The **observation definitions** that template these readings are a separate resource, governed at the facility level by their own permission set. -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can submit questionnaire about patients | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | -| Can view questionnaire responses on patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +### Patient clinical data permissions -Separately, the **observation definitions** that template these readings are governed at the facility level: "Can Read Observation Definition" is held by most clinical and admin roles, while "Can Create Observation Definition on Facility" is restricted to Facility Admin and Admin. +These are the complete patient-context permissions that govern observation instances and the surrounding patient record. + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Edit an existing patient's details | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients in scope | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including observations | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit questionnaires that create patient observations | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Observation definition permissions + +These facility-context permissions govern the definitions that standardise codes, units, and reference ranges for observations — distinct from the observation instances above. + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Observation Definition on Facility | Create observation definition templates for a facility | Facility Admin, Admin | +| Can Read Observation Definition | Read a facility's observation definition templates | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, encounter, and direct patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a role granted at a facility flows down to the patients and encounters beneath it. diff --git a/versioned_docs/version-3.0/concepts/clinical/service-request.mdx b/versioned_docs/version-3.0/concepts/clinical/service-request.mdx index 55dbfe0..b1a021e 100644 --- a/versioned_docs/version-3.0/concepts/clinical/service-request.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/service-request.mdx @@ -51,12 +51,12 @@ A service request never stands alone. It is always created within an **encounter ## Permissions -Access to service requests is governed by a dedicated permission set: +Access to service requests is governed by a dedicated permission set. The table below lists the complete set of permissions and the system roles that hold each by default: -| Permission | Roles | -| --- | --- | -| Can Read Service Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Write Service Request on Facility | Facility Admin, Admin, Doctor, Nurse | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Service Request on Facility | Create or update service requests within a facility | Facility Admin, Admin, Doctor, Nurse | +| Can Read Service Request | View service requests for a facility's patients | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A user reaches a specific request either through their membership in the encounter's facility organization (and its current location) or through the facility organizations of the locations the request is attached to. diff --git a/versioned_docs/version-3.0/concepts/clinical/specimen.mdx b/versioned_docs/version-3.0/concepts/clinical/specimen.mdx index e4d8d2c..f4568bf 100644 --- a/versioned_docs/version-3.0/concepts/clinical/specimen.mdx +++ b/versioned_docs/version-3.0/concepts/clinical/specimen.mdx @@ -49,12 +49,21 @@ Each specimen carries an **accession identifier** — the lab accession number o ## Permissions -Access to specimens is controlled by role-based permissions, scoped to the facility: +Access to specimens is controlled by role-based permissions, scoped to the facility. The tables below list the complete set of permissions that govern specimens and the specimen-definition templates they are based on. -| Permission | Roles | -| --- | --- | -| Can Read Specimen | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Create Specimen on Facility | Facility Admin, Admin, Doctor, Nurse | +### Specimen + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Specimen | View specimen records within a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Create Specimen on Facility | Register a new specimen within a facility | Facility Admin, Admin, Doctor, Nurse | + +### Specimen Definition + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Specimen Definition | View specimen-definition templates within a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Specimen Definition on Facility | Create a specimen-definition template within a facility | Facility Admin, Admin | In practice, viewing and creating a specimen are also gated by access to the linked service request, so a user must be able to reach the underlying order. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. diff --git a/versioned_docs/version-3.0/concepts/facility/device.mdx b/versioned_docs/version-3.0/concepts/facility/device.mdx index 560ba15..35c4d62 100644 --- a/versioned_docs/version-3.0/concepts/facility/device.mdx +++ b/versioned_docs/version-3.0/concepts/facility/device.mdx @@ -48,11 +48,11 @@ Care also keeps a **service history** — a log of maintenance and servicing eve Access to devices is governed by the device permissions, granted to users through their roles: -| Permission | Roles | -| --- | --- | -| Can List Devices on Facility | Staff, Administrator, Doctor, Nurse, Facility Admin, Pharmacist | -| Can Manage Devices on Facility | Staff, Administrator, Facility Admin, Pharmacist | -| Can Manage Device Associations to Encounters | Staff, Administrator, Doctor, Nurse, Facility Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can List Devices on Facility | View the devices registered on a facility | Staff, Admin, Doctor, Nurse, Facility Admin, Pharmacist | +| Can Manage Device Associations to Encounters | Attach devices to or detach them from encounters | Staff, Admin, Doctor, Nurse, Facility Admin | +| Can Manage Devices on Facility | Create, update, and manage devices on a facility | Staff, Admin, Facility Admin, Pharmacist | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. A device is visible to users whose memberships overlap its managing organization (or the organization of the location it currently sits in), so listing and management follow the facility's organization hierarchy rather than being open to everyone in the facility. diff --git a/versioned_docs/version-3.0/concepts/facility/facility.mdx b/versioned_docs/version-3.0/concepts/facility/facility.mdx index e1b4e20..e9a2003 100644 --- a/versioned_docs/version-3.0/concepts/facility/facility.mdx +++ b/versioned_docs/version-3.0/concepts/facility/facility.mdx @@ -40,13 +40,13 @@ Each facility can carry its own monetary configuration: facility-defined discoun ## Permissions -Access to facilities is governed by the `FacilityPermissions` enum. The key permissions and the roles that hold them: +Access to facilities is governed by the `FacilityPermissions` enum. The complete set of permissions, what each allows, and the system roles that hold them by default: -| Permission | Roles | -| --- | --- | -| Can Create on Facility | Administrator, Admin, Facility Admin | -| Can Read on Facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | -| Can Update on Facility | Facility Admin, Administrator, Admin, Staff | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Facility | Register a new facility in the deployment | Administrator, Admin, Facility Admin | +| Can Read on Facility | View a facility's details and configuration | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Can Update on Facility | Edit a facility's details and configuration | Facility Admin, Administrator, Admin, Staff | Roles are granted to users through organization memberships — a user holds a role within a facility's root organization, a facility sub-organization (team or department), or the geographic organization tree. Access is then scoped by that tree: a permission held at a parent organization cascades to its descendants, so a role granted high in the geographic hierarchy can authorize action on the facilities beneath it, while a role on a facility's own root org governs that site directly. diff --git a/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx b/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx index 917b977..71c2315 100644 --- a/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx +++ b/versioned_docs/version-3.0/concepts/facility/healthcare-service.mdx @@ -45,10 +45,10 @@ Because of these links, a healthcare service is what scheduling, ordering, and s Access to healthcare services is governed by the `HealthcareService` permissions: -| Permission | Roles | -| --- | --- | -| Can Read Healthcare Service | Facility Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Healthcare Service on Facility | Facility Admin, Administrator | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Healthcare Service on Facility | Create a healthcare service under a facility | Facility Admin, Admin | +| Can Read Healthcare Service | View a facility's healthcare services | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Reading the catalogue of services is broadly available to clinical and support staff, while creating or changing services is restricted to facility administrators. Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. Creating a service additionally requires the permission at the facility root. diff --git a/versioned_docs/version-3.0/concepts/facility/location.mdx b/versioned_docs/version-3.0/concepts/facility/location.mdx index 119301f..b8a5bd7 100644 --- a/versioned_docs/version-3.0/concepts/facility/location.mdx +++ b/versioned_docs/version-3.0/concepts/facility/location.mdx @@ -52,12 +52,12 @@ Separately, an **operational status** describes the live state of a bed or room Access to locations is governed by the facility-location permissions: -| Permission | Roles | -| --- | --- | -| Can List Facility Locations | Administrator, Doctor, Nurse, Staff, Pharmacist, Facility Admin, Admin | -| Can Create/Update Facility Locations | Facility Admin, Staff, Admin | -| Can List Facility Location Organizations | Facility Admin, Staff, Admin | -| Can Create/Update Facility Location Organizations | Facility Admin, Staff, Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can List Facility Locations | View the locations and location tree within a facility | Admin, Doctor, Facility Admin, Administrator, Nurse, Staff, Pharmacist | +| Can Create/Update Facility Locations | Add new locations or edit existing ones in a facility | Facility Admin, Admin, Staff | +| Can List Facility Location Organizations | View the organizations granted access to a location | Facility Admin, Admin, Staff | +| Can Create/Update Facility Location Organizations | Grant or update organization access to a location | Facility Admin, Admin, Staff | Roles are granted to users through facility-organization membership, and access is scoped by the organization tree: a permission held on an organization applies to the locations that organization can reach, and grants at a parent location cascade to its children. Because that cascade is computed asynchronously, newly granted access settles a moment after the change is made. diff --git a/versioned_docs/version-3.0/concepts/facility/organization.mdx b/versioned_docs/version-3.0/concepts/facility/organization.mdx index 60f2c85..2243482 100644 --- a/versioned_docs/version-3.0/concepts/facility/organization.mdx +++ b/versioned_docs/version-3.0/concepts/facility/organization.mdx @@ -56,28 +56,32 @@ Membership is also deliberate: belonging to an organization does not automatical ## Permissions -Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. - -Key instance-wide organization permissions: - -| Permission | Roles | -| --- | --- | -| Can View Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | -| Can Create Organizations | Admin | -| Can Delete Organizations | Admin | -| Can Manage Organizations | Admin, role-org Admin | -| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | -| Can List Users in an Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager | - -Key facility-organization permissions: - -| Permission | Roles | -| --- | --- | -| Can View Facility Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer | -| Can Create Facility Organizations | Facility Admin | -| Can Delete Facility Organizations | Facility Admin | -| Can Manage Facility Organizations | Facility Admin, Administrator | -| Can Manage Users in a Facility Organization | Facility Admin, Administrator | +Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. The tables below list the complete set of permissions in each, with the system roles that hold them by default. + +### Organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can View Organizations | View organizations and their details in the tree | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Create Organizations | Create new organizations in the instance-wide tree | Admin | +| Can Delete Organizations | Remove organizations from the tree | Admin | +| Can Manage Organizations | This includes changing names, descriptions, metadata, etc. | Admin, Admin (role org) | +| Can Manage Users in an Organization | Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) | +| Can Manage Connected Role Organizations | Add, remove, and assign roles to users in connected role organizations | Admin (role org), Manager (role org) | +| Can List Users in an Organizations | List the users who belong to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) | +| Is Geo Admin | Geo Admins can manage facilities in their organization | None by default | + +### Facility organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Facility Organizations | Create departments and teams within a facility | Facility Admin | +| Can Create Facility Organizations Root | Create the root facility organization for a facility | Facility Admin | +| Can View Facility Organizations | View a facility's internal organizations and their details | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer | +| Can Delete Facility Organizations | Remove organizations from a facility's internal tree | Facility Admin | +| Can Manage Facility Organizations | This includes changing names, descriptions, metadata, etc. | Facility Admin, Administrator | +| Can List Users in a Facility Organizations | List the users who belong to a facility organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse | +| Can Manage Users in a Facility Organization | Add, remove, and assign roles to users in a facility organization | Facility Admin, Administrator | Roles are granted to users through organization and facility-organization memberships. Access is then scoped by the tree: a permission held at a parent organization cascades to all of its descendants, so checks walk the chain of ancestors above a given organization. Geo admins are a special case — they can manage and view facility organizations within the geography they administer, regardless of facility membership. When assigning a role to another user, an admin can only grant a role whose permissions are a subset of their own. diff --git a/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx b/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx index 23faf64..3009ad4 100644 --- a/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx +++ b/versioned_docs/version-3.0/concepts/forms/questionnaire.mdx @@ -45,17 +45,24 @@ Questions are typed, which is what makes the captured data structured. Common ty ## Permissions -Access to questionnaires is governed by a dedicated permission set; response templates have their own. The key permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Read Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin, Organization Admin/Manager/Member | -| Can Submit Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Facility Admin, Organization Admin/Manager/Member | -| Can Create/Update Questionnaires | Administrator, Facility Admin | -| Can Archive Questionnaires | Administrator, Facility Admin | -| Can Manage Questionnaires | Administrator, Facility Admin, Organization Admin | -| Can Read Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | -| Can Create/Update Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | +Access to questionnaires is governed by a dedicated permission set; response templates have their own. The complete set of permissions and the system roles that hold them by default: + +### Questionnaire + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Questionnaires | View questionnaire definitions and their questions | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Submit Questionnaires | Fill out and submit responses to a questionnaire | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Admin (role org), Manager (role org), Member (role org) | +| Can Create/Update Questionnaires | Author new questionnaires and edit existing ones | Admin, Facility Admin | +| Can Archive Questionnaires | Retire a questionnaire so it stops accepting submissions | Admin, Facility Admin | +| Can Manage Questionnaires | Add or remove organizations from questionnaires to control access | Admin, Facility Admin, Admin (role org) | + +### Questionnaire Response Template + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Questionnaire Response Templates | View saved response templates and order sets | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | +| Can Create/Update Questionnaire Response Templates | Create and edit reusable response templates | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, and patient memberships. A questionnaire is attached to organizations, and access is decided by checking the user's roles against those organizations. Because permissions cascade down the organization tree, a role held at a parent organization also applies to the questionnaires scoped to its descendants. diff --git a/versioned_docs/version-3.0/concepts/forms/valueset.mdx b/versioned_docs/version-3.0/concepts/forms/valueset.mdx index dc3368f..67f77ec 100644 --- a/versioned_docs/version-3.0/concepts/forms/valueset.mdx +++ b/versioned_docs/version-3.0/concepts/forms/valueset.mdx @@ -48,12 +48,7 @@ This split lets the platform ship sensible defaults while still letting each sit ## Permissions -Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. Any authenticated user can read and search them — that is what powers the code pickers throughout the product. Authoring is gated to administrators. - -| Permission | Roles | -| --- | --- | -| Read / search value sets | Any authenticated user (shared reference data) | -| Create / update value sets | Administrator, Facility Admin | +Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. There is no value-set permission enum to enumerate: any authenticated user can read and search value sets — that is what powers the code pickers throughout the product — while authoring (creating or changing value sets) is gated to administrators, and system-defined value sets are read-only for everyone. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a role held at a parent organization cascades to its descendants. Because value sets are global reference data rather than patient- or encounter-scoped, read access is universal; the administrative roles above are what control who may author or change them, and system-defined value sets are read-only for everyone. diff --git a/versioned_docs/version-3.0/concepts/medications/medication.mdx b/versioned_docs/version-3.0/concepts/medications/medication.mdx index 0d6335d..33e985e 100644 --- a/versioned_docs/version-3.0/concepts/medications/medication.mdx +++ b/versioned_docs/version-3.0/concepts/medications/medication.mdx @@ -56,18 +56,18 @@ Medication access splits along two access models. **Dispense** has dedicated, location-centric permissions — pharmacists work in the pharmacy and often have no encounter access, so dispensing keys off the dispensing location instead: -| Permission | Roles | -| --- | --- | -| Pharmacist in Care | Facility Admin, Administrator, Pharmacist | -| Medication Dispense Read | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | -| Write Medication Dispense | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | +| Permission | Description | System Roles | +| --- | --- | --- | +| Pharmacist in Care | Grants full access to medication requests and lets the holder create dispenses for patients | Facility Admin, Admin, Pharmacist | +| Medication Dispense Read | Allows reading medication dispense records | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Write Medication Dispense | Allows creating and updating medication dispense records | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | **Requests, administrations, and statements** are clinical data on the encounter, so they are governed by the encounter clinical-data permissions: -| Permission | Roles | -| --- | --- | -| Can Read encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read encounter related clinical data | Allows reading clinical data recorded on an encounter | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Allows creating and updating clinical data on an encounter | Admin, Doctor, Nurse, Facility Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — and dispense access is checked against the location's facility-organization rather than the encounter. diff --git a/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx b/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx index da46e83..3c41150 100644 --- a/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx +++ b/versioned_docs/version-3.0/concepts/scheduling/scheduling.mdx @@ -48,15 +48,15 @@ Other terminal or branch states include `noshow` (patient did not arrive), `wait ## Permissions -Access to schedules and bookings is governed by the schedule permission set. The key permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Create on Schedule | Admin, Staff, Facility Admin, Doctor, Nurse | -| Can list schedule on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | -| Can list bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | -| Can update bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse | -| Can reschedule bookings on Object | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | +Access to schedules and bookings is governed by the schedule permission set. This is the complete set of schedule permissions and the system roles that hold them by default: + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Schedule | Create and edit schedules and availability for a resource | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can list schedule on Object | View the schedules and availability of a resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list bookings on Object | View the bookings (appointments) made against a resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can update bookings on Object | Create and update bookings, including status changes | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can reschedule bookings on Object | Reschedule or cancel a booking to a different slot | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. For practitioner schedules, access is decided against the organizations the practitioner belongs to within the facility; for locations and healthcare services, against that resource's managing organization. diff --git a/versioned_docs/version-3.0/concepts/scheduling/token.mdx b/versioned_docs/version-3.0/concepts/scheduling/token.mdx index b3e8731..1d33d6a 100644 --- a/versioned_docs/version-3.0/concepts/scheduling/token.mdx +++ b/versioned_docs/version-3.0/concepts/scheduling/token.mdx @@ -50,12 +50,12 @@ Queue progression — which token is current and who is next — is maintained b Token access is governed by facility-scoped permissions. Whether a user can see or manage a queue is decided by their membership in the facility organization that owns the resource the queue is bound to. -| Permission | Roles | -| --- | --- | -| Can Create on Token | Administrator, Staff, Facility Admin, Doctor, Nurse | -| Can list token on Object | Administrator, Staff, Facility Admin, Doctor, Nurse | -| Can Create on Token Category | Administrator, Staff, Facility Admin | -| Can list token category on Facility | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Token | Issue and update tokens in a facility queue | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list token on Object | View the tokens issued for a queue | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can Create on Token Category | Create and manage token categories for a facility | Admin, Staff, Facility Admin | +| Can list token category on Facility | View the token categories defined for a facility | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | Roles are granted to users through facility-organization memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a user's reach over a queue follows the organization that manages the queue's practitioner, location, or healthcare service. diff --git a/versioned_docs/version-3.0/concepts/supply/supply.mdx b/versioned_docs/version-3.0/concepts/supply/supply.mdx index dc615da..d5c939a 100644 --- a/versioned_docs/version-3.0/concepts/supply/supply.mdx +++ b/versioned_docs/version-3.0/concepts/supply/supply.mdx @@ -59,20 +59,42 @@ Supply ties together several other parts of Care: ## Permissions -Access to supply resources is governed by facility-scoped permissions. The main ones, with the roles that hold them by default: - -| Permission | Roles | -| --- | --- | -| Can Read Product | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Product on Facility | Facility Admin, Admin | -| Can Read Product Knowledge | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Product Knowledge on Facility | Facility Admin, Admin | -| Can Read Inventory Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Read Supply Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Supply Request on Facility | Facility Admin, Admin, Staff, Doctor, Nurse | -| Can Read Supply Delivery | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Supply Delivery on Facility | Facility Admin, Admin | -| Can Create External Supply Delivery on Facility | Facility Admin, Admin | +Access to supply resources is governed by facility-scoped permissions. The complete set, grouped by resource, with the system roles that hold each by default: + +### Product + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Product | View batch-level product instances stocked at a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product on Facility | Add a new batch-level product instance to a facility | Facility Admin, Admin | + +### Product knowledge + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Product Knowledge | View catalogue definitions of stockable items | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product Knowledge on Facility | Define a new catalogue item for a facility | Facility Admin, Admin | + +### Inventory item + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Inventory Item | View on-hand stock quantities at facility locations | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | + +### Supply request + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Supply Request | View requests to move stock into a location | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Request on Facility | Raise a request to move stock into a location | Facility Admin, Admin, Staff, Doctor, Nurse | + +### Supply delivery + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Supply Delivery | View records of stock moving in, between, or out | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Delivery on Facility | Record a delivery moving stock at a facility | Facility Admin, Admin | +| Can Create External Supply Delivery on Facility | Record a delivery of goods arriving from a supplier | Facility Admin, Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access to a location's inventory, requests, and deliveries is checked against the facility organizations that own that location, and a permission held at a parent organization cascades to its descendants in the organization tree. In practice, clinical and pharmacy staff can read stock and raise supply requests, while creating catalogue items and recording deliveries is reserved for facility administrators. diff --git a/versioned_docs/version-3.1/concepts/access/access-control.mdx b/versioned_docs/version-3.1/concepts/access/access-control.mdx index d2328d5..ce73fc5 100644 --- a/versioned_docs/version-3.1/concepts/access/access-control.mdx +++ b/versioned_docs/version-3.1/concepts/access/access-control.mdx @@ -72,18 +72,27 @@ So a request to read a patient resolves to "which roles do I hold that reach thi ## Permissions -Permissions are declared in code with a display name, a context, and the default roles that hold them. A few representative examples: +Permissions are declared in code with a display name, a context, and the default roles that hold them. The complete set of organization- and user-related permissions follows. -| Permission | Roles | -| --- | --- | -| Can Create Patient | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Create encounter | Doctor, Nurse, Admin, Facility Admin | -| Can create User in care | Admin, Facility Admin, Administrator | -| Can View Organizations | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | -| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | -| Can Create Organizations | Admin | -| Can Delete Organizations | Admin | +### Organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can View Organizations | View organizations the user can reach | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Create Organizations | Create new organizations in the tree | Admin | +| Can Delete Organizations | Delete existing organizations | Admin | +| Can Manage Organizations | Change an organization's name, description, metadata, etc. | Admin, Admin (role org) | +| Can Manage Users in an Organization | Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) | +| Can Manage Connected Role Organizations | Add, remove, and assign roles to users in connected role organizations | Admin (role org), Manager (role org) | +| Can List Users in an Organizations | List the users who belong to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) | +| Is Geo Admin | Geo Admins can manage facilities in their organization | (no default roles) | + +### User permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can create User in care | Create new user accounts in Care | Admin, Facility Admin, Administrator | +| Can list Users in Care | List user accounts in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, or patient memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective permissions in any context are the union of all roles that reach it. Permissions themselves are platform-maintained reference data — administrators assign roles, not individual permissions. diff --git a/versioned_docs/version-3.1/concepts/access/user.mdx b/versioned_docs/version-3.1/concepts/access/user.mdx index 5bd951f..8c098c9 100644 --- a/versioned_docs/version-3.1/concepts/access/user.mdx +++ b/versioned_docs/version-3.1/concepts/access/user.mdx @@ -40,12 +40,12 @@ Each user has a stable public identifier (surfaced as `id` in the API) that is s ## Permissions -User administration is governed by the user permission set. The two key permissions and the roles that hold them: +User administration is governed by the user permission set. The complete set of user permissions, what each allows, and the system roles that hold it by default: -| Permission | Roles | -| --- | --- | -| Can create User in care | Admin, Facility Admin, Administrator | -| Can list Users in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can create User in care | Create new user accounts within a facility | Admin, Facility Admin, Administrator | +| Can list Users in Care | List and view user accounts in the facility | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Creating users is reserved for administrators, while most clinical and support roles can list and view other users in their facility. Roles are granted to a user through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A superuser bypasses these checks entirely. diff --git a/versioned_docs/version-3.1/concepts/billing/billing.mdx b/versioned_docs/version-3.1/concepts/billing/billing.mdx index b316d08..dd54514 100644 --- a/versioned_docs/version-3.1/concepts/billing/billing.mdx +++ b/versioned_docs/version-3.1/concepts/billing/billing.mdx @@ -62,24 +62,50 @@ A new account opens as `active` / `open` and keeps accruing charges until billin ## Permissions -Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The key permissions: - -| Permission | Roles | -| --- | --- | -| Can Read Account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Account / Can Update Account | Facility Admin, Admin | -| Can Create Charge Item | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Update Charge Item / Can Cancel Charge Item | Facility Admin, Admin | -| Can Create Negative Charge Item | Facility Admin, Admin | -| Can Read Charge Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Read Charge Item Definition | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Charge Item Definition on Facility / Can Set Charge Item Definition on Facility | Facility Admin, Admin | -| Can Write Invoice | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Read Invoice | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Destroy Invoice / Can Manage Locked Invoice | Facility Admin, Admin | -| Can Write Payment Reconciliation | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Read Payment Reconciliation | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Destroy Payment Reconciliation | Facility Admin, Admin | +Billing data is sensitive financial information, so access is governed by dedicated, facility-scoped permissions for each resource. The complete set of billing permissions and the system roles that hold them by default is listed below, grouped by resource. + +### Account + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Account | Open a new financial account for a patient at a facility | Facility Admin, Admin | +| Can Update Account | Edit an existing account, including its billing status | Facility Admin, Admin | +| Can Read Account | View a patient's account and its running balances | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | + +### Charge item + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Negative Charge Item | Raise a charge with a negative amount, such as a refund or adjustment | Facility Admin, Admin | +| Can Create Charge Item | Add a billable line for a service or product to an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Update Charge Item | Edit an existing charge item's details | Facility Admin, Admin | +| Can Read Charge Item | View charge items recorded on an account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Cancel Charge Item | Cancel a charge item so it no longer counts toward billing | Facility Admin, Admin | + +### Charge item definition + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Charge Item Definition on Facility | Create a reusable pricing template for a facility | Facility Admin, Admin | +| Can Read Charge Item Definition | View pricing templates and their rates, surcharges, and taxes | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Set Charge Item Definition on Facility | Assign or activate a pricing template for use at a facility | Facility Admin, Admin | + +### Invoice + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Invoice | Create or edit an invoice grouping charge items for an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Invoice | View invoices, their line items, and computed totals | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Invoice | Delete an invoice from an account | Facility Admin, Admin | +| Can Manage Locked Invoice | Modify or unlock an invoice that has been locked | Facility Admin, Admin | + +### Payment reconciliation + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Payment Reconciliation | Record a payment, advance, or credit note against an account | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Read Payment Reconciliation | View payments and credit notes recorded against an account | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Destroy Payment Reconciliation | Delete a recorded payment reconciliation | Facility Admin, Admin | A broad set of clinical roles can read billing and raise charges, invoices, and payments, while creating or editing accounts, editing or cancelling charges, defining prices, and destroying or unlocking invoices are reserved for administrators. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendant facilities and locations. diff --git a/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx b/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx index 25a27af..0a5cec4 100644 --- a/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/allergy-intolerance.mdx @@ -48,13 +48,30 @@ Alongside the clinical state, a **verification status** (unconfirmed, presumed, ## Permissions -Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient clinical-data** and **encounter clinical-data** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Doctor, Nurse, Staff, Administrator, Facility Admin | -| Can Update a Patient's data | Doctor, Nurse, Staff, Administrator, Facility Admin | -| Update Encounter related clinical data | Doctor, Nurse, Administrator, Facility Admin | +Allergy & Intolerance has no dedicated permission of its own. Access is governed by the **patient** and **encounter** permissions, checked against the patient the entry belongs to and the encounter it is recorded in. The tables below list the complete set of permissions for both resources. + +### Patient + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient in the system | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | Browse and search the patient list | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical records, including allergies | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Fill and submit questionnaires about a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | Browse encounters; no clinical data is exposed | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Create or modify clinical data on an encounter, including allergies | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data recorded on an encounter, including allergies | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Fill and submit questionnaires about an encounter | Staff, Doctor, Nurse, Admin, Facility Admin | Reading allergies requires "Can view clinical data about patients"; creating an entry requires "Can Update a Patient's data"; updating one requires "Update Encounter related clinical data" on its encounter. These roles are granted to users through organization, facility-organization, or direct patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants, so a user with the right role on a facility automatically reaches the patients and encounters beneath it. diff --git a/versioned_docs/version-3.1/concepts/clinical/condition.mdx b/versioned_docs/version-3.1/concepts/clinical/condition.mdx index 3cde8ff..e6efe37 100644 --- a/versioned_docs/version-3.1/concepts/clinical/condition.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/condition.mdx @@ -60,13 +60,30 @@ Because the patient is taken from the encounter, conditions stay tied to the vis ## Permissions -Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** clinical-data permission and the **encounter** clinical-data permissions, since every condition lives inside an encounter for a patient. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | +Conditions are clinical data. There is no separate "condition" permission — access is governed by the **patient** and **encounter** permission sets, since every condition lives inside an encounter for a patient. The complete set of permissions from both resources is listed below. + +### Patient permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Create a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's demographic and record data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including conditions | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire against a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | View the list of encounters (no clinical data exposed) | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical fields | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Write clinical data on an encounter, including conditions | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data on an encounter, including conditions | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit a questionnaire against a patient encounter | Staff, Doctor, Nurse, Admin, Facility Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective roles on a patient are resolved across their organization, the patient's encounters and locations, and any direct patient assignment. Reading or writing a condition therefore requires the right clinical-data permission on the patient or the encounter it belongs to. diff --git a/versioned_docs/version-3.1/concepts/clinical/consent.mdx b/versioned_docs/version-3.1/concepts/clinical/consent.mdx index c803707..602ce35 100644 --- a/versioned_docs/version-3.1/concepts/clinical/consent.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/consent.mdx @@ -64,12 +64,18 @@ A consent belongs to a single **encounter**, and an encounter can carry many con ## Permissions -Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the patient permissions defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. - -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +Consent is patient clinical data, so it has no dedicated permission of its own — access is governed by the complete patient permission set defined in `PatientPermissions`. Reading consents requires the clinical-data permission; creating or updating them requires patient write access. The full set of patient permissions is listed below. + +### Patient + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Modify an existing patient's data, including their consents | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | List and search patient records | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | View a patient's clinical data, including their consents | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | View questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire about a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | Roles are granted to users through organization, facility-organization, and patient memberships. Access to a specific consent is decided by the roles a user holds on its patient — gathered through the patient's encounters, locations, owning organizations, and any direct patient association. Because access is scoped by the organization tree, a permission held at a parent organization cascades to its descendants. diff --git a/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx b/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx index d76bd81..862c6d0 100644 --- a/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/diagnostic-report.mdx @@ -45,10 +45,10 @@ A diagnostic report sits downstream of an order and pulls together the data arou Access to diagnostic reports is governed by a dedicated permission enum: -| Permission | Roles | -| --- | --- | -| Can Create Diagnostic Report on Facility | Facility Admin, Admin, Doctor, Nurse | -| Can Read Diagnostic Report | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Diagnostic Report on Facility | Create diagnostic reports for a facility's patients | Facility Admin, Admin, Doctor, Nurse | +| Can Read Diagnostic Report | View diagnostic reports and their results | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | Roles are granted to users through organization, facility-organization, and patient memberships. Access is then scoped by the organization tree: a permission held at a parent organization cascades to its descendants. In practice, Care decides report access via the originating service request — a user can act on a report if they hold the matching permission on the encounter (or on a facility organization tied to the request's locations) that the report belongs to. diff --git a/versioned_docs/version-3.1/concepts/clinical/encounter.mdx b/versioned_docs/version-3.1/concepts/clinical/encounter.mdx index 09e5c1a..0ba0c31 100644 --- a/versioned_docs/version-3.1/concepts/clinical/encounter.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/encounter.mdx @@ -65,17 +65,17 @@ An encounter sits at the centre of an episode of care and connects to: ## Permissions -Access to encounters is governed by the encounter permission set. The core permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Create encounter | Admin, Doctor, Nurse, Facility Admin | -| Can list encounters | Admin, Doctor, Nurse, Facility Admin | -| Can Read encounter | Admin, Doctor, Nurse, Facility Admin | -| Can Read encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter non clinical | Admin, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Admin, Doctor, Nurse, Facility Admin | -| Can submit questionnaire about patient encounters | Staff, Doctor, Nurse, Admin, Facility Admin | +Access to encounters is governed by the encounter permission set. The complete set of permissions, what each allows, and the system roles that hold them by default: + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Create a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | List encounters; no clinical data is exposed | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical fields | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Edit clinical data recorded against the encounter | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | View clinical data recorded against the encounter | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit questionnaire responses about a patient's encounters | Staff, Doctor, Nurse, Admin, Facility Admin | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendant organizations. A user can reach an encounter when they hold the relevant permission in any organization linked to that encounter — either through the encounter's responsible organizations or through the patient's current location. Writes are additionally blocked once an encounter is in a closed (terminal) state. diff --git a/versioned_docs/version-3.1/concepts/clinical/notes.mdx b/versioned_docs/version-3.1/concepts/clinical/notes.mdx index e425e57..698a82c 100644 --- a/versioned_docs/version-3.1/concepts/clinical/notes.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/notes.mdx @@ -36,12 +36,30 @@ Editing is also restricted to the original author: a user can revise their own m Notes do not have a dedicated permission set — access is governed by the same **patient** and **encounter** clinical-data permissions that protect the rest of the record. Whether a thread is patient-level or encounter-scoped decides which one applies. -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Administrator (admin), Facility Admin | -| Can Read encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | -| Can Update a Patient's data | Staff, Doctor, Nurse, Administrator, Administrator (admin), Facility Admin | -| Update Encounter related clinical data | Administrator (admin), Doctor, Nurse, Facility Admin | +Because there is no notes-specific permission set, the complete set that can govern note access is the patient and encounter permissions below. + +### Patient permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Edit a patient's data, including patient-level notes | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including notes | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | View questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit a questionnaire response for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Encounter permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create encounter | Start a new encounter for a patient | Admin, Doctor, Nurse, Facility Admin | +| Can list encounters | View the list of a patient's encounters (no clinical data) | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter non clinical | Edit an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Edit clinical data on an encounter, including encounter-scoped notes | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter | View an encounter's core details | Admin, Doctor, Nurse, Facility Admin | +| Can Read encounter related clinical data | Read clinical data on an encounter, including notes | Admin, Doctor, Nurse, Facility Admin | +| Can submit questionnaire about patient encounters | Submit a questionnaire response for an encounter | Staff, Doctor, Nurse, Admin, Facility Admin | In practice: reading notes requires clinical-data read access on the patient (or, for encounter-scoped threads, on the encounter). Posting or editing a message in a patient-level thread requires permission to update the patient's data; in an encounter-scoped thread it requires permission to update the encounter's clinical data, and is blocked once the encounter is closed. diff --git a/versioned_docs/version-3.1/concepts/clinical/observation.mdx b/versioned_docs/version-3.1/concepts/clinical/observation.mdx index 67b6539..f432976 100644 --- a/versioned_docs/version-3.1/concepts/clinical/observation.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/observation.mdx @@ -52,15 +52,29 @@ An observation always belongs to a **patient** and is normally recorded within a ## Permissions -Observations are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. +Observation instances are clinical data, so access is governed by the **patient** permission set rather than a dedicated observation permission. Whether a user can record or read observations depends on the roles they hold for that patient. The **observation definitions** that template these readings are a separate resource, governed at the facility level by their own permission set. -| Permission | Roles | -| --- | --- | -| Can view clinical data about patients | Staff, Doctor, Nurse, Admin, Facility Admin | -| Can submit questionnaire about patients | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | -| Can view questionnaire responses on patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +### Patient clinical data permissions -Separately, the **observation definitions** that template these readings are governed at the facility level: "Can Read Observation Definition" is held by most clinical and admin roles, while "Can Create Observation Definition on Facility" is restricted to Facility Admin and Admin. +These are the complete patient-context permissions that govern observation instances and the surrounding patient record. + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Patient | Register a new patient record | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can Update a Patient's data | Edit an existing patient's details | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin | +| Can list patients | View the list of patients in scope | Staff, Doctor, Nurse, Administrator, Admin, Facility Admin, Volunteer, Pharmacist | +| Can view clinical data about patients | Read a patient's clinical data, including observations | Staff, Doctor, Nurse, Admin, Facility Admin | +| Can view questionnaire responses on patient | Read questionnaire responses recorded for a patient | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator, Pharmacist | +| Can submit questionnaire about patients | Submit questionnaires that create patient observations | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | + +### Observation definition permissions + +These facility-context permissions govern the definitions that standardise codes, units, and reference ranges for observations — distinct from the observation instances above. + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Observation Definition on Facility | Create observation definition templates for a facility | Facility Admin, Admin | +| Can Read Observation Definition | Read a facility's observation definition templates | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, encounter, and direct patient memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a role granted at a facility flows down to the patients and encounters beneath it. diff --git a/versioned_docs/version-3.1/concepts/clinical/service-request.mdx b/versioned_docs/version-3.1/concepts/clinical/service-request.mdx index 55dbfe0..b1a021e 100644 --- a/versioned_docs/version-3.1/concepts/clinical/service-request.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/service-request.mdx @@ -51,12 +51,12 @@ A service request never stands alone. It is always created within an **encounter ## Permissions -Access to service requests is governed by a dedicated permission set: +Access to service requests is governed by a dedicated permission set. The table below lists the complete set of permissions and the system roles that hold each by default: -| Permission | Roles | -| --- | --- | -| Can Read Service Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Write Service Request on Facility | Facility Admin, Admin, Doctor, Nurse | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Write Service Request on Facility | Create or update service requests within a facility | Facility Admin, Admin, Doctor, Nurse | +| Can Read Service Request | View service requests for a facility's patients | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A user reaches a specific request either through their membership in the encounter's facility organization (and its current location) or through the facility organizations of the locations the request is attached to. diff --git a/versioned_docs/version-3.1/concepts/clinical/specimen.mdx b/versioned_docs/version-3.1/concepts/clinical/specimen.mdx index e4d8d2c..f4568bf 100644 --- a/versioned_docs/version-3.1/concepts/clinical/specimen.mdx +++ b/versioned_docs/version-3.1/concepts/clinical/specimen.mdx @@ -49,12 +49,21 @@ Each specimen carries an **accession identifier** — the lab accession number o ## Permissions -Access to specimens is controlled by role-based permissions, scoped to the facility: +Access to specimens is controlled by role-based permissions, scoped to the facility. The tables below list the complete set of permissions that govern specimens and the specimen-definition templates they are based on. -| Permission | Roles | -| --- | --- | -| Can Read Specimen | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | -| Can Create Specimen on Facility | Facility Admin, Admin, Doctor, Nurse | +### Specimen + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Specimen | View specimen records within a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Pharmacist | +| Can Create Specimen on Facility | Register a new specimen within a facility | Facility Admin, Admin, Doctor, Nurse | + +### Specimen Definition + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Specimen Definition | View specimen-definition templates within a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Specimen Definition on Facility | Create a specimen-definition template within a facility | Facility Admin, Admin | In practice, viewing and creating a specimen are also gated by access to the linked service request, so a user must be able to reach the underlying order. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. diff --git a/versioned_docs/version-3.1/concepts/facility/device.mdx b/versioned_docs/version-3.1/concepts/facility/device.mdx index 560ba15..35c4d62 100644 --- a/versioned_docs/version-3.1/concepts/facility/device.mdx +++ b/versioned_docs/version-3.1/concepts/facility/device.mdx @@ -48,11 +48,11 @@ Care also keeps a **service history** — a log of maintenance and servicing eve Access to devices is governed by the device permissions, granted to users through their roles: -| Permission | Roles | -| --- | --- | -| Can List Devices on Facility | Staff, Administrator, Doctor, Nurse, Facility Admin, Pharmacist | -| Can Manage Devices on Facility | Staff, Administrator, Facility Admin, Pharmacist | -| Can Manage Device Associations to Encounters | Staff, Administrator, Doctor, Nurse, Facility Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can List Devices on Facility | View the devices registered on a facility | Staff, Admin, Doctor, Nurse, Facility Admin, Pharmacist | +| Can Manage Device Associations to Encounters | Attach devices to or detach them from encounters | Staff, Admin, Doctor, Nurse, Facility Admin | +| Can Manage Devices on Facility | Create, update, and manage devices on a facility | Staff, Admin, Facility Admin, Pharmacist | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. A device is visible to users whose memberships overlap its managing organization (or the organization of the location it currently sits in), so listing and management follow the facility's organization hierarchy rather than being open to everyone in the facility. diff --git a/versioned_docs/version-3.1/concepts/facility/facility.mdx b/versioned_docs/version-3.1/concepts/facility/facility.mdx index e1b4e20..e9a2003 100644 --- a/versioned_docs/version-3.1/concepts/facility/facility.mdx +++ b/versioned_docs/version-3.1/concepts/facility/facility.mdx @@ -40,13 +40,13 @@ Each facility can carry its own monetary configuration: facility-defined discoun ## Permissions -Access to facilities is governed by the `FacilityPermissions` enum. The key permissions and the roles that hold them: +Access to facilities is governed by the `FacilityPermissions` enum. The complete set of permissions, what each allows, and the system roles that hold them by default: -| Permission | Roles | -| --- | --- | -| Can Create on Facility | Administrator, Admin, Facility Admin | -| Can Read on Facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | -| Can Update on Facility | Facility Admin, Administrator, Admin, Staff | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Facility | Register a new facility in the deployment | Administrator, Admin, Facility Admin | +| Can Read on Facility | View a facility's details and configuration | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer | +| Can Update on Facility | Edit a facility's details and configuration | Facility Admin, Administrator, Admin, Staff | Roles are granted to users through organization memberships — a user holds a role within a facility's root organization, a facility sub-organization (team or department), or the geographic organization tree. Access is then scoped by that tree: a permission held at a parent organization cascades to its descendants, so a role granted high in the geographic hierarchy can authorize action on the facilities beneath it, while a role on a facility's own root org governs that site directly. diff --git a/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx b/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx index 917b977..71c2315 100644 --- a/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx +++ b/versioned_docs/version-3.1/concepts/facility/healthcare-service.mdx @@ -45,10 +45,10 @@ Because of these links, a healthcare service is what scheduling, ordering, and s Access to healthcare services is governed by the `HealthcareService` permissions: -| Permission | Roles | -| --- | --- | -| Can Read Healthcare Service | Facility Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Healthcare Service on Facility | Facility Admin, Administrator | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Healthcare Service on Facility | Create a healthcare service under a facility | Facility Admin, Admin | +| Can Read Healthcare Service | View a facility's healthcare services | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | Reading the catalogue of services is broadly available to clinical and support staff, while creating or changing services is restricted to facility administrators. Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. Creating a service additionally requires the permission at the facility root. diff --git a/versioned_docs/version-3.1/concepts/facility/location.mdx b/versioned_docs/version-3.1/concepts/facility/location.mdx index 119301f..b8a5bd7 100644 --- a/versioned_docs/version-3.1/concepts/facility/location.mdx +++ b/versioned_docs/version-3.1/concepts/facility/location.mdx @@ -52,12 +52,12 @@ Separately, an **operational status** describes the live state of a bed or room Access to locations is governed by the facility-location permissions: -| Permission | Roles | -| --- | --- | -| Can List Facility Locations | Administrator, Doctor, Nurse, Staff, Pharmacist, Facility Admin, Admin | -| Can Create/Update Facility Locations | Facility Admin, Staff, Admin | -| Can List Facility Location Organizations | Facility Admin, Staff, Admin | -| Can Create/Update Facility Location Organizations | Facility Admin, Staff, Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can List Facility Locations | View the locations and location tree within a facility | Admin, Doctor, Facility Admin, Administrator, Nurse, Staff, Pharmacist | +| Can Create/Update Facility Locations | Add new locations or edit existing ones in a facility | Facility Admin, Admin, Staff | +| Can List Facility Location Organizations | View the organizations granted access to a location | Facility Admin, Admin, Staff | +| Can Create/Update Facility Location Organizations | Grant or update organization access to a location | Facility Admin, Admin, Staff | Roles are granted to users through facility-organization membership, and access is scoped by the organization tree: a permission held on an organization applies to the locations that organization can reach, and grants at a parent location cascade to its children. Because that cascade is computed asynchronously, newly granted access settles a moment after the change is made. diff --git a/versioned_docs/version-3.1/concepts/facility/organization.mdx b/versioned_docs/version-3.1/concepts/facility/organization.mdx index 60f2c85..2243482 100644 --- a/versioned_docs/version-3.1/concepts/facility/organization.mdx +++ b/versioned_docs/version-3.1/concepts/facility/organization.mdx @@ -56,28 +56,32 @@ Membership is also deliberate: belonging to an organization does not automatical ## Permissions -Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. - -Key instance-wide organization permissions: - -| Permission | Roles | -| --- | --- | -| Can View Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager / Member | -| Can Create Organizations | Admin | -| Can Delete Organizations | Admin | -| Can Manage Organizations | Admin, role-org Admin | -| Can Manage Users in an Organization | Admin, Administrator, Facility Admin, role-org Admin | -| Can List Users in an Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer, Pharmacist, plus role-org Admin / Manager | - -Key facility-organization permissions: - -| Permission | Roles | -| --- | --- | -| Can View Facility Organizations | Facility Admin, Admin, Administrator, Staff, Doctor, Nurse, Volunteer | -| Can Create Facility Organizations | Facility Admin | -| Can Delete Facility Organizations | Facility Admin | -| Can Manage Facility Organizations | Facility Admin, Administrator | -| Can Manage Users in a Facility Organization | Facility Admin, Administrator | +Access to organizations is governed by two permission sets — `OrganizationPermissions` for the instance-wide tree and `FacilityOrganizationPermissions` for facility-scoped organizations. The tables below list the complete set of permissions in each, with the system roles that hold them by default. + +### Organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can View Organizations | View organizations and their details in the tree | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Create Organizations | Create new organizations in the instance-wide tree | Admin | +| Can Delete Organizations | Remove organizations from the tree | Admin | +| Can Manage Organizations | This includes changing names, descriptions, metadata, etc. | Admin, Admin (role org) | +| Can Manage Users in an Organization | Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) | +| Can Manage Connected Role Organizations | Add, remove, and assign roles to users in connected role organizations | Admin (role org), Manager (role org) | +| Can List Users in an Organizations | List the users who belong to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) | +| Is Geo Admin | Geo Admins can manage facilities in their organization | None by default | + +### Facility organization permissions + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create Facility Organizations | Create departments and teams within a facility | Facility Admin | +| Can Create Facility Organizations Root | Create the root facility organization for a facility | Facility Admin | +| Can View Facility Organizations | View a facility's internal organizations and their details | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer | +| Can Delete Facility Organizations | Remove organizations from a facility's internal tree | Facility Admin | +| Can Manage Facility Organizations | This includes changing names, descriptions, metadata, etc. | Facility Admin, Administrator | +| Can List Users in a Facility Organizations | List the users who belong to a facility organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse | +| Can Manage Users in a Facility Organization | Add, remove, and assign roles to users in a facility organization | Facility Admin, Administrator | Roles are granted to users through organization and facility-organization memberships. Access is then scoped by the tree: a permission held at a parent organization cascades to all of its descendants, so checks walk the chain of ancestors above a given organization. Geo admins are a special case — they can manage and view facility organizations within the geography they administer, regardless of facility membership. When assigning a role to another user, an admin can only grant a role whose permissions are a subset of their own. diff --git a/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx b/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx index 23faf64..3009ad4 100644 --- a/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx +++ b/versioned_docs/version-3.1/concepts/forms/questionnaire.mdx @@ -45,17 +45,24 @@ Questions are typed, which is what makes the captured data structured. Common ty ## Permissions -Access to questionnaires is governed by a dedicated permission set; response templates have their own. The key permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Read Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin, Organization Admin/Manager/Member | -| Can Submit Questionnaires | Administrator, Doctor, Nurse, Staff, Volunteer, Facility Admin, Organization Admin/Manager/Member | -| Can Create/Update Questionnaires | Administrator, Facility Admin | -| Can Archive Questionnaires | Administrator, Facility Admin | -| Can Manage Questionnaires | Administrator, Facility Admin, Organization Admin | -| Can Read Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | -| Can Create/Update Questionnaire Response Templates | Administrator, Doctor, Nurse, Staff, Volunteer, Pharmacist, Facility Admin | +Access to questionnaires is governed by a dedicated permission set; response templates have their own. The complete set of permissions and the system roles that hold them by default: + +### Questionnaire + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Questionnaires | View questionnaire definitions and their questions | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | +| Can Submit Questionnaires | Fill out and submit responses to a questionnaire | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Admin (role org), Manager (role org), Member (role org) | +| Can Create/Update Questionnaires | Author new questionnaires and edit existing ones | Admin, Facility Admin | +| Can Archive Questionnaires | Retire a questionnaire so it stops accepting submissions | Admin, Facility Admin | +| Can Manage Questionnaires | Add or remove organizations from questionnaires to control access | Admin, Facility Admin, Admin (role org) | + +### Questionnaire Response Template + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Questionnaire Response Templates | View saved response templates and order sets | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | +| Can Create/Update Questionnaire Response Templates | Create and edit reusable response templates | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist | Roles are granted to users through organization, facility-organization, and patient memberships. A questionnaire is attached to organizations, and access is decided by checking the user's roles against those organizations. Because permissions cascade down the organization tree, a role held at a parent organization also applies to the questionnaires scoped to its descendants. diff --git a/versioned_docs/version-3.1/concepts/forms/valueset.mdx b/versioned_docs/version-3.1/concepts/forms/valueset.mdx index dc3368f..67f77ec 100644 --- a/versioned_docs/version-3.1/concepts/forms/valueset.mdx +++ b/versioned_docs/version-3.1/concepts/forms/valueset.mdx @@ -48,12 +48,7 @@ This split lets the platform ship sensible defaults while still letting each sit ## Permissions -Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. Any authenticated user can read and search them — that is what powers the code pickers throughout the product. Authoring is gated to administrators. - -| Permission | Roles | -| --- | --- | -| Read / search value sets | Any authenticated user (shared reference data) | -| Create / update value sets | Administrator, Facility Admin | +Value sets are **shared terminology**, so they do not have a dedicated permission context the way patients or encounters do. There is no value-set permission enum to enumerate: any authenticated user can read and search value sets — that is what powers the code pickers throughout the product — while authoring (creating or changing value sets) is gated to administrators, and system-defined value sets are read-only for everyone. Roles are granted to users through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a role held at a parent organization cascades to its descendants. Because value sets are global reference data rather than patient- or encounter-scoped, read access is universal; the administrative roles above are what control who may author or change them, and system-defined value sets are read-only for everyone. diff --git a/versioned_docs/version-3.1/concepts/medications/medication.mdx b/versioned_docs/version-3.1/concepts/medications/medication.mdx index 0d6335d..33e985e 100644 --- a/versioned_docs/version-3.1/concepts/medications/medication.mdx +++ b/versioned_docs/version-3.1/concepts/medications/medication.mdx @@ -56,18 +56,18 @@ Medication access splits along two access models. **Dispense** has dedicated, location-centric permissions — pharmacists work in the pharmacy and often have no encounter access, so dispensing keys off the dispensing location instead: -| Permission | Roles | -| --- | --- | -| Pharmacist in Care | Facility Admin, Administrator, Pharmacist | -| Medication Dispense Read | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | -| Write Medication Dispense | Facility Admin, Administrator, Staff, Doctor, Nurse, Pharmacist | +| Permission | Description | System Roles | +| --- | --- | --- | +| Pharmacist in Care | Grants full access to medication requests and lets the holder create dispenses for patients | Facility Admin, Admin, Pharmacist | +| Medication Dispense Read | Allows reading medication dispense records | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| Write Medication Dispense | Allows creating and updating medication dispense records | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | **Requests, administrations, and statements** are clinical data on the encounter, so they are governed by the encounter clinical-data permissions: -| Permission | Roles | -| --- | --- | -| Can Read encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | -| Update Encounter related clinical data | Administrator, Doctor, Nurse, Facility Admin | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read encounter related clinical data | Allows reading clinical data recorded on an encounter | Admin, Doctor, Nurse, Facility Admin | +| Update Encounter related clinical data | Allows creating and updating clinical data on an encounter | Admin, Doctor, Nurse, Facility Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants — and dispense access is checked against the location's facility-organization rather than the encounter. diff --git a/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx b/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx index da46e83..3c41150 100644 --- a/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx +++ b/versioned_docs/version-3.1/concepts/scheduling/scheduling.mdx @@ -48,15 +48,15 @@ Other terminal or branch states include `noshow` (patient did not arrive), `wait ## Permissions -Access to schedules and bookings is governed by the schedule permission set. The key permissions and the roles that hold them: - -| Permission | Roles | -| --- | --- | -| Can Create on Schedule | Admin, Staff, Facility Admin, Doctor, Nurse | -| Can list schedule on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | -| Can list bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | -| Can update bookings on Object | Admin, Staff, Facility Admin, Doctor, Nurse | -| Can reschedule bookings on Object | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | +Access to schedules and bookings is governed by the schedule permission set. This is the complete set of schedule permissions and the system roles that hold them by default: + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Schedule | Create and edit schedules and availability for a resource | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can list schedule on Object | View the schedules and availability of a resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list bookings on Object | View the bookings (appointments) made against a resource | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can update bookings on Object | Create and update bookings, including status changes | Admin, Staff, Facility Admin, Doctor, Nurse | +| Can reschedule bookings on Object | Reschedule or cancel a booking to a different slot | Doctor, Staff, Nurse, Administrator, Facility Admin, Admin | Roles are granted to users through facility-organization memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants. For practitioner schedules, access is decided against the organizations the practitioner belongs to within the facility; for locations and healthcare services, against that resource's managing organization. diff --git a/versioned_docs/version-3.1/concepts/scheduling/token.mdx b/versioned_docs/version-3.1/concepts/scheduling/token.mdx index b3e8731..1d33d6a 100644 --- a/versioned_docs/version-3.1/concepts/scheduling/token.mdx +++ b/versioned_docs/version-3.1/concepts/scheduling/token.mdx @@ -50,12 +50,12 @@ Queue progression — which token is current and who is next — is maintained b Token access is governed by facility-scoped permissions. Whether a user can see or manage a queue is decided by their membership in the facility organization that owns the resource the queue is bound to. -| Permission | Roles | -| --- | --- | -| Can Create on Token | Administrator, Staff, Facility Admin, Doctor, Nurse | -| Can list token on Object | Administrator, Staff, Facility Admin, Doctor, Nurse | -| Can Create on Token Category | Administrator, Staff, Facility Admin | -| Can list token category on Facility | Administrator, Staff, Facility Admin, Doctor, Nurse | +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Create on Token | Issue and update tokens in a facility queue | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can list token on Object | View the tokens issued for a queue | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | +| Can Create on Token Category | Create and manage token categories for a facility | Admin, Staff, Facility Admin | +| Can list token category on Facility | View the token categories defined for a facility | Admin, Staff, Facility Admin, Doctor, Nurse, Administrator | Roles are granted to users through facility-organization memberships. Access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, so a user's reach over a queue follows the organization that manages the queue's practitioner, location, or healthcare service. diff --git a/versioned_docs/version-3.1/concepts/supply/supply.mdx b/versioned_docs/version-3.1/concepts/supply/supply.mdx index dc615da..d5c939a 100644 --- a/versioned_docs/version-3.1/concepts/supply/supply.mdx +++ b/versioned_docs/version-3.1/concepts/supply/supply.mdx @@ -59,20 +59,42 @@ Supply ties together several other parts of Care: ## Permissions -Access to supply resources is governed by facility-scoped permissions. The main ones, with the roles that hold them by default: - -| Permission | Roles | -| --- | --- | -| Can Read Product | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Product on Facility | Facility Admin, Admin | -| Can Read Product Knowledge | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Product Knowledge on Facility | Facility Admin, Admin | -| Can Read Inventory Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Read Supply Request | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Supply Request on Facility | Facility Admin, Admin, Staff, Doctor, Nurse | -| Can Read Supply Delivery | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | -| Can Create Supply Delivery on Facility | Facility Admin, Admin | -| Can Create External Supply Delivery on Facility | Facility Admin, Admin | +Access to supply resources is governed by facility-scoped permissions. The complete set, grouped by resource, with the system roles that hold each by default: + +### Product + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Product | View batch-level product instances stocked at a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product on Facility | Add a new batch-level product instance to a facility | Facility Admin, Admin | + +### Product knowledge + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Product Knowledge | View catalogue definitions of stockable items | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Product Knowledge on Facility | Define a new catalogue item for a facility | Facility Admin, Admin | + +### Inventory item + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Inventory Item | View on-hand stock quantities at facility locations | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | + +### Supply request + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Supply Request | View requests to move stock into a location | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Request on Facility | Raise a request to move stock into a location | Facility Admin, Admin, Staff, Doctor, Nurse | + +### Supply delivery + +| Permission | Description | System Roles | +| --- | --- | --- | +| Can Read Supply Delivery | View records of stock moving in, between, or out | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| Can Create Supply Delivery on Facility | Record a delivery moving stock at a facility | Facility Admin, Admin | +| Can Create External Supply Delivery on Facility | Record a delivery of goods arriving from a supplier | Facility Admin, Admin | Roles are granted to users through organization, facility-organization, and patient memberships. Access to a location's inventory, requests, and deliveries is checked against the facility organizations that own that location, and a permission held at a parent organization cascades to its descendants in the organization tree. In practice, clinical and pharmacy staff can read stock and raise supply requests, while creating catalogue items and recording deliveries is reserved for facility administrators.