IHE Pharmacy Medication Overview, published by Integrating the Healthcare Enterprise (IHE). This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/pharm-meow/tree/jct-draft and changes regularly. See the Directory of published versions
Built from commit 62c0f394.   Branch: jct-draft.

PHARM-11 Retrieve Medication Overview

PHARM-11: Retrieve Medication Overview

Scope

The Retrieve Medication Overview transaction [PHARM-11] allows a Medication Overview Consumer to retrieve a complete, self-contained medication overview from a Medication Overview Responder.

The response is a MedicationOverviewBundle — a Bundle of type document — that carries authorship metadata via a Composition, and is suitable for handover, discharge summaries, and legal records. Unlike PHARM-12, which returns a live searchset of individual resources, this transaction returns a snapshot that is attributed and immutable.

The Consumer may either retrieve a specific known overview by identifier, or search for available overviews matching criteria such as patient, overview type, and date.

Actors and Roles

Note: The Medication Overview Responder supports this transaction only if the Document Option is declared. A Responder that does not store pre-assembled overviews MAY instead support on-demand generation (see Option: On-Demand Generation).

Referenced Standards

• HL7 FHIR R5 — Bundle (type: document), Composition, RESTful search
• IHE ITI Appendix Z — FHIR Common Implementation Material
• IHE ITI IUA — Authorization token (grouping requirement)
• IHE ITI ATNA — Audit trail (grouping requirement)
• IHE ITI MHD — Reference pattern for document-based exchange (non-normative)

Interaction Diagram

​

Request Messages

This transaction supports two request patterns. Both return a MedicationOverviewBundle. Systems SHALL support Pattern A (direct fetch); Pattern B (search for overviews) is required if the Responder holds multiple overviews per patient.

Pattern A — Retrieve a Known Overview

Used when the Consumer already has an identifier for a specific overview (e.g. obtained from a prior directory query or notification).

GET [base]/Bundle/[logical-id]

or, using a business identifier:

GET [base]/Bundle?identifier=[system]|[value]

Pattern B — Find Available Overviews for a Patient

Used when the Consumer wants to discover what overviews exist for a patient and retrieve the most appropriate one.

GET [base]/Bundle?type=document&patient=[ref]&[optional-parameters]

Optional Filter Parameters for Pattern B

Example Requests

Fetch an overview by logical id:

GET [base]/Bundle/550e8400-e29b-41d4-a716-446655440000

Find the most recent active medication list for a patient:

GET [base]/Bundle?type=document
    &patient=Patient/123
    &type=http://loinc.org|10160-0
    &_sort=-date
    &_count=1

Find all discharge medication overviews for a patient since a date:

GET [base]/Bundle?type=document
    &patient=Patient/123
    &type=http://loinc.org|56445-0
    &date=ge2024-01-01

Using a national patient identifier:

GET [base]/Bundle?type=document
    &patient.identifier=urn:oid:2.16.840.1.113883.2.51.1|A123456789
    &_sort=-date

Overview Types

The type parameter selects the kind of medication overview. The following types are anticipated; the ValueSet is under development (see issue #42):

Open issue: Finalize the ValueSet for overview type codes, considering existing LOINC codes and the need for additional types (issue #42).

Response Message

Success — 200 OK (Pattern A)

A single MedicationOverviewBundle resource is returned, conforming to MedicationOverviewBundle.

The Bundle SHALL contain:

• 1..1 MedicationOverviewComposition — authorship, date, type, and section structure
• 1..1 Patient — subject of the overview
• 0..* MedicationTreatmentLine — the treatment lines (mandatory clinical content)
• 0..* MedicationTreatment (CarePlan) — grouping of treatment lines (conditional; present when treatment grouping is represented)
• 0..* MedicationRequest — related prescriptions (optional; included based on Composition sections)
• 0..* MedicationDispense — related dispenses (optional)
• 0..* MedicationAdministration — related administrations (optional)
• 0..* Medication — medication product details referenced by treatment lines

Success — 200 OK (Pattern B)

A Bundle of type searchset is returned. Each entry in the searchset is a MedicationOverviewBundle.

• Bundle.total reflects the number of matching overviews.
• Each overview entry SHALL be a full MedicationOverviewBundle or a reference that the Consumer can dereference to retrieve the full overview.

Design question: Should Pattern B return full overview Bundles inline in the searchset, or references? Full inlining is simple but produces large responses. Returning references (with a subsequent Pattern A fetch) is more scalable. This decision is open.

No Results — 200 OK

An empty searchset Bundle (total = 0) for Pattern B. The Responder SHALL NOT return 404 when there are simply no overviews matching the criteria.

Errors

All error responses SHALL include an OperationOutcome.

Option: On-Demand Generation

A Responder that does not store pre-assembled overviews MAY support on-demand generation using the FHIR $document operation on a Composition:

GET [base]/Composition/[id]/$document

In this case:

• The Responder internally holds a MedicationOverviewComposition resource (with section references to live resources).
• On receipt of $document, it assembles and returns a complete MedicationOverviewBundle.
• The Consumer receives the same response shape as Pattern A.
• The Responder SHALL declare support for this operation in its CapabilityStatement.

Open question: Should this option be normative (i.e. a defined actor option) or informative? Declare as an Actor Option if on-demand generation is expected to be a distinct implementation pattern.

Expected Actions

Medication Overview Responder

• SHALL return a MedicationOverviewBundle conforming to MedicationOverviewBundle for a successful Pattern A request.
• SHALL support Pattern B (search) if it holds multiple overviews per patient.
• SHALL perform patient identity resolution per IHE ITI Appendix Z.
• SHALL validate that the requested overview belongs to the authorized patient.
• SHALL record an ATNA PHI-access audit event for each retrieval.
• SHALL return 404 for Pattern A requests when the overview identifier does not exist.
• SHALL return 410 Gone if an overview has been explicitly retracted or replaced.

Medication Overview Consumer

• SHALL be capable of processing a complete MedicationOverviewBundle, including all defined section types.
• SHALL validate the overview's Composition.author and Composition.date for provenance purposes.
• SHALL use Pattern A when it has a direct overview reference; SHOULD use Pattern B only for discovery.
• SHALL present an IUA access token per IHE ITI IUA.

CapabilityStatement Requirements

The Medication Overview Responder (Document Option) SHALL declare:

{
  "type": "Bundle",
  "interaction": [
    { "code": "read" },
    { "code": "search-type" }
  ],
  "searchParam": [
    { "name": "type",      "type": "token",     "documentation": "Filter by overview type (overview category)" },
    { "name": "patient",   "type": "reference",  "documentation": "Required for patient-scoped search" },
    { "name": "date",      "type": "date" }
  ]
}

If on-demand generation via $document is supported:

{
  "type": "Composition",
  "operation": [
    {
      "name": "document",
      "definition": "http://hl7.org/fhir/OperationDefinition/Composition-document"
    }
  ]
}

Relationship to PHARM-12

Security Considerations

• All exchanges SHALL use TLS (HTTPS).
• The Consumer SHALL present an IUA access token.
• The Responder SHALL enforce patient-level access control and verify the overview subject matches the authorized patient scope.
• Both actors SHALL record ATNA PHI-access audit events.
• Overviews marked as confidential in Composition.confidentiality SHALL be subject to additional access control enforcement.

Open Issues