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

2026-07-06T04:14:27Z

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

← Older revision		Revision as of 09:44, 6 July 2026
Line 504:		Line 504:
	* Updates reach only <code>status</code>, <code>note</code>, and <code>dispense_status</code>.		* Updates reach only <code>status</code>, <code>note</code>, and <code>dispense_status</code>.
	* <code>requester</code>, <code>requested_product</code>, and <code>prescription</code> use <code>SET_NULL</code>, so a request outlives the user, product, or prescription it referenced.		* <code>requester</code>, <code>requested_product</code>, and <code>prescription</code> use <code>SET_NULL</code>, so a request outlives the user, product, or prescription it referenced.

			{{Navbox medications}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:23Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=medications
|title=Medication Request
|order=1
|introduced=3.0
|model=MedicationRequest
|reference=References/Base models & conventions
}}

A <code>MedicationRequest</code> records a prescriber's intent to supply or administer a medication to a patient — the FHIR [<nowiki/>https://hl7.org/fhir/medicationrequest.html <code>MedicationRequest</code>] resource. You create one whenever a drug is ordered during an encounter; it carries the medication, dosage instructions, timing, and route as structured JSON, grouped under a prescription.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/medication_request.py <code>care/emr/models/medication_request.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/request/spec.py <code>resources/medication/request/spec.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/request_prescription/spec.py <code>resources/medication/request_prescription/spec.py</code>]
* Value sets: [<nowiki/>https://github.com/ohcnetwork/care/tree/develop/care/emr/resources/medication/valueset <code>resources/medication/valueset/</code>]

Several fields are opaque <code>JSONField</code>s whose structure the Django model never declares. The contract lives in the Pydantic resource specs under <code>care/emr/resources/medication/request/</code>: the enums, the nested shape of those JSON fields, validation rules, the read/write schema split, and the server-side side effects. The tables below merge both layers.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>MedicationRequestPrescription</code>
| Groups medication requests authored together for an encounter (a prescription)
|-
| <code>MedicationRequest</code>
| A single medication order/request for a patient within an encounter
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>MedicationRequest</code> fields ==

=== Order status & intent ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=MedicationRequest|section=Order status & intent|name=status|type=CharField(100) → MedicationRequestStatus|notes=Yes (spec)}}
{{Field|model=MedicationRequest|section=Order status & intent|name=status_reason|type=CharField(100) → StatusReason | None|notes=No}}
{{Field|model=MedicationRequest|section=Order status & intent|name=intent|type=CharField(100) → MedicationRequestIntent|notes=Yes (spec)}}
{{Field|model=MedicationRequest|section=Order status & intent|name=category|type=CharField(100) → MedicationRequestCategory|notes=Yes (spec)}}
{{Field|model=MedicationRequest|section=Order status & intent|name=priority|type=CharField(100) → MedicationRequestPriority|notes=Yes (spec)}}
{{Field|model=MedicationRequest|section=Order status & intent|name=do_not_perform|type=BooleanField → bool|notes=Yes}}
{{Field|model=MedicationRequest|section=Order status & intent|name=dispense_status|type=CharField(100) → MedicationRequestDispenseStatus | None|notes=No}}
|}

=== Medication & dosage ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=MedicationRequest|section=Medication & dosage|name=medication|type=JSONField → ValueSetBoundCoding[system-medication] | None|notes=Conditional}}
{{Field|model=MedicationRequest|section=Medication & dosage|name=method|type=JSONField|notes=n/a}}
{{Field|model=MedicationRequest|section=Medication & dosage|name=dosage_instruction|type=JSONField → list[DosageInstruction]|notes=Yes}}
{{Field|model=MedicationRequest|section=Medication & dosage|name=note|type=TextField → str | None|notes=No}}
|}

