This page is part of the Da Vinci Coverage Requirements Discovery (CRD) FHIR IG (v2.1.0-preview: STU 2.1) based on FHIR (HL7® FHIR® Standard) R4. The current version which supersedes this version is 2.0.1. For a full list of available versions, see the Directory of published versions

CDS Hook Deviations and Enhancements

Page standards status: Trial-use

CDS Hooks is a relatively new technology. It is considered a "Standard for Trial Use" (STU), meaning that it will continue to evolve based on implementer feedback and could change in ways that are not compatible with the current draft. As well, the initial version of the CDS Hooks specification has focused on the core architecture and a relatively simple set of capabilities. Additional capabilities will be introduced in future versions.

To meet requirements identified by Da Vinci project participants, it is necessary to introduce additional capabilities above and beyond what is currently found in the CDS Hooks specification. This section of the CRD implementation guide describes those additional capabilities and the mechanism the implementation guide proposes to implement them. The purpose of these customizations is to enable testing at connectathons and to support feedback into the CDS Hooks design process.

Each capability listed here has been proposed to the CDS Hooks community and could become part of the official specification in a future release. However, there is a significant likelihood that the way the requirements are met will vary from the syntax or even the architectural approach proposed in this guide. Future versions of this implementation guide will be updated to align with how these requirements are addressed in future versions of the CDS Hook specification. Until both the CDS Hooks content and the FHIR and US Core content underlying this specification are Normative (locked into backward compatibility mode), the CRD implementation guide will remain as STU.

This implementation guide extends/customizes CDS Hooks in 5 ways: additional hook resources, a hook configuration mechanism, additional prefetch capabilities, additional response capabilities, and the ability to link hooks to their corresponding request. Each are described below:

Additional Hook scope

In the current build, the order-sign hook can be used for both 'draft' orders that are newly created as well as for updated orders that are active. The balloted version of the hooks this IG release is bound to are limited to draft orders. This IG adopts the newer wording, meaning that the order-sign hook can be triggered both on newly created orders, as well as when orders are updated (changing status, changing time-frame, etc.). The hook can also be re-triggered if there is a key change to the context, most typically the establishment of new or renewed coverage relevant to the order.

Additional Hook resources

Two of the hooks used by this specification (order-select and order-sign) identify specific "order" resources that can be passed as part of the hook invocation. CRD has use-cases for additional resource types to be passed to this hook. Specifically:

• CommunicationRequest - Needed to trigger CRD when a provider requests that another provider transfer patient records or other supporting information to another organization or agency.

• Task - Task is used to seek fulfillment of an order from service providers. Because coverage can be influenced by who is asked to perform an order, coverage requirements can be relevant here. As well, task is used to request changes to existing therapies (e.g. stopping a medication, suspending a therapy, etc.) and changes to therapy can also have impacts on coverage requirements.

The proposal to add these resources to the existing hook definitions can be found on the CDS hooks issue tracker.

New hook configuration mechanism

The CRD Servers provided by payers will support discovery of different types of coverage requirements that will return different types of information to users on CDS Cards, such as:

• Whether authorization is required
• Recommended alternative therapies
• Best practices associated with the planned therapy that are expected to be adhered to
• Forms and documentation for retention within the CRD client
• Forms and documentation that must be provided with a prior authorization request
• Forms and documentation that must be included with a claim submission

Not all the coverage information returned by a CRD Server will be relevant to all users of all CRD Clients. It would therefore be useful to be able to configure CRD Servers to withhold certain card types from certain provider types, user roles, or specific users. Preferences could potentially be configured within the CRD Server or within the CRD Client.

Managing preferences within a CRD Server would require processes to support communication and management of customization requests, as well as additional complexity within the CRD Server software. Managing preferences within the CRD Client would require it to either request specific information by invoking multiple calls to different services or by invoking a single call to the service indicating the response types desired.

The approach in this implementation guide is designed to allow the users or administrators of CRD Clients to manage and dynamically communicate desired response types to the CRD Server at the time a service is invoked. At this time, it is not clear whether this capability will be of interest to vendors, users, or other types of CDS Services. Therefore, rather than proposing a change to the base CDS Hook specification, this IG leverages the CDS Hook extension mechanism to provide an experimental approach to specify and control the types of information returned to users. Connectathon and implementation experience could support requesting that these changes, or some variant of them, be included in a future version of the CDS Hook specification.

