DTR SMART APP - confluence.hl7.org

DTR SMART APPTechnical Overview

Keeyan Ghoreshi

© 2020 Health Level Seven ® International. Licensed under Creative Commons Attribution 4.0 International HL7, Health Level Seven, FHIR and the FHIR flame logo are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

1/14/21'Approved for Public Release; Distribution Unlimited. Public Release Case Number 20-2988'

Housekeeping Announcements

• If you have technical difficulties, log out of Whova and sign back on. In most cases, this should resolve your issues.

• Post your questions in the Q&A box and not through the chat feature.

• Do not enable your video or microphone unless prompted by the presenter.

• If you can’t hear or see something, use the chat box to let us know.

• Sessions will be recorded. Recordings will be posted in Whovalater in the day. Slides will be posted in HL7’s Education on Demand within a week.

® Health Level Seven and HL7 are registered trademarks of Health Level Seven International, registered with the United States Patent and Trademark Office. 2

DTR Overview

• A brief overview of DTR (Document Templates and Rules)

• This presentation is meant to give an overview of how the DTR app works

© 2019 Health Level Seven ® International. Licensed under Creative Commons Attribution 4.0 International HL7, Health Level Seven, FHIR and the FHIR flame logo are registered trademarks of Health Level Seven International. Reg. U.S. TM Office. 3

Tutorial Outline

• Introduction – DTR and CRD• SMART Launch • Resource Retrieval• Prepopulation • Interoperability

© 2019 Health Level Seven ® International. Licensed under Creative Commons Attribution 4.0 InternationalHL7, Health Level Seven, FHIR and the FHIR flame logo are registered trademarks of Health Level Seven International. Reg. U.S. TM Office. 4

INTRODUCTION

© 2019 Health Level Seven ® International. Licensed under Creative Commons Attribution 4.0 International HL7, Health Level Seven, FHIR and the FHIR flame logo are registered trademarks of Health Level Seven International. Reg. U.S. TM Office. 5

CRD

• CRD (Coverage Requirements Discovery) is the companion workflow to DTR

• CRD determines if the DTR app is needed, and if so, what parameters are required for its launch

• The CRD workflow produces a CDS hook, which is used to kick off the DTR workflow


DTR

• DTR (Document Templates and Rules) gathers the data necessary to make a request

• A provider making a device request would ideally not have to input any information at all, as DTR gathers the necessary information to authorize the request

• DTR relies on the SMART protocol to authenticate and CQL to gather FHIR resources


SMART LAUNCH


CDS Hooks


• The EHR should launch the SMART app from the card, allowing it to use information contained in the card without complicated data handling

• Most notably, the EHR can store all the information it needs to make the app_context by parsing the card

• Prior to the interaction the EHR should receive a card

‒ A card contains relevant information from the CRD app like the questionnaire and CQL

SMART Basics: EHR side


• The EHR initiates the SMART launch ‒ First, the EHR creates a session with

a unique `launch` id‒ Then, the /launch page is opened

• All information the EHR has is withheld until the SMART app authenticates

‒ Access to the patient ID without authentication is a security violation

• After the access_token is sent, the EHR’s job in the handshake is over

• Our EHR uses /_services/smart/Launchas the endpoint for creating a session

• The EHR creates a unique launch ID as the key for an object containing all the relevant session information

• We proxy auth requests to fill the auth token with relevant details, like patient ID and app_context

• The access_token returns through the proxy with additional fields

SMART Basics: EHR side


EHR CRD DTR

Make request to CRD to discover if requirements are

required

Process Request and return CDS Hooks card

If documentation is needed, initiate SMART launch from

the card

Create Launch ID: launch1234Open the /launch page

Receive launch id and iss from the /launch url

SMART Basics: DTR launch


• The process begins at the /launch page

• Upon access, a log is created and the urlparams are fetched

• Metadata is fetched from the FHIR server (iss)

‒ The metadata will contain the security urls for authentication

• The app redirects to the authentication endpoint, which is given a redirect to the /index page

‒ Authentication endpoint returns a code, which can be exchanged for an access_token

/launch page URL constructed by the EHR:

http://localhost:3005/launch?launch=ca93-poi5&iss=http://localhost:8080/test-ehr/r4




SMART Basics: Auth Redirect


"response_type=code&" +"client_id=" + encodeURIComponent(clientId) +"&" +"scope=" + encodeURIComponent(scope) +"&" +"redirect_uri=" + encodeURIComponent(redirectUri) +"&" +"aud=" + encodeURIComponent(serviceUri) +"&" +"launch=" + encodeURIComponent(launchContextId) +"&" +"state=" + state;

The authentication redirect uses the URI obtained from the FHIR servers metadata to redirect with the required parameters.

The clientId is retrieved out-of-band, in our case it is registered beforehand for specific fhir endpoints

The state is a unique ID generated by the DTR app to maintain the session with



Create Launch ID: launch1234Open the /launch page

Receive launch id and iss from the /launch url

EHR DTR

Open the FHIR server’s metadata page using the iss

Return security endpoints for authentication

Redirect to the authentication endpointAuthenticate the app

