Integrating with Ocean using FHIR CDS Hooks

What is FHIR CDS Hooks?

Clinical Decision Support (CDS) Hooks is a FHIR-based standard that enables Electronic Health Record (EHR) systems to integrate real-time clinical decision support services into healthcare workflows. CDS Hooks allows external systems to provide contextual recommendations, alerts, and guidance at critical decision points during patient care.

The standard defines a webhook-based architecture where EHR systems (clients) invoke external CDS services at specific workflow moments called "hooks." These services can analyze patient data and clinical context to provide relevant decision support directly within the clinician's workflow.

Familiarize yourself with https://cds-hooks.org/ which contains an overview of CDS Hooks and other high level information.

For technical implementation details refer to the full specification at https://cds-hooks.hl7.org/.

Ocean is a CDS Client implementing the components necessary to configure, invoke, and display responses from CDS Services.

If you plan to integrate with Ocean through CDS Hooks you will be implementing the CDS Server responsibilities.

Supported Hooks

The CDS specification has a number of standardized hooks.

Ocean currently supports the following CDS Hook:

  • order-sign: Triggered during eRequest sending workflows after the form is filled out and before the request is submitted
    • Includes patient demographics, provider info, and request details
    • Enables CDS services to suggest alternatives, validate request appropriateness, or provide clinical guidance

If you would like to integrate a CDS Hook into a different workflow, please contact us! Other hooks will be implemented once we have parties interested in implementing the corresponding CDS servers.

The order-sign Hook

Hook specification: https://cds-hooks.hl7.org/hooks/order-sign.html

Note: Whenever you see { {something}} the intent is for there to be no spaces. This is a limitation of the documentation platform

Context Data

  • userId - Random Practitioner UUID per request (format: "Practitioner/{ {UUID}}")
  • patientId - Random UUID string per request
  • encounterId - Random UUID string per request
  • draftOrders - Bundle containing a single ServiceRequest with DRAFT status. The ServiceRequest included here is very sparse. See Bundle?_query=on-v11-add-service-request if you need more details

Supported Prefetch Parameters

  • "Patient/{ {context.patientId}}" - Returns FHIR Patient resource from Ocean patient data. Use this if you care about the patient demographics.
  • QuestionnaireResponse?encounter={ {context.encounterId}} - Returns a Bundle with questionnaire responses from referral forms. Use this if you care about the form responses.
  • { {context.userId}} - Returns a FHIR Practitioner resource for current user
  • PractitionerRole?practitioner={ {context.userId}} - Returns a Bundle with the PractitionerRole for the current user
  • Bundle?_query=on-v11-add-service-request - Returns Ontario eReferral v0.11.1 message Bundle for service request notifications

Example Use Cases

Below are some example use cases that could be implemented using the order-sign hook:

  • Recommend other services that have a shorter wait time
  • Prevent duplicate submissions
  • Do complex form validation with access to the ordering provider, patient demographics and form answers
  • Provide info customized to the patient with next steps following a submission

Implementing a CDS Hooks Server

CDS Servers are a backend service that is implemented outside of Ocean. To satisfy the the spec it must be able to respond to only 2 requests. The Discovery call at GET /cds-hooks and the actual service invocations at POST /cds-hooks/{service-id}.

For an example implementation see: Example Server

The Discovery call returns a JSON payload describing what services the server supports.

// Example Discovery response
{
  "services": [
    {
      "hook": "order-sign",
      "title": "Duplicate Request Service",
      "description": "Checks the patient demographics against existing requests",
      "id": "duplicate-on-order-sign",
      "prefetch": {
        "patient": "Patient/{ {context.patientId}}",
      }
    }
  ]
}

The service invocation receives data about the workflow and returns cards to be shown to the user.

// Example request payload
{
  "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
  "hook": "order-sign",
  "context": {
    "userId": "Practitioner/example",
    ...
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      ...
    }
  }
}


// Example response payload
{
  "cards": [
    {
      "summary": "Potential Duplicate Order",
      "detail": "A similar order may have been recently placed for this patient. Please review before signing.",
      "indicator": "warning",
      "source": {
        "label": "Ocean Example CDS Server"
      }
    }
  ]
}

Technical Requirements

  • FHIR R4 Compatibility: CDS services must support FHIR R4 resource formats
  • HTTPS Endpoints: All CDS service endpoints must support HTTPS
  • JSON Communication: Services must accept and return JSON-formatted payloads
  • CDS Hooks Specification: Compliance with CDS Hooks specification v2.0.1

Authentication Support

Ocean supports the following authentication methods for CDS Hooks:

  • No Authentication: Not recommended. For extremely early testing only
  • API Key Header/HTTP Basic Auth: Static header-based authentication. Not recommended for production integrations
  • OAuth2: Recommended for production integrations
  • Self-Signed JWT: Available upon request

Network Requirements

  • Outbound HTTPS: Ocean must be able to make outbound HTTPS requests to CDS service endpoints
  • Response Times: As CDS Hooks are a realtime workflow (i.e. a user will be waiting for the response) CDS services should respond in a timely manner (within a few seconds) to avoid degrading the user experience
  • Availability: Services should maintain high availability especially during business hours

Ocean Configuration

CDS Hooks are configured within the Ocean Portal. See the following support article for notes on setting it up: https://support.cognisantmd.com/hc/en-us/articles/360034919811-Enabling-Ocean-Integrations

Ocean Implementation Notes

Card Indicator Behaviour

Returned cards have an indicator field to signify the card's importance. indicator is one of info, warning or critical.

The 3 indicators have different effects on the Provider's submission workflow.

  • info - shown to the Provider after the submission has been sent

cds-info-card

  • warning - shown to the Provider before confirming the submission. The Provider can choose to continue to send the submission or select cancel to edit the form before proceeding

cds-warning-card

  • critical - shown to the Provider and prevents them from confirming the submission. The Provider is allowed to resubmit and can edit the submission before doing so

cds-critical-card

Actions

Ocean does not support Actions at this time. Please contact us if you have a compelling use case that would require Actions.

FHIR Resource Access

Ocean will not send the CDS Server fhirServer or fhirAuthorization parameters. Data will be passed through the context and prefetch. See https://cds-hooks.hl7.org/#fhir-resource-access for more info.

Feedback Mechanism

Ocean does not support the Feedback flow at this time. Please contact us if you have a compelling use case that would require its implementation.

Markdown Rendering

Ocean does not support the rendering of the Card response text as Markdown

Failing Services

Ocean will not allow the request to proceed if the service call returns a non-200 response code