=== Subject & provenance ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=MedicationRequest|section=Subject & provenance|name=patient|type=FK → Patient|notes=server-set}}
{{Field|model=MedicationRequest|section=Subject & provenance|name=encounter|type=FK → Encounter|notes=Yes (create)}}
{{Field|model=MedicationRequest|section=Subject & provenance|name=authored_on|type=DateTimeField → datetime|notes=Yes (spec)}}
{{Field|model=MedicationRequest|section=Subject & provenance|name=requester|type=FK → users.User|notes=No}}
{{Field|model=MedicationRequest|section=Subject & provenance|name=requested_product|type=FK → ProductKnowledge|notes=Conditional}}
{{Field|model=MedicationRequest|section=Subject & provenance|name=prescription|type=FK → MedicationRequestPrescription|notes=No}}
|}

== Enum values ==

Spec enums use '''underscored''' member values (<code>on_hold</code>, <code>entered_in_error</code>, <code>original_order</code>), not the hyphenated FHIR spellings. These are the exact strings the API accepts and returns.

=== <code>MedicationRequestStatus</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>active</code>
|-
| <code>on_hold</code>
|-
| <code>ended</code>
|-
| <code>stopped</code>
|-
| <code>completed</code>
|-
| <code>cancelled</code>
|-
| <code>entered_in_error</code>
|-
| <code>draft</code>
|-
| <code>unknown</code>
|}

=== <code>StatusReason</code> values ===

{| class="wikitable"
|-
! Value
! Meaning (FHIR)
|-
| <code>altchoice</code>
| Alternative choice
|-
| <code>clarif</code>
| Prescription requires clarification
|-
| <code>drughigh</code>
| Drug level too high
|-
| <code>hospadm</code>
| Admission to hospital
|-
| <code>labint</code>
| Lab interference issues
|-
| <code>non_avail</code>
| Patient not available
|-
| <code>preg</code>
| Patient is pregnant or breastfeeding
|-
| <code>salg</code>
| Allergy
|-
| <code>sddi</code>
| Drug interaction
|-
| <code>sdupther</code>
| Duplicate therapy
|-
| <code>sintol</code>
| Suspected intolerance
|-
| <code>surg</code>
| Patient scheduled for surgery
|-
| <code>washout</code>
| Washout
|}

=== <code>MedicationRequestIntent</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>proposal</code>
|-
| <code>plan</code>
|-
| <code>order</code>
|-
| <code>original_order</code>
|-
| <code>reflex_order</code>
|-
| <code>filler_order</code>
|-
| <code>instance_order</code>
|}

=== <code>MedicationRequestPriority</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>routine</code>
|-
| <code>urgent</code>
|-
| <code>asap</code>
|-
| <code>stat</code>
|}

=== <code>MedicationRequestCategory</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>inpatient</code>
|-
| <code>outpatient</code>
|-
| <code>community</code>
|-
| <code>discharge</code>
|}

=== <code>MedicationRequestDispenseStatus</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>complete</code>
|-
| <code>partial</code>
|-
| <code>incomplete</code>
|-
| <code>declined</code>
|}

=== <code>TimingUnit</code> values ===

UCUM time units used by <code>Timing.repeat.period_unit</code> and <code>bounds_duration.unit</code>.

{| class="wikitable"
|-
! Value
! Unit
|-
| <code>s</code>
| second
|-
| <code>min</code>
| minute
|-
| <code>h</code>
| hour
|-
| <code>d</code>
| day
|-
| <code>wk</code>
| week
|-
| <code>mo</code>
| month
|-
| <code>a</code>
| year
|}

=== <code>DoseType</code> values ===

Used by <code>DoseAndRate.type</code>.

{| class="wikitable"
|-
! Value
|-
| <code>ordered</code>
|-
| <code>calculated</code>
|}

== <code>DosageInstruction</code> nested spec ==

