SMART®

General

Introduction

The SMART® (Substitutable Medical Apps and Reusable Technology) platform defines a specification for an electronic health record (EHR) to safely and securely open other applications with context. These SMART applications are commonly web applications but may also be native mobile applications and that use HL7® FHIR® standard to read and write data from the EHR. With SMART, Cerner can embed a SMART app in the EHR. Cerner believes that SMART applications will be a major user of FHIR resources. We will also support FHIR access through mobile SMART applications, as those specifications emerge from the SMART web site.

SaaS Model

Cerner expects the majority of SMART apps to be provided to clients in a SaaS (software as a service) model. That is, the SMART app is hosted or managed by the SMART developer or provider. In this case, clients do not need to install any code or package in order to implement a particular SMART app.

Authorization Model

At a high level, provider facing applications must receive the following authorizations:

  1. Cerner must validate and register every SMART app. As part of this process, Cerner validates the usage of FHIR resources and operations (for example, READ and WRITE). Cerner will not validate the usage of FHIR resources for direct to consumer apps.
  2. Each client decides whether they want to allow a SMART app to run on a domain-by-domain basis.
  3. Each client decides which users and roles can access the SMART app.

To learn more about general SMART on FHIR app authorization process, see the SMART App Authorization Guide. For implementation information regarding Cerner’s Authorization server, see the Authorization page at fhir.cerner.com.

Access Points

Currently, end users can open SMART apps in the following ways:

Cerner is continuing to look at incorporating SMART app support into our other applications and platforms.

SMART App Data Retrieval

SMART apps can leverage Cerner’s implementation of the FHIR standard server to retrieve data from the EHR based upon the current patient in context. However, SMART apps are not limited to FHIR data for their needs. SMART apps may choose to leverage other data sources for their needs, from other third party data sources to private and proprietary data the SMART app maintains. SMART apps may even retrieve data through Cerner proprietary means (for example, MillenniumObjects, CareAware services, or CCL scripts). Of course, leveraging proprietary APIs hampers interoperability, but if that is not a concern of the SMART app, it is a viable option.

SMART Without FHIR

Technically speaking, the SMART specification requires that a FHIR server exist so that a SMART app can communicate with the FHIR server when the app opens in order to determine the location of the authorization (OAuth 2) server. However, outside of this requirement, FHIR does not need to be leveraged otherwise by the SMART app.

At a minimum, a SMART app that does not require FHIR must include at least one of the following scopes in its access token requests:

Well-Known SMART Configuration

It is also possible to view SMART authorization endpoints and launch capabilities using a Well-Known Uniform Resource Identifier.

See Cerner’s Well-Known SMART Configuration for more information.

Technical

Terra UI

Some of the things that we take into consideration when validating your SMART app are user interface (UI) and user experience (UX). They are an important part of the overall user’s experience.

If you are building your SMART app using the React JavaScript library, we highly recommend that you take a look at the Terra UI framework that we’ve created and open sourced. Terra follows Cerner’s Design Standard Guidelines so your app will look and feel like a Cerner app.

Screen Resolution

The recommended screen resolution varies based on the available screen’s real estate. Instead of targeting a specific resolution, the app should be designed to be responsive, and the app should adjust according to the available screen sizes.

Loading indicator

For a better user experience we encourage the use of a loading overlay or a status indicator of progress inside your SMART apps.

The loading overlay we recommend for SMART apps is the one found among the Terra UI components. You might want to use this one if you’re building your SMART app with React and have not yet decided on a loading indicator style.

Browser Requirement

For provider-facing apps running from within the Cerner Millennium EHR, the only embedded browsers we currently support are Internet Explorer (IE) and Edge. The embedded browser controls we use are IWebBrowser2 C++ interface for IE and WebView2 for Edge both developed by Microsoft. The minimum version of IE we support is IE10. The latest supported browser varies based on the version of the browser that is currently installed at each Cerner client site. Although it is no longer supported by Microsoft, many of our clients still use IE10, especially clients who host their own system. We highly suggest that you code your app for IE10 for validation. If you must use IE11 or Edge for your app, please note that you may struggle if you plan on deploying across our entire client base.

