Specialty Medication Enrollment
0.1.0 - STU1 Ballot

Publication Build: This will be filled in by the publication tooling

## 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

### 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 | 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:

- Search syntax
- AllergyIntolerance search parameters
- Condition search parameters
- DocumentReference search parameters
- Lab Observation search parameters
- MedicationRequest search parameters

#### Base FHIR

- FHIR Search

### 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.