What is a launch context?

A launch context is defined as part of the SMART on FHIR Authorization Specification. The launch context represents the state of the EHR at the time the SMART on FHIR application was launched from the EHR. During the embedded launch flow, the launch context is communicated from the EHR to the App using the "launch" parameter.

How does the Logica Sandbox Manager use the launch context?

The Logica Sandbox Manager system simulates an EHR system by allowing a user to create a sandbox instance with a FHIR server, register SMART on FHIR applications, and then launch those SMART on FHIR applications within their sandbox using their FHIR server. The Logica Sandbox Manager uses the following flow to launch an app:

How can an external system launch register a launch context?

If an external system has an access token to the Reference API server (received as part of the SMART on FHIR launch flow), the external system can also follow a similar process as the Logica Sandbox Manager uses to launch an app. The following flow is a simplified variant of the launch registration process, using the CDS Hooks sandbox as an example external system. The ISS Server is the a tenant on the Logica Reference API (FHIR) server that launches the CDS Hooks sandbox. In this flow, the example SMART app should be registered with the Logica Sandbox instance prior to attempting to launch the app from the CDS Hooks sandbox.

Protocol Details

Definitions

SMART on FHIR launch: see http://docs.smarthealthit.org/authorization/
Logica Reference API: see Logica Reference API
Logica Reference Auth: see Logica Reference Auth
Logica Sandbox Manager: see FHIR Sandbox Manager
launching system: A system that issues a SMART on FHIR launch request to a SMART on FHIR app, typically an EHR or EHR simulator.

Preconditions:

The launching system has obtained an access token to the Logica Reference API server
The downstream SMART on FHIR app has been registered with the Logica Sandbox Manager (and Logica Reference Auth server)

Step 1: Build the launch context

The launching system begins the process of registering a launch context by assembling the appropriate context values. Context values could include the patient that has been selected, the user of the system, the location. Here is a sample launch context from the Logica Sandbox:

Launch Context

{"client_id":"bilirubin_chart","parameters":{"patient":"BILIBABY","need_patient_banner":false}}

Note, at this time, client_id is not required. Only 'parameters' is required, and at minimum, an empty object.
Minimum Launch Context
```
{"parameters":{}}
```

Step 2: Registering the launch context

The launch context is registered with the Logica Reference API server by sending an HTTP POST to the /_services/smart/Launch endpoint. The request must contain an access token for the Logica Reference API server. The launching system should obtain this token as part of the preconditions, for example, through a SMART on FHIR launch flow.

Registering launch context

HTTP POST
Authorization:Bearer ...
Payload: {"client_id":"bilirubin_chart","parameters":{"patient":"BILIBABY","need_patient_banner":false}}

Step 3: Launch context is synchronized

The launch context is enriched with a launch_id that is the key to the launch context given to the downstream app. The launch context must be synchronized between the Logica Reference API server and the Logica Reference Auth server. This synchronization allows both servers to check the launch context for various APIs. For example, the Logica Reference Auth server can determine if a patient context has been established when issueing a patient-scope access token, and the Logica Reference API server can remove results from a query that are not for the patient in context.

Step 4: Launch context is returned

HTTP Response Body

{"launch_id":"GNpcsR","created_at":"Mon Nov 06 23:31:53 UTC 2017","created_by":"...","parameters":{"patient":"BILIBABY","need_patient_banner":false},"username":"none"}