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

2026-07-06T04:15:02Z

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

← Older revision		Revision as of 09:45, 6 July 2026
Line 354:		Line 354:
	* Set either <code>medication</code> or <code>administered_product</code>, never both. Use <code>administered_product</code> when a specific catalogued product was given, so the administration reconciles against inventory; use <code>medication</code> for a coded drug with no catalog product.		* Set either <code>medication</code> or <code>administered_product</code>, never both. Use <code>administered_product</code> when a specific catalogued product was given, so the administration reconciles against inventory; use <code>medication</code> for a coded drug with no catalog product.
	* After create, only <code>status</code>, <code>note</code>, and <code>occurrence_period_end</code> are updatable; <code>encounter</code>, <code>request</code>, and <code>patient</code> are immutable.		* After create, only <code>status</code>, <code>note</code>, and <code>occurrence_period_end</code> are updatable; <code>encounter</code>, <code>request</code>, and <code>patient</code> are immutable.

			{{Navbox medications}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:18Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=medications
|title=Medication Administration
|order=2
|introduced=3.0
|model=MedicationAdministration
|reference=References/Base models & conventions
}}

<code>MedicationAdministration</code> records that a medication was given to a patient — or that giving it was attempted — fulfilling a [[References/Medication Request|<code>MedicationRequest</code>]]. You write one each time a dose is administered against an order. The Django model is the storage layer; several columns are opaque <code>JSONField</code>s whose structure comes from the Pydantic resource specs in <code>care/emr/resources/medication/administration/</code>. Both layers are documented below.

