Specialty Medication Enrollment
0.1.0 - STU1 Ballot

This page is part of the Specialty Medication Enrollment (v0.1.0: STU1 Ballot 1) based on FHIR R4. . For a full list of available versions, see the Directory of published versions

Search Conventions

Required Searches

To ensure that the most common data requests are supported by all participants, Data Sources SHALL be able to return information in response to the following search strings–whether responding to RESTful search requests or the Specialty Rx Query message. The required search parameters match those required for each resource by the US Core.

Note: When specifying searches in the Specialty Rx Query message, the patient parameter is omitted (see below)

Resource Parameters Example
Condition category
clinical-status
onset-date
code
patient		 
Condition?patient=123
Returns all patient conditions
AllergyIntolerance clinical-status
patient		 
AllergyIntolerance?patient=123&clinical-status=active
Returns all active patient allergies and intolerances
Observation status
category
code
date
patient		 
Observation?patient=123&category=vital-signs&date=ge2020-01-01
Returns all patient vital signs recorded in the specified date period
Coverage patient 
Coverage?patient=123
Returns all patient insurance coverages
MedicationRequest status
intent
encounter
authoredon
patient
_include		 
MedicationRequest?patient=123&status=active&_include=MedicationRequest:Medication
Returns all active patient MedicationRequests and the associated Medications

In addition to the required searches above, implementers SHOULD support DocumentReference searches and retrieval, to enable those participating in the fulfillment of specialty medication prescriptions to access patient information recorded in patient documents.

Resource Parameters Example
DocumentReference category
date
type
patient
_id		 
DocumentReference?patient=123 &category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Returns all patient clinical notes

Optional Searches

Requesters MAY include searches other than those outlined above.

  • Data Source Systems SHALL return a search-result for each–even if the search is not supported–which SHALL include an OperationOutcome indicating when the responder does not support the submitted search or search parameter.

Further search guidance

US Core

This guide leverages search guidance given in the US Core FHIR Implementation Guide. Below are particular sections in that IG that detail certain search aspects:

Base FHIR

Search conventions in the Specialty Rx Query Message

The Specialty Rx Query message requests specific information from a given patient’s records in the responding system. The desired information is specified as FHIR search statements which are sent as parameters in the message. Responders are expected to execute these searches for the patient supplied in the request and return the results in a Specialty Rx Query Response message.

Specifying a query string

Specialty Rx messaging enables requesters to submit requests without performing a patient match ahead of time. This accommodates a common situation where the requester hasn’t participated in previous FHIR exchanges about this patient with the responder and doesn’t possess the responder’s Patient resource ID. This also addresses challenges that may arise if the requester interacts with the responder via an intermediary–for example if the requester lacks details about the responder’s endpoint or is otherwise unable to submit patient match requests directly to the responder.

To support this scenario, the Specialty Rx Query message omits the patient parameter from submitted search strings, with the expectation that the responder will append it after locating the desired patient in its system.

For example, a search for a given patient’s vital signs that that would ordinarily be stated as:

Observation?patient=[patient id]&category=vital-signs

… is submitted in the Specialty Rx Query without the patient search parameter:

Observation?category=vital-signs

Identifying the desired patient

The requester identifies the desired patient by including one or both the following in the Specialty Rx Query message:

  • a Patient resource representing the patient in the requester’s system (mandatory)
  • a Patient resource from the responder’s system (if available)

The responder locates the desired patient and completes the query string as follows, based on the submitted patient information:

  • If the request includes only the requester’s Patient, the responder performs a matching process and locates the associated patient in its own system. It appends its Patient ID to each submitted search string.
  • If the request includes both the requester’s Patient and responder’s Patient, the responder confirms the match and then appends its Patient ID to each submitted search string.

Returning the executed search string in the response message

In the Specialty Rx Query Response, the responder returns the full search string that was ultimately executed–including patient parameter–in the .link element of each returned searchset Bundle.

Bundle
    .link
        .relation = "self"
        .url = "MedicationRequest?patient=12345&status=active"
    .entry

Patient references within search results

All searches performed within a request/response exchange flow relate to a single patient, who is represented in the responder-patient parameter in the Query Response message bundle. Patient references contained in resources in searchset bundles SHOULD be resolvable to the responder-patient entry in the outer, Query Response message bundle.