CDS Hooks Integration and Implementation – Summary
CDS, Clinical Decision Support, Hooks is a technology from SMART on FHIR that allows third-party CDS systems to register with an EHR using a “hook” pattern. The third-party CDS system is able to provide the EHR with information in the form of “cards” that the EHR may use to show the end-user or otherwise interweave into the workflow. This article outlines the workflow for a CDS Hooks service provider that is planned to be implemented for integration with a HAPI server deployed on Microsoft Azure.
The hooks, that CDS hooks refer to, are defined in EHR that is willing to implement these integration points. The CDS service provider merely offers some services to the EHR systems, which are then configured by the EHR to invoke those services on those hooks, thus, returning the relevant cards to the EHR. Therefore, this separation of concern must be known before diving into details of the document. CDS service providers and EHRs must work together to get the best out of this technology.
In conforming to the draft of the specification, we will have to deviate only in one particular place. The only difference in the request for CDS hooks as compared to the documentation (https://cds-hooks.org/specification/1.0/#http-request_1) will be that we will be sending Azure API gateway authentication token (OCP-Apim-Subscription-Key) instead of OAuth 2.0 token in the request payload and then in the hook implementation we will pull FHIR resources via Azure API gateway. This can be tweaked if someone wants to generalize the implementation for other EHR systems.
We are assuming that the EHR is our own HAPI’s server deployed on Azure since it is the entity that would be consuming the services from our custom CDS service provider. Therefore, any references to EHR succeeding this sentence refer to our own HAPI’s server.
CDS Hook Validation of EHR Request
Any request that the EHR would make for invoking the CDS service, the request would include an authorization header. The authorization header would consist of a generated JWT, signed using the EHR’s private key. The generated JWT would include the issuer, the subject whom the token refers to and other related information. Furthermore, the EHR’s public JWK set must be available online so that our CDS service provider is able to verify that the request has come from an authenticated EHR.
The business logic for processing the lab result would be done at our custom CDS service provider.
Example – Diagnostic Report FHIR Resource Create/Update
Summary of Workflow
A hook (defined below) would have been configured within the EHR, which would trigger whenever the following two events (within the EHR) occur:
a) A new lab result for a patient is created.
b) An existing lab result for a patient is updated.
The CDS provider would have exposed the service as an API endpoint, which would be able to determine whether a lab result is out of range or not. For the EHR to consume this service, it would pass the relevant data (contextual data of the hook) along with the authorization information. The EHR could associate the consumption of multiple services from a particular CDS provider with a hook if that’s desirable. So whenever the hook is triggered, the EHR would send a request, having passed the patient’s identifier and an instance of the DiagnosticReport resource (lab result in FHIR representation) as contextual data of the hook, along with a signed JSON web token in the authorization header. The CDS provider would validate the integrity of the token by performing appropriate checks and confirm whether the EHR is white-listed in their database. If those checks are failed, an error response would be sent back to the EHR. If those checks are passed, the service would apply business rules on the received data, determine the range of the lab result and send back appropriate card(s) depending on the determined range by the service. These card(s) would be rendered by the EHR.
Our CDS service provider would expose a discovery endpoint, which would return the information related to the single service that we have implementing. This service determines whether a particular patient’s lab result is out of range or not, depending upon the lab result passed in as a context.
Example CDS Hooks Implementation Following We Show a Sample CDS Hooks Implementation Data Follow Scenario
Hook’s name: patient-lab-result-update
Purpose: This hook informs an external CDS service that a practitioner has created or updated a patient’s lab result.
Contextual data: The patient’s identifier value in context and the lab result as an FHIR resource.
| “context”: { “patientId”: “123”, “labResult”: { “resourceType”: “DiagnosticReport”, “id”: “101”, … has been snipped for the sake of brevity … } } |
Data Flow Scenario
- Upon the boot-up of the HAPI’s FHIR server, it would call the discovery endpoint of our CDS service provider to store the information about the service(s) it provides with the necessary authorization information passed. The authorization information would be a JWT in the header.
- The CDS service provider receives a request with the authorization information passed in the header by the EHR. It would decode the JWT and verify the signature of the JWT using the public key the EHR has made online. If the EHR is in our whitelist, we would allow the request to continue and return the service(s) our custom CDS service provider provides.
- Thereafter, at some point in time, a request for the insertion/updation of a lab result in the form of a DiagnosticReport resource would hit our server.
- Upon the successful insertion/updation of this resource, we would invoke the custom CDS service that the provider had already given us information about in step #1 (with the authorization header). This request would include the resource in the request body.
- The CDS service would perform some business logic on the FHIR resource and return back a card in response based on the rules set in business logic.
- Depending upon the information received in the card from the CDS service, we would perform an action in our own FHIR server. At this point there will be only two possibilities, we would either create a Flag resource for the patient or we wouldn’t. Prior would happen in case the lab result is out of range. Later on, we will add more features and there would more outcomes of CDS flags.
This is the Strategy for the Integration and Implementation of CDS Hook. If you want to know more please send an email to info@techno-soft.com.
Technosoft strives to provide the best healthcare software development and integration. Please contact us for any of your healthcare integration or development needs.
