CDS Hooks

EBMEDS uses a slightly customized version of the CDS Hooks standard. This standard is still in flux and will soon reach its 1.0 version, at which point these customizations will be re-evaluated.

The overall point of CDS hooks is that the calling party calls EBMEDS using three pieces of information:

This enables EBMEDS to tailor its output depending on the usage context, and also to provide a machine-readable format for what data is required. The context itself is not machine-readable, i.e. it is described by natural language, but some standardized hooks exist.

Differences between the EBMEDS implementation and the current CDS hooks documentation:

CDS hooks REST API

The REST API for CDS hooks is very simple. One can GET the list of available hooks (the "hook catalog") from [base-url]/cds-services, and one calls a hook by POSTing to [base-url]/cds-services/[hook-name]. The base URL depends on where and how EBMEDS is installed: one example is https://ebmedscloud.org/api/fhir/v1.

Hook description format

We will continue with the questionnaire-completed example mentioned briefly above. The EBMEDS hook catalog specifies this kind of hook:

{
  "id": "selfcare-filled-questionnaire",
  "hook": "questionnaire-completed",
  "name": "Self-care questionnaire analysis service",
  "description": "A hook for when a FHIR QuestionnaireResponse filled out by a patient/citizen is available for EBMEDS to process. The response may include directions both for the patient himself, and a medical professional.",
  "prefetch": {
    "questionnaireResponse": "/QuestionnaireResponse?patient={{Patient.id}}"
  }
}

So what does this mean? Let's go through the hook description field by field:

Calling a hook

So, given the hook description above, we can call the hook. The format is, quite simply:

{
  "hook": "questionnaire-completed",
  "prefetch": {
    "questionnaireResponse": {
      "resource": { QuestionnaireResponse... }
    }
  },
  "context": {
    "dataVersion": "latest"
  }
}

Hook response

EBMEDS uses two patterns for CDS hook responses. The first pattern is a traditional approach, well suited for the CDS hooks standard. The second pattern is customized for the selfcare context. The example above, as you may remember, is in the selfcare context, so the call above will return the second pattern. More details below.

Traditional response (to be implemented)

Traditional CDS is focused on providing one or more text-based messages to a clinical professional, sometimes accompanied by some suggested actions, identified by a code. Each message, or reminder, is independent of the others, i.e. the same actions may be suggested in multiple reminders. It is up to the calling party to handle a user-friendly display of the information, potentially removing duplicate suggested actions, rendering different kinds of messages in different ways etc. An example, showing two reminders, is the following:

{
  "cards": [
    {
      "summary": "Decreased renal function, switch tiatside to furosemide?",
      "detail": "Renal function is decreased (eGFR 21 ml/min 16.10.2017). Tiatsides lose their effect when GFR < 30 ml/min. Consider switching to furosemide.",
      "indicator": "info",
      "source": {
        "name": "EBMEDS v2.0.6",
        "url": "https://ebmeds.org/version/v2.0.6/data-version/v0.9.2"
      },
      "suggestions": [
        { ActivityDefinition... },
        { ActivityDefinition... },
        ...
      ]
    },
    {
      "summary": "High ferritinine (355 ug/l 15.10.2017) - hemocromatosis?",
      "detail": "High ferritinine concentration (355 ug/l 15.10.2017): Consider the possibility of hemocromatosis. Ferritinine concentration may also be elevated due to infection or liver disease.",
      "indicator": "info",
      "source": {
        "name": "EBMEDS v2.0.6",
        "url": "https://ebmeds.org/version/v2.0.6/data-version/v0.9.2"
      },
      "suggestions": [
        { ActivityDefinition... },
        { ActivityDefinition... },
        ...
      ]
    }
  ]
}

Again, ActivityDefinition... signifies a FHIR resource that is omitted for brevity.

These cards are to be displayed by the calling party in a manner they see fit. Refer to the documentation of individual hooks regarding the formats and codings for suggested actions.

Custom self-care card format

The self-care context poses some unique challenges. Originally created for a national project in Finland, these CDS cards are required to leave nothing to chance, since most parts of the self-care project in question are automated, without human intervention. In other words, the card format is too vague to offer much help, and all human-readable data is stripped out of it. Instead, the data is all in coded form inside suggestions, more specifically in the form of ActivityDefinition resources. Please refer to the selfcare-* hooks in the hook catalog.

{
  "cards": [
    {
      "source": {
        "name": "EBMEDS v0.9.6",
        "url": "https://ebmeds.org/version/v0.9.6/data-version/v0.9.2"
      },
      "suggestions": [
        { ActivityDefinition... },
        { ActivityDefinition... },
        ...
      ]
    }
  ]
}