Extensions will be enabled in two places:

1. The CDS Service Discovery Response object that describes the service's capabilities will include an extension that describes what configuration options can be set by the CRD Client
2. The hook's HTTP Request object will include an extension to pass specific configuration settings as part of the hook invocation

Configuration options extension

An extension called davinci-crd.configuration-options will define a configuration object with an array of available configurable options within the CDS Service, where:

• Each option SHALL include four mandatory elements:
  • A code that will be used when setting configuration during hook invocation, and has an (extensible) binding to the CRD Card Types ValueSet.
  • A data type for the parameter. At present, allowed values are "boolean" and "integer". (NOTE: These are the JSON data types and not the FHIR data types.)
  • A display name for the configuration option to appear in the client's user interface when performing configuration.
  • A description providing a 1-2 sentence description of the effect of the configuration option.
• A default value SHALL also be provided to show users what to expect when an override is not specified.

CRD servers SHALL, at minimum, offer configuration options for each type of card they support (with a code corresponding to the CRD Card Types ValueSet and a type of ‘boolean’, where setting the flag to false will result in the server not returning any cards of the specified type). This allows CRD clients to control what types of cards they wish to receive at all, or to receive in particular workflow contexts or for certain users. This configuration mechanism also allows EHRs to minimize information overload and avoid presentation of duplicative or low-utility CRD alerts.

For example, a CDS Discovery Response from a CRD Server might look like this:

{
  "services" : [
    ...
    {
      "extension" : {
        "davinci-crd.configuration-options" : [
          {
            "code" : "coverage-info",
            "type" : "boolean",
            "name" : "Coverage Information",
            "description" : "Information related to the patient's coverage, including whether a service is covered, requires prior authorization, is approved without seeking prior authorization, and/or requires additional documentation or data collection",
            "default" : true
          },
          ...
          {
            "code" : "max-cards",
            "type" : "integer",
            "name" : "Maximum cards",
            "description" : "Indicates the maximum number of cards to be returned from the service.  The services will prioritize cards such as highest priority ones are delivered",
            "default" : 10
          }
        ]
      },
      "hook" : "order-sign",
      ...
    }
  ]
}

Notes:

• This version of the implementation guide provides only limited standardization of the codes, names, types, or descriptions for configuration options for CRD Servers. Future versions of the CRD specification may standardize additional configuration options that have been identified as useful by individual payer and CRD client experimentation - thereby improving consistency in behavior across payer services to ease the burden on those performing configuration.

• There is no mechanism to express co-occurrence rules amongst configuration options. Guidance can be given about allowed combinations in descriptions, but payer services SHALL gracefully handle disallowed/nonsensical combinations. I.e. the CRD Server must:

  • allow for the possibility that CRD Clients might not adhere to their co-occurrence rules,

  • include explicit checks of inbound data for adherence to rules; and

  • indicate that CRD checking could not be done and log appropriate information to allow engagement with CRD Clients to address any payer-specific needs.

• Codes SHALL be valid JSON property names and SHALL come from the CRD Card Types list if an applicable type is in that list.

• Codes, names, and descriptions SHALL be unique within a CDS Service definition. They SHOULD be consistent across different hooks supported by the same payer when dealing with the same types of configuration options.

• Payer services providing more than one type of coverage requirement information/guidance SHOULD expose configuration options allowing clients to dynamically control what information is returned by the service.

Hook configuration extension

An extension called davinci-crd.configuration will define a second configuration object that will contain an array of codes and values corresponding to the configuration options configured within the CRD Client.

For example, the hook HTTP Request would look like this:

{
  "extension" : {
    "davinci-crd.configuration" : {
      "cost" : false,
      "claim" : false,
      "appropriate-use" : false,
      "max-cards" : 5
    }
  },
  "hook" : "order-sign",
  ...
}

Notes:

• Where CRD Clients support the optional configuration options, the following requirements apply:
  • CRD Clients SHOULD expose configuration options through a configuration screen to allow users and/or system administrators to control the types of information returned.
  • CRD Clients SHALL convey configuration options when invoking the hook using the davinci-crd.configuration extension. It will be a single object whose properties will be drawn from the code values from configuration options and whose values will be of the type defined for that option.
  • CRD Clients SHOULD provide an ability to leverage the dynamic configuration capabilities of payer services based on provider role, individual provider, and/or hook invocation location as best meets the needs of their users.
