Skip to main content

Introduction to the CDS Hooks API

InterSystems® Healthcare Action Engine (HAE) provides synchronous notifications through an API which implements the HL7® CDS Hooks specification for decision support (https://cds-hooks.org/Opens in a new tab). HAE fulfils the role of a CDS Hooks server, which can be summarized as follows:

  1. A client application—such as an electronic health record (EHR)—can contact a CDS Hooks service on a CDS Hooks server in response to a specified trigger event (a hook).

  2. The service evaluates HL7® FHIR® resources that the client application makes available in order to determine the appropriate response.

  3. The service responds to the client application with a JSON object containing cards or system actions. Cards provide context-based decision support information (such as warnings or suggestions); system actions trigger edits to resources within the client application’s connected FHIR repository.

  4. The client application can display the cards to the end user directly within the end user’s workflow.

For example: an EHR can be configured so that each time a provider views a patient chart (the patient-view hook), the application communicates with a CDS Hooks service which checks whether the patient exhibits indicators of uncontrolled diabetes and provides a warning card if an indicator is present. The EHR can display this warning card to alert the provider that the patient may require special intervention.

The pages which follow briefly describe Healthcare Action Engine’s CDS Hooks API for developers who want to connect an application as a client of a HAE synchronous services. For a hands-on guide, Explore a Healthcare Action Engine Demo models the interactions between a CDS Hooks server and a client using a demo deployment of HAE and a collection of Postman requests. For an exhaustive description of how CDS Hooks works, refer to the official CDS Hooks specification (https://cds-hooks.hl7.org/2.0/Opens in a new tab).

Prerequisites

To communicate with a CDS Hooks server such as HAE, a client application must fulfil a number of requirements, described at length in the CDS Hooks specification (https://cds-hooks.hl7.org/2.0/Opens in a new tab).

Notably, a client application must be able to do the following:

Note:

The list below includes links to InterSystems documentation, to assist readers who are developing client applications using InterSystems technology. If that is not the case, refer to your development tools’ documentation for guidance fulfilling these requirements.

  1. Send and receive HTTPS requests using TLS. Refer to the CDS Hooks specification for details: https://cds-hooks.hl7.org/2.0/#security-and-safetyOpens in a new tab

  2. Acquire digitally-signed JSON web tokens (JWT) from a recognized authorization server. The client must authorize each request it sends to the CDS Hooks server with a new JWT according to the procedure outlined in the CDS Hooks specification: https://cds-hooks.hl7.org/2.0/#trusting-cds-clientsOpens in a new tab

  3. Provide services on the CDS Hooks server with access to relevant FHIR resource data from its connected FHIR repository (or repositories). As described previously, CDS Hooks services evaluate FHIR resource data to determine the appropriate response. The client application can provide access to this data in multiple ways; see Invoke a Service.

Communicate with CDS Hooks EndpointsNext section
FeedbackOpens in a new tab