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 HSPC 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 HSPC The Logica Sandbox Manager uses the following flow to launch an app:

...

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 HSPC 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 HSPC the Logica Reference API (FHIR) server that launches the CDS Hooks sandbox.  In this flow, the example SMART app should be registered with the HSPC the Logica Sandbox instance prior to attempting to launch the app from the CDS Hooks sandbox.  

...

• SMART on FHIR launch: see http://docs.smarthealthit.org/authorization/
• HSPC Reference Logica Reference API: see Logica Reference API
• HSPC Reference Logica Reference Auth: see Logica Reference Auth
• HSPC Sandbox 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.

...

• The launching system has obtained an access token to the HSPC the Logica Reference API server
• The downstream SMART on FHIR app has been registered with the HSPC the Logica Sandbox Manager (and HSPC 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 HSPC the Logica Sandbox:

{"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.

• 
  

  Code Block
  title Minimum Launch Context
  {"parameters":{}}

  
  

Step 2: Registering the launch context

The launch context is registered with the HSPC 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 HSPC 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.

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 HSPC the Logica Reference API server and the HSPC the Logica Reference Auth server.  This synchronization allows both servers to check the launch context for various APIs.  For example, the HSPC the Logica Reference Auth server can determine if a patient context has been established when issueing a patient-scope access token, and the HSPC 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

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

...