Redirect to the redirect URL provided Open the /index page

In a real EHR, the user should already be logged in, so the authentication passes without reentering credentials

In the reference implementation and some sandboxes, this is instead where the user is asked to login with a username/password

SMART Basics: Scope

• The scope is part of the request made to the authentication endpoint– The scope is which FHIR resources we ask for access to

• Since the app doesn’t know which resources it needs specifically, it asks for access to all of them

– Note that most FHIR servers will not serve requests for resources without a specific ID – This means that even with access to all the resource types, a FHIR client would not be able to

access any resources without a patient ID, and will only be able to access resources related to that patient

• Ideally, the scope would be more restricted and only ask for resource types that it needs


SMART Basics: Example Scope


log.scope = ["launch","user/Observation.read","user/Patient.read","patient/Observation.read","patient/Patient.read","patient/Coverage.read", "patient/Condition.read", "user/Practitioner.read" ].join(" ");

The user scopes give access to all resources that the current user can access, while the patient scopes only give access to resources the patient can access

For example, user/Observation.read gives access to all observations across the EHR, but patient/Observation.read would only give access to observations related to the specific patient.


• Before redirecting, we use the state ID to save some information that the index page will need. Most importantly, we pass the index page the authorization URL with this method.

• Recall that this is right before redirecting to the authentication endpoint, a redirection will “end” the current session


