Introduction

This implementation guide contains common HL7® Fast Healthcare Interoperability Resources (FHIR®) assets for use in content IGs built using the approach and specifications developed as part of the Clinical Quality Framework (CQF) initiative, including the FHIRHelpers and FHIR-ModelInfo libraries.

The CQF approach brings a suite of standards and methodologies to bear on the problem of authoring, sharing, and evaluating clinical knowledge, with the goal of streamlining the development and implementation of guideline-based clinical care.

For more information on this approach, see the Approach and Methodology sections of the FHIR Clinical Guidelines implementation guide.

This implementation guide was built as part of the Clinical Quality Framework community by identifying and refactoring common patterns used across projects. Feedback and contributions are welcome and can be submitted using the New Issue link in the footer of every page. Discussions on the use of this IG as well as other CQF projects take place regularly on the CPG-on-FHIR calls, a subworkgroup of the HL7 Clinical Decision Support Workgroup.

Roadmap

This project uses the FHIR Community Process. For complete documentation on the change management process used, refer to the Change Management documentation.

This first release of the CQF Common implementation guide supports use of CQL v1.4+ with FHIR v4.01 and CPG v1.0.0. This content will be periodically updated as required to incorporate support for new versions of FHIR, CQL, and CPG as they are published, and as needed by projects that make use of these assets.

To submit feedback on this project, submit a New Issue on Github (also linked in the Propose a change link in the footer of every page of the IG).

Contents

This implementation guide contains libraries that facilitate the use of CQL with FHIR®, as explained in the sections below. To use these libraries in your implementation guide, include a reference to this implementation guide as an implementation guide dependency:

<dependsOn id="cqf">
  <uri value="http://fhir.org/guides/cqf/common/ImplementationGuide/fhir.cqf.common"/>
  <packageId value="fhir.cqf.common"/>
  <!--NOTE: Use the dev version here because the CQF IG has not yet been published.
  Note that this also means that the CQF IG must be built locally in order to be installed in your local FHIR package cache
  <version value="4.0.1"/>
  -->
  <version value="dev"/>
</dependsOn>

FHIR ModelInfo

Clinical Quality Language (CQL) is a high-level, domain-specific language focused on clinical quality and targeted at measure and decision support artifact authors. In addition, the CQL specification provides a machine-readable canonical representation called Expression Logical Model (ELM) targeted at implementations and designed to enable automated sharing of clinical knowledge.

To use CQL with FHIR, model information must be provided to the implementation environment. The FHIR-ModelInfo library provides this information for FHIR. To use FHIR, include a using declaration as shown in the example below:

using FHIR version '4.0.1'

Although not required by CQL, current best-practice is to include the version of FHIR.

FHIR Helpers

As an exchange specification, FHIR has a rich syntax for expressing the values of elements defined in FHIR resources. In particular, FHIR data types for representing basic values such as integers, strings, and dates and times allow for extensions. This means that a FHIR string is not just a string value, but has elements (specifically, id, extension, and value, where the value element contains the actual string value). This means that to access the actual value of a FHIR string element in CQL, authors would need to reference the value element:

define "Patient is Female":
  Patient.gender.value = 'female'

To avoid this, the FHIRHelpers library defines implicit conversions for all the FHIR types, allowing authors to treat FHIR elements as integers, strings, etc. directly:

define "Patient is Female":
  Patient.gender = 'female'

Note that these conversions are performed automatically by the CQL-to-ELM translator when they are used by CQL, resulting in a conversion error if the FHIRHelpers library is not included using an include declaration:

include FHIRHelpers version '4.0.1'

Again, the version of the library is not required by CQL, but for the FHIRHelpers reference, because it is so closely tied to the FHIR ModelInfo, current best-practice is to include the version of FHIRHelpers. This does not imply that all library references should be versioned, that is a decision left up to implementations.

FHIR Common

In addition to FHIR Helpers, the FHIR Common library contains several useful constructs for FHIR-based CQL artifact development, including declarations for commonly used terminologies, as well as functions for dealing with common choice patterns and extensions.

Note that FHIRCommon is not a "well-known" library name, so it must be included using it's namespace:

include fhir.cqf.common.FHIRCommon