DTR SMART on FHIR App

This subproject contains a SMART on FHIR app, which provides a standardized way to interact with FHIR servers. This Reference Impementation (RI) supports the Documents Templates and Rules (DTR) IG which specifies how payer rules can be executed in a provider context to ensure that documentation requirements are met. This RI and IG are companions to the Coverage Requirements Discovery (CRD) IG and Coverage Requirements Discovery (CRD) RI.

A live demo is hosted by HL7 FHIR Foundry, where you may also download curated configurations to run yourself.

Running DTR

You can find a complete end-to-end set up guide for DRLS, including DTR, here.

Getting Started

If you are running DRLS for the first time, we highly recommend you refer to our comprehensive setup guide for instructions on how to install DTR. Once you have DRLS up and running, you can return here to find more detailed information about how DTR works.

Prerequisites

Install Node.js 16 (Node 18+ not currently supported)

Installation

1. Clone the repository git clone https://github.com/HL7-DaVinci/dtr.git
2. In a terminal, navigate to the directory the project was cloned into
3. Run npm install
4. To Run:
   • dev: npm start
   • production: npm run startProd

The service will run on port 3005. This can be changed in package.json and the configuration file for the desired version. The dev version is configured with webpack.config.js and does not use https by default. The production version is configured through webpack.config.prod.js and does use https by default. This can also be changed in the desired config by changing the https boolean. There is currently no redirection between https and http, so using the wrong scheme in the url will result in an empty response.

Using the App

EHR Launch

Once the app is up and running you can launch it manually by visiting the launch page and including the two required parameters:

Param	Description
iss	The base URL of the FHIR server
launch	The unique ID for this launch

The FHIR server must properly comply with the SMART on FHIR specification and have a conformance statement with a security section that contains the authorization endpoints that the app needs to request a token from.

For example, http://localhost:3005/launch?iss=http://launch.smarthealthit.org/v/r2/fhir/&launch=1234 is an example of a valid launch url that will successfully launch the app. Note that the launch id is generally not something the user defines themselves, but rather is generated by the EHR and is automatically appended to the url parameters as part of the launch sequence when clicking on a SMART link.

Standalone Launch

The app can be launched standalone by omitting a launch id. Unlike an EHR launch, standalone launches can be initiated outside of an EHR context and don't require the generation of a launch id. Simply navigate to the launch url and include the iss parameter to initiate a standalone launch.

An example url that launches the standalone app is http://localhost:3005/launch?iss=http://launch.smarthealthit.org/v/r2/fhir/. When the app is launched standalone, it authenticates against the EHR referenced by the iss, but does not have any context such as patient ID or device request. Instead, the app will allow the user to select a patient from a list if that patient has an outstanding in-progress questionnaire available. If there are no in-progress questionnaires in the EHR, the standalone launch cannot proceed.

Connecting with other subprojects:

It is recommmended when first starting out you have all five applications running (CRD Request Generator, Test EHR (FHIR) Server, CRD Server, DTR Server, and KeyCloak Server) to test the full SMART on FHIR App launch sequence. After getting these applications up and running you can swap in your appliaction if desired.

Note: If you have your own EHR then you should not need to run the EHR (FHIR) Server, KeyCloak and the Request Generator. Otherwise please follow the below steps.

Steps to prepare local EHR server, Keycloak server, and Request Generator:

1. Remove the target folder (if it exists) in the Test EHR server folder.

2. Start the Test EHR server, by running gradle appRun.

3. Make sure the Test EHR server has the data it needs, by running gradle loadData to populate it.

4. Then, run the KeyCloak server. Follow the guide in the CRD readme if you have never set it up before, make the appropriate realm/client/user.

5. Then run the CRD server, DTR server, and CRD Request Generator.

   Note: The DTR app's authorization against the EHR server requires a client_id that is registered with the auth server of that EHR to work. The DTR app has a /register endpoint that allows user entry of which client_id to use for a specific EHR server. If following the KeyCloak guide provided in the CRD readme, the client would be called app-login.

Test it!

Assuming you have completed the above. You should be able to send a request from the CRD Request Generator in order for the SMART app to launch by clicking the Patient Select: button to pre-populate the inputs. Choose a Device, Service, or Medication Request from the drop-down for one of the patients, then click anywhere in the row corresponding to the patient for whom you selected a Device, Service, or Medication Request. The data will be prefetched and you can send the request by pressing the Submit button. You should get a CDS Hooks Card back. Click the SMART link button for Order Form and you should see a login screen. Login with whatever user you've registered, and the SMART App should proceed to launch.

CDex Task-Based Launch

An implementation of the CDex task-based launch is available. This launch is available at /launch-cdex?iss=<FHIR server>&launch=<launch id>.

A launch helper form is available at /cdex. If running locally, this is available at http://localhost:3005/cdex

Building Releases

Official releases are built automatically, but you may test the process or roll your own similar to the following:

docker build -t hspc/davinci-dtr:latest .

To run dev (https=false, port=3005, proxy=http://localhost:8090):

docker run -it --name davinci-dtr -p 3005:3005 --rm hspc/davinci-dtr:latest

To run production (https=true, port=3005, proxy=https://davinci-crd.logicahealth.org):

docker run -e VERSION='Prod' -it --name davinci-dtr -p 3005:3005 --rm hspc/davinci-dtr:latest

To run configurable template:

docker run -e VERSION='Template' -e PROXY_TARGET='http:\/\/localhost:8090' -e SERVER_PORT='3005' -e SERVER_HTTPS='false' -it --name davinci-dtr -p 3005:3005 --rm hspc/davinci-dtr:latest

The configurable template will use the environment variables passed to the docker run command to replace the PROXY_TARGET, SERVER_PORT, and SERVER_HTTPS values in the webpack configuration file.

Other Documentation

Using ValueSets in DTR Rules

License

This project is licensed under the Apache License 2.0. See LICENSE for more details.

Questions and Contributions

Questions about the project can be asked in the Da Vinci DTR stream on the FHIR Zulip Chat.

This project welcomes Pull Requests. Any issues identified with the RI should be submitted via the GitHub issue tracker.

As of October 1, 2022, The Lantana Consulting Group is responsible for the management and maintenance of this Reference Implementation. In addition to posting on FHIR Zulip Chat channel mentioned above you can contact Corey Spears for questions or requests.