Specialty Medication Enrollment
2.1.0 - CI Build

Specialty Medication Enrollment, published by HL7 International - Pharmacy. This is not an authorized publication; it is the continuous build for version 2.1.0). This version is based on the current content of https://github.com/HL7/fhir-specialty-rx/ and changes regularly. See the Directory of published versions

## Search Conventions

### US Core Search Guidance

Data Source and Data Consumer systems SHALL follow US Core search requirements and guidance when performing searches associated with this guide.

### 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 searches on the resources below–whether responding to RESTful search requests or the Specialty Rx Query message.

Notes:

- Examples in the tables below reflect searches submitted using REST GET and POST interactions. However, when specifying searches in the Specialty Rx Query message, the URL base and patient parameter are omitted (see below)
- Submitting searches using HTTP GET and POST is described here in the FHIR specification

Resource | Parameters | Example
--- | --- | ---
AllergyIntolerance | Per US Core |
    GET [base]/AllergyIntolerance?patient=123&clinical-status=active
or
    POST [base]/AllergyIntolerance/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123&clinical-status=active
Returns all active patient allergies and intolerances
Condition | Per US Core |
    GET [base]/Condition?patient=123
or
    POST [base]/Condition/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123
Returns all patient conditions
Observation | Per US Core |
    GET [base]/Observation?patient=123&category=vital-signs&date=ge2020-01-01
or
    POST [base]/Observation/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123&category=vital-signs&date=ge2020-01-01
Returns all patient vital signs recorded in the specified date period
Coverage | SHALL: patient SHOULD: beneficiary (Not profiled in US Core) |
    GET [base]/Coverage?patient=123
or
    POST [base]/Coverage/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123
Returns all patient insurance coverages
MedicationRequest | Per US Core |
    GET [base]/MedicationRequest?patient=123&intent=order&status=active&_include=MedicationRequest:Medication
or
    POST [base]/MedicationRequest/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123&intent=order&status=active&_include=MedicationRequest:Medication
Returns all active patient MedicationRequest orders and the associated Medications

### Recommended Searches

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 | See US Core |
    GET [base]/DocumentReference?patient=123 &category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
or
    POST [base]/DocumentReference/_search
    Content-Type: application/x-www-form-urlencoded:
    patient=123&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Returns all patient clinical notes

### Optional Searches

Data Consumers 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 Data Source does not support the submitted search or search parameter.

### Returning related resources within search results

Data Sources SHALL be capable of supporting the `_revinclude=Provenance:target` parameter as defined in US Core, returning US Core Provenance resource(s) that reference returned resources, as specified here in US Core. In addition, Data Sources SHALL support mandatory `_include` parameters defined in US Core.

Each related resource SHALL be included as an entry in the response’s searchset bundle with a `search.mode` value of `include`. Below are examples:

- `_include` : MedicationRequest referencing an included Medication resource
- `_revinclude` : AllergyIntolerance with an included Provenance resource

### Further search guidance

This guide leverages search guidance given in the US Core FHIR Implementation Guide and the base FHIR specification.

- US Core Search syntax

- FHIR Search guidance

### 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 Data Consumer systems to submit requests without performing a patient match ahead of time. This accommodates a common situation where the Data Consumer hasn’t participated in previous FHIR exchanges about this patient with the Data Source and doesn’t possess the Data Source’s Patient resource ID. This also addresses challenges that may arise if the Data Consumer interacts with the Data Source via an intermediary–for example if the Data Consumer lacks details about the Data Source’s endpoint or is otherwise unable to submit patient match requests directly to the Data Source.

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

For example, a search for a given patient’s vital signs 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 Data Consumer 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 Data Consumer system (mandatory)
- a Patient resource from the Data Source system (if available)

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

- If the request includes only the Data Consumer’s Patient, the Data Source 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 Data Consumer’s Patient and Data Source’s Patient, the Data Source 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 Data Source 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.