• Because support for some configuration is required for all CRD servers, the following requirements apply:
  • CRD Servers SHALL behave in the manner prescribed by any supported configuration information received from the CRD Client.
  • CRD Servers SHALL NOT require the inclusion of configuration information in a hook call (i.e. no hook invocation is permitted to fail because configuration information was not included).
  • CRD Clients MAY send configuration information that CRD Servers do not support. In this case, the CRD Server SHALL ignore the unsupported configuration information.
• This specification provides no guidance on exactly when/how CRD Clients are expected to manage hook configuration. This could be done at the level of provider roles, individual providers, location from which the hook is invoked, or other means. CRD Clients can experiment and determine what types of configuration make the most sense and at what levels they can support managing/persisting configuration information.

Additional prefetch capabilities

One of the options supported in CDS Hooks is the ability for a service to request that certain data be prefetched for efficiency reasons and to simplify processing for the CDS service. However, there is a limit in that, in the current CDS Hooks specification, prefetch can only use hook context information that is expressed as a simple key value. It cannot leverage context information passed as resources.

A proposal has been submitted suggesting how to address this issue. This version of the implementation guide pre-adopts that proposal.

Specifically, where a hook defines a context element that consists of a resource or collection of resources (e.g. order-select.draftOrders or order-sign.draftOrders), systems SHALL recognize context tokens of the form context.<context property>.<FHIR resource name>.id in prefetch queries. Those tokens SHALL evaluate to a comma-separated list of the identifiers of all resources of the specified type within that context key.

Note: Recognizing these tokens doesn't mean the client must support prefetch or the requested prefetch query, only that it recognizes the token, doesn't treat it as an error and - if it supports the query - substitutes the token correctly.

For example, a prefetch for order-sign might look like this:

{
  ...
  "prefetch" : {
    "patient" : "Patient/{{context.patientId}}",
    "encounter" : "Encounter?_id={{context.encounterId}}&_include=Encounter:service-provider&_include=Encounter:practitioner&_include=Encounter:location",
    "coverage" : "Coverage?patient={{context.patientId}}&status=active",
    "appointment" : "Appointment?_id={{context.appointments.entry.resource.ofType(Appointment).id}}&_include=Appointment:practitioner:PractitionerRole&_include:iterate=PractitionerRole:organization&_include:iterate=PractitionerRole:practitioner&_include=Appointment:location"
  }
}

This might result in an executed query that looks like this: ServiceRequest?_id=2347,10948,5881&_include=ServiceRequest:performer

This proposed pre-adoption is not CDS Hooks conformant. It is possible that the CDS Hooks community will adopt an alternative solution or choose not to make any changes. Community discussion about this proposal can be found on the CDS Hooks issue list here and in Jira here. This implementation guide will be updated to align with the decision of the community and might, if necessary, fall back to the use of extensions if CDS Hooks does not choose to support prefetch based on context resources and the payer community determines that prefetch is still required.

In addition to this preadoption, this implementation guide presumes support for prefetch query capabilities more sophisticated than the recommended prefetch query restrictions in the CDS Hooks specification. Specifically, the use of _include, as seen in the example above. It also uses a query-like mechanism to reference 'draft' orders that might not yet be available in the CRD client's repository for query, which will require query-like functionality to be implemented against in-memory objects.

Additional response capabilities

CDS Hooks supports suggestions that involve multiple actions. Coverage Requirements Discovery uses this in one situation where additional capabilities will be needed:

• Creating a Task to complete a Questionnaire; and

In this case, the creation of the Questionnaire needs to be conditional - it SHOULD only occur if that specific Questionnaire version doesn't already exist, and the payer service SHALL query to determine if the client has a copy of the Questionnaire before sending the request. This capability is supported in FHIR's transaction
functionality. However, not all the capabilities/guidance included there has been incorporated into CDS Hooks 'suggestions', in part to keep the specification simpler.

For this release of the implementation guide, these requirements will be handled as follows:

if-none-exist

The suggestion.action object will use an extension to carry the if-none-exist query, as per FHIR's conditional create functionality. The extension property will be davinci-crd.if-none-exist.

For example, this CDS Hook Suggestion contains two Actions - one referencing an HL7 Questionnaire and the other the Task to complete the Questionnaire. The Questionnaire will only be created if it didn't already exist:

