Pharmacy

Medication Administration

MedicationAdministration records that a medication was given to a patient — or that giving it was attempted — fulfilling a MedicationRequest. You write one each time a dose is administered against an order. The Django model is the storage…

3.1 · versioned documentation · 8 min read

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

Source:

• Model: care/emr/models/medication_administration.py
• Spec: care/emr/resources/medication/administration/spec.py
• Value sets: care/emr/resources/medication/valueset/

Models

MedicationAdministration extends EMRBaseModel, the shared MANSOQ EMR base that provides external_id, audit fields, and soft-delete semantics (see Base model). It maps to the FHIR MedicationAdministration resource.

MedicationAdministration fields

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

Status & classification

Medication & product

Subject & context

Timing & attribution

Enum values

MedicationAdministrationStatus values

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

MedicationAdministrationCategory values

MedicationAdministrationPerformerFunction values

Nested specs (JSON-field shapes)

Dosage (nested spec)

Structured shape of the dosage JSONField. Every field is optional.

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

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

MedicationAdministrationPerformer (nested spec)

Element shape of the performer JSONField list.

Bound value sets

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

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

Resource specs (API schema)

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

Validation rules

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

Server-maintained behaviour

MedicationAdministrationSpec.perform_extra_deserialization (create only, is_update == False):

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

MedicationAdministrationReadSpec.perform_extra_serialization:

• Sets id to external_id; flattens encounter and request to their external_ids.
• Serializes administered_product (when present) via ProductKnowledgeReadSpec.
• Adds created_by / updated_by via serialize_audit_users.

Related models

administered_product references the supply-side catalog rather than carrying a nested record:

administered_product → FK ProductKnowledge (nullable, CASCADE)
patient              → FK Patient (CASCADE)
encounter            → FK Encounter (nullable, CASCADE)
request              → FK MedicationRequest (nullable, CASCADE)

medication, dosage, status_reason, and performer are stored inline as JSONFields rather than in separate tables, mirroring the FHIR MedicationAdministration structure; their real shape comes from the resource specs above.

Methods & save behaviour

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

API integration notes

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

Related

• Reference: Medication Request
• Reference: Medication Dispense
• Reference: Medication Statement
• Reference: Product Knowledge
• Reference: Encounter
• Reference: Patient
• Reference: User
• Reference: Base model
• Source: medication_administration.py on GitHub
• Source: administration/spec.py on GitHub
• Source: medication value sets on GitHub

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/medications/medication-administration.mdx:1 · f6e9f05f