Each entry in the <code>dosage_instruction</code> JSON list deserializes to a <code>DosageInstruction</code> (Pydantic, snake_case keys) — the structure hiding behind the opaque <code>JSONField</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=sequence|type=int | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=text|type=str | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=additional_instruction|type=list[Coding] | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=patient_instruction|type=str | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=timing|type=Timing | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=as_needed_boolean|type=bool|notes='''Yes'''}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=as_needed_for|type=Coding | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=site|type=Coding | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=route|type=Coding | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=method|type=Coding | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=dose_and_rate|type=DoseAndRate | None|notes=No}}
{{Field|model=MedicationRequest|section=DosageInstruction nested spec|name=max_dose_per_period|type=DoseRange | None|notes=No}}
|}

=== Sub-types under <code>DosageInstruction</code> ===

<syntaxhighlight lang="text">Timing {
repeat: TimingRepeat # required
code: Coding | None # e.g. BID/TID/QID timing abbreviation
}

TimingRepeat {
frequency: int # required — repetitions per period
period: Decimal(20,0) # required — duration the frequency applies to
period_unit: TimingUnit # required — s|min|h|d|wk|mo|a
bounds_duration: TimingQuantity # required — total span
}

TimingQuantity { # integer-valued time amount
value: Decimal(20,0) # required
unit: TimingUnit # required
}

DoseAndRate {
type: DoseType # required — ordered | calculated
dose_range: DoseRange | None # for titrated doses
dose_quantity: DosageQuantity | None # for regular doses
}

DoseRange {
low: DosageQuantity # required
high: DosageQuantity # required
}

DosageQuantity { # measured dose amount
value: Decimal(20,6) # required
unit: Coding # required
}</syntaxhighlight>
The Pydantic specs define these JSON keys as snake_case (<code>as_needed_boolean</code>, <code>period_unit</code>, <code>dose_and_rate</code>, <code>max_dose_per_period</code>, <code>bounds_duration</code>), so that is how they sit in storage — not the camelCase FHIR wire format.

== Bound value sets ==

Coded fields bind to Care value sets through <code>ValueSetBoundCoding[<slug>]</code>. On write, the supplied <code>Coding.code</code> is validated against the value set; a code outside it is rejected. All draw from SNOMED CT (<code>http://snomed.info/sct</code>).

{| class="wikitable"
|-
! Field
! Value set slug
! SNOMED CT scope
|-
| <code>medication</code>
| <code>system-medication</code>
| <code><< 763158003</code> Medicinal product
|-
| <code>dosage_instruction[].route</code>
| <code>system-route</code>
| <code>is-a 284009009</code> Route of administration
|-
| <code>dosage_instruction[].site</code>
| <code>system-body-site</code>
| <code>is-a 91723000</code> Anatomical structure
|-
| <code>dosage_instruction[].method</code>
| <code>system-administration-method</code>
| <code>is-a 736665006</code>
|-
| <code>dosage_instruction[].as_needed_for</code>
| <code>system-as-needed-reason</code>
| <code>is-a 404684003</code> Clinical finding
|-
| <code>dosage_instruction[].additional_instruction</code>
| <code>system-additional-instruction</code>
| <code>is-a 419492006</code>
|}

<code>system-medication-not-given</code> lives in this directory too, but it binds on [[References/Medication Administration]], not on the request.

== Resource specs (API schema) ==

Every spec extends [[References/Base models & conventions|<code>EMRResource</code>]], which provides <code>serialize</code> / <code>de_serialize</code> plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>MedicationRequestResource</code> sets <code>__exclude__ = [patient, encounter, requester, requested_product, prescription]</code>, so those relations are wired up by hand instead of auto-mapped.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>MedicationRequestAbstractSpec</code>
| shared (fields)
| Plain <code>BaseModel</code> holding the clinical fields: <code>status</code>, <code>status_reason</code>, <code>intent</code>, <code>category</code>, <code>priority</code>, <code>do_not_perform</code>, <code>medication</code>, <code>dosage_instruction</code>, <code>authored_on</code>, <code>note</code>, <code>dispense_status</code>
|-
| <code>MedicationRequestResource</code>
| shared (binding)
| Binds the spec to the <code>MedicationRequest</code> model and declares <code>__exclude__</code>
|-
| <code>BaseMedicationRequestSpec</code>
| shared
| <code>MedicationRequestResource</code> + <code>MedicationRequestAbstractSpec</code> + <code>id: UUID4</code>
|-
| <code>MedicationRequestSpec</code>
| write · create
| Adds <code>encounter</code> (UUID, required), <code>requester</code>, <code>requested_product</code>, <code>prescription</code> (UUIDs), and <code>create_prescription</code>. Carries the validators and <code>perform_extra_deserialization</code>
|-
| <code>MedicationRequestUpdateSpec</code>
| write · update
| Narrow — only <code>status</code>, <code>note</code>, <code>dispense_status</code> are mutable after create
|-
| <code>MedicationRequestReadWithoutPrescriptionSpec</code>
| read · embedded
| Full read minus prescription; expands <code>requested_product</code> (<code>ProductKnowledgeReadSpec</code>), <code>requester</code>/<code>created_by</code>/<code>updated_by</code> (<code>UserSpec</code>), plus <code>created_date</code>/<code>modified_date</code>
|-
| <code>MedicationRequestReadSpec</code>
| read · detail/list
| Adds expanded <code>prescription</code> (<code>MedicationRequestPrescriptionReadSpec</code>) and the <code>encounter</code> external id
|-
| <code>CreatePrescription</code>
| write · nested
| <code>{ name?, note?, alternate_identifier (required) }</code> — inline prescription creation
|}

