Home

Clinical Decision Support (CDS) Hooks is a specification that enables integration of remote decision support within a clinician's EHR workflow through a "hook"-based pattern. See more here.

This tutorial will help walk you through setting up real CDS Services and acting as the 3rd party providing decision support to an EHR system.

After completing this tutorial, you should be able to:

• Understand the exchange between the EHR and 3rd party CDS Services
• Stand up local CDS Services that can integrate with the CDS Hooks Sandbox
• See how FHIR and SMART work within CDS Hooks

Define Terms

Before we dive in, we can define a few terms that will be used commonly throughout this tutorial.

hook - An event triggered by the EHR as part of the clinicians workflow. The EHR will invoke 3rd party CDS services registered to this event.

CDS Service - A 3rd party service set up to observe EHR activity. Specifically, this service listens for a specific hook to be invoked by the clinician. When the hook is invoked, the EHR calls upon this service, and the service may decide whether or not to respond with decision support back.

card - One type of response the CDS Service can give when called upon by the EHR. It is an entity containing all the information the CDS Service wants to display on the EHR. These cards can contain textual information, suggestions to add/remove/update FHIR resources (mostly pertaining to the patient), or even links to external web pages or SMART applications.

patient-view - A spec-defined hook where the clinician opens a patient's chart in the EHR

medication-prescribe - A spec-defined hook where a clinician authors a new prescription

sandbox - The CDS Hooks Sandbox web application that acts as a mock EHR. With this tool, you can simulate opening a patient's chart and prescribing a medication with a patient in context. Additionally, you can configure your own CDS Services to test functionality as if being invoked by a real EHR system. You can reach the sandbox at http://sandbox.cds-hooks.org.

Goal

Our goal of this tutorial is to set up two services that respond to the patient-view and medication-prescribe hook respectively through a server-side application. We will test these services using the CDS Hooks Sandbox. Let's define the scenarios for each service, and what our services should do.

patient-view-example: Invoked by the patient-view hook, this service should simply prefetch the Patient FHIR resource for the patient in context of the EHR and display a message on a card with the patient's first and last name. Additionally, this service will add a link on the card with the URL to the CDS Hooks spec.

medication-prescribe-example: Invoked by the medication-prescribe hook, this service should read the FHIR context the EHR provides (medication being prescribed), and display a suggestion (button) to switch the medication to Aspirin 81 MG Oral Tablet. If the medication prescribed is that specific Aspirin we want to suggest, or the provider has "clicked" on the suggestion already, the service will provide a message on a card confirming their medication choice.

Prerequisites

The following are necessary to work with this tutorial application:

• Git installed on your machine
• A Github account created
• Node.js (min. v 8.4.0) installed on machine
  • To make sure it's ready to use, open your command prompt or terminal console and type the command node -v which should respond with the Node.js version installed on the machine

If you are having some trouble with installing/updating Node.js, see the FAQ.

Project Overview

Let's go over some important files and tools in this project:

package.json - Here is where the metadata for the project lives. This contains the dependencies required for this project as well as the scripts used to run our application. You can read more about this file here.

index.js - This is where our application logic lives. This file sets up app configuration and how to respond to specific GET and POST requests to our CDS Service routes.

We will use Node.js for this project, which allows us to write server-side logic in JavaScript to handle HTTP requests to our server. To simplify this, we will use the Express framework, which is a Node.js web application framework that contains several HTTP utility methods and middleware to use.

Project Setup

Once you have completed all the prerequisites, it's time to setup the project locally on your machine. Complete the following steps:

1. Login to your Github account and navigate to the tutorial repository.
2. Clone the repository down to your machine using the following steps:
   • In your command prompt or terminal, navigate to the folder you would like your local copy of the repository to live
   • Once you're at the location in your file system, type the following command to clone the local copy of the repository to your machine:

     git clone https://github.com/uw-fhir/cds-services-tutorial.git

   • Navigate inside the local cds-service-tutorial repository folder on your command prompt or terminal
3. Once you're inside the project directory, type the command npm install to install all dependencies for the project

If the above steps have all been done successfully, you can run the project by typing the command npm run start-server. This will start the express application, which will be hosted locally for you, and can be accessible at:

http://localhost:3000

How it Works

Let's look at how this application starts up. Begin by looking inside the project directory at the index.js file, which is where all the host code for our Express application lives. You can open up this file with any text editor of your choice and walk through the code for this tutorial.

const express = require('express');
const bodyParser = require('body-parser');
const app = express();

The first 2 lines of code are creating variables that reference two very important dependencies. We pulled these dependencies in via the command npm install from above.

• express - As we mentioned above, Express is a framework for Node.js which allows us to use several HTTP methods to handle routing, as well as middleware.
• body-parser - This dependency is a middleware necessary to parse the body of an incoming request; specifically, from POST requests. This allows the application to get data the EHR may send in a POST request to our CDS Services.

On that last line above, we construct an Express instance in a variable called app that will expose the Express API that we can use throughout our application.

At this point, we can define a middleware that will parse incoming request bodies to our services as JSON, for those potential POST HTTP requests.

...
app.use(bodyParser.json());
...

And finally, we need to allow the app to be hosted on some port, so let's define this app to listen in at port 3000 for the purposes of this tutorial. We can define this at the bottom of the application.

...
app.listen(3000);

Next step: Cross Origin Resource Sharing (CORS)