'''Source:'''

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

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>MedicationAdministration</code>
| The administration event that fulfils a [[References/Medication Request
|}

<code>MedicationAdministration</code> extends <code>EMRBaseModel</code>, the shared Care EMR base that provides <code>external_id</code>, audit fields, and soft-delete semantics (see [[References/Base models & conventions|Base model]]). It maps to the FHIR [<nowiki/>https://hl7.org/fhir/medicationadministration.html <code>MedicationAdministration</code>] resource.

== <code>MedicationAdministration</code> fields ==

Each row lists the storage column type and, where the column is a <code>JSONField</code>, the structured shape the resource spec enforces.

=== Status & classification ===

{| class="wikitable"
|-
! Field
! Storage
! Spec shape
! Notes
|-
| <code>status</code>
| <code>CharField(100)</code>
| <code>MedicationAdministrationStatus</code> enum
| Required. Administration event status — see [[#medicationadministrationstatus-values
|-
| <code>status_reason</code>
| <code>JSONField</code> (null)
| <code>Coding</code> bound to <code>system-medication</code> value set
| Optional. Coded reason for the status. The spec binds this to the medication value set, not the "not given" reason set you might expect
|-
| <code>category</code>
| <code>CharField(100)</code> (null)
| <code>MedicationAdministrationCategory</code> enum
| Optional. Administration setting — see [[#medicationadministrationcategory-values
|}

=== Medication & product ===

{| class="wikitable"
|-
! Field
! Storage
! Spec shape
! Notes
|-
| <code>medication</code>
| <code>JSONField</code> (default <code>{}</code>)
| <code>Coding</code> bound to <code>system-medication</code> value set
| Optional in spec. <code>{ system, version?, code, display? }</code>. Mutually exclusive with <code>administered_product</code> (model validator)
|-
| <code>administered_product</code>
| <code>FK → ProductKnowledge</code> (null, <code>CASCADE</code>)
| <code>UUID4</code> (write) / nested <code>ProductKnowledgeReadSpec</code> (read)
| Optional. The specific catalog product administered. Cannot be set together with <code>medication</code>
|-
| <code>dosage</code>
| <code>JSONField</code> (null)
| <code>Dosage</code> nested spec
| Optional. Dose, rate, route, site, and method actually administered — see [[#dosage-nested-spec
|}

=== Subject & context ===

{| class="wikitable"
|-
! Field
! Storage
! Spec shape
! Notes
|-
| <code>patient</code>
| <code>FK → Patient</code> (<code>CASCADE</code>)
| not in spec (server-derived)
| The patient who received the medication. Set server-side from the encounter's patient on create — never accepted from the client
|-
| <code>encounter</code>
| <code>FK → Encounter</code> (null, <code>CASCADE</code>)
| <code>UUID4</code> (required, write)
| The encounter during which the medication was administered. Validated to exist; read schema returns the encounter's <code>external_id</code>
|-
| <code>request</code>
| <code>FK → MedicationRequest</code> (null, <code>CASCADE</code>)
| <code>UUID4</code> (required, write)
| The order this administration fulfils. Validated to exist; read schema returns the request's <code>external_id</code>
|}

=== Timing & attribution ===

{| class="wikitable"
|-
! Field
! Storage
! Spec shape
! Notes
|-
| <code>authored_on</code>
| <code>DateTimeField</code> (null)
| <code>datetime</code>
| Optional. When the record was authored, distinct from when the dose was given
|-
| <code>occurrence_period_start</code>
| <code>DateTimeField</code> (default <code>datetime.now</code>)
| <code>datetime</code> (required)
| When the administration began. Required on create; defaults to now at the model level
|-
| <code>occurrence_period_end</code>
| <code>DateTimeField</code> (null)
| <code>datetime</code>
| Optional. End of the administration, for infusions and extended doses. Updatable via <code>MedicationAdministrationUpdateSpec</code>
|-
| <code>recorded</code>
| <code>DateTimeField</code> (null)
| <code>datetime</code>
| Optional. When the event was entered into the system, distinct from <code>occurrence_period_start</code>
|-
| <code>performer</code>
| <code>JSONField</code> (default <code>[]</code>)
| <code>list[MedicationAdministrationPerformer]</code>
| Optional. Actors who performed the administration and their function — see [[#medicationadministrationperformer-nested-spec
|-
| <code>note</code>
| <code>TextField</code> (null)
| <code>str</code>
| Optional. Free-text annotation. Updatable via <code>MedicationAdministrationUpdateSpec</code>
|}

== Enum values ==

=== <code>MedicationAdministrationStatus</code> values ===

<code>str</code> enum (<code>care/emr/resources/medication/administration/spec.py</code>). These use underscores (e.g. <code>not_done</code>), not the FHIR hyphenated forms.

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

=== <code>MedicationAdministrationCategory</code> values ===

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

=== <code>MedicationAdministrationPerformerFunction</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>performer</code>
|-
| <code>verifier</code>
|-
| <code>witness</code>
|}

== Nested specs (JSON-field shapes) ==

=== <code>Dosage</code> (nested spec) ===

Structured shape of the <code>dosage</code> <code>JSONField</code>. Every field is optional.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=text|type=str | None|notes=Free-text dosage instructions}}
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=site|type=Coding | None|notes=Bound to <code>system-body-site</code> value set (SNOMED CT <code><< 91723000</code>)}}
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=route|type=Coding | None|notes=Bound to <code>system-route</code> value set (SNOMED CT <code><< 284009009</code>)}}
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=method|type=Coding | None|notes=Bound to <code>system-administration-method</code> value set (SNOMED CT <code><< 736665006</code>)}}
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=dose|type=Quantity | None|notes=The amount of medication administered}}
{{Field|model=MedicationAdministration|section=Dosage (nested spec)|name=rate|type=Quantity | None|notes=The speed of administration}}
|}

<code>Quantity</code> shape (<code>care/emr/resources/common/quantity.py</code>, <code>extra="forbid"</code>): <code>{ value: Decimal? (max_digits 20, decimal_places 6), unit: Coding?, code: Coding?, meta: dict? }</code>.

<code>Coding</code> shape (<code>care/emr/resources/common/coding.py</code>, <code>extra="forbid"</code>): <code>{ system: str?, version: str?, code: str (required), display: str? }</code>.

=== <code>MedicationAdministrationPerformer</code> (nested spec) ===