=== Validation (create — <code>MedicationRequestSpec</code>) ===

* '''Medication XOR product:''' you cannot set both <code>medication</code> and <code>requested_product</code>, and one is required.
* '''Prescription XOR create:''' you cannot set both <code>prescription</code> and <code>create_prescription</code>.
* '''Encounter existence:''' the <code>encounter</code> UUID must match an existing <code>Encounter</code> (field validator).
* <code>authored_on</code>, and any nested <code>PeriodSpec</code>/timing datetimes, must be timezone-aware.

=== Server-side side effects (<code>perform_extra_deserialization</code>) ===

* <code>encounter</code> is resolved from its UUID, then <code>patient</code> is copied from <code>encounter.patient</code> — the client never sets <code>patient</code> directly.
* <code>requester</code> / <code>requested_product</code> are resolved by <code>external_id</code>. If <code>requested_product.facility</code> is set and differs from <code>encounter.facility</code>, the write raises <code>"Product not found in facility"</code>.
* <code>prescription</code> is resolved by <code>external_id</code>, scoped to the same <code>encounter</code>.
* <code>create_prescription</code> looks up an existing prescription by <code>(alternate_identifier, encounter)</code>. A match that is '''not''' <code>active</code> raises <code>"Prescription is not active"</code>; no match creates a new <code>MedicationRequestPrescription</code> (<code>status=active</code>, copying <code>name</code>/<code>note</code>, <code>prescribed_by=requester</code>) and links the request to it.

=== Serialization (read) ===

<code>perform_extra_serialization</code> sets <code>id = external_id</code> and expands <code>requested_product</code>, <code>requester</code>, and the audit users (<code>created_by</code>/<code>updated_by</code>) from cache. <code>MedicationRequestReadSpec</code> goes further, expanding <code>prescription</code> and emitting <code>encounter</code> as its external id.

== Related models ==

=== <code>MedicationRequestPrescription</code> ===

The container that groups every medication request authored together for an encounter into one prescription. Each request points back via <code>MedicationRequest.prescription</code>.

<syntaxhighlight lang="text">encounter → FK Encounter (CASCADE)
patient → FK Patient (CASCADE)
name → CharField(100), nullable
note → TextField, nullable
prescribed_by → FK users.User (CASCADE, nullable)
status → CharField(100), nullable → MedicationRequestPrescriptionStatus
approval_status → CharField(100), nullable
alternate_identifier → CharField(100), nullable
tags → ArrayField[int], default []</syntaxhighlight>
A <code>UniqueConstraint</code> (<code>unique_alternate_identifier_encounter</code>) keeps <code>alternate_identifier</code> unique per <code>encounter</code>.

