Patient View Service

Goal: To display a card containing a message with the patient's first and last name, along with an absolute link to the CDS Hooks web page.

See documentation on the EHR calling a CDS Service: https://cds-hooks.org/specification/current/#calling-a-cds-service

See documentation on the CDS Service response: https://cds-hooks.org/specification/current/#cds-service-response

As we defined in our discovery endpoint, we have a CDS Service set up to listen for the patient-view hook to be invoked. Once this hook is invoked, the EHR may decide to call upon our patient-view-example CDS Service to provide support. This call to our service must be from a POST HTTP request that contains a JSON POST body with various fields that give our service context information to proceed with decision support. An example request body might look similar to this:

{
  "hookInstance" : "88f0dc37-e374-4bbd-8927-124b287ca092",
  "fhirServer" : "https://sb-fhir-dstu2.smarthealthit.org/api/smartdstu2/open",
  "hook" : "patient-view",
  "user" : "Practitioner/example",
  "context" : {
    "patientId" : "Patient-1",
  },
  "prefetch" : {
    "requestedPatient" : {
      "resourceType" : "Patient",
      "id" : "Patient-1",
      "name": [ 
        {
          "text": "Adams, John",
          "family": [
            "Adams"
          ], 
          "given": [
            "John"
          ],
          "use": "official"
        }
      ],
      "birthDate" : "1925-12-23",
      // {...snipped for brevity...}
    }
  }
}

As shown above, the entity may post back to our patient-view-example service with the prefetch property containing the Patient resource associated with the patient whose chart was just opened by a clinician. Since this FHIR resource contains the name of the patient, we should be able to parse this request body for the name, and create a card to display it. But first, let's see how we can expose our patient-view-example CDS Service for the EHR to call.

  app.post('/cds-services/patient-view-example', (request, response) => {
    ...
  });

Here, we define the method that allows POST HTTP requests to our /cds-services/patient-view-example endpoint. The key to getting the data from the POST body will be in the request object, which we can parse simply by using request.body. At this point, we will be able to get a JSON object similar to that above. Now we can start on the logic inside this block of code to send a response back to the EHR.

// This is where we construct the body of the service response
const patientResource = request.body.prefetch.requestedPatient;
const patientViewCard = {
    cards: [
      {
        // Use the patient's First and Last name
        summary: 'Now seeing: ' + patientResource.name[0].given[0] + ' ' + patientResource.name[0].family[0],
        indicator: 'info',
        links: [
          {
            label: 'Learn more about CDS Hooks',
            url: 'http://cds-hooks.org',
            type: 'absolute'
          }
        ]
      }
    ]
};
response.send(JSON.stringify(patientViewCard, null, 2));

On the first line above, we parse the request body to get the prefetch object, and access the FHIR resource via the prefetch key requestedPatient, which we defined in our service definition in the discovery endpoint of our application. Once we store this in a variable, we can construct our card according to the spec (see CDS Service response documentation at the top of the section). And just like our discovery endpoint, we must send back a response in JSON format. In the last line, we send the JSON object with our array of cards in the response. As a default, this response will have a HTTP 200 status code.

Other Considerations

Here are a few questions to think about as it pertains to this specific CDS Service and as you are looking to make your CDS Services more robust:

• The EHR is not required or expected to prefetch whatever data a CDS Service needs. As a result, it may not return the prefetch key in the POST request body. What should the CDS Service do in this case?
• What should the CDS Service do if the first OR last name is not included in the patient resource?
• Notice that we included an absolute link to the service response body in our card. Not only can we provide links to other web pages, but we can also provide SMART app links as well. Instead of an absolute type, we indicate a smart type. In the url field, we can define the SMART launch URL. The EHR will take care of appending the necessary parameters to run the SMART app when clicked on.

Next step: Order Select Service