Element shape of the <code>performer</code> <code>JSONField</code> list.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=MedicationAdministration|section=MedicationAdministrationPerformer (nested spec)|name=actor|type=UUID4 (required)|notes=The user who performed the administration. Validated server-side to reference an existing [[References/User & Skills}}
{{Field|model=MedicationAdministration|section=MedicationAdministrationPerformer (nested spec)|name=function|type=MedicationAdministrationPerformerFunction | None|notes=The performer's function — see [[#medicationadministrationperformerfunction-values}}
|}

== Bound value sets ==

Coded fields bind to Care system value sets (SNOMED CT). <code>ValueSetBoundCoding</code> rejects any code outside the bound set.

{| class="wikitable"
|-
! Field
! Value set
! Slug
! SNOMED CT constraint
|-
| <code>medication</code>, <code>status_reason</code>
| Medication
| <code>system-medication</code>
| <code><< 763158003</code> (Medicinal product)
|-
| <code>dosage.site</code>
| Body Site
| <code>system-body-site</code>
| <code>is-a 91723000</code>
|-
| <code>dosage.route</code>
| Route
| <code>system-route</code>
| <code>is-a 284009009</code>
|-
| <code>dosage.method</code>
| Administration Method
| <code>system-administration-method</code>
| <code>is-a 736665006</code>
|}

Three more medication value sets are defined alongside these but go unreferenced by this resource's specs: Medication Not Given Reason (<code>system-medication-not-given</code>, <code>is-a 242990004</code> + <code>is-a 182895007</code>), Additional Instruction (<code>system-additional-instruction</code>, <code>is-a 419492006</code>), and As Needed (<code>system-as-needed-reason</code>, <code>is-a 404684003</code>).

== Resource specs (API schema) ==

All specs build on <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB object → read schema) and <code>de_serialize</code> (write schema → DB object), each with a <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hook. <code>__exclude__</code> lists the fields those hooks handle manually rather than copying field-for-field.

{| class="wikitable"
|-
! Spec class
! Role
! Key fields / behaviour
|-
| <code>BaseMedicationAdministrationSpec</code>
| shared base
| All common fields: <code>status</code>, <code>status_reason</code>, <code>category</code>, <code>medication</code>, <code>authored_on</code>, <code>occurrence_period_start</code>, <code>occurrence_period_end</code>, <code>recorded</code>, <code>encounter</code>, <code>request</code>, <code>performer</code>, <code>dosage</code>, <code>note</code>. <code>__exclude__ = ["patient", "encounter", "request", "administered_product"]</code>
|-
| <code>MedicationAdministrationSpec</code>
| write · create
| Extends base; adds <code>administered_product: UUID4 | None</code>. Validates <code>encounter</code> and <code>request</code> exist; rejects <code>medication</code> + <code>administered_product</code> set together
|-
| <code>MedicationAdministrationUpdateSpec</code>
| write · update
| Narrow update schema: only <code>status</code>, <code>note</code>, <code>occurrence_period_end</code>. <code>__exclude__ = ["patient", "encounter", "request"]</code> — those are immutable after create
|-
| <code>MedicationAdministrationReadSpec</code>
| read · detail/list
| Extends base; adds audit fields <code>created_by</code>, <code>updated_by</code>, <code>created_date</code>, <code>modified_date</code>, and nested <code>administered_product: dict</code>
|-
| <code>Dosage</code>
| nested
| Shape of the <code>dosage</code> JSON field (see above)
|-
| <code>MedicationAdministrationPerformer</code>
| nested
| Element of the <code>performer</code> JSON list (see above)
|}

=== Validation rules ===

* '''Mutual exclusion''' (<code>MedicationAdministrationSpec.validate_administered_product</code>, <code>model_validator(mode="after")</code>): <code>medication</code> and <code>administered_product</code> cannot both be set.
* '''Existence checks''' (field validators, create): <code>encounter</code> must reference an existing <code>Encounter</code>; <code>request</code> must reference an existing <code>MedicationRequest</code>; each <code>performer.actor</code> must reference an existing <code>User</code>.
* '''Bound codings''': <code>medication</code>, <code>status_reason</code>, and <code>dosage.{site,route,method}</code> are validated against their bound value sets; unknown codes raise.
* '''Required on create''': <code>status</code>, <code>occurrence_period_start</code>, <code>encounter</code>, <code>request</code>.

