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, Oracle Cerner can embed a SMART app in the EHR. Oracle 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 website.

SaaS Model

Oracle 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. Oracle Cerner must validate and register every SMART app. As part of this process, Oracle Cerner validates the usage of FHIR resources and operations (for example, READ and WRITE). Oracle 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 the Oracle Cerner Authorization server, see the Authorization topics.

Access Points

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

• Providers can access SMART apps from the Cerner Millennium PowerChart TOC (table of contents, a column of options that open different PowerChart components) and the Organizer view.
• Providers can access SMART apps from an MPages component that is embedded in PowerChart.
• Consumers can access SMART apps from HealtheLife to view their patient information.
• Providers/Consumers can access SMART apps from a stand-alone provider/patient facing SMART apps.

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

SMART App Data Retrieval

SMART apps can leverage the Oracle Cerner 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 Oracle 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:

• launch
• launch/patient
• openid fhirUser
• openid profile (deprecated)

Well-Known SMART Configuration

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

See the Cerner Well-Known SMART Configuration (CapabilityStatement) 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 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 have created and open sourced. Terra follows the Oracle Cerner Design Standard Guidelines so your app will look and feel like an Oracle Cerner app.

Screen Resolution

The recommended screen resolution varies based on the available real estate of the screen. 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 are 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 (https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752127(v=vs.85)?redirectedfrom=MSDN) 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.

Single Sign On (SSO)

Cerner understands that it is 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.

• Due to technical limitations (see the No Shared Cookies section below), apps should use the same embedded browser (no pop-up) to authorize and launch when embedded in PowerChart. We still recommend using a pop-up for authorization and authentication in other workflows outside of PowerChart.
• If you would like to flex your app based on the current execution context (embedded vs stand-alone mode), please see the Embedded in PowerChart? section for more information.

Embedded Browser Control

There have been a lot of questions and interest around what embedded browser control the Oracle Cerner 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 (https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752127(v=vs.85)?redirectedfrom=MSDN) 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 is 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 would like to flex your app based on the current execution context (embedded vs stand-alone mode), please see the Embedded in PowerChart? section for more information.

HTML5 Session Storage

With the introduction of HTML5, sessionStorage is a good way to persist data within a browser 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 would like to flex your app based on the current execution context (embedded vs stand-alone mode), please see the Embedded in PowerChart? section for more information.

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:

• Java: https://github.com/hapifhir/hapi-fhir
• .NET: https://github.com/FirelyTeam/firely-net-sdk
• Python: https://github.com/smart-on-fhir/client-py
• iOS: https://github.com/smart-on-fhir/Swift-FHIR

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

The Oracle Cerner 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 Context 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. Oracle 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. For more information, see A Quick Look at 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, Oracle Cerner now supports embedded Microsoft Edge browser (Chromium based) inside Oracle 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.

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 http://oracle.com/health/developer, 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 SSL certificates is Qualys SSL Labs. Ensure your server certificate gets A grade or higher.

Public Access

In order for PowerChart to open and display your app in the Oracle Cerner 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 environment, the URL of your app does not need to be publicly accessible. However, the application URL will need to be accessible from your organization Citrix servers. A good way to test the connectivity is by opening IE browser from Citrix servers to your application URL.

No Custom TCP Port

When testing your app in the Oracle Cerner 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 application 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.