Add Medication Request flow docs for 3.1

versioned_docs/version-3.1/concepts/medications/medication-request.mdx

@@ -4,81 +4,118 @@ sidebar_position: 1
 
 # Medication Request
 
-A **medication request** is a prescriber's instruction to supply and/or administer a medication to a patient. It is the starting point of the medication journey in Care — the order that everything downstream (dispensing, administration, the patient's medication history) refers back to.
-
-## What it represents
-
-In Care's FHIR-aligned model, a medication request maps to the **MedicationRequest** resource. It captures:
-
-- **What to give** — a coded drug from a managed list, or a specific product from your facility's catalogue
-- **How to give it** — structured dosage instructions: dose, route, body site, timing and frequency, and whether the medication is taken only as needed (PRN)
-- **Why and how urgently** — the intent (a proposal, a plan, or a firm order), the care setting (inpatient, outpatient, community, or discharge), and the priority (routine through stat)
-- **Who and where** — the patient, the encounter it was written during, the prescriber, and when it was authored
-
-A medication request records the *intent* to medicate — it is not proof that the drug was handed over or taken. Handing the drug out is a [medication dispense](../medications/medication-dispense.mdx), giving it to the patient is a [medication administration](../medications/medication-administration.mdx), and what the patient reports actually taking is a [medication statement](../medications/medication-statement.mdx). The request is the order; the others are the follow-through.
-
-## How it connects
-
-A medication request never stands alone. It is always tied to a clinical context:
-
-- **Patient** — every request belongs to one patient. The patient is taken from the encounter, never supplied directly, so a request can never point at someone who wasn't actually seen.
-- **Encounter** — the visit or admission the order was written during. This anchors the order in time and place and decides who is allowed to touch it.
-- **Prescription** — requests authored together in one sitting are grouped under a single **prescription** for the encounter. Think of the prescription as the sheet of paper and each medication request as one line on it.
-- **Requester** — the clinician who authored the order.
-
-Grouping by prescription is what lets a pharmacist review or act on a whole prescribing event at once, rather than one drug at a time.
-
-## Lifecycle
-
-A medication request moves through a status that reflects where the order stands:
-
-```text
-draft → active → (on_hold) → completed / stopped / ended / cancelled
-```
-
-- **draft** — written but not yet finalised or acted on
-- **active** — the live order; this is the default for a real prescription
-- **on_hold** — temporarily suspended (for example, paused before surgery), expected to resume
-- **completed** — the course has run as intended
-- **stopped** — deliberately discontinued before completion (for example, an adverse reaction)
-- **ended** — the order's validity period has lapsed
-- **cancelled** — withdrawn before it took effect
-- **entered_in_error** — recorded by mistake and retracted; kept for audit, not treatment
-- **unknown** — status cannot be determined
-
-When a request is stopped or changed, a **status reason** can record *why* — for example an allergy, a suspected drug interaction, a duplicate therapy, or the patient being scheduled for surgery. Once a request is created, only a narrow set of things can change: its status, its note, and its dispensing progress. The clinical substance of the order — the drug and the dosage — is fixed at authoring.
-
-## Classification
-
-Two coded fields shape how a request is read and routed:
-
-- **Intent** — how firm the order is, from a loose `proposal`, to a `plan`, to a true `order`. This separates "we're thinking about this drug" from "give this drug."
-- **Category** — the care setting the order applies to: `inpatient`, `outpatient`, `community`, or `discharge`. Discharge medications, for instance, are what the patient goes home with.
-
-A request can also be marked **do not perform** — an explicit instruction that a medication must *not* be given, which is a clinical statement in its own right, not merely the absence of an order.
+## Definition
+
+A **[medication request](https://build.fhir.org/medicationrequest.html)** in Care is an order
+or prescription for a specific medicine for a patient. You create a medication request during
+an encounter. Care groups one or more medication requests together under a named prescription.
+A medication request records what you order, not what the patient receives.
+
+Care keeps the medication request separate from three related records. Medicine Administration
+records a dose that staff give to the patient. Dispense History records the pharmacy dispense.
+Medication Statements record the medicines that the patient reports or took in the past. Care
+shows each of these records in its own sub-tab of the **Medicines** tab.
+
+## Key Attributes
+
+| Components | What it captures |
+| --- | --- |
+| Medicine | The drug that you prescribe. You select it from a clinical drug list or from the facility's inventory. |
+| Dosage | The amount of the medicine that the patient takes. This field is mandatory. |
+| Frequency | How often the patient takes the medicine. This field is mandatory. |
+| Duration | How long the patient takes the medicine. This field is optional. |
+| Instructions | More instructions for the patient. This includes the reason to take the medicine when needed. This field is optional. |
+| Route | How the patient receives the medicine, for example by mouth or by injection. This field is optional. |
+| Site | The body site that the medicine applies to. This field is optional. |
+| Method | The method of administration. This field is optional. |
+| Authored On | The date that you write the request. Care sets the current date and time by default. You cannot enter a future date. |
+| Requester | The user that Care records as the person who requests the medicine. This field is optional. |
+| Note | Free text notes about the medicine. This field is optional. |
+| Status | The current state of the request. |
+| Category | The care setting that the request applies to. |
+| Priority | The urgency of the request. |
+| Dispense Status | How much of the request the pharmacy dispensed. The separate dispense process updates this field. |
+
+### Prescription
+
+A prescription is a named batch that groups one or more medication requests for the same
+encounter. When you prescribe a medicine, you add it to a new prescription or to an existing
+one. A new prescription needs a name. You can also add an optional note to it. An encounter can
+have more than one prescription. Care lets you switch between the prescriptions of an encounter.
+
+### Changes after you save
+
+After you save a medicine on a prescription, you cannot change its dosage, frequency, route, or
+other clinical details. You can edit its note. You can add new medicines to the same
+prescription. You can also remove the medicine. When you remove a medicine, Care marks it as
+Entered in Error and keeps the record.
+
+### Category
+
+| Category | Description |
+| --- | --- |
+| Inpatient | The request applies to a patient who stays in the facility. |
+| Outpatient | The request applies to a patient who visits the facility. |
+| Community | The request applies to care in the community. |
+| Discharge | The request applies to the medicines that the patient takes after discharge. |
+
+### Priority
+
+| Priority | Description |
+| --- | --- |
+| Routine | The patient takes the medicine in the normal order of work. |
+| Urgent | Staff act on the request before routine requests. |
+| ASAP | Staff act on the request as soon as possible. |
+| Stat | Staff act on the request immediately. |
+
+### Dispense Status
+
+| Dispense Status | Description |
+| --- | --- |
+| Complete | The pharmacy dispensed the full amount of the request. |
+| Partial | The pharmacy dispensed part of the request. |
+| Incomplete | The pharmacy did not finish the dispense of the request. |
+| Declined | The pharmacy declined to dispense the request. |
+
+## Status
+
+| Status | Description |
+| --- | --- |
+| Active | The patient takes the medicine now. |
+| On Hold | The patient stops the medicine for a limited time. |
+| Ended | The request reached its end. |
+| Stopped | Staff stopped the medicine before its planned end. |
+| Completed | The patient took the full course of the medicine. |
+| Cancelled | Staff cancelled the request before the patient took the medicine. |
+| Entered in Error | Staff created the request by mistake. |
+| Draft | The request is not complete and staff did not issue it. |
+| Unknown | The state of the request is not known. |
 
 ## Permissions
 
-Access to a medication request follows the encounter it belongs to, with one addition: pharmacists get a facility-wide grant so they can fill orders across the floor. Authoring an order requires write access on the encounter; reading one requires clinical-data access for the patient, or read access on the specific encounter.
+| Permission | What it allows |
+| --- | --- |
+| Update Encounter related clinical data | Prescribe a medication, add medicines to an existing prescription, edit a note, and remove a medicine. |
+| Can view clinical data about patients | View the medication requests and the prescriptions of a patient. |
+| Can Read encounter related clinical data | View the medication requests and the prescriptions of an encounter. |
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_encounter_clinical_data` | Author, update, or discontinue a medication request on an encounter | Admin, Doctor, Nurse, Facility Admin |
-| `is_pharmacist` | Pharmacist-wide access to read every medication request in a facility (and create dispenses) | Facility Admin, Admin, Pharmacist |
-| `can_view_clinical_data` | Read the medication requests recorded for a patient | Staff, Doctor, Nurse, Admin, Facility Admin |
-| `can_read_encounter_clinical_data` | Read the medication requests on a specific encounter (when scoped by encounter) | Admin, Doctor, Nurse, Facility Admin |
+To change medicines, you also need an open encounter. Care blocks changes when the encounter
+status is Completed, Cancelled, Discontinued, or Entered in Error.
 
-Roles are granted to a user through their membership in an organization, facility, or patient's care team; permissions cascade down the organization tree, so access granted higher up flows to the facilities and encounters beneath it.
+Care has a separate Pharmacist role. This role has its own permissions for pharmacy work on
+dispense records and prescription status.
 
-## Related
+## Configuration
 
-- Reference: [Medication Request (technical)](../../references/medications/medication-request.mdx)
-- Concept: [Medication Dispense](../medications/medication-dispense.mdx)
-- Concept: [Medication Administration](../medications/medication-administration.mdx)
-- Concept: [Medication Statement](../medications/medication-statement.mdx)
-- Concept: [Encounter](../clinical/encounter.mdx)
-- Concept: [Patient](../clinical/patient)
+No deployment configuration changes which fields are mandatory. One configuration option sets
+the default tab of the medicine picker. This option selects either the clinical drug list or the
+facility's inventory.
 
-## FHIR reference
+## Related
 
-This concept aligns with the HL7 FHIR [MedicationRequest](https://hl7.org/fhir/medicationrequest.html) resource, which represents an order or instruction for a medication for a patient. Care uses underscored status and intent values (for example `on_hold`, `original_order`) rather than the hyphenated FHIR spellings.
+- Flow: [Prescribe a medication](../../flows/medications/medication-request/prescribe-medication.mdx)
+- Flow: [Manage a prescription](../../flows/medications/medication-request/manage-prescription.mdx)
+- Flow: [Add medications from past records](../../flows/medications/medication-request/add-medications-from-past-records.mdx)
+- Flow: [View prescriptions and medications for an encounter](../../flows/medications/medication-request/view-encounter-medications.mdx)
+- Flow: [Update a prescription](../../flows/medications/medication-request/update-prescription.mdx)
+- Flow: [Print a prescription](../../flows/medications/medication-request/print-prescription.mdx)

versioned_docs/version-3.1/flows/medications/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Medications",
+  "position": 3,
+  "key": "medications-flows"
+}

versioned_docs/version-3.1/flows/medications/medication-request/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Medication Request",
+  "position": 1,
+  "key": "medications-medication-request-flows"
+}

versioned_docs/version-3.1/flows/medications/medication-request/add-medications-from-past-records.mdx

@@ -0,0 +1,56 @@
+---
+sidebar_position: 3
+---
+
+# Add medications from past records
+
+## Overview
+
+This flow describes how to add medicines from a patient's past records into a new prescription in Care. You start from the same screen that you use to prescribe a [medication request](../../../concepts/medications/medication-request.mdx).
+
+## Pre-requisites
+
+- The patient is registered in Care, and you record the encounter for that patient.
+- The encounter is open. You cannot add medicines when the encounter status is Completed, Cancelled, Discontinued, or Entered in Error.
+- You prescribe a medicine for the encounter. See [Prescribe a medication](./prescribe-medication.mdx).
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter related clinical data | Lets you add and change medicines for the encounter. |
+
+## Steps
+
+### 1. Open the medication history
+
+Select the **Medication History** action on the prescription screen. Care opens a picker.
+
+### 2. Review the past records
+
+The picker shows the patient's earlier medication requests. The picker also shows the patient's medication statements, which record the medicines that the patient reports or used before.
+
+### 3. Select the medicines to add
+
+Select each past record that you want to add. Care adds each selected record to the current prescription as a new medicine row.
+
+### 4. Review and save
+
+Review each new medicine row. Change the details when you need to. Save the prescription.
+
+## Expected Outcome
+
+- Care adds the selected past medicines to the current prescription as new medicine rows.
+- You see the added medicines with the other medicines for the encounter. See [View prescriptions and medications for an encounter](./view-encounter-medications.mdx).
+
+## Related
+
+Concepts:
+
+- [Medication Request](../../../concepts/medications/medication-request.mdx)
+
+Flows:
+
+- [Prescribe a medication](./prescribe-medication.mdx)
+- [View prescriptions and medications for an encounter](./view-encounter-medications.mdx)

versioned_docs/version-3.1/flows/medications/medication-request/manage-prescription.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 2
+---
+
+# Manage a prescription
+
+## Overview
+
+A prescription is a named batch that groups one or more [medication requests](../../../concepts/medications/medication-request.mdx) for the same encounter. This flow describes how to create a prescription and how to see the prescriptions of an encounter.
+
+## Pre-requisites
+
+- The patient is registered in Care, and you record the encounter for that patient.
+- You are a member of the facility that manages the encounter.
+- If you create a prescription, you prescribe a medicine in the same encounter. See [Prescribe a medication](./prescribe-medication.mdx).
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter related clinical data | Lets you create a prescription when you prescribe a medicine. |
+| Can view clinical data about patients | Lets you see the prescriptions of the encounter. |
+| Can Read encounter related clinical data | Lets you see the prescriptions of the encounter. |
+
+## Steps
+
+### 1. Create a prescription
+
+Create a prescription when you prescribe a medicine.
+
+1. Prescribe a medicine for the encounter.
+2. Choose to add the medicine to a new prescription.
+3. Enter a name for the prescription.
+4. Enter a note for the prescription. The note is optional.
+5. Save the medicine.
+
+Note: An encounter can have more than one prescription. To add a medicine to a prescription that exists, choose that prescription instead of a new one.
+
+### 2. Open the prescriptions of the encounter
+
+1. Open the encounter.
+2. Select the **Medicines** tab.
+3. Select the **Prescriptions** sub-tab.
+
+Care shows a list of the prescriptions of the encounter. The list shows each prescription by name.
+
+### 3. Select a prescription
+
+- Select a prescription in the list. Care shows only the medicines that belong to that prescription.
+- Select **All Prescriptions**. Care shows every medicine of every prescription of the encounter.
+
+## Expected Outcome
+
+- Care groups the medicine in the prescription that you choose.
+- The list shows each prescription of the encounter by name.
+- You see the medicines of one prescription, or the medicines of all prescriptions.
+
+## Related
+
+Concepts:
+
+- [Medication Request](../../../concepts/medications/medication-request.mdx)
+
+Flows:
+
+- [Prescribe a medication](./prescribe-medication.mdx)
+- [View prescriptions and medications for an encounter](./view-encounter-medications.mdx)
+- [Update a prescription](./update-prescription.mdx)