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

2026-07-06T04:15:52Z

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

← Older revision		Revision as of 09:45, 6 July 2026
Line 529:		Line 529:
	* Set <code>fully_dispensed</code> to roll the linked [[References/Medication Request]] into <code>complete</code> / <code>partial</code>, so pharmacists don't re-dispense an already-fulfilled request.		* Set <code>fully_dispensed</code> to roll the linked [[References/Medication Request]] into <code>complete</code> / <code>partial</code>, so pharmacists don't re-dispense an already-fulfilled request.
	* Use <code>create_dispense_order</code> to start an order inline, or <code>order</code> to attach to an existing one — never both.		* Use <code>create_dispense_order</code> to start an order inline, or <code>order</code> to attach to an existing one — never both.

			{{Navbox medications}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:20Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=medications
|title=Medication Dispense
|order=3
|introduced=3.0
|model=MedicationDispense
|reference=References/Base models & conventions
}}

<code>MedicationDispense</code> records products handed to a patient and draws down the location's inventory as it does so. It closes out the workflow a [[References/Medication Request]] opens: in inpatient settings, items are dispensed into the room and refilled as needed; in outpatient settings, they go out once an encounter completes. A dispense can carry a [[References/Charge Item]] for billing.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/medication_dispense.py <code>care/emr/models/medication_dispense.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/dispense/spec.py <code>care/emr/resources/medication/dispense/spec.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/dispense/dispense_order.py <code>care/emr/resources/medication/dispense/dispense_order.py</code>]
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/medication_dispense.py <code>care/emr/api/viewsets/medication_dispense.py</code>]

The Django model is the storage layer; several of its fields are opaque <code>JSONField</code>s. The Pydantic resource specs under <code>care/emr/resources/medication/dispense/</code> define the API schema — enums, JSON-field shapes, validation, and the read/write contracts. Where the two disagree, the spec wins: <code>status</code> stores underscored enum values like <code>in_progress</code>, not the FHIR hyphenated forms.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>MedicationDispense</code>
| A single dispense event: a quantity of one inventory item handed to a patient
|-
| <code>DispenseOrder</code>
| Groups dispense events at a location into a named order with a shared status
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, audit fields, and soft-delete semantics.

== <code>MedicationDispense</code> fields ==

