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 could be native mobile applications and that use HL7 FHIR standard to read and write data from the EHR. With SMART, Oracle Health can embed a SMART application in the EHR. Oracle Health believes that SMART applications are a major user of FHIR resources. Oracle Health also supports FHIR access through mobile SMART applications, as those specifications emerge from the SMART website.

SaaS Model

Oracle Health expects most SMART applications to be provided to customers using a SaaS (software as a service) model. That is, the SMART developer or provider hosts the application. In this case, customers do not need to install any code or package to implement a particular SMART application.

Authorization Model

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

  1. Oracle Health must validate and register every SMART application. As part of this process, Oracle Health validates the use of FHIR resources and operations (for example, READ and WRITE). Oracle Health does not validate the use of FHIR resources for direct-to-consumer applications.
  2. Each customer decides whether to allow a SMART application to run on a domain-by-domain basis.
  3. Each customer decides which users and roles can access the SMART application.

To learn more about the general SMART on FHIR application authorization process, see the SMART App Authorization Guide. For implementation information regarding Oracle Health’s Authorization server, see the Authorization page on Oracle Help Center.

Access Points

Currently, users can open SMART applications in the following ways:

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

SMART Application Data Retrieval

SMART applications can use Oracle Health’s implementation of the FHIR standard server to retrieve data from the EHR based on the patient chart being viewed. However, SMART applications are not limited to FHIR data for their needs. SMART application developers can use other data sources for their needs, including other third-party data sources, private, and proprietary data the SMART application maintains. SMART applications can also retrieve data through Oracle Health proprietary means (for example, MillenniumObjects, CareAware services, or Discern Explorer scripts). Using proprietary APIs limits interoperability, but if that is not a concern of the SMART application, it is an option.

SMART Without FHIR

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

At a minimum, a SMART application 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 access capabilities using a Well-Known Uniform Resource Identifier.

See Oracle Health’s Well-Known SMART Configuration Capability Statement for more information.

Technical

User Interface

Oracle Health considers user interface (UI) and user experience (UX) when validating your SMART application. UI and UX are important parts of the overall user experience.

Screen Resolution

The recommended screen resolution varies based on the available screen’s real estate. Instead of targeting a specific resolution, design your application to be responsive, and ensure that the application adjusts according to available screen sizes.

Progress Indicator

Oracle Health encourages using a loading overlay or a status progress indicator in your SMART applications.

Browser Requirement

For provider-facing applications running in the Oracle Health Millennium EHR, both Microsoft Edge and Internet Exporer (IE) are supported. The embedded browser controls we use are WebView2 for Edge and IWebBrowser2 C++ interface for IE.

Oracle Health recommends upgrading from IE to Edge. With MPages 9.0 and later, applications embedded in MPages Workflow or Summary views must function correctly with Edge. Where the SMART on FHIR applications are dependent on IE, Oracle recommends using Edge with IE mode. See Modern Security Protection for Vulnerable Legacy Apps on Microsoft Learn for more information.

IE may be required for applications that integrate with previous Millennium and MPages releases. IE10 is the minimum version of IE that we support. The latest supported browser varies based on the browser version installed at the Oracle Health customer site. Although no longer supported by Microsoft, customers could still use IE10, especially customers who host their own system.

The MPages 6.x platform depends on other components that require IE10 to run. Even though a newer version of IE is available in Citrix, MPages 6.x generates the application using IE10. Therefore, Oracle Health recommends that the embedded SMART application uses functions that work correctly for both IE and Edge.

Single Sign On (SSO)

Oracle Health understands that it is counterintuitive to prompt a user for their credentials when opening a SMART application in PowerChart when the user is already logged in. With that in mind, the system is designed to provide an SSO experience for the users when a SMART application is opened from PowerChart.

As a developer, follow the guidelines below when developing your applications to be embedded in PowerChart.

Embedded Browser Control

Oracle Health uses the IWebBrowser2 C++ interface browser controls for IE and WebView2 for Edge, both developed by Microsoft. Review the documentation for more information. This embedded browser control has some limitations compared to the stand-alone IE or Edge browser controls.

No Shared Cookies

Web and stand-alone applications can use a separate window for the authorization flow to allow users to authenticate with the system. However, if the application is embedded in PowerChart, browser cookies are not shared between the embedded browser and the newly opened browser window. In this scenario, single-sign-on (SSO) does not work and the user needs to manually enter their credentials when prompted. Oracle Health recommends performing all navigation and redirects in the embedded browser without needing to open a new browser while embedding in PowerChart. To learn more about the technical details of IE, see IE8 and Loosley-Coupled IE and Tab Isolation.

