This page is part of the Common CQL Assets for FHIR (US-Based) (v1.0.0: Informative 1 - Informative) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

Authoring Documentation

Page standards status: Informative

The following topics provide tools and guidance for authoring CQL-based knowledge artifacts.

Content Implementation Guide Authoring

Content implementation guides allow for CQL-based knowledge artifacts to be authored, validated, tested, and published as part of FHIR implementation guides. The primary tool that supports this use case is the FHIR Implementation Guide publisher itself.

In particular, the publisher supports processing and validation of CQL libraries through Binary Adjunct Files. The source for these libraries can be edited alongside the other source for the rest of the IG, using tools such as the CQFramework CQL Plugin for Visual Studio Code.

For a walkthrough of how to build and maintain a content implementation guide, refer to the Colorectal Cancer Screening Walkthrough. This walkthrough covers the creation of a content implementation guide that has a simple decision support and quality measure related to colorectal cancer screening.

CDS Connect Authoring Tool - Community Edition

For authoring Clinical Decision Support Rules, as well as general CQL Libraries, the CDS Connect Authoring Tool - Community Edition is an easy-to-use, stand-alone visual editor for Clinical Quality Language-based knowledge artifacts. In addition to support the CDS and Data Elements Library use cases, this tool is being actively evolved by a community of stakeholders to support other use CQL-based knowledge artifact use cases. For prior-authorization questionnaires, this tool was evaluated for supporting questionnaire authoring. See the Tooling Support page for more information.

LHC Forms Builder

For authoring questionnaires specifically, the LHC Forms Builder provides a user-friendly tool for building and validating FHIR Structured Data Capture Questionnaires. For prior-authorization questionnaires, this tool was evaluated to determine what would be needed to expand it to support CQL-based population and form behavior expressions. See the Tooling Support page for more information.

Steps for Adding New Questionnaires

Adding new content to this IG involves several steps. There are multiple ways to complete many of these steps, and this guide highlights one path for adding a new Questionnaire:

1. Select a questionnaire form (e.g. a prior authorization form), which typically is in a non-computable format such as the PDF form Medical Necessity For Authorization Of Catheters
2. Manually translate the PDF content into a FHIR Questionnaire (this can optionally be done first in FSH format but ultimately must be present as an XML or JSON FHIR resource located at the path input/resources/questionnaire). An example for the form in #1 can be found here.
3. Add the extension http://hl7.org/fhir/StructureDefinition/cqf-library to the Questionnaire with the canonical value of the related CQL library.
4. Setup a launch context extension sdc-questionnaire-launchContext for the Patient and any parameters the CQL Library has.
5. For each Questionnaire item that should ultimately have an initial value assigned, add the extension http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression with an expression title that will later be used as a link to the related CQL definitions that are responsible for determining the content of the initial value for this item.
   • If there is a group item that repeats or if multiple items are being populated from the same Resource, the extension http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-itemPopulationContext can be used in combination with the initial expression extension. Details on how to use this expression can be found in the SDC IG.
6. Create a CQL file located at input/cql and remember to name it the same as the end of the canonical URL defined in step #3. An example for the MNAC form can be found here.
7. For each unique initial expression present in the FHIR Questionnaire file, create a definition with the same title in the CQL file created in step #5, and fill those expressions with CQL content.
8. The CQL VS Code extension allows for right-clicking Execute CQL. To successfully investigate if a certain definition results in the desired output, some test resources need to be provided and located in a folder at the following path: input/tests/library/YOUR-CQL-LIBRARY-NAME. Sub-folders can define multiple patients filled with multiple resource files. The MNAC test folder with resources of a Patient called example can be found here.
9. Execute the _refresh script (.sh or .bat as appropriate), and watch multiple things happening automatically:
   • In bundles/questionnaires, a new folder with the Questionnaire name is create, which includes a bundle containing the FHIR Library with the CQL content and the related dependency libraries.
   • In the Library's test folder, a test bundle appears that contains all test resources in one file.
10. Start a local instance of the Clinical Reasoning enabled HAPI JPA Server Starter (e.g. by using Docker) or use a publicly available FHIR server that supports CQL processing and the SDC $populate operation.
11. Use a REST tool such as Postman to POST the two bundles described in step #9.
12. Test and see if the operation $populate for your questionnaire results in the expected initial values for each item. A complete sample Postman collection for a different Questionnaire can be found here. This collection also contains automated tests to highlight what to look for.

Frequent Errors

• When refreshing the IG (by executing sh _refresh.sh), sometimes errors in the Questionnaire or CQL cause the new content to be ignored and no output bundle being created. A frequent error is that a wrong or non-existent library name is defined within the Questionnaire.json element cql-library extension.
• Special Characters in CQL expression titles: The engine will not be able to resolve special characters within CQL expression titles. E.g. define "Practitioner's phone" will fail and must be renamed to define "Practitioner phone".