SMART Web Messaging Implementation Guide: STU1
0.1.0 - Build CI

SMART Web Messaging Implementation Guide: STU1, published by HL7 FHIR Infrastructure. This is not an authorized publication; it is the continuous build for version 0.1.0). This version is based on the current content of https://github.com/HL7/smart-web-messaging/ and changes regularly. See the Directory of published versions

Home

SMART Web Messaging enables tight UI integration between EHRs and embedded SMART apps via HTML5’s Web Messaging. SMART Web Messaging allows applications to push unsigned orders, note snippets, risk scores, or UI suggestions directly to the clinician’s EHR session. Built on the browser’s javascript window.postMessage function, SMART Web Messaging is a simple, native API for health apps embedded within the user’s workflow.

Why

Clinical workflow systems (such as EHRs) may be able to launch SMART applications in a few different ways: automatically at specific points in the workflow, by user interaction in the UI, or in response to a suggestion from a CDS Hooks Service (or other decision support service). Once launched, web applications are often embedded within an iframe of the main UI. In this model, the new application appears in close proximity to a patient’s chart and can work with the EHR via RESTful FHIR API. These RESTful APIs are great for CRUD operations on a logical FHIR Server endpoint, but they don’t enable tight workflow integration or access to draft FHIR resources that may only exist in memory on the EHR client.

For these embedded apps, there are some key use cases that SMART and CDS Hooks don’t address today:

  • Communicating a decision made by the clinician within the SMART app, such as:
    • placing an order
    • annotating a procedure with an appropriateness score or a radiation count
    • transmitting a textual note snippet
    • suggesting a diagnosis or a condition to the patient’s chart
  • Interrogating the orders scratchpad / shopping cart, currently only known within the ordering provider’s CPOE session.
  • Allowing an app to communicate UX-relevant results back to the EHR, for example, automatic navigation to a native EHR activity, or sending an “I’m done” signal.

Additionally, SMART Web Messaging enables other interesting capabilities. For example:

  • Saving app-specific session or state identifiers to the EHR for later retrieval (continuing sessions).
  • Interacting with the EHR’s FHIR server through this messaging channel (enabling applications that cannot access the FHIR server directly, e.g. those hosted on the internet).

How

SMART Web Messaging builds on HTML5’s Web Messaging specification, which allows web pages to communicate across domains. In JavaScript, calls to window.postMessage pass MessageEvent objects between windows.

The following sequence diagram outlines several of the key events that take place leading up to a successful app invocation of an EHR launched activity via SMART Web Messaging messages. For simplicity, the full details of the SMART App Launch sequence are abbreviated and the only details shown are the fields needed for conformant SMART Web Messaging.

entryspacing%200.5%0Aparticipantgroup%20%23lightblue%20%2B%2B**EHR%20Browser%20Interface**%5Cnhttps%3A%2F%2Fehr.example.org%2B%2B%0A%0Aparticipantspacing%205%0Aparticipant%20%22%2B%2Behr.window%2B%2B%22%20as%20ehr.window%0Alifelinestyle%20ehr.window%20%3A%3Asolid%0A%0Aparticipantgroup%20%23lightgreen%20%2B%2B**embedded%20iframe**%2B%2B%0A%20participant%20%22%2B%2Bapp.window%2B%2B%22%20as%20app.window%0A%20end%0A%20lifelinestyle%20app.window%20%3A%3Asolid%0Aend%0A%0Aparticipantgroup%20%23pink%20%2B%2B**EHR%20Auth%20Server**%2B%2B%0Aparticipant%20%22%2B%2Bauthorize.html%2B%2B%22%20as%20authorize.html%0Alifelinestyle%20%3A%3Asolid%0Aend%0A%0A%0Aparallel%0Agroup%20%23orange%20SMART%20Launch%0Aauthorize.html%3C-%3Eapp.window%3A%20%0Aparallel%20off%0A%0A%0Afontfamily%20monospace%0Abox%20over%20app.window%20%23lightyellow%3A%20%2B%2BlaunchClientData%20%3D%20%7B%5Cn%20%20%22smart_web_messaging_handle%22%3A%20**%22RXhhbXBsZSBoYW5kbGUK%22**%2C%5Cn%20%20%22smart_web_messaging_origin%22%3A%20**%22https%3A%2F%2Fehr.example.org%22**%2C%5Cn...%5Cn%7D%2B%2B%0Aend%0A%0Aspace%201%0Aehr.window%3C-app.window%3A%20%2B%2BpostMessage(message%2C%20**%22https%3A%2F%2Fehr.example.org%22**)%2B%2B%20%20%20%20%0Abox%20over%20app.window%20%23lightyellow%3A%20%2B%2Bmessage%20%3D%20%7B%5Cn%20%20%22messageId%22%3A%20**%22248cd0b0-5167-4824-babc-f250e5296527%22**%2C%5Cn%20%20%22messagingHandle%22%3A%20**%22RXhhbXBsZSBoYW5kbGUK%22**%2C%5Cn%20%20%22messageType%22%3A%20%22ui.launchActivity%22%2C%5Cn%20%20%22payload%22%3A%20%7B...%7D%5Cn%7D%2B%2B%0A%0Aspace%201%0Aapp.window%3C-ehr.window%3A%20%2B%2BpostMessage(response%2C%20%22https%3A%2F%2Fapp%2Fafter-auth%22)%2B%2B%0Afontfamily%20monospace%0Abox%20over%20ehr.window%20%23lightyellow%3A%20%2B%2Bresponse%20%3D%20%7B%5Cn%20%20%22messageID%22%3A%20%229befe172-f5b2-408b-a993-939690f5388b%22%2C%5Cn%20%20%22responseToMessageId%22%3A%20**%22248cd0b0-5167-4824-babc-f250e5296527%22**%2C%5Cn%20%20%22payload%22%3A%20%7B...%7D%5Cn%7D%2B%2B%0Afontfamily%20arialEHR Browser Interfacehttps://ehr.example.orgembedded iframeEHR Auth Serverehr.windowapp.windowauthorize.htmllaunchClientData = {  "smart_web_messaging_handle": "RXhhbXBsZSBoYW5kbGUK",  "smart_web_messaging_origin": "https://ehr.example.org",...}postMessage(message, "https://ehr.example.org")    message = {  "messageId": "248cd0b0-5167-4824-babc-f250e5296527",  "messagingHandle": "RXhhbXBsZSBoYW5kbGUK",  "messageType": "ui.launchActivity",  "payload": {...}}postMessage(response, "https://app/after-auth")response = {  "messageID": "9befe172-f5b2-408b-a993-939690f5388b",  "responseToMessageId": "248cd0b0-5167-4824-babc-f250e5296527",  "payload": {...}}SMART Launch

Refer to the SMART Web Messaging technical documentation page for details on the specification.

Underlying Standards

SMART Web Messaging is designed for compatibility with FHIR R4 and above.