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-12 Query Medication Resources

PHARM-12: Query Medication Resources

Scope

The Query Medication Resources transaction [PHARM-12] allows a Medication Overview Consumer to search a Medication Overview Responder for the FHIR resources constituting a patient's medication overview.

The response is a FHIR searchset Bundle. The Responder SHALL return medication resources matching the query parameters. The exact set of resource types returned depends on the query — the Consumer may ask for:

• Treatment lines only — MedicationTreatmentLine (MedicationStatement) resources, which are the clinician-determined treatment lines; the mandatory content of any medication overview.
• Patient-reported statements — MedicationStatement resources representing self-reported usage that are not (yet) reconciled into a treatment line.
• Both — when the Consumer wants the full picture including both treatment lines and patient-reported data.
• Related workflow resources — MedicationRequest, MedicationDispense, MedicationAdministration linked to the above, via _include/_revinclude.
• A named List — via _list, to retrieve a pre-defined or server-maintained list of resources (e.g. a patient's active medication list, a discharge list).

This transaction is appropriate for live, current-state queries — displaying a patient's active medication list, feeding clinical decision support, or synchronising medication data between systems.

For pre-assembled overviews, see PHARM-11.

Actors and Roles

Referenced Standards

• HL7 FHIR R5 — RESTful search interactions (search-type), List resource, _list search parameter
• IHE ITI Appendix Z — FHIR Common Implementation Material (patient identity, error handling)
• IHE ITI IUA — Authorization token (grouping requirement)
• IHE ITI ATNA — Audit trail (grouping requirement)

Interaction Diagram

​

Request Message

HTTP Verb and Endpoint

Primary resource query:

GET [base]/MedicationStatement?[parameters]

List-based query (retrieve a named or server-defined medication list):

GET [base]/MedicationStatement?_list=[list-id]&[parameters]
GET [base]/List?patient=[ref]&code=[list-type-code]

Required Query Parameters

Filter Parameters

Statement Type Parameter

A key distinction in MEOW is between two kinds of MedicationStatement:

The Consumer uses the category parameter to select which type to retrieve:

// Treatment lines only
GET [base]/MedicationStatement?patient=Patient/123&category=treatment-line

// Patient-reported statements only
GET [base]/MedicationStatement?patient=Patient/123&category=patient-reported

// Both (full picture)
GET [base]/MedicationStatement?patient=Patient/123

Open issue: The code values for the category slice that distinguishes treatment lines from patient-reported statements need to be defined in a ValueSet. This is related to issue #42.

List-Based Queries

The Consumer MAY use the _list parameter or query the List resource directly to retrieve a named, server-defined medication list rather than performing an open search.

This supports scenarios where the Responder maintains named lists such as:

• The patient's current active medication list
• The discharge medication list from a specific encounter
• A reconciled medication list produced at a specific date

// Retrieve resources belonging to a known List
GET [base]/MedicationStatement?patient=Patient/123&_list=List/456

// Find available medication lists for a patient
GET [base]/List?patient=Patient/123&code=http://loinc.org|10160-0

// Retrieve all resources in a List by expanding it
GET [base]/List/456?_include=List:item

The Responder MAY maintain lists automatically (e.g. a continuously updated "active medication list" per patient) or MAY require the Consumer to discover list identifiers via a prior List search.

Include Parameters (Related Resources)

The Responder SHALL support the includes it declares in its CapabilityStatement. Unsupported includes SHALL NOT cause an error — the Responder returns base resources and MAY include an OperationOutcome noting the unsupported parameter.

Example Requests

All active treatment lines:

GET [base]/MedicationStatement?patient=Patient/123&category=treatment-line&status=active

Treatment lines with their prescriptions and dispenses:

GET [base]/MedicationStatement?patient=Patient/123&category=treatment-line
    &_include=MedicationStatement:basedOn
    &_revinclude=MedicationDispense:prescription

Full picture — treatment lines and patient-reported statements, with grouping:

GET [base]/MedicationStatement?patient=Patient/123
    &_include=MedicationStatement:partOf
    &_include=MedicationStatement:medication

All resources in a named active medication list:

GET [base]/MedicationStatement?patient=Patient/123&_list=List/active-meds-123
    &_include=MedicationStatement:basedOn

Using a national patient identifier:

GET [base]/MedicationStatement
    ?patient.identifier=urn:oid:2.16.840.1.113883.2.51.1|A123456789
    &category=treatment-line&status=active

Response Message

Success — 200 OK

A Bundle of type searchset is returned.

• Bundle.total reflects the count of matching MedicationStatement resources (not includes).
• MedicationTreatmentLine resources SHALL conform to MedicationTreatmentLine.
• Included CarePlan resources SHALL conform to MedicationTreatment.
• Included Medication resources SHALL conform to IHEMedication.
• Included MedicationRequest, MedicationDispense, MedicationAdministration MAY conform to profiles from IHE PHARM MPD where applicable.

No Results — 200 OK

An empty Bundle (total = 0). The Responder SHALL NOT return 404 when there are simply no matching resources for a valid patient.

Errors

All error responses SHALL include an OperationOutcome.

Expected Actions

Medication Overview Responder

• SHALL reject requests missing the patient parameter with 400 Bad Request.
• SHALL return MedicationStatement resources matching the query parameters for the identified patient.
• SHALL support the category parameter to distinguish treatment lines from patient-reported statements.
• SHOULD support _list parameter to allow retrieval of named medication lists.
• SHALL perform patient identity resolution per IHE ITI Appendix Z.
• SHALL honour _include and _revinclude parameters declared in its CapabilityStatement.
• SHALL record an ATNA PHI-query audit event per transaction.
• SHALL NOT return resources belonging to patients other than the one specified.

Medication Overview Consumer

• SHALL include the patient parameter on every request.
• SHALL be capable of processing a mixed-type searchset Bundle.
• SHALL handle an empty result set without treating it as an error.
• SHALL handle OperationOutcome entries in the response appropriately.
• SHALL present an IUA authorization token when accessing a protected endpoint.

CapabilityStatement Requirements

The Medication Overview Responder actor SHALL declare the following in its CapabilityStatement:

{
  "type": "MedicationStatement",
  "interaction": [
    { "code": "search-type" },
    { "code": "read" }
  ],
  "searchParam": [
    { "name": "patient",      "type": "reference", "documentation": "Required" },
    { "name": "status",       "type": "token" },
    { "name": "effective",    "type": "date" },
    { "name": "category",     "type": "token", "documentation": "Used to distinguish treatment lines from patient-reported statements" },
    { "name": "_list",        "type": "special", "documentation": "Retrieve resources belonging to a named List" }
  ],
  "searchInclude": [
    "MedicationStatement:medication",
    "MedicationStatement:basedOn",
    "MedicationStatement:partOf"
  ],
  "searchRevInclude": [
    "MedicationDispense:prescription",
    "MedicationAdministration:request"
  ]
}

If List-based queries are supported:

{
  "type": "List",
  "interaction": [
    { "code": "search-type" },
    { "code": "read" }
  ],
  "searchParam": [
    { "name": "patient", "type": "reference" },
    { "name": "code",    "type": "token" }
  ]
}

Security Considerations

• All exchanges SHALL use TLS (HTTPS).
• The Consumer SHALL present an IUA access token scoped to the patient being queried.
• The Responder SHALL enforce patient-level access control.
• Both actors SHALL record ATNA PHI-query audit events per transaction.

Open Issues