Specialty Medication Enrollment
0.1.0 - STU1 Ballot

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

## Information Flows Requiring Human Interaction

Pharmacies and other stakeholders (referred to as “requester” below) sometimes need information that isn’t available through systematic querying of the prescriber’s EHR (using the RESTful searches or Specialty Rx Query messages as described in the Systematic Query Workflows section).

For example, the requester may need to:

- ask the clinic to clarify the prescription’s dosing instructions
- ask whether the clinic intends to order a lab test that must be performed prior to the patient starting the medication
- ask the clinic to provide a copy of a consent form that the patient completed by hand.

This implementation guide describes a method to support these situations by enabling the prescriber or staff to provide information through a SMART application launched from the EHR–prompted by a request from the pharmacy or other requester.

### SMART Application Launch Using the Task Workflow

A requester may host a SMART application that the prescriber or staff can launch from the EHR to view and respond to questions. Below is a scenario illustrating this approach for (a) communicating the need for information to the EHR and (b) enabling an EHR user to launch the application and complete the task.

- While working the prescription, staff at the requester organization captures the questions they need to be answered by the prescriber clinic.
- The requester’s application (Requesting System) associates this set of questions with an identifier that will be used to pull the questions up when clinic staff launches the SMART app from the EHR.
- The Requesting System POSTs a Task resource to the prescriber’s EHR, asking it to create a staff work queue item to launch the requester’s app and answer the questions. Included in the Task are elements that associate the request with the related prescription as well as fields containing the URL of the SMART app and the identifier needed to present the correct questions.
- The EHR places an item based on the Task in a user work queue, and sets the Task status to `ready`. The EHR returns a `201 CREATED` response
- When the clinic user takes action on the work queue item, the EHR…
  - launches the requester’s SMART App
  - sets a session launch context using the Patient ID it received in the `.for` element of the Task resource
  - includes the `Task.identifier` value in the `appContext` launch parameter… which the SMART app uses to pull up the right patient/medication questions
  - sets the Task `status` to `in-progress`
- During this period, the Requesting System may poll the Task’s `status` to monitor its progress. E.g., `GET [base]/Task/1135804`
- Once the questions have been completed in the SMART app, the Requesting System updates the Task’s status to `completed`. The EHR updates the status and returns a `200 OK` response
- The Requesting System may also alert staff at the requester organization and/or further process the information from the SMART app at this time. (This guide does not provide direction on how to accomplish this step)

### Process flow: Task to SMART Launch

Note: If an event occurs within the Data Source system that prevents the Task from being performed, it SHOULD indicate that the request will not completed by updating Task.status to `failed` and, optionally, indicating why in `Task.statusReason`.

### Task Content

The Task resource contains the following information needed to reference related information in the EHR and launch the SMART application:

- `Task.identifier` - This is a unique identifier representing the context of this task within the SMART application (e.g., the specific set of questions that need to be answered). It is to be conveyed during launch of the referenced SMART application in the `appContext` parameter and used by that application to direct the user to information and functions necessary to complete this task

- `Task.code` - A code that characterizes the requested user action
  - Value: `complete-app-questionnaire` (`display`: “Complete Questionnaire in SMART App”)
- `Task.description` - Human-readable description of the task to be performed by the user. This description SHALL include the user-recognizable name of the SMART application to launch to perform the task, and SHALL state the action to be performed in the app once it’s been launched.
  - Example: “Launch the My Pharmacy SMART App and complete the questionnaire.”

- `Task.for` - A reference to the patient

- `Task.requester` - The organization submitting the Task

- `Task.owner` - The prescriber

- `Task.reasonReference` - The prescription to which the task pertains. A human-readable description is included in `Task.display`, and specific identification is conveyed through either…
  - `Task.reasonReference.reference` - A reference to a MedicationRequest resource, or
  - `Task.reasonReference.identifier` - The prescription identifier set by the prescribing system. (Referred to as the Placer Order Number in HL7 v2 and Prescriber Order Number in NCPDP SCRIPT)
- `Task.input` - The location of the SMART app to be launched. `Task.input.type` contains the code, `smart-app-launch` and `Task.input.valueUrl` contains the actual endpoint URL to launch the SMART app.

See this example of a populated Task.

### Populating the SMART Launch appContext

The `appContext` parameter is sent to the SMART app as part of the OAuth 2.0 access token response, alongside other SMART launch parameters when the SMART app is launched. The `appContext` contains the value received in the `Task.identifier` value.

Example:

    "appContext": "05d06540dd00d"

SMART App Launch Implementation Guide

### Hosting of SMART Applications

A requester may potentially partner with an intermediary or other party to host the SMART application and perform the above process on its behalf.