Communicate with CDS Hooks Endpoints
An HL7® CDS Hooks server—such as the InterSystems® Healthcare Action Engine (HAE)—provides an API to support three types of interactions:
-
Discovery: the client application sends a request to the CDS Hooks server’s discovery endpoint to receive information about the services that are available at that server, including the HL7® FHIR® resources required by each service.
-
Service: the client invokes one of the available services by sending a request to the endpoint for the service. This request provides access to any FHIR resources that the service requires to perform its evaluation. The server responds to a valid service call with the appropriate cards or system actions, if any.
-
Feedback: optionally, the client sends information about the end user’s response to a card to the feedback endpoint for the service.
This page provides information about each interaction type. It also includes a brief guide to the HTTP status codes which Healthcare Action Engine may return to the client.
For a detailed walkthrough of a complete CDS Hooks interaction, see A Closer Look at CDS Hooks Interactions
As mentioned in Prerequisites, under most circumstances a request to a CDS Hooks server must authorize itself by presenting a single-use JWT from the server’s designated authorization server. A service request which requires the CDS Hooks server to fetch FHIR resources must provide an access token which allows HAE to query the client application’s FHIR repository.
Discover Available Services
When a client application sends a valid GET request to the discovery endpoint, HAE responds by providing a service description about every synchronous CDS Hooks service which is currently active. The description for a service contains all the information necessary to invoke it, including the service’s ID, its associated hook, and the FHIR resource data it requires to perform its evaluation.
Refer to the CDS Hooks specification for an exhaustive description of the structure of discovery requests and responses: https://cds-hooks.hl7.org/2.0/#discoveryOpens in a new tab.
https://<baseURL>/csp/healthshare/<hsnamepsace>/cds-hooks/<fhir-version>/cds-services
Where:
-
<baseURL> — the base URL for the server.
-
<haeNamespace>— the name of the namespace where the CDS Hooks services are running.
-
<fhir-version> — the FHIR version (either stu3 or r4).
GET https://example.com/csp/healthshare/hshae/cds-hooks/r4/cds-services
Invoke a Service
A client application invokes a service by sending a valid POST request to the endpoint for that service. The service endpoint can be constructed programmatically given the service ID, which the discovery response provides for each available service.
Each service requires FHIR resource data to perform a meaningful evaluation. (The discovery response also specifies the data required by each available service.) The client application must provide access to this data in the body of the service request using one of the following methods:
-
The client fetches the data prior to sending the service request, and then passes along the “prefetch” data within the request body.
-
The client acquires an OAuth 2.0 access token from the FHIR repository’s authorization server which will allow HAE to query the FHIR repository directly for the data it requires. The client includes the access token along with other FHIR resource access parameters (see https://cds-hooks.hl7.org/2.0/#fhir-resource-accessOpens in a new tab) in the body of the service request.
-
The client combines methods (1) and (2): the service request body provides some prefetch data; it also provides FHIR resource access parameters which HAE can use to query the FHIR repository for the rest of the data.
The structure of a complete CDS Hooks interaction varies considerably depending upon which of these methods is used; see A Closer Look at CDS Hooks Interactions.
The body of the response to a service request contains all cards or system actions which are relevant to the given conditions. If no cards or system actions apply, the body of the service response is an empty JSON object.
For an exhaustive description of the service interaction, refer to the CDS Hooks specification: https://cds-hooks.hl7.org/2.0/#calling-a-cds-serviceOpens in a new tab.
https://<baseURL>/csp/healthshare/<hsnamespace>/cds-hooks/<fhir-version>/cds-services/<serviceID>
Where:
-
<baseURL> — the base URL for the server.
-
<haeNamespace> — the name of the namespace where the CDS Hooks services is running.
-
<fhir-version> — the FHIR version (either stu3 or r4).
-
<serviceID> — the ID of the service that you wish to invoke. You can obtain this ID by making a request to the discovery endpoint.
POST https://example.com/csp/healthshare/hshae/cds-hooks/r4/cds-services/MeningococcalVaccineCheck
{
"cards": [
{
"summary": "Patient is >= 12 and has not had a Meningococcal
Vaccine in the last year",
"detail": "",
"indicator": "warning",
"source": {
"label": "CDC guidelines",
"url": "https://www.cdc.gov/vaccines/schedules/hcp/imz/child-adolescent.html",
"icon": "",
"topic": []
},
"selectionBehavior": "at-most-one",
"suggestions": [
{
"label": "Order Meningococcal ACWY vaccine",
"isRecommended": true,
"actions": []
},
{
"label": "meningococcal B, recombinant vaccine",
"isRecommended": false,
"actions": []
}
],
"overrideReasons": [
{
"code": "1234",
"system": "sampleSystem",
"display": "parent refused to vaccinate child"
}
],
"links": []
}
]
}
Provide Optional Feedback
When the client application displays a card that it has received from a CDS Hooks service, the client application’s end user may choose to interact with the card by accepting or overriding its suggestions. The client application can share information about how the user interacted with a service’s output by sending a POST request to the feedback endpoint for the service.
According to the CDS Hooks specification, the feedback interaction is optional. However, your organization may be subject to reporting requirements which require your application to submit feedback.
The HL7 CDS Hooks specification provides an exhaustive description of the structure of the feedback request: https://cds-hooks.hl7.org/2.0/#feedback.Opens in a new tab
https://<baseURL>/csp/healthshare/<haeNamespace>/cds-hooks/cds-services/<serviceID>/feedback
Where:
-
<baseURL> — the base URL for the server.
-
<haeNamespace> — the name of the namespace where the CDS Hooks services are running.
-
<serviceID> — the ID of the service you have invoked.
POST https://example.com/csp/healthshare/hshae/cds-hooks/r4/cds-services/MeningococcalVaccineCheck/feedback
HTTP Status Codes
The following status codes may be returned by a service response:
| HTTP Status Code | Description |
|---|---|
| 200 | (OK) — The service was invoked successfully.
Note:
A successful service may not contain a card response, so this status code may be returned even if the response body contains an empty card array. |
| 400 | (Error) — Error when validating the service request. The request may be invalid structurally (improper JSON, for example), or semantically (an improper service ID is given, for example.) |
| 401 | (Unauthorized) — The bearer token used for authentication failed validation (if it expired, for example). |
| 404 | (Not Found) — The named service does not exist, or is not linked to the hook identified in the request body. |
| 412 | (Precondition Failed) — Error when trying to fetch necessary FHIR data |
| 500 | (Internal Server Error) — Uncaught error was thrown while attempting to invoke the named service. |
The following status codes may be returned by a feedback response:
| HTTP Status Code | Description |
|---|---|
| 200 | (OK) — The service was invoked successfully. |
| 400 | (Error) — Error when validating the feedback request. |
| 401 | (Unauthorized) — The bearer token used for authentication failed validation (if it expired, for example). |
| 500 | (Internal Server Error) — Unexpected error while processing the feedback request. |