NOTE: Applications that will embed in MPages Workflow or Summary must function correctly with IE10. The MPages 6.x platform currently depends on other components that require IE10 to run. This means that even though there is a newer version of IE in Citrix, MPages 6.x will render the application using IE10. Even though we have support for Edge some clients may still be using IE due to delayed upgrades, or app compatibility issues. Therefore, it is recommended that the embedded SMART app uses functions that work correctly for both IE and Edge at this time.

Microsoft offers a free IE10 VM and newer on various versions of Windows for application testing at https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/.

Single Sign On (SSO)

Cerner understands that it’s counter-intuitive to prompt the user for their credential when launching a SMART application within PowerChart, where the user is already logged into the system. With that in mind, we designed the system to provide a good SSO experience for the users when any SMART application is launched within PowerChart. As a developer, you can help us give the users the best experience possible by following the following guideline when developing your apps to be embedded within PowerChart.

Embedded Browser Control

There have been a lot of questions and interest around what embedded browser control Cerner’s implementation uses. In this section, you’ll learn more about the embedded browser control. The actual browser controls that we use are IWebBrowser2 C++ interface for IE and WebView2 for Edge both developed by Microsoft. Please take a look at the documentation for more information. With this embedded browser control, there are some limitations compared to the stand-alone IE or Edge. See below for these limitations.

No Shared Cookies

If your app uses a pop-up window for the authorization flow to allow users to authenticate with the system, that is fine for web and stand-alone apps. However, if the app is going to be embedded within PowerChart, browser cookies will NOT be shared between the embedded browser and the newly popped-up browser window. What does this mean? It means that single-sign-on (SSO) will not work; the user would need to manually type in their credential when prompted, which is not the best experience for the users. It’s best to perform all navigations and redirects using the embedded browser without needing to pop-up a new browser while embedding in PowerChart. To learn more about the technical details of IE inner workings, please visit this page and this page.

If you’d like to flex your app based on the current execution context (embedded vs stand-alone mode), please see this section for more information.

HTML5 Session Storage

With the introduction of HTML5, sessionStorage is a good way to persist data within a browser’s session. Depending on the Cerner Millennium PowerChart release, sessionStorage may not be isolated per instances of the embedded browser. As such, if your app is going to be embedded within PowerChart, we do NOT recommend using sessionStorage.

If you’d like to flex your app based on the current execution context (embedded vs stand-alone mode), please see this section for more information.

Embedded in PowerChart?

If I want to flex my app based on where it’s being loaded, how do I programmatically determine when my app is embedded within PowerChart? Good question! Check out this method which checks for certain conditions to exist and determine if the app is loaded within PowerChart or not.

HTML5 DOCTYPE

The doctype declaration tells the browser what version of HTML the document is written in. It is a good idea to include this declaration so that the browser will render the document correctly. It must be included at the very first line of the document, right above the <html> tag.

<!DOCTYPE html>

X-UA-Compatible Tag

In order for the embedded IE browser to render the app in the latest supported IE version, set the following HTML tag in the first line of the <head> section for all pages:

<meta http-equiv="X-UA-Compatible" content="IE=edge">

If this tag is not present as the first <head> element on a page, the page and all associated JavaScript will be rendered in IE 7 mode, often times resulting in errors and unwanted behavior.

Technology and Framework for SMART Apps

What technology and framework you use is really up to you and your company. Regardless of which technology, framework, or language you choose, make sure that your app is fast, responsive, and adaptable to various screen sizes.

Open Source FHIR Client Libraries

To start development quickly, there is an open source fhir-client JavaScript library that takes care of the OAuth2 handshake and provides a built-in library to call FHIR resources. The library is usable but has several known issues in previous versions. One particular issue is around the usage of the sessionStorage property. Cerner requires that you upgrade the library to version v0.1.10 or higher to correct a known patient safety issue. You also must download and include this additional code into your project to correct this issue.

Other additional FHIR clients are available:

Tutorial

