CDS Hooks

The CDS Hooks extension enables the system to provide clinical decision support in the form of advice or alert cards triggered by specific clinical workflows.

CDS Hooks allows an Electronic Health Record (EHR) system (the CDS Client) to call an external CDS Service at defined points in a workflow — for example when viewing a patient chart or selecting an order. The CDS Service evaluates the provided clinical context and returns actionable recommendations.

To generate meaningful recommendations, CDS Services require access to specific FHIR® resources. In theory, a CDS Service could receive minimal context information (such as patient and user identifiers) and retrieve all necessary data directly from the client’s FHIR API. However, CDS Hooks is designed for near real-time interactions (typically within ~500 milliseconds). Performing multiple FHIR requests at runtime can negatively impact performance.

To address this, the specification supports performance optimization through prefetching.

Prefetching

Prefetching allows the CDS Client to send relevant FHIR® data to the CDS Service in advance, as part of the hook request.

During service discovery, the CDS Service defines prefetch templates. These templates describe the FHIR read or search requests required for decision logic. When the hook is triggered, the CDS Client executes these queries and includes the results directly in the service call.

• Prefetched data is passed as key-value pairs
• Each key corresponds to a template defined during discovery
• The value contains the resulting FHIR resource
• For search operations, the value may be a FHIR searchset Bundle

Prefetch configuration is explained in detail in the CDS Hooks standard.

Configuration

The plugin is configured using the following parameters:

• Type: Defines when the CDS Service is triggered. Supported values:
  • Patient View or
  • Order Select
• Title: The display title of the CDS service
• Description: A short explanation of the service’s purpose
• Prefetch configuration: (optional) Defines FHIR queries to be executed in advance and supplied to the service

Prefetch configuration

A prefetch template defines a FHIR read or search request that retrieves relevant clinical data needed by the CDS Service.

Using the prefetch editor, you define named entries consisting of:

• A key (identifier)
• A value (FHIR query)

The EHR executes these queries before invoking the CDS Service and passes the results as part of the hook request payload.

In the example below, the full value for the key report is defined as:

DiagnosticReport?subject=Patient/{{context.patientID}}&_total=accurate&_include=Observation:result

This query template instructs the calling system to retrieve the DiagnosticReport resources including its result observations and provide them in the argument object:

{ "prefetch": { "report": <here> } }

Example configuration

Usage

MLM

An MLM is attached to a CDS Hook by listening to it through its evoke slot. When the CDS Hook of a plugin is called, all attached MLMs are called, any cards they return are collected into a list and that list of cards is sent back to the calling system.

Each MLM receives a single argument with the hook request, as per documentation. It is expected that the calling system provides the prefetch resources, but this is not verified by the API.

knowledge:
   	type: data_driven;;
   	data:
		// Request as argument, prefetch is accessed like request.prefetch.report
		request := Argument;
		// Expected result object definition
		CdsCard := OBJECT [summary, detail, indicator, source, suggestions, selectionBehavior];
		// CDS Hook event definition
		MyCdsHook := EVENT { FROM my-cds-hook };
    ;;
	logic:
		card := return new CdsCard with [
			summary := "A summary of the alert card",
			indicator := "warning" // Severity of the alert card (info, warning, critical)
		]
		conclude true;
	;;
	action: return card;;
   	priority: 50;;
   	evoke: MyCdsHook;
;;

API

Listing and calling hooks is supported in the standardized way via REST API