{
  "type" : "create",
  "description" : "Add version 2 of the XYZ form to the clinical system's repository (if it doesn't already exist)",
  "resource" : {
    "resourceType" : "Questionnaire",
    "url" : "http://example.org/Questionnaire/XYZ",
    "version" : "2",
    ...
  }
}

Linkage between created resources

The linkage between resources by id in different Actions within a single Suggestion doesn't require any extension to CDS Hooks, but it does require additional guidance. For the purposes of this implementation guide, the inclusion of the id element in 'created' resources and references in created and updated resources within multi-action suggestions SHALL be handled as per FHIR's transaction processing rules. I.e. Treating each requested action as being an entry in a FHIR transaction bundle where the base URL is the base URL of the CRD Client's server. POST corresponds to an action.type of 'create' and PUT corresponds to an action.type of 'update'. Specifically, this means that if a FHIR Reference points to the resource type and id of a resource of another 'create' Action in the same Suggestion, then the reference to that resource SHALL be updated by the server to point to the id assigned by the client when performing the 'create'. CRD Clients SHALL perform 'creates' in an order that ensures that referenced resources are created prior to referencing resources.

For example, the following CDS Hook Suggestion will cause the creation of a new ServiceRequest that will be pointed to by a newly created (DeviceRequest resource). The ClaimResponse would be created before the MedicationRequest would be updated:

{
  "label" : "Change to an order for purchase",
  "actions" : [
    ...
    {
      "type" : "create",
      "description" : "Add purchase order",
      "resource" : {
        "resourceType" : "ServiceRequest",
        "id" : "AAA",
        ...
      }
    },
    {
      "type" : "create",
      "description" : "Add specific (discounted) device order",
      "resource" : {
        "resourceType" : "DeviceRequest",
        "id" : "BBB",
        ...
        "basedOn" : [
          {
            "reference" : "ServiceRequest/AAA"
          }
        ],
        ...
      }
    }
  ]
}

Note: Sending existing prior authorizations is not in scope for this version of the IG.

Linking cards to requests

Some CDS hooks have a single context. encounter-start and encounter-discharge are tied to their respective encounter and there is no question as to which encounter a returned card is associated with. However, the appointment-book, order-select, and order-sign hooks all allow passing in multiple resources as part of the hook invocation. Each card returned in the hook response might be associated with only one of the referenced appointment or order resources, or a subset of them. A CRD client might wish to be able to track what resource(s) a card was associated with. This might be for audit, to control how or where the card is rendered on the screen, to allow the card to be directly associated with the triggering resource, or to enable various other workflow considerations.

This implementation guide defines a standard extension - davinci-associated-resource - that can appear on any card that provides a local reference to the appointment, order, or other context resource to which the card is 'pertinent'. It is optional and has a value consisting of 1..* local references referring to the resource type and resource id of the resource being linked.

If a hook service is invoked on a collection of resources, all cards returned that are specific to only a subset of the resources passed as context SHALL disambiguate in the detail element which resources they're associated with in a human-friendly way. Typically, this means using test name, drug name, or some other mechanism rather than a bare identifier as identifiers might not be visible to the end user for resources that are not yet fully 'created'. As well, cards SHOULD include this new extension to allow computable linkage.

{
  ...
  "summary" : "Replace order with covered generic?",
  "indicator" : "info",
  ...
}

Controlling hook invocation

Provider systems SHALL only invoke hooks on payer services where the patient record indicates active coverage with the payer associated with the service. Providers MAY limit hook invocation to only those payers that are believed to potentially have relevant information related to the current action - for example, clinical guidance, contraindication detection, etc. This might be more payers than just those that are likely to provide coverage for the services referred to by the hook.

NOTE: There is no expectation that CRD clients will only make calls to payer services that are 'known' to provide coverage for the proposed service. In some cases, the EHR will not know at time of order entry which payer(s) will have claims submitted to them. Also, a payer with active coverage might have information relevant to the order even if a claim will never be submitted to them (e.g. contraindications) or require a formal declaration of non-coverage, even though that declaration is a given.

Where the patient has multiple active coverages that the CRD client deems appropriate to call the respective CRD servers for, the CRD client SHALL invoke all CRD server calls in parallel and display results simultaneously to ensure timely response to user action.