A Closer Look at CDS Hooks Interactions
How your client application interacts with an HL7® CDS Hooks server (such as the InterSystems® Healthcare Action Engine) depends upon the method by which it provides access to the HL7® FHIR® resource data that a service requires:
-
Prefetching: the client application fetches the data prior to sending the service request, and then passes along the “prefetch” data within the service request body.
-
Delegated access: the client application acquires an OAuth 2.0 access token from the FHIR repository’s authorization server to access the FHIR repository and includes FHIR resource access parametersOpens in a new tab within the service request body. The CDS Hooks server uses the token to query the client’s FHIR repository for the data required by the service.
-
Hybrid: the client application provides some “prefetch” data and FHIR resource access parameters within the service request body. The CDS Hooks server uses the access token to request any required data which was not prefetched.
This page diagrams the structure of a complete CDS Hooks interaction for each of the aforementioned three methods. Each interaction begins with discovery, concludes with optional feedback, and includes all the necessary authorization requests along the way.
The diagrams that follow assume that the client application receives authorization to access the CDS Hooks server (HAE) by means of bearer tokens issued by an OAuth 2.0 server.
Provide Prefetched Data
When the client application obtains the FHIR resource data required by a given service prior to performing the service request, a complete CDS Hooks interaction proceeds as follows:
-
The client application acquires a bearer token for the discovery request from the OAuth 2.0 server. This token authorizes the client application to access the discovery endpoint for the CDS Hooks server (HAE).
-
The client sends a discovery request, and receives descriptions for all currently active CDS Hooks services.
-
Using information from the service description, the client application obtains authorized access to its FHIR repository and acquires (“prefetches”) the FHIR resource data which the desired service requires to perform its evaluation.
-
After acquiring a new OAuth 2.0 bearer token to access the endpoint for the service, the client sends a request to the desired service. The request body includes the “prefetch” data (see https://cds-hooks.hl7.org/2.0/#prefetch-templateOpens in a new tab). The service evaluates the data and responds by returning the applicable cards or system actions (if any).
-
Optionally, the client can acquire a bearer token to access the feedback endpoint for the service and then transmit feedback.
Provide a FHIR Fetch Access Token
As an alternative to prefetching the FHIR resource data, the client application can provide an OAuth 2.0 access token for the FHIR repository to the CDS Hooks server (HAE), allowing HAE to acquire and evaluate the FHIR resource data required by a service on it’s own. In this case, the CDS Hooks interaction proceeds as depicted in the following diagram:
Compared with the preceding interaction (wherein FHIR resource data was prefetched), this interaction proceeds as follows:
-
The client application authorizes and performs the discovery request in the same way as in the preceding interaction.
-
The client requests an access token from the FHIR repository’s OAuth 2.0 server which will authorize the CDS Hooks server (HAE) to query the FHIR repository.
-
The client authorizes the request for the service in the same way as in the preceding interaction. Instead of including the required FHIR resources, the server request body includes FHIR resource access parameters (see https://cds-hooks.hl7.org/2.0/#fhir-resource-accessOpens in a new tab), including the access token.
-
HAE uses the access token from the request body to query the client application’s FHIR repository for the FHIR resource data that the service requires.
-
The service evaluates the data and responds by returning the applicable cards or system actions (if any).
-
As in the preceding interaction, the client can (optionally) acquire a bearer token to access the feedback endpoint for the service and then transmit feedback.
Hybrid: Provide Both Prefetched Data and an Access Token
The client application can also combine the two preceding methods for providing access to FHIR resource data: it can provide some “prefetch” data (those available within the client application’s current context, perhaps) as well as an access token from the FHIR resource server’s OAuth 2.0 server, enabling the CDS Hooks server (HAE) to obtain the rest of the required data.
In this case, the CDS Hooks interaction proceeds as depicted in the following diagram:
Compared with the preceding interactions, this hybrid interaction proceeds as follows:
-
The client application authorizes and performs the discovery request in the same way as in the preceding interactions.
-
The client obtains the necessary authorization to access its FHIR resource repository and obtain some of FHIR resource data that the service requires, as in the prefetch interaction.
-
The client obtains an access token from the FHIR resource repository’s OAuth 2.0 server for HAE, as in the previous interaction.
-
The client authorizes the service request in the same way as in the preceding interaction. The service request body includes both the “prefetch” FHIR resource data and the FHIR resource access parameters.
-
HAE uses the access token from the request body to query the client application’s FHIR repository for the rest of the FHIR resource data that the service requires.
-
As in the preceding interactions, the service evaluates the data and responds by returning the applicable cards or system actions (if any).
-
As in the preceding interactions, the client can (optionally) acquire a bearer token to access the feedback endpoint for the service and then transmit feedback.
