Hello, CDS Hooks!
Real-world synchronous decision support interactions with the InterSystems® Healthcare Action Engine are complex, and consist of multiple requests: the client must obtain authorization to access the Healthcare Action Engine; to perform most evaluations, the Healthcare Action Engine must have access to data from an HL7® FHIR® resource server; this access must also be authorized. For more information about the supported synchronous decision support interactions with the Healthcare Action Engine, see Invoke Synchronous Services from a Client Using the CDS Hooks API.
However, at the core of any interaction with the Healthcare Action Engine is an HTTPS request from the client application to one of the Healthcare Action Engine’s CDS Hooks API endpoints. In the exercise on this page, you will temporarily configure the Healthcare Action Engine within your demo environment so that you can complete two such requests in isolation. The first request is a discovery call, which provides the client with a list of available rules. The second request is a service call invoking a test rule (EDSDemoHelloCDSHooks) which does not require the evaluation of any FHIR data.
Disable CDS Hooks Token Validation
To be compliant with the CDS Hooks specification, every client request to the Healthcare Action Engine must be authorized with single-use tokens from an OAuth 2.0 server (https://cds-hooks.hl7.org/2.0/#trusting-cds-clientsOpens in a new tab). However, for the purposes of demonstration or testing, you can temporarily disable the validation of client tokens within the Healthcare Action Engine.
For security reasons, do not disable token validation for the Healthcare Action Engine within a production environment. The instructions which follow are provided for demonstration and testing purposes only.
To disable token validation:
-
Access the Management Portal for the Healthcare Action Engine and switch to your Healthcare Action Engine namespace.
-
Navigate to Interoperability > Production > Configuration.
-
On the Production Configuration page, select the CDSHooks service from the Service column.
-
In the settings tabs pane, select the Settings tab and expand the Security section.
-
Select the DisableAllTokenValidation and DisableTokenSigValidation checkboxes, as depicted in the following image:
-
Select Apply.
Request 1: Discover HAE Services (no CDS Hooks OAuth)
With token validation disabled, your simulated client can now access information about the available rules using the Healthcare Action Engine’s discovery endpoint, without the need for authorization. To do so:
-
Within Postman, access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and modify the Current Value of the following variables:
-
haeBaseURL — the base URL for accessing your demo Healthcare Action Engine instance over HTTPS, including the port number or instance prefix as needed (for example: https://www.testserver.net/demohae). The Initial Value demonstrates the general syntax expected for this URL using placeholder values in .
-
haeNamespace — the name of the demo Healthcare Action Engine namespace, in all lowercase characters
Requests in subsequent steps use these variables to construct their target URLs.
-
-
Select Save to save this update to your Variables.
-
Select the request 1. Discover HAE Services (no CDS Hooks OAuth).
-
Select Send to send a discovery request to the Healthcare Action Engine.
The body of the response to a successful discovery request contains information about each of the rules (or “services,” in CDS Hooks terms) currently active within the Healthcare Action Engine. An excerpt of the discovery response for a Healthcare Action Engine demo instance is depicted in the following screenshot:
Request 2: Hello CDS Hooks! (no FHIR Fetch, no CDS Hooks OAuth)
As depicted in the preceding screenshot, one of the active rules within a Healthcare Action Engine demo instance is titled EDSDemoHelloCDSHooks.
In production, a service request to a Healthcare Action Engine rule would need to provide access to the FHIR data which the rule is designed to evaluate—a rule that does not evaluate any data is not very useful.
However, EDSDemoHelloCDSHooks is a demo rule that does not evaluate FHIR data. It returns a card in response to any valid request sent to its service endpoint.
To invoke EDSDemoHelloCDSHooks:
-
Within Postman, select the request 2. Hello CDS Hooks! (no FHIR Fetch, no CDS Hooks OAuth) from the Healthcare Action Engine Demo Walkthrough collection. Note that the target URL for this request is the service endpoint which corresponds to this rule. Also note the content of the request body, which models some of the requirements outlined in the CDS Hooks specification.
-
Select Send.
The body of the response to a successful service request for EDSDemoHelloCDSHooks contains a CDS Hooks card. An excerpt of this card is depicted in the following screenshot:
