What is SMART?
SMART(Substitutable Medical Apps, Reusable Technology) is an App Platform for Healthcare. SMART Health IT is an open, standards-based technology platform that enables innovators to create apps that seamlessly and securely run across the healthcare system. Using an electronic health record (EHR) system or data warehouse that supports the SMART standard, patients, doctors, and healthcare practitioners can draw on this library of apps to improve clinical care, research, and public health.
What is SMART on FHIR?
SMART (“Substitutable Medical Applications, Reusable Technologies”) on FHIR is an open, HL7 FHIR standard-based platform that enables developers to create apps that can securely and seamlessly be integrated into all the major EHRs in the industry. SMART on FHIR is a set of open specifications to integrate apps with Electronic Health Records, portals, Health Information Exchanges, and other Health IT systems.
How a SMART on FHIR app works in Epic
Like all other major EHRs, Epic allows integration of SMART on FHIR apps within its EHR. A user of Hyperspace (Epic’s provider facing software) can activate a third-party vendor’s SMART on FHIR app from within the Hyperspace. The third-party SMART on FHIR app can be instantiated from the menu, left navigation bar, etc. When a SMART on FHIR app is instantiated, an authenticated token for access to an FHIR server, along with the FHIR server URL, is passed to the third-party app developer. The third-party App developer can query the authorized patient’s data from the FHIR server and use it in the SMART on FHIR app. For the user, SMART on FHIR App is shown in an iFrame within the Hyperspace simulator and in ActiveX based web browser control in Hyperspace Desktop Application.
Integrating SMART app with Epic
To integrate a SMART on FHIR app into the Epic EHR, one needs to register their app at the Epic’s App store, App Orchard. Lets first understand the following two related concepts for EPIC as these are used in the coming sections.
AppOrchard
Epic has an App Store, App Orchard, where one can publish a patient or provider facing SMART on FHIR apps for users. Once the user is interested in a published app there are steps needed to integrate that app into Epic in the user’s premises. AppOrchard is also the place where developers can learn about and access Epic’s APIs and list their apps for Epic community members to explore and acquire. To access go to URL https://apporchard.epic.com.
MyApps
It’s the place where you register your app with Epic that can later be deployed to AppOrchard or integrated into hospital EHR directly. One must have a valid account at MyApps to register an application with Epic that can later publish to AppOrchard or can be integrated with hospital EHR directly.
You can test your app without registering at MyApps (using Epic launchpad that runs the app in EHR launch context) but to test the app as standalone you need to code accordingly so you have to register with MyApps to get client_id used in the code. See the section below “Epic Launch Sequences” for more details on the code.
Here is snap from MyApps registration screen:
(Figure: Application registration screen on MyApps)
Epic Launch Sequences
As per SMART standards, Epic integration allows to launch the app in three SMART supported contexts:
1. Launch with EHR context
You can deploy your application at any server and using Epic LaunchPad you can launch it in EHR context.
And in launch.html:
Make sure the client_id given in code is exactly we have on the MyApps registration screen. See ( Figure: Application registration screen on MyApps )
Here is what happens when you do it:
- Epic will open your web app’s launch URL with at least two URL parameters:
- launch contains a SMART on FHIR launch token
- Epic’s base FHIR server URL
Your web application should query Epic’s FHIR server’s metadata endpoint (https://open-ic.epic.com/Argonaut/api/FHIR/Argonaut/metadata) to find Epic’s OAuth2 authorization and token endpoints.
2. In order to bind your web app’s session with the existing end-users EHR session, your app should redirect the browser to the Epic OAuth authorization endpoint with the following parameters:
response_type = "code" client_id = client_id (defined above) redirect_uri = redirect_url (defined in the above form) launch = the launch token (as passed to your web app's launch URL) state = <an opaque value used by the client to maintain state between the request and callback.> scope = "launch" (this is necessary to indicate the app is launching from the EMR context to enable single sign-on)
Epic will then redirect to your provided redirect URL with an authorization code and the state parameter you provided.
3. Your web app should exchange the authorization code for an access token by posting the following parameters to Epic’s OAuth token service:
grant_type = "authorization_code" code = the authorization code your web app received redirect_uri = redirect_url (defined in the above form) client_id = client_id (defined in the above form)
Epic will return an access_token. (In a production customer environment, a health system may configure additional SMART launch parameters which will be presented to your app during an EHR launch alongside the access_token, just as a user parameter is presented from this internal environment.)
4. Your web app can use the time-limited access token to access Epic FHIR resources. Include the token as a “Bearer” token in the Authorization HTTP header as part of your RESTful queries.
2. Standalone application launch
To test your app as a standalone launch there is no launchpad like platform. You have to code as per given guidelines. See image below from launch.html file
Below are some details about above code snippet:
- You have SMART web app created and deployed on some server
- In your launch.html provide redirect_url and FHIR Server URL as shown below. Make sure this redirect_url is the same that you gave when registering the app on MyApps. See ( Figure: Application registration screen on MyApps )
- The server variable should be set to some public Epic FHIR server or one that your hospital has set up for you, not a PROD server URL.
- The next important piece of code is client_id While testing the app in a non-production environment, make sure to use the NONPROD CLIENT ID that is given on the Epic registration screen. The other ID listed as CLIENTID on Epic registration screen can only be used in a PRODUCTION environment. How to sense if we are in PROD or NonPROD env; is easy; check your FHIR Server URL set in a variable server; if its PROD or NONPROD
Here is what happens when the app is launched:
- As you access your app launch.html in the browser it hits the given FHIR server. This FHIR server validates the client_id with Epic (Epic know this as we registered our application via MyApps).
- Since we are testing a standalone context and authentication is not yet made; the FHIR server redirects you to the provider facing app. In Epic sandbox or public servers it’s Epic MyCharts application for authentication as shown below:
3. On a successful login, it takes you to the patient selection page. Selecting the required patient and clicking Allow Access allow Epic to exchange info with the SMART app as shown below:
4. Finally, It redirects to the URL in variable redirect_url configured in the Epic registration screen and launch.html file. Here is your index.html file, you will have patient context available and a token that you can use to call FHIR APIs to get patient-related data.
3. SMART on FHIR JS Client
When launching in the EHR context; SMART on FHIR JS Client can automatically get the parameters passed in query string including FHIR server URL. After one has the FHIR server URL, it can be used to call conformance API to know authorization endpoints. Then the authorization server can be accessed sending the token to authorize one’s app. If the call is successful, the authorization server will send the access token back. This access token can be used to call the FHIR APIs to get patient info from the FHIR server URL and patient FHIR data can be served within the SMRT on the FHIR app or passed on to the Third-party application for further workflow.
If you are not using SMART on FHIR JS client we have to handle all that stuff ourselves and guide is available or SMART on FHIR website and EPIC sandbox website.
