Ontario eReferral - eConsult HL7® FHIR® Implementation Guide

Technical Specifications > SMART Integration

Specification - SMART Integrations

This section of the IG defines specific requirements for implementers who aim to establish the SMART integration defined in this implementation guide (IG). The focus is on the expected use of the SMART App Launch Framework and a RESTful FHIR API to launch a "SMART App" (or "App"), typically a Referral Management System (RMS), from a Point of Service (POS) or another RMS to help users select an appropriate Healthcare Service and/or auto-populate forms needed to submit a referral request electronically (eReferral/eConsult).

The requirements and expectations described here are not intended to be exhaustive. This IG establishes a baseline of expected behavior that communication partners can rely on and then build upon without standardizing referral pathways or defining what clinical data must be exchanged when referring patients. Therefore, implementers SHALL anticipate the need to discuss and mutually agree on the end user workflow that a SMART integration will enable, including:

any forms, supporting information or functionality that will be provided by the SMART App to support the workflow;
how the application will be launched from the POS or RMS ("SMART Server" or "Server");
information that will be needed from the Server to populate forms or otherwise support the workflow and/or App;
the FHIR Resources that will be used to retrieve information required from the Server;
the RESTful FHIR endpoint that will be used to access the information; and
the RESTful interactions that will be used to retrieve information from the endpoint.

Future iterations of this IG are expected to build upon this baseline based on implementer experience.

Context

Prerequisites

Before reading this formal specification, implementers are encouraged to first familiarize themselves with other key portions of this IG, specifically:

The business model for information about what this IG aims to accomplish including an overview of the business solution and process flow this specification will enable.
The technical background page for information about the underlying specifications this IG builds upon including references to sections that implementers should read to establish a necessary foundation to understand the constraints and usage guidance described here.

IMPORTANT: In addition to an understanding of FHIR concepts, familiarity with the OAuth2 Authorization Framework and OpenID Connect and their use within the SMART App Launch Framework (SMART on FHIR) will be necessary to successfully implement the SMART integration specified on this page.

Participating Systems

A SMART integration provides a standard way for implementers of eServices solutions to establish a user interface level integration with shared context (both user and patient) between two software applications with a secure data connection in the background to share information.

Two different software applications participate in a SMART integration. In an eServices context these are typically:

a POS or RMS application that has been configured as a SMART Server (EHR launch) so it can be extended with the functionality of one or more SMART Apps; and
an RMS application that can be launched from a SMART Server as a SMART App (confidential app) to assist users with the creation, management or fulfillment of electronic referrals, using the RESTful FHIR API to retrieve information.

SMART integrations

This IG uses a subset of the functionality described in the SMART App Launch Framework (SMART on FHIR) to establish a secure, lightweight, web browser based user interface level integration with shared context (both user and patient) between two software applications with a data connection in the background.

An overview of the SMART Integration is provided below to provide readers with context for the requirements that follow. Links to relevant sections of the SMART App Launch Framework (SMART on FHIR) are provided throughout.

App Registration

To be used as a SMART App, an RMS must first be registered with an POS or RMS that is configured as a SMART Server. Registration of Apps will typically be a manual process.

SMART App Launch (using OAuth2)

To function as a SMART Server, a POS or RMS must present multiple endpoints to a SMART app:

a FHIR server where the SMART App will access patient and user information
an authorization server to authorize the SMART App to access to the FHIR endpoint (authorization code)
a token endpoint to exchange authorization for tokens needed to access information from the FHIR endpoint

An App will typically be 'launched' in response to a user action performed in the SMART Server's user interface. Applications conformant to this IG SHALL use the SMART EHR launch sequence and SMART authorization sequence to launch and access data from a SMART Server. The steps in the launch process are illustrated below.

Notes:

Step 4: SMART Servers conformant with this IG SHOULD publish endpoint information in their CapabilityStatement to enable conformance testing
Step 4: SMART App providers MAY choose to configure systems with static endpoint information shared during the app registration instead of retrieving the information dynamically
Step 5: a SMART App must communicate its access requirements to the SMART Server, this is discussed below

Retrieving Data (using RESTFul FHIR)

Once an App has been successfully launched and authorized to access the server, it will have launch context information from the Server including:

an access_tokenthat can be used to retrieve protected information from the Server's FHIR endpoint;
fhiruser context that can be used to retrieve information about the person who initiated the App launch;
patient context that can be used to retrieve information from the patient record the user was viewing when the App was launched.

These parameters SHOULD be used by the App to retrieve the information it needs to align its context (user and patient) with the Server, as well as to collect information needed to create and submit the referral request.

In the example, a SMART App retrieves information about a Patient from the SMART Server's FHIR endpoint using patient context ("patient": "123") recevied from the SMART Server.

Single Sign On (using an OpenID Token)

To provide a seamless user experience, an OpenID Token (id_token) and fhiruser context issued by the (token) Server during the launch process SHOULD be used by a RMS to validate the user's identity so access to the application can be granted without requiring the user to log in each time the RMS is launched.

A SMART App can retrieve identity information about the user (typically a Practitioner for referrals) from the FHIR endpoint using the fhiruser context recevied from the SMART Server.

Note: An RMS will typically need to provide a one-time process to associatate EHR user identity with RMS user identity, for each user.

For more information see scopes for requesting identity data and steps for using an ID token.

Use of the SMART integration

The SMART Integration provides a framework for launching a SMART App with access to restricted information available from the SMART Server's FHIR endpoint. The level of access that will be granted and information available will depend on the capabilities of the system hosting the FHIR endpoint and the level of access (scope) requested by and granted to the App.

This section specifies the minimum capabilites expected of SMART Servers that declare conformance with this IG as well as guidance for implementers of SMART Apps.

Scope and Launch Context

The SMART App Launch Framework (SMART on FHIR) specifies that OAuth scopes be used for Apps to communicate (and negotiate) their access requirements with Servers. Scopes defined within the framework correspond to different types of data that are relevant to this IG.

Category	Relevance to use case	Recommended approach
contextual data	Is provided to the App with the grant information so it knows which patient (and potentially which ServiceRequest) the user was viewing when the App was launched.	Referencing the EHR launch process illustrated above: - the SMART Server SHALL pass the `launch` context URL parameter (e.g. `launch=abc123`) to a SMART App at the time of launch (step 3) - the SMART App SHALL pass the URL parameter it received at launch (`launch=abc123`) to the SMART Server's authorization endpoint as an URL parameter with its request for `launch` `scope` (step 5) - if access to the FHIR endpoint is granted, the SMART Server's token endpoint SHALL return appropriate launch context parameters to the SMART App when it exchanges authorization with an `access_token` in Step 10.
clinical data	Will be accessed by the App using the RESTful FHIR API.	The App SHOULD include a request for `patient/Patient.read`¹ access in it's `scope` request to the authorization server (step 5) so it has the ability to query for patient information needed to create a referral request. If approved, granted scope SHALL be returned from the Server with the `access_token` in step 10.
user identity data	Will be provided in a separate `id_token` from the server so the App can authenticate the user and grant access to its functionality.	If the App requires user authentication, it SHALL request a pair of OpenID Connect scopes `openid` and `fhirUser` in it's `scope` request to the authorization server (step 5). If approved, identify information SHALL be returned from the Server in an `id_token` sent with the `access_token` in step 10.

¹ As a best practice, SMART Apps SHALL request only the scopes and permissions they need to function. Scopes requested will often be broader than above.

Retrieving Information from a FHIR Server

Using inforamtion received through the launch process (e.g.: "access_token"="i8hweunweunweofiwweoijewiwe", "scope": "patient/Patient.read" and "patient": "123" context), a SMART App can access protected information about the patient by issuing a FHIR API calls to the SMART Server's FHIR endpoint.

Each request SHALL include an Authorization header that presents the access_token as a “Bearer” token.

For example, the request

GET [base]/Patient/123
Authorization: Bearer i8hweunweunweofiwweoijewiwe

would return

{
  "resourceType": "Patient",
  "id": "123",
  ...
  "identifier": [
    ...
  ],
  "active": true,
  "name": [
    {
      "family": "Doe",
      "given": [
        "Jane"
  ...
}

link to a complete example of the Patient resource

Additional information pertaining to retrieving information from a FHIR Server can be found here: RESTful FHIR API.

Example instances of each of the different FHIR Profiles defined in this IG are available from the Structures - Resource Profiles section of the FHIR Artifacts page. (See right column.)

Expectations of the SMART Server

Every SMART Server conforming to this specification:

SHALL specify the resource types, profiles and operations that are supported by its FHIR Endpoint by providing a CapabilityStatement (kind=instance) at [base]/metadata
SHALL convey the FHIR OAuth authorization endpoints, core capabilities and capability sets to SMART App developers using both:
- the FHIR CapabilityStatement, and
- a A Well-Known Uniform Resource Identifiers (URIs) JSON file
SHOULD be capable of granting patient/Patient.read scope with patient context information to enable authorized SMART Apps to access information about Patients that may become the subject of ServiceRequests created on the app
SHALL be capable of granting openid and fhiruser scope with fhiruser context to enable authorized SMART Apps to access information about Practitioners who use the app to enable single sign on using OpenID connect, etc.
SHALL enable a SMART App to validate the signatures of OpenID Tokens (id_token) issued by its token server, see: steps for using an ID token.

Expectations of the SMART App

A SMART App declaring conformance to this specification:

SHALL conform to the SMART launch framework confidential app profile and SHALL therefore be able to protect a client_secret
SHALL conform to all App protection requirements in the SMART App launch framework
SHOULD be able to request and use patient/Patient.read scope using the patient context granted by a SMART Server to enable the app to retrieve Patient demographic information that will be needed to support the completion of forms used for referral (where applicable, a SMART App SHOULD also be capable of supporting other resources defined in this IG)
SHALL to be able to request and use openid and fhiruser scope with fhiruser context granted by a SMART Server to enable retrieve Provider identity information needed to support single sign on using OpenID connect, etc.