To flex your application based on the current execution context (embedded versus stand-alone mode), see Embedded in PowerChart.

HTML5 Session Storage

With the introduction of HTML5, sessionStorage can help persist data in a browser’s session. Depending on the PowerChart release, sessionStorage may not be isolated per instances of the embedded browser. If your application is going to be embedded in PowerChart, Oracle Health does not recommend using sessionStorage.

To flex your application based on the current execution context (embedded versus stand-alone mode), see Embedded in PowerChart for more information.

Embedded in PowerChart?

To flex your application based on where it is being accessed, see the FHIR Client Oracle Health Additions GitHub, which verifies that certain conditions exist and determines whether the application is available in PowerChart.

HTML5 DOCTYPE

The doctype declaration tells the browser what version of HTML the document is written in. Oracle Health recommends including this declaration so that the browser generates the document correctly. It must be included in the first line of the document, right above the <html> tag.

<!DOCTYPE html>

X-UA-Compatible Tag

For the embedded IE browser to generate the application 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 element on a page, the page and all associated JavaScript are generated in IE 7 mode, which may cause errors and unwanted behavior.

Technology and Framework for SMART Apps

The technology and framework you use is up to you and your company. Regardless of the technology, framework, or language you choose, make sure that your application is fast, responsive, and adaptable to various screen sizes.

Open Source FHIR Client Libraries

To start development, see the 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 use of the sessionStorage property. Oracle Health 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

See SMART on FHIR Tutorial for step-by-step instructions on how to start creating a SMART application. The tutorial application is written in HTML and JavaScript with some CSS. Oracle Health recommends reviewing the tutorial.

code Console and Sandbox

Oracle Health’s implementation of the SMART on FHIR ecosystem allows you to register, update, and delete your SMART application from our code Console. Also, you can open and test your application from the code Console in our Sandbox environment. Currently, code Console has a 15-minute waiting period for new or updated application 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 about obtaining the context. Generally, your application must be able to retrieve SMART context parameters such as patient ID, encounter ID (if available), tenant, and a few other parameters. You can inspect the OAuth2 access_token value that is returned to see the actual context.

SMART Apps in MPages

SMART applications can be embedded and opened from MPages Workflow or Summary views. To securely embed a SMART application in an MPages iframe, additional code must be included in the SMART application. See Cerner SMART Embeddable Library on GitHub for more information.

iframe Cookies

For IE, if your SMART application uses cookies, set the P3P header or meta tag to save cookies correctly while running in an MPages iframe. See P3P for more information.

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

Microsoft Edge Browser (Chromium based) Support

Along with Internet Explorer, Oracle Health supports embedded Microsoft Edge (Chromium based) in PowerChart.

With Microsoft Edge as an option, customers can configure any SMART application to load using Edge where available. Based on our test results, SMART applications generate faster, use less CPU, and less memory, compared to IE. If your application uses cookies while being loaded inside an iframe, or is embedded in MPages (which loads the application in an iframe), set the Set-Cookie response header with additional SameSite=None; Secure attributes for your cookies to persist.

Note: Even though Microsoft Edge is supported in newer versions of Oracle Health Millennium Platform, older PowerChart environments do not support Edge. For compatibility, Oracle Health recommends that the embedded SMART application use functions that work correctly in both IE and Edge browsers.

Testing

code Console

For provider and patient facing applications, 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 application from a new web browser in code Console. Testing from code Console through the browser can help you start developing and testing your application more quickly.

PowerChart

Once your application works in code Console and you are committed to taking your application to production, contact us through Code.cerner.com/submit, and we can provide access to PowerChart to test your application. For provider-facing applications, PowerChart is the environment where providers access applications in a production environment, so it is important to test the applications in PowerChart.

Note: You must be a member of the Oracle Health Developer Program to access PowerChart.

SSL Certificate

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

Public Access

For PowerChart to open and display your application in Oracle Health’s sandbox environment, your application’s URL must 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, your application’s URL does not need to be publicly accessible. However, the application’s URL needs to be accessible from your organization’s Citrix servers. One way to test the connectivity is to open a browser from Citrix servers to your application’s URL.

No Custom TCP Port

When testing your application in the Oracle Health Sandbox environment using PowerChart, your application must be hosted on a standard https port 443. If nonstandard ports are used, PowerChart cannot load the application’s URL because of a firewall rule in place for security reasons.

Oracle Health Patient Portal (formerly HealtheLife)

Direct-to-consumer applications can also be opened from Oracle Health Patient Portal (formerly HealtheLife). Once our patient portal is available for developers, developers in our program can open SMART applications from Oracle Health Patient Portal so that you can test as a consumer accessing your application.

Additional Resources