Building SMART Applications

info

This document is based on the SMART on openEHR specification located here

What is SMART?

SMART stands for “Substitutable Medical Applications and Reusable Technologies”, a healthcare standard through which applications can access clinical information through a data store. It was initially proposed by SMART Health IT project (run by Boston Children’s Hospital Computational Health Informatics Program) and was later specified as SMART on FHIR, a protocol which works on top of the FHIR APIs facilitating access to data. The specification builds on OAuth2 and OpenID Connect (OIDC), which are industry standards for authentication and authorization, and allows 3rd-party applications to authorize and seamlessly work with any system that implements the protocol.

Create a Client with the correct scopes

First create a client in Medblocks Ignite here with the scopes you need - guide is here. The descriptions of scopes are given below. Then create an application with the right target URL - you can use the guide here

Available scopes are:

Scope	Description
launch	Permission to obtain launch context when Application is launched from an EHR (Embedded iFrame Launch). This should be accompanied by an additional launch parameter in the authorization request.
launch/patient	The ability to launch a SMART app with a specific patient context
launch/episode	Need episode context at launch time (this is experimental, the semantic and the resource is to be determined).
patient/composition-<templateId>.crud	Permission to create, read, update and delete compositions of <templateId> that are within the EHR of the patient in context.
user/composition-<templateId>.crud	Permission to create, read, update and delete compositions of <templateId> that are within the EHRs the logged-in user has access to.
system/composition-<templateId>.crud	Permission to create, read, update and delete compositions of <templateId> of all EHRs in the system.
patient/template-<templateId>.r	Permission to read a template with <templateId>
user/template-<templateId>.crud	Permission to create and read a template with <templateId>
system/template-<templateId>.crud	Permission to create, read, update and delete a template with <templateId>
patient/aql-<queryName>.rs	Permission to read and execute AQL with <queryName> on EHR ID of the patient in context.
user/aql-<queryName>.cruds	Permission to create, read, update, delete and execute AQL with <queryName> on EHR IDs that the logged-in user has access to. If <queryName> is equal to the wildcard *, this scope will allow the ad-hoc query endpoint.
system/aql-<queryName>.cruds	Permission to create, read, update, delete and execute AQL with <queryName>. If <queryName> is equal to the wildcard *, this scope will allow the ad-hoc query endpoint.

You can read more about the scopes here

Initiating the Authentication Flow

There are two ways to initiate the authentication flow:

1. Standalone launch: Used when the application is used directly by the end-user
2. EHR launch: Used when the application is launched from within an EHR system

Then the application is launched using the Authorization Code flow, you can find the specifics here.

Service Discovery

The SMART on FHIR specification requires that the authorization server provides a /.well-known/smart-configuration endpoint that provides the necessary information for the client to interact with the server. The services section of response contains the following openEHR and FHIR specific information:

"services": {
    "org.openehr.rest": {
        "baseUrl":"https://platform.example.com/openehr/rest/v1",
        "description": "The openEHR REST APIs baseUrl",
        "documentation": "https://example.com/openehr/docs",
        "openapi": "https://example.com/openehr/rest/v1/openapi.json"
    },
    "org.fhir.rest" : {
      "baseUrl":"https://platform.example.com/",
      "description": "The FHIR APIs baseUrl"
    }
}