sessionStorage[state] = JSON.stringify({clientId: clientId, //the client’s unique idsecret: secret, //the client secret, if availableserviceUri: serviceUri, //the fhir server (iss)redirectUri:redirectUri, //the URL of the index pagetokenUri: tokenUri, //the authorization URLlog: log //to persist the current log});

SMART Basics: DTR index


• When the auth endpoint redirects back to the /index page, the state is used to reload all session info from localStorage

• Using the code returned from the authentication endpoint, the app POSTs the relevant info to the authorization endpoint

‒ The authorization endpoint returns the actual access_token

• The DTR app uses the access_token to create a SMART client

‒ The client can make authorized calls to the FHIR server for resources

DTR

Open the /index page

EHR

Load session info from storage with the state ID

Redirect to the authorization endpoint

Authorize the app and gather information to populate token

Return the access_token Create SMART client with the token

SMART Basics: DTR Index


var data =`code=${code}&grant_type=authorization_code&redirect_uri=${redirectUri}&client_id=${clientId}`

The data is sent to the authorization endpoint in a POST request, with the code from the authentication endpoint.

Note that the redirect_uri was persisted in the localStorage because the redirect_uri MUST match the one given to the authentication endpoint.

Security Notes

• The SMART workflow keeps the patient ID, and any information in the app context, secret from the client until is authorizes

– The patient ID is considered patient data, and thus cannot be given to unauthorized clients

• The app uses the redirect_uri to ensure the client doesn’t redirect to a different endpoint after authorizing

• The payer server in the reference implementation is protected with JWT, which only verifies identity

– Payers and Providers should coordinate out-of-band to create a whitelist of clients to serve for JWT to work

– This is effectively the same as for the DTR app registering client ids with the EHR – The payer server is not the same as the payers FHIR server, which may be protected with

SMART itself


SMART Basics: Access Token

• The access token contains a bearer token which can be used to make requests against the FHIR server

• Additionally, any information the EHR wants to provide is also included in the JSON.

• Along with the token, it contains the patient ID and the app context


const encodedAppString = auth_response.appContext.replace(/\+/g, '%20');

SMART Basics: App Context


• The app_context contains three properties‒ Template: the questionnaire ID‒ DeviceRequest: the fhir resource for

this interaction‒ Filepath: the location of the associated

cql

• The app uses this info to retrieve the questionnaire and its prepopulation CQL files

‒ Requests are proxied to CRD

context: ["/files", "/fhir"],target: "http://localhost:8090",

NOTE

Though the reference implementation proxies request to the CRD server, the template can also include the canonical URI of the questionnaire, which would provide the location of the payer FHIR server

It is currently not specified in the IG how the payer FHIR server is authenticated to or accessed

SMART Basics: App Context


appContext = {template: "Questionnaire/HomeOxygenTherapy",request: '{\\"resourceType\\":\\"DeviceRequest\\",\\"id\\":\\"ecea4560-e72c-4f69-8efd-b0f240ecef40\\",\\"meta\\":{\\"profile\\":[\\"http:\\/\\/hl7.org\\/fhir\\/us\\/davinci-crd\\/R4\\/StructureDefinition\\/profile-devicerequest-r4\\"]},\\"status\\":\\"draft\\",\\"codeCodeableConcept\\":{\\"coding\\":[{\\"system\\":\\"https:\\/\\/bluebutton.cms.gov\\/resources\\/codesystem\\/hcpcs\\",\\"code\\":\\"E0424\\"}]},\\"subject\\":{\\"reference\\":\\"Patient\\/e3uD6HlZwY69BYkprsNDh2Du7KroLDCIzX8uiCuKkahM3\\"},\\"authoredOn\\":\\"2019-12-30\\",\\"performer\\":{\\"reference\\":\\"Practitioner\\/1912007\\"}}',filepath: '../../getfile/cms/hcpcs/E0424'}

An example app context

RESOURCE RETRIEVAL


CQL Retrieval

• With the SMART client and app context, the app can load the Questionnaire needed for the request.

• The Questionnaire is a FHIR resource, so it can be requested from the payer like any other FHIR resource

• The Questionnaire contains the relevant information to retrieve the CQL


CQL Retrieval


"extension": ["url": "http://hl7.org/fhir/StructureDefinition/cqf-library","valueCanonical": "http://hl7.org/fhir/us/davinci-

dtr/Library/HomeOxygenTherapy-prepopulation"

The Questionnaire contains an extension with a reference to the CQL file that prepopulates it

• The fetched ELM is a library that references other related resources

• Common ELMs that every questionnaire can use• Specific ELMs for prepopulating this questionnaire• Valuesets that are used in the questionnaire

CQL Retrieval


"relatedArtifact": ["type": "depends-on","resource": {

"reference": "Library/DTRHelpers"

The CQL library contains references to other libraries

And most importantly, a reference to the main prepopulation CQL file

"content": ["contentType": "application/elm+json","url": "files/HomeOxygenTherapy/r4/HomeOxygenTherapyPrepopulation-0.1.0.cql"

Resource Retrieval


• Before prepopulating, the app queries the FHIR server for resources‒ It uses dataRequirements specified in the prepopulation Library to determine which

resources to query for

• The app builds a bundle of fetched resources‒ Uses specific resources where available, for coverage, device request, etc.‒ Makes broad requests for observations, procedures, etc.‒ The difference is whether the patient is referenced in the resource

Resource Retrieval


"dataRequirement": ["type": "Condition","codeFilter": [

"path": "code","valueSet": "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1219.25"

]

const requirementTypes = libraryResource.dataRequirement.map((d) => d.type);

The Prepopulation Library is parsed for its dataRequirements

smart.patient.request(`${type}?${query}`)

The dataRequirements contain the resources required, which can then be requested from the fhir server.

PREPOPULATION AND APP FUNCTIONS


Prepopulation


• The questionnaire contains references to variable names in the CQL, which are used to match CQL statements to questions

• The questionnaire is recursively searched for questions‒ Questions with a cqf expression are matched with one of the CQL results‒ The QuestionnaireResponse answers are autofilled, then used to initialize

the UI

Prepopulation


First the CQL is executed on the collected resources. As mentioned before, the main CQL is accompanied by other CQL files referenced in the library

patientSource.loadBundles([resourceBundle]); //the resource bundle contains loaded resourcesconst elmResults = executeElmAgainstPatientSource(executionInputs, patientSource);

The elm results match CQL variables to their calculated values

Prepopulation


1.DeviceRequestedIsPortable: false2.DeviceRequestedIsStationary: true

"url": "http://hl7.org/fhir/StructureDefinition/cqf-expression","valueExpression": {"language": "text/cql","expression": "\"HomeOxygenTherapyPrepopulation\".DeviceRequestedIsPortable"

In the Questionnaire

In the CQLdefine DeviceRequestedIsPortable: "DeviceRequestHcpcsCoding" in "Portable Oxygen Therapy Device"

DTR App Prepopulation Results

Prepopulation

• The questions in the questionnaire can easily be matched with result from the CQL execution

• The QuestionnaireResponse is filled out with these results, and used to initialize the first rendering of the form in the user interface


INTEROPERABILITY


Interoperability Notes


• Integrating with EHRs brings some unforeseen issues

• Some of these interoperability issues fall outside of the scope of the DTR IG

• Though the SMART interaction is standardized, and the DTR app is being standardized through the IG, there are still areas where it is not yet clear how the DTR app and the EHR should connect.



• Usage of different browsers can hamper the javascript-based DTR app

• Epic uses IE11 for its EHR, which is incompatible with some libraries and functions of modern javascript

• In order to work around this, our code had to be updated to use polyfills, or avoid some functions altogether, to work on IE11

• Polyfills are meant to produce the functionality you expect from the browser

import '@babel/polyfill'

import 'react-app-polyfill/ie11’;

import "isomorphic-fetch";

Some functions that work in Google Chrome don’t work in IE11, and polyfillsare written specifically to replace those functions without changing what they do



• When dealing with FHIR resources, EHRs typically have strict rules restricting their content and access

• Many of our test resources were rejected for not following EHR specific profiles

• Some resources are simply not supported by the EHR, and must be replaced with another resource type

• Information the app needs might be stored in different locations

• Some EHRs require different scopes to be requested, though the SMART spec allows for apps to request access to all resources, some servers reject this request and require that each resource be individually requested.



• Requests made to the EHR need to be formatted correctly

• Responses from the EHR need to be parsed correctly

• Though basic, some FHIR servers return XML by default, and some return JSON. Similarly, some EHRs store information, such as the patients practitioner, in different places, and some of the code had to be modified to handle different cases.

var conformanceUri = log.serviceUri + "/metadata?_format=json";

THANK YOU!


DTR SMART APP - confluence.hl7.org

Documents

Transcript of DTR SMART APP - confluence.hl7.org