=== Status & classification ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>status</code>
| <code>CharField(100)</code>
| <code>MedicationDispenseStatus</code>
| Required. See [[#medicationdispensestatus-values
|-
| <code>not_performed_reason</code>
| <code>CharField(100)</code>, null
| <code>MedicationDispenseNotPerformedReason | None</code>
| Coded reason a dispense was not performed. See [[#medicationdispensenotperformedreason-values
|-
| <code>category</code>
| <code>CharField(100)</code>, null
| <code>MedicationDispenseCategory | None</code>
| Setting the dispense happened in. See [[#medicationdispensecategory-values
|}

=== Timing & instructions ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>when_prepared</code>
| <code>DateTimeField</code>, null
| <code>datetime | None</code>
| When the product was prepared
|-
| <code>when_handed_over</code>
| <code>DateTimeField</code>, null
| <code>datetime | None</code>
| When the product was handed to the patient
|-
| <code>note</code>
| <code>TextField</code>, null
| <code>str | None</code>
| Free-text annotation
|-
| <code>dosage_instruction</code>
| <code>JSONField</code> (default <code>list</code>)
| <code>list[DosageInstruction]</code> (default <code>[]</code>)
| Structured dosage directions. See [[#dosageinstruction-shape
|-
| <code>substitution</code>
| <code>JSONField</code> (default <code>dict</code>)
| <code>MedicationDispenseSubstitution | None</code>
| Substitution record. See [[#medicationdispensesubstitution-shape
|}

=== Quantities ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>quantity</code>
| <code>DecimalField(20, 6)</code>
| <code>Decimal</code> (write: <code>max_digits=20, decimal_places=0</code>)
| Required. Amount dispensed; checked against inventory stock on create
|-
| <code>days_supply</code>
| <code>DecimalField(20, 6)</code>, null
| <code>Decimal | None</code> (<code>max_digits=20, decimal_places=0</code>)
| Expected number of days the dispensed amount lasts
|}

=== Relationships ===

{| class="wikitable"
|-
! Field
! Model type
! Notes
|-
| <code>encounter</code>
| <code>FK → Encounter</code>
| <code>CASCADE</code>. Resolved from the <code>encounter</code> UUID on write; <code>patient</code> is derived from it rather than sent directly
|-
| <code>patient</code>
| <code>FK → Patient</code>
| <code>CASCADE</code>. Server-set from <code>encounter.patient</code>
|-
| <code>location</code>
| <code>FK → FacilityLocation</code>
| <code>CASCADE</code>. Must belong to the encounter's facility
|-
| <code>authorizing_request</code>
| <code>FK → MedicationRequest</code>
| <code>SET_NULL</code>, null. The prescription this dispense fulfils; must be on the same encounter. Cleared server-side when the dispense is cancelled
|-
| <code>item</code>
| <code>FK → InventoryItem</code>
| <code>CASCADE</code>. Stock item consumed; must sit in a location of the encounter's facility
|-
| <code>charge_item</code>
| <code>FK → ChargeItem</code>
| <code>CASCADE</code>, null. Server-created from the product's charge item definition when one exists
|-
| <code>order</code>
| <code>FK → DispenseOrder</code>
| <code>CASCADE</code>, null. Parent dispense order, when grouped
|}

<code>patient</code>, <code>encounter</code>, <code>authorizing_request</code>, <code>item</code>, and <code>location</code> sit in <code>__exclude__</code> on the spec base. The viewset resolves them by hand in <code>perform_extra_deserialization</code> instead of copying them off the Pydantic object.

== Enum values ==

=== <code>MedicationDispenseStatus</code> values ===

From <code>MedicationDispenseStatus</code> (<code>spec.py</code>).

{| class="wikitable"
|-
! Value
|-
| <code>preparation</code>
|-
| <code>in_progress</code>
|-
| <code>cancelled</code>
|-
| <code>on_hold</code>
|-
| <code>completed</code>
|-
| <code>entered_in_error</code>
|-
| <code>stopped</code>
|-
| <code>declined</code>
|}

<code>MEDICATION_DISPENSE_CANCELLED_STATUSES = [cancelled, entered_in_error, stopped, declined]</code> are terminal. Once a dispense lands in one, no further updates are allowed, and the transition into it triggers charge-item cancellation (see [[#methods--save-behaviour|Methods & save behaviour]]).

=== <code>MedicationDispenseNotPerformedReason</code> values ===

From <code>MedicationDispenseNotPerformedReason</code> (<code>spec.py</code>). Coded reasons drawn from FHIR <code>medicationdispense-status-reason</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>outofstock</code>
| Out of stock
|-
| <code>washout</code>
| Washout
|-
| <code>surg</code>
| Surgery
|-
| <code>sintol</code>
| Sensitivity / intolerance to drug
|-
| <code>sddi</code>
| Drug interaction
|-
| <code>sdupther</code>
| Duplicate therapy
|-
| <code>saig</code>
| Allergy to ingredient of medication
|-
| <code>preg</code>
| Patient pregnant
|}

=== <code>MedicationDispenseCategory</code> values ===

From <code>MedicationDispenseCategory</code> (<code>spec.py</code>).

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

=== <code>SubstitutionType</code> values ===

From <code>SubstitutionType</code> (<code>spec.py</code>) — used in <code>substitution.substitution_type</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>E</code>
| Equivalent
|-
| <code>EC</code>
| Equivalent composition
|-
| <code>BC</code>
| Brand composition
|-
| <code>G</code>
| Generic composition
|-
| <code>TE</code>
| Therapeutic alternative
|-
| <code>TB</code>
| Therapeutic brand
|-
| <code>TG</code>
| Therapeutic generic
|-
| <code>F</code>
| Formulary
|-
| <code>N</code>
| None
|}

=== <code>SubstitutionReason</code> values ===

From <code>SubstitutionReason</code> (<code>spec.py</code>) — used in <code>substitution.reason</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>CT</code>
| Continuing therapy
|-
| <code>FP</code>
| Formulary policy
|-
| <code>OS</code>
| Out of stock
|-
| <code>RR</code>
| Regulatory requirement
|}

== JSON field shapes ==

=== <code>MedicationDispenseSubstitution</code> shape ===

The <code>substitution</code> field (<code>MedicationDispenseSubstitution</code>). When present, all three keys are required:

<syntaxhighlight lang="text">substitution = {
was_substituted: bool # required
substitution_type: SubstitutionType # required; see SubstitutionType values
reason: SubstitutionReason # required; see SubstitutionReason values
}</syntaxhighlight>
=== <code>DosageInstruction</code> shape ===

<code>dosage_instruction</code> is a <code>list[DosageInstruction]</code>. <code>DosageInstruction</code> comes straight from the [[References/Medication Request]] spec (<code>care/emr/resources/medication/request/spec.py</code>):

<syntaxhighlight lang="text">DosageInstruction {
sequence: int | None
text: str | None
additional_instruction: list[Coding]@system-additional-instruction | None
patient_instruction: str | None
timing: Timing | None
as_needed_boolean: bool # required
as_needed_for: Coding@system-as-needed-reason | None
site: Coding@system-body-site | None
route: Coding@system-route | None
method: Coding@system-administration-method | None
dose_and_rate: DoseAndRate | None
max_dose_per_period: DoseRange | None
}

Timing { repeat: TimingRepeat, code: Coding | None }
TimingRepeat{ frequency: int, period: Decimal(20,0), period_unit: TimingUnit, bounds_duration: TimingQuantity }
TimingQuantity { value: Decimal(20,0), unit: TimingUnit }
DoseAndRate { type: DoseType, dose_range: DoseRange | None, dose_quantity: DosageQuantity | None }
DoseRange { low: DosageQuantity, high: DosageQuantity }
DosageQuantity { value: Decimal(20,6), unit: Coding }</syntaxhighlight>
<code>Coding@<slug></code> denotes a <code>Coding</code> bound to a Care value set (<code>ValueSetBoundCoding</code>), where <code>Coding = { system?, version?, code (required), display? }</code>. <code>TimingUnit ∈ {s, min, h, d, wk, mo, a}</code>; <code>DoseType ∈ {ordered, calculated}</code>. The shared <code>PeriodSpec</code> (from <code>base.py</code>) — <code>{ start: datetime, end: datetime }</code>, both tz-aware, <code>start ≤ end</code> — is the standard period shape elsewhere, but <code>MedicationDispense</code> exposes no period field of its own.

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>base.py</code>) and rides its <code>serialize</code> / <code>de_serialize</code> plumbing. Read-side data is assembled in <code>perform_extra_serialization</code>; write-side FK resolution and side effects happen in <code>perform_extra_deserialization</code>.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseMedicationDispenseSpec</code>
| shared base
| <code>__model__ = MedicationDispense</code>. Exposes <code>status</code>, <code>not_performed_reason</code>, <code>category</code>, <code>when_prepared</code>, <code>when_handed_over</code>, <code>note</code>, <code>dosage_instruction</code>, <code>substitution</code>. Excludes the FK fields
|-
| <code>MedicationDispenseWriteSpec</code>
| write · create
| Adds <code>encounter</code>, <code>location</code>, <code>authorizing_request</code>, <code>item</code> (UUIDs), <code>quantity</code>, <code>days_supply</code>, <code>fully_dispensed</code>, <code>order</code>, <code>create_dispense_order</code>. Resolves FKs and runs create-time logic
|-
| <code>MedicationDispenseUpdateSpec</code>
| write · update
| Base fields plus <code>fully_dispensed</code> and <code>order</code>. Cannot re-point <code>encounter</code>/<code>item</code>/<code>location</code>
|-
| <code>MedicationDispenseReadSpec</code>
| read · list
| Serializes nested <code>item</code>, <code>charge_item</code>, <code>location</code>, <code>authorizing_request</code>, <code>order</code>; adds <code>created_date</code>, <code>modified_date</code>
|-
| <code>MedicationDispenseRetrieveSpec</code>
| read · detail
| Extends <code>ReadSpec</code>, also serializing the full <code>encounter</code>
|-
| <code>MedicationDispenseSubstitution</code>
| nested
| Shape of the <code>substitution</code> JSON field
|-
| <code>CreateDispenseOrder</code>
| nested (write)
| Inline order creation payload — see below
|}

=== Write-spec fields ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=MedicationDispense|section=Write-spec fields|name=encounter|type=UUID4|notes=yes}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=location|type=UUID4|notes=yes}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=item|type=UUID4|notes=yes}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=authorizing_request|type=UUID4 | None|notes=no}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=quantity|type=Decimal|notes=yes}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=days_supply|type=Decimal | None|notes=no}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=fully_dispensed|type=bool | None|notes=no}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=order|type=UUID4 | None|notes=no}}
{{Field|model=MedicationDispense|section=Write-spec fields|name=create_dispense_order|type=CreateDispenseOrder | None|notes=no}}
|}