Creating your first app can be overwhelming, so Cerner has created a step by step tutorial on how to start creating your very first SMART app. The app is written in HTML and JavaScript with some CSS. We highly recommend that you take a look at the tutorial.

code Console and Sandbox

Cerner’s implementation of SMART on FHIR ecosystem allows you to register, update, and delete your SMART app from our code Console. Additionally, you can open and test your app from code Console in our Sandbox environment. Currently, there is a 15-minute waiting period for new or updated app configurations to take effect. If you cannot open the application after the 15-minute period, post a question to the Open Developer Experience forum.

Launch Context

See the Scopes and Launch Content page for more information on how you can obtain the context. Generally, your app must be able to retrieve SMART context parameters such as patient id, encounter id (if available), tenant, and a few others. You can inspect the OAuth2 access_token value that is returned to see the actual context.

SMART Apps in MPages

SMART apps can be embedded and launched from the MPages Workflow or Summary. In order to securely embed a SMART app within an MPages iframe, additional code must be included in the SMART app. Cerner provides this code for you. Head over to cerner-smart-embeddable-lib on GitHub to get started!

iframe Cookies

For IE if your SMART app uses cookies, the P3P header or meta tag must be set in order for cookies to be saved correctly while running in an MPages iframe. Please see this page for more information on P3P.

For Edge if your SMART app uses cookies, the Set-Cookie response header has to contain the attributes: SameSite=None; Secure for your cookies to be saved correctly while running in an iframe.

Microsoft Edge Browser (Chromium based) Support

Along with Internet Explorer, Cerner now supports embedded Microsoft Edge browser (Chromium based) inside Cerner Millennium PowerChart.

With Microsoft Edge as an additional option, clients can configure any SMART app to load using Edge (where available). Based on our test results, SMART apps render faster, use less CPU, and less memory to run, in comparison to IE. If your app uses cookies while being loaded inside an iframe, or is embedded in MPages (which loads the app in an iframe) you would need to set the Set-Cookie response header with additional attributes: SameSite=None; Secure for your cookies to be persisted.

Note: Even though there is support for Microsoft Edge in newer versions of Cerner Millennium, older Cerner Millennium PowerChart environments will not have support for Edge. For compatibility, it is recommended that the embedded SMART app uses functions that work correctly for both IE and Edge browsers at this time.

Testing

code Console

For provider and patient facing apps, you can select any patient from a list of patients in our Sandbox environment to begin testing. After selecting a patient to test, you can open your app from a new web browser in code Console. Testing from Code Console through the browser helps you start developing and testing your app quickly.

PowerChart

Once you have your app working in code Console and you are committed to taking your app to production, contact us through the application available at https://code.cerner.com/submit, and we can provide access to PowerChart to test your app. For provider facing apps, PowerChart is the environment where providers will access apps in a production environment, so it is very important to test the apps in PowerChart. Access to PowerChart is a benefit only offered to members of our code program.

SSL Certificate

Your app must be reachable through an https endpoint. Also, you need a valid SSL certificate for your site to test your app in PowerChart. A good resource to check your server’s SSL certificates is Qualys SSL Labs. Ensure your server’s certificate gets A grade or higher.

Public Access

In order for PowerChart to open and display your app in Cerner’s sandbox environment, the URL of your app needs to be publicly accessible. In other words, the URL cannot point to hosts on your internal network.

If you plan to perform tests in PowerChart using your organization’s environment, the URL of your app does not need to be publicly accessible. However, the app’s URL will need to be accessible from your organization’s Citrix servers. A good way to test the connectivity is by opening IE browser from Citrix servers to your app’s URL.

No Custom TCP Port

When testing your app in Cerner’s Sandbox environment via PowerChart, your app must be hosted on a standard https port 443. When other non-standard ports are used, PowerChart will not be able to load the app’s URL. This is due to an existing firewall rule set in place for security reasons.

HealtheLife

Direct to consumers apps may also be launched from our patient portal, HealtheLife. Once our patient portal is available for developers, developers in our program will have the ability to launch SMART applications from HealtheLife. This is how you can test as a consumer accessing your application.

Additional Resources