What is CDS-Hooks?

CDS Hooks is both a free open-source specification and an HL7® published specification for user-facing remote clinical decision support (CDS). CDS Hooks can use FHIR® to represent patient information and recommendations but is architecturally an independent specification. The CDS Hooks specification is licensed under a Creative Commons Attribution 4.0 International License.

HL7 Fast Healthcare Interoperability Resources (FHIR) Logo

Note: HL7®, and FHIR® are the registered trademarks of Health Level Seven International and their use of these trademarks does not constitute an endorsement by HL7.

Learn More

The four basic components of CDS Hooks are:

  • Service – A decision support service that accepts requests containing patient information, and provides responses
  • Hook – A defined point within the client system’s workflow with well-known contextual information provided as part of the request
  • EHR – An electronic health record, or other clinical information system that consumes decision support in the form of services
  • Card – Guidance from decision support services is returned in the form of cards, representing discrete recommendations or suggestions that are presented to the user within the EHR

In 2015, The SMART team launched the CDS Hooks project to trigger third party decision support services. Today, Clinical Decision Support (CDS) Hooks is a Health Level Seven International® (HL7) specification managed by the HL7 Clinical Decision Support (CDS) Workgroup. CDS Hooks provides a way to embed near real-time functionality in a clinician’s workflow when an EHR (Electronic Health Record) system notifies external services that a specific activity occurred within an EHR user session. For example, services can register to be notified when a new patient record is opened, a medication is prescribed, or an encounter begins. Services can then return “cards” displaying text, actionable suggestions, or links to launch a SMART app from within the EHR workflow. A CDS service can gather needed data elements through secure Fast Healthcare Interoperability Resources® (FHIR®) services. Using FHIR services allows CDS Hooks to provide interoperability between healthcare systems operating on different platforms.

SMART – Substitutable Medical Applications, Reusable Technologies
The SMART Health IT project is run out of the Boston Children’s Hospital Computational Health Informatics Program. Through co-development and close collaboration, SMART and FHIR have evolved together since the SMART standard enables FHIR to work as an application platform. The SMART project’s most recognized work is the “SMART on FHIR” application programming interface (API) which enables an app written once to run anywhere in a healthcare system.
SMART on FHIR (Fast Healthcare Interoperability Resources)
SMART on FHIR defines a way for health apps to securely connect to EHR systems. A SMART on FHIR application or service executes via SMART specifications on a FHIR system, extending its functionality through the use of clinical and contextual data. Together with the FHIR models and API, the SMART on FHIR specification components include authorization, authentication, and UI integration.

Who Uses CDS Hooks?

CDS Hooks support is built into all the major EHR products including EPIC, Cerner, Allscripts and athenahealth. Indeed, every type of healthcare organization from large-scale HMOs like UnitedHealth Group, Anthem, Kaiser, and Humana; to PPOs like Clover Health; to teaching hospitals like the University of Utah, Stanford Hospital, Mayo Clinic, and North Shore University Hospital (Northwell); to professional organizations like the American College of Emergency Physicians (ACEP) and the American College of Obstetricians and Gynecologists (ACOG) have access to these technologies.

Standards-Based Implementation of CDC Recommendations use the CDS Hooks interoperability framework for the integration of the guideline recommendations into EHR systems.

In the United States, SMART support is specifically referenced in the 21st Century Cures Act of 2016. The 21st Century Cures Act requires a universal API for health information technology, providing access to all elements of a patient’s record accessible across the SMART API, with no special effort. CDS Hooks are typically implemented as SMART applications.

What is CDS Hooks Used For?

CDS Hooks enables the creation of standard places within the EHR workflow where the EHR can issue a notification of an event that is happening. This notification can be received by an external (typically SMART) application which returns pertinent information to the EHR for display to the EHR user. In FHIR-speak, the information returned is a “card.” Cards can be of three types:

  • Information card – Conveys text that may be useful for the clinician
  • Suggestion card – Provides suggestions for the clinician
  • App Link card – Links to reference materials or apps

Because FHIR is an open-source standard, new hooks can be created by any interested party. Today, there are six standard “hooks,” which have been defined as part of Version 1 of the standard:

  1. patient-view – Patient View is typically called only once at the beginning of a user’s interaction with a specific patient’s record
  2. order-select – Order Select fires when a clinician selects one or more orders to place for a patient (including orders for medications, procedures, labs and other orders). If supported by the CDS Client, this hook may also be invoked each time the clinician selects a detail regarding the order
  3. order-sign – Order Sign fires when a clinician is ready to sign one or more orders for a patient, (including orders for medications, procedures, labs and other orders).
  4. appointment-book – Appointment Book is invoked when the user is scheduling one or more future encounters/visits for the patient
  5. encounter-start – Encounter Start is invoked when the user is initiating a new encounter. In an inpatient setting, this would be the time of admission. In an outpatient/community environment, this would be the time of patient-check-in for a face-to-face or equivalent for a virtual/telephone encounter
  6. encounter-discharge – Encounter Discharge is invoked when the user is performing the discharge process for an encounter where the notion of ‘discharge’ is relevant – typically an inpatient encounter