<code>validate_prescription</code> rejects a payload that sends both <code>order</code> and <code>create_dispense_order</code>.

=== <code>CreateDispenseOrder</code> ===

Inline order payload on the write spec. With no matching order (by <code>alternate_identifier</code> + <code>patient</code> + <code>location</code>), one is created. A matching order whose status is not <code>draft</code>/<code>in_progress</code> is rejected with <code>"Prescription is not active"</code>.

<syntaxhighlight lang="text">CreateDispenseOrder {
name: str | None
note: str | None
alternate_identifier: str # required
status: CreateDispenseOrderStatusOptions # default "draft"
}</syntaxhighlight>
<code>CreateDispenseOrderStatusOptions ∈ {draft, in_progress}</code>.

=== Bound value sets ===

<code>dosage_instruction</code> codings bind to Care value sets, all SNOMED CT and registered as systems:

{| class="wikitable"
|-
! Field (within <code>DosageInstruction</code>)
! Value set slug
|-
| <code>additional_instruction</code>
| <code>system-additional-instruction</code>
|-
| <code>as_needed_for</code>
| <code>system-as-needed-reason</code>
|-
| <code>site</code>
| <code>system-body-site</code>
|-
| <code>route</code>
| <code>system-route</code>
|-
| <code>method</code>
| <code>system-administration-method</code>
|}

The dispense-level <code>not_performed_reason</code> lines up with the <code>system-medication-not-given</code> value set (<code>medication_not_given_reason.py</code>), but it is stored and validated as the <code>MedicationDispenseNotPerformedReason</code> enum, not as a bound <code>Coding</code>.

== Related models ==

=== <code>DispenseOrder</code> ===

Groups one or more <code>MedicationDispense</code> events at a location into a named order under a single status.

<syntaxhighlight lang="text">location → FK FacilityLocation (CASCADE)
patient → FK Patient (CASCADE)
facility → FK Facility (CASCADE)
name → CharField(255), nullable
status → CharField(255)
note → TextField, nullable
tags → ArrayField[int], default []
alternate_identifier → CharField(100), nullable</syntaxhighlight>
The <code>unique_alternate_identifier_encounter_location</code> constraint enforces uniqueness on <code>(alternate_identifier, patient, location)</code>, so each external identifier appears at most once per patient and location.

'''Source / specs:'''

* Model: <code>DispenseOrder</code> in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/medication_dispense.py <code>medication_dispense.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/dispense/dispense_order.py <code>dispense_order.py</code>]
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/inventory/dispense_order.py <code>api/viewsets/inventory/dispense_order.py</code>]

==== <code>MedicationDispenseOrderStatusOptions</code> values ====

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>in_progress</code>
|-
| <code>completed</code>
|-
| <code>abandoned</code>
|-
| <code>entered_in_error</code>
|}

<code>MEDICATION_DISPENSE_ORDER_COMPLETED_STATUSES = [abandoned, entered_in_error, completed]</code> are terminal. <code>abandoned</code> and <code>entered_in_error</code> are the cancel transitions.

==== <code>DispenseOrder</code> specs ====

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseMedicationDispenseOrderSpec</code>
| shared base / update
| Exposes <code>status</code>, <code>name</code>, <code>note</code>. Doubles as the update spec
|-
| <code>MedicationDispenseOrderWriteSpec</code>
| write · create
| Adds <code>patient</code>, <code>location</code> (UUIDs), resolved in deserialization. <code>facility</code> is set server-side from the URL
|-
| <code>MedicationDispenseOrderReadSpec</code>
| read · list
| Serializes nested <code>patient</code> (list spec), <code>location</code>; adds <code>created_date</code>, <code>modified_date</code>
|-
| <code>MedicationDispenseOrderRetrieveSpec</code>
| read · detail
| Full <code>patient</code> (retrieve spec) plus <code>created_by</code> / <code>updated_by</code> audit users
|}

== Methods & save behaviour ==

The model has no custom <code>save()</code>. The dispense workflow lives in <code>MedicationDispenseViewSet</code>, inside a <code>transaction.atomic()</code> block, layering side effects over the spec's <code>perform_extra_deserialization</code>.

'''On create (<code>perform_create</code>):'''

* Takes an <code>InventoryItemLock</code> on <code>item</code> and rejects if <code>item.net_content < quantity</code> (<code>"Inventory item does not have enough stock"</code>).
* When <code>item.product.charge_item_definition</code> exists, applies it to create a <code>ChargeItem</code> (resource <code>medication_dispense</code>, linked to this dispense's <code>external_id</code>; <code>performer_actor</code> is the authorizing request's requester when present) and attaches it via <code>charge_item</code>.
* Calls <code>sync_inventory_item(item.location, item.product)</code> to draw down stock.
* When <code>fully_dispensed</code> is set and an <code>authorizing_request</code> exists, sets that request's <code>dispense_status</code> to <code>complete</code> (on <code>True</code>) or <code>partial</code> (on <code>False</code>).
* Order resolution: <code>create_dispense_order</code> does a get-or-create by <code>(alternate_identifier, patient, location)</code>; an existing non-<code>draft</code>/<code>in_progress</code> order is rejected.

'''On update (<code>perform_update</code>):'''

* <code>validate_data</code> rejects any update while the current status is in <code>MEDICATION_DISPENSE_CANCELLED_STATUSES</code>.
* A transition ''into'' a cancelling status with a <code>charge_item</code> attached cancels that charge item (<code>handle_charge_item_cancel</code>, status → <code>aborted</code>), sets the authorizing request's <code>dispense_status</code> to <code>incomplete</code>, and detaches <code>authorizing_request</code> (<code>SET_NULL</code>).
* Re-syncs inventory and re-applies the <code>fully_dispensed</code> → <code>dispense_status</code> (<code>complete</code>/<code>partial</code>) logic.

'''Dispense-order cancellation (<code>cancel_dispense_order</code> in the order viewset):''' moving an order to <code>abandoned</code> or <code>entered_in_error</code> cascades to every member dispense. It cancels their charge items, marks each dispense <code>cancelled</code> / <code>entered_in_error</code> respectively, sets authorizing requests' <code>dispense_status</code> to <code>incomplete</code>, and detaches them. An order already in <code>abandoned</code>/<code>entered_in_error</code> cannot transition, and a <code>completed</code> order can only be cancelled.

== API integration notes ==

* The resource is exposed through <code>MedicationDispenseViewSet</code> (create, retrieve, update, list, upsert) and tracks the FHIR <code>MedicationDispense</code> resource. API field names may differ from FHIR — <code>authorizing_request</code> ≈ FHIR <code>authorizingPrescription</code> — and enum '''values''' use underscores (<code>in_progress</code>, <code>entered_in_error</code>), not FHIR hyphens.
* List and summary need either a <code>location</code> or <code>encounter</code> query param, otherwise they <code>400</code>. <code>include_children=true</code> widens a location query to descendant locations via <code>parent_cache</code>. Filters: <code>status</code>, <code>exclude_status</code>, <code>category</code>, <code>encounter</code>, <code>patient</code>, <code>item</code>, <code>authorizing_prescription</code>, <code>authorizing_request</code>, <code>location</code>, <code>order</code>. The <code>summary</code> action returns per-encounter dispense counts.
* Permissions are location-centric. Creating needs only write access to the dispensing <code>location</code> — pharmacists often lack encounter access — while reads need either location-list or encounter-view permission.
* Send <code>item</code> as an <code>InventoryItem</code> UUID, not a bare product code; that UUID is what draws down stock.
* <code>quantity</code> and <code>days_supply</code> are constrained to whole units (<code>decimal_places=0</code>) on the write spec, even though the column stores 6 decimal places.
* Leave <code>charge_item</code> alone. It is server-managed: created from the product's charge item definition and cancelled on dispense or order cancellation.
* Set <code>fully_dispensed</code> to roll the linked [[References/Medication Request]] into <code>complete</code> / <code>partial</code>, so pharmacists don't re-dispense an already-fulfilled request.
* Use <code>create_dispense_order</code> to start an order inline, or <code>order</code> to attach to an existing one — never both.

{{Related}}

References/Medication Dispense - Revision history

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

Admin: OHC identity seed