=== Server-maintained behaviour ===

<code>MedicationAdministrationSpec.perform_extra_deserialization</code> (create only, <code>is_update == False</code>):

* Resolves <code>encounter</code> from the supplied <code>external_id</code> and sets <code>obj.encounter</code>.
* Derives <code>obj.patient</code> from <code>obj.encounter.patient</code> — <code>patient</code> is never taken from the client.
* Resolves <code>request</code> from its <code>external_id</code> and sets <code>obj.request</code>.
* If <code>administered_product</code> is supplied, resolves the <code>ProductKnowledge</code> and sets <code>obj.administered_product</code>.

<code>MedicationAdministrationReadSpec.perform_extra_serialization</code>:

* Sets <code>id</code> to <code>external_id</code>; flattens <code>encounter</code> and <code>request</code> to their <code>external_id</code>s.
* Serializes <code>administered_product</code> (when present) via <code>ProductKnowledgeReadSpec</code>.
* Adds <code>created_by</code> / <code>updated_by</code> via <code>serialize_audit_users</code>.

== Related models ==

<code>administered_product</code> references the supply-side catalog rather than carrying a nested record:

<syntaxhighlight lang="text">administered_product → FK ProductKnowledge (nullable, CASCADE)
patient → FK Patient (CASCADE)
encounter → FK Encounter (nullable, CASCADE)
request → FK MedicationRequest (nullable, CASCADE)</syntaxhighlight>
<code>medication</code>, <code>dosage</code>, <code>status_reason</code>, and <code>performer</code> are stored inline as <code>JSONField</code>s rather than in separate tables, mirroring the FHIR <code>MedicationAdministration</code> structure; their real shape comes from the resource specs above.

== Methods & save behaviour ==

* <code>de_serialize(obj?)</code> dumps the write schema with <code>model_dump(exclude_defaults=True)</code>, so unset fields never overwrite existing values — the same path handles both create and update.
* Audit and soft-delete fields (<code>external_id</code>, <code>created_by</code>, <code>created_date</code>, <code>modified_date</code>, <code>deleted</code>, etc.) are inherited from <code>EMRBaseModel</code> and maintained by the platform; clients never set them.

== API integration notes ==

* Write requests use <code>MedicationAdministrationSpec</code> (create) and <code>MedicationAdministrationUpdateSpec</code> (update); reads return <code>MedicationAdministrationReadSpec</code>. Field names mostly match the model; <code>occurrence_period_start</code> / <code>occurrence_period_end</code> map to the FHIR <code>occurence[x]</code> period.
* Send coded fields (<code>medication</code>, <code>status_reason</code>, <code>dosage.site/route/method</code>) as <code>Coding</code> objects (<code>system</code> / <code>code</code> / <code>display</code>) drawn from the bound value sets — free strings and out-of-set codes are rejected.
* <code>status</code> values use underscores (<code>in_progress</code>, <code>not_done</code>, <code>on_hold</code>, <code>entered_in_error</code>), not the FHIR hyphenated spellings.
* Provide <code>encounter</code> and <code>request</code> as <code>external_id</code> UUIDs; <code>patient</code> is derived server-side from the encounter and must not be sent.
* Set either <code>medication</code> or <code>administered_product</code>, never both. Use <code>administered_product</code> when a specific catalogued product was given, so the administration reconciles against inventory; use <code>medication</code> for a coded drug with no catalog product.
* After create, only <code>status</code>, <code>note</code>, and <code>occurrence_period_end</code> are updatable; <code>encounter</code>, <code>request</code>, and <code>patient</code> are immutable.

{{Related}}

References/Medication Administration - Revision history

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

Admin: OHC identity seed