Prescription writing is an example you can use to visualize the way this technology works. In the EHR the event of writing the prescription triggers a CDS Hooks (order-select). The hook can be received by a patient engagement application. The application then returns a Suggestion card recommending that the patient be provided educational materials, enrollment into a support program and given an offer for copay assistance. An Information card indicating drug/drug or drug/disease adverse reactions might also be supplied.

The CDS Hooks Standard

The CDS Hooks Standard

The CDS Hooks specification and Implementation Guide describes the RESTful APIs and interactions to integrate Clinical Decision Support (CDS) between CDS Clients (typically EHRs but possibly other health information systems) and CDS Services. All data exchanged through the RESTful APIs is sent and received as JSON structures and transmitted over channels secured using HTTPS (Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS).

This specification describes a “hook”-based pattern for invoking decision support from within a clinician’s workflow. The API supports:

  • Synchronous, workflow triggered CDS calls returning information and suggestions
  • Launching a user-facing SMART app when CDS requires additional interaction

User activity inside the clinician’s workflow, typically in the organization’s EHR, triggers CDS hooks in real-time. Examples of this include:

  • patient-view when opening a new patient record
  • order-select on authoring a new prescription
  • order-sign on viewing pending orders for approval

When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow context (via the context parameter of the hook) plus whatever service-specific data are required. This data is often provided by the FHIR prefetch functionality of the CDS Hooks Discovery URL.

Each CDS service can return any number of cards in response to the hook. Cards convey some combination of text (Information card), alternative suggestions (Suggestion card), and links to apps or reference materials (App Link card). A user sees these cards, one or more of each type, in the EHR user interface, and can interact with them as follows:

  • Information card: read the informational text
  • Suggestion card: read a specific suggestion(s) for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician’s EHR user interface
  • App Link card: click a link to an app (typically a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision

A good way to get a single-page technical overview of CDS Hooks including Discovery, Request and Response specs is to view the CDS Hooks “cheat sheet”.

Download Cheat Sheet

Trisotech and CDS Hooks

Trisotech CDS Hooks option generates CDS Hooks compliant end points for Trisotech automation services.

Learn More
Digital Automation Suite logo

CDS Hooks Discovery Endpoint

Trisotech modeling and automation platforms support the CDS Hooks 1.0 standard for processing and data prefetch in the Workflow and Decision Management modelers. Once the desired actions are modeled, publishing the models to the Service Library for automation purposes automatically provides a CDS Hooks Discovery endpoint URL for that service. That endpoint describes the CDS Service definition including the prefetch information required to invoke it according to the CDS Hooks 1.0 standard. Currently, this endpoint implements the standard CDS Hooks discovery endpoint for Patient View (patient-view).

CDS Hooks FHIR Prefetch

Using the CDS Hooks endpoint features requires preparation through entries in model inputs. Each input that will be prefetched from FHIR needs to have a custom attribute called FHIR that contains the query for the prefetch. For example, in a Workflow Data Input shape the custom attribute to prefetch the current patient information might look like this: FHIR: Patient/{{context.patientId}}

If you were using a decision model the DMN Input shape to prefetch a specific-code observation from the current patient might have a custom attribute like this: FHIR: Observation?subject={{context.patientId}}&code=29463-7

If your model is properly configured with the FHIR custom attributes and published to the Trisotech Service Library, an HTTP “GET” on the provided endpoint will result in a JSON description of the service. Each CDS Service is described by the following attributes:

Field Optionality Type Description
hook REQUIRED string The hook this service should be invoked on
title RECOMMENDED string The human-friendly name of this service
description REQUIRED string The description of this service
id REQUIRED string The {id} portion of the URL to this service which is available at {baseUrl}/cds-services/{id}
prefetch OPTIONAL object An object containing key/value pairs of FHIR queries that this service is requesting that the EHR prefetch and provide on each service call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query.

Also, the prefetched data can be “POST”ed at the base URL (removing the /cds-services from the discovery URL) to execute the service.

CDS Card FEEL Templates

Trisotech modeling also supplies modeling templates for all three types of CDS Cards. Information, Suggestion and App Link card templates are available in the FEEL language format for inclusion in Decision and Workflow models.

CDS Card Automatic Default Generation and Explicit Card Mapping

A CDS Card is automatically generated from the service unless your service is designed to explicitly output cards. By default, an Information card that has the name of the service as its summary will be automatically generated. Each service output will be added to the card detail in the format Key: Value.

For explicit mapping needs, if your model/service outputs a data type that is consistent with the CDS Card definition (required fields: summary, indicator, and source), only these outputs will be transformed to cards. It should be moted that your model/service can have one or many outputs that are CDS Cards. An output can also be a collection of cards. The data type of the output is what is considered to determine if explicit mapping is used for a service.

CDS Hooks Sandbox Testing

The CDS Hooks community provides a publicly available sandbox for services testing and all Trisotech modeling/service CDS Hooks features are tested and demonstrated using the CDS Hooks sandbox.

CDS Hooks Continuous Improvement

Trisotech is continuously improving CDS Hooks features including plans to add additional Version 1 standard hooks such as order-select, encounter-start, etc.



View all

Learn how it works

Request Demo

Confirm your budget

Request Pricing

Discuss your project

Request Meeting