==== <code>MedicationRequestPrescriptionStatus</code> values ====

<code>active</code>, <code>on_hold</code>, <code>ended</code>, <code>stopped</code>, <code>completed</code>, <code>cancelled</code>, <code>entered_in_error</code>, <code>draft</code>.

A pharmacist may only move a prescription between <code>active</code>, <code>on_hold</code>, <code>completed</code> (<code>MEDICATION_PRESCRIPTION_PHARMACIST_ALLOWED_STATUS</code>).

==== Prescription specs ====

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseMedicationRequestPrescriptionSpec</code>
| shared
| <code>id</code>, <code>status</code> (<code>MedicationRequestPrescriptionStatus</code>), <code>note</code>, <code>name</code>
|-
| <code>MedicationRequestPrescriptionWriteSpec</code>
| write · create
| Adds <code>encounter</code> (UUID), <code>prescribed_by</code> (UUID); resolves <code>encounter</code>→<code>patient</code> and <code>prescribed_by</code> server-side
|-
| <code>MedicationRequestPrescriptionUpdateSpec</code>
| write · update
| Same shared fields, no new FKs
|-
| <code>MedicationRequestPrescriptionReadSpec</code>
| read · list
| Adds <code>created_date</code>, <code>modified_date</code>, expanded <code>prescribed_by</code> (<code>UserSpec</code>), <code>tags</code> (rendered via <code>SingleFacilityTagManager</code>)
|-
| <code>MedicationRequestPrescriptionRetrieveSpec</code>
| read · detail
| Adds audit <code>created_by</code>/<code>updated_by</code>
|-
| <code>MedicationRequestPrescriptionRetrieveMedicationsSpec</code>
| read · detail+children
| Adds <code>medications</code> (each via <code>MedicationRequestReadWithoutPrescriptionSpec</code>) and full <code>encounter</code> (<code>EncounterRetrieveSpec</code>)
|-
| <code>MedicationRequestPrescriptionRetrieveDetailedSpec</code>
| read · detail
| Adds <code>encounter</code> via <code>EncounterListSpec</code>
|}

== Methods & save behaviour ==

* Read and write run through the inherited <code>EMRResource.serialize</code> / <code>de_serialize</code>. <code>de_serialize</code> dumps with <code>exclude_defaults=True</code>, maps the remaining fields onto the model, then calls <code>perform_extra_deserialization</code> for the relation and prescription handling above.
* <code>patient</code> always comes from <code>encounter</code>; the client never writes it.
* Inline prescription creation (<code>create_prescription</code>) is idempotent on <code>(alternate_identifier, encounter)</code> and proceeds only when an existing match is <code>active</code>.
* <code>authored_on</code> falls back to <code>timezone.now</code> at the model layer when omitted.

== API integration notes ==

* Coded fields take a single <code>Coding</code> object <code>{ system, code, display }</code> validated against bound SNOMED CT value sets — send a <code>code</code> from the right value set or the write fails.
* Enum members are underscored (<code>on_hold</code>, <code>entered_in_error</code>, <code>original_order</code>); send those literals, not the FHIR hyphenated forms.
* <code>dosage_instruction</code> carries SIG text, timing/frequency, PRN flags, dose and rate, and max-dose limits — write the full nested shape (snake_case keys) rather than free text alone.
* On create, send either <code>medication</code> or <code>requested_product</code> (not both) and at most one of <code>prescription</code> / <code>create_prescription</code>.
* Updates reach only <code>status</code>, <code>note</code>, and <code>dispense_status</code>.
* <code>requester</code>, <code>requested_product</code>, and <code>prescription</code> use <code>SET_NULL</code>, so a request outlives the user, product, or prescription it referenced.

{{Related}}

References/Medication Request - Revision history

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

Admin: OHC identity seed