Skip to main content

SMART-on-FHIR Scope Management

· 3 min read
Eric Morgan
  • SMART-on-FHIR scopes can be specified in different formats
  • The format depends on the EHR and FHIR Server being connected to
  • Plasma can format scopes in whichever way is necessary

When building a SMART-on-FHIR application, requesting scopes is yet another small, but crucial detail that may differ from EHR-to-EHR. When launching your app, you must pass a string representing the scopes that your app is requesting and it must be formatted precisely based on the EHR or FHIR Server you are connecting to.

Usually, when registering an app with an EHR, you are asked which scopes your app will be requesting. Here are a few examples of how some of the larger EHRs ask you which scopes your app is requesting

Epic Cerner Athena

However, after registering your apps, you must make sure to request those scopes using the proper format for that EHR.

Scope Format​

The format of FHIR scopes can be found on the website.

There are three basic patterns for scopes.

  1. Resource Scopes Resource scopes have the pattern context/resource.actions. For example, patient/Observation.rs means an app can read and search for all observations about a patient.
  2. Launch Scopes Launch scopes have the pattern launch/context and indicate that the app will need some piece of information before launching. For example, launch/patient indicates that an app requires a patient context.
  3. Other Scopes Other scopes are simply keywords that specify some information or functionality that is needed. For example, fhirUser specifies that the current user should be available as a FHIR resource.

Scope Versions​

There are also two types of versions for specifying scopes, called v1 and v2. v2 is the current version, but sometimes v1 scopes still need to be supported. You can read about the differences between v1 and v2 scopes at the link above.

When launching your app, you must be sure to pass scopes the way that the server you are connecting to expects them to be formatted.

Plasma Solution​

With Plasma, we have defined a discrete way to represent scopes and we provide parsers and formatters that can generate the scope string. The formatters are configurable, and as always, we provide plugins that generate the correct format for all of the major EHRs.

Scope Parser/Formatter​

Our scope module works like the code shown below. Here, we are parsing a string of scopes in the v2 format and then converting them back to a string in the v1 format.

// Parse the string into discrete scopes...
const fhirScopes = FHIRScopes.fromString("patient/Patient.rs launch launch/patient fhirUser");

// Define a formatter for how you want to format your scopes...
const formatter = new FHIRScopeFormatter({ version: "v1", expandResourceScopes: false });
// Or: const formatter = FHIRScopeFormatter.forEpic();
// Or: const formatter = FHIRScopeFormatter.forCerner();

// Format the discrete scopes as a string in the intended format...
const sScope = formatter.formatScopes(fhirScopes);

Scope Builder​

We also provide a UI tool that lets you build a scope string and set whichever format you need.

v2 v1

Scope Management​

In addition to formatting scopes properly, some EHRs require certain custom scopes to always be included in every launch.

Use Plasma to manage your SMART-on-FHIR applications to ensure that your app is always conforming to the latest requirements of your target platforms.