cqframework/cqf-tooling

Tooling for CQL and IG Authors

cqf-tooling

Tooling for CQL and IG Authors

This tooling provides various useful tools for building CQFramework related content and implementation guides, including QUICK page generation, ModelInfo generation from StructureDefinitions, and ValueSet creation.

Usage

Building this project requires Java 11+ and Maven 3.8+. The resulting jar is compatible with Java 11+.

Build the project with:

mvn package

Run a specific operation using (example running VSAC Spreadsheet conversion):

mvn exec:java \
-Dexec.mainClass="org.opencds.cqf.tooling.cli.Main" \
-Dexec.args="-VsacXlsxToValueSetBatch \
-ptsd=src/test/resources/org/opencds/cqf/tooling/terminology \
-op=target/test/resources/org/opencds/cqf/tooling/terminology/output \
-setname=true \
-vssrc=cms"

Executable jars are produced by the CI system on Maven Central: Download executable jar

This can be run with java -jar tooling-cli-2.0.0.jar -VsacXlsxToValueSetBatch

Documentation of the various operations is provided in the Main class.

Commit Policy

All new development takes place on <feature> branches off master. Once feature development on the branch is complete, the feature branch is submitted to master as a PR. The PR is reviewed by maintainers and regression testing by the CI build occurs.

Changes to the master branch must be done through an approved PR. Delete branches after merging to keep the repository clean.

Merges to master trigger a deployment to the Maven Snapshots repositories. Once ready for a release, the master branch is updated with the correct version number and is tagged. Tags trigger a full release to Maven Central and a corresponding release to Github. Releases SHALL NOT have a SNAPSHOT version, nor any SNAPSHOT dependencies.

Release Process

To release a new version of the tooling:

1. Update master to be a release version (and all the reviews, bug fixes, etc. that that requires)
   1. Regression test against IGs known to use CQF Tooling
2. Passed Travis Build = ready for release
3. Create a Github Release (which creates a tag at the current commit of master)
   1. Choose the "Auto-generate release notes" option
4. Travis does the release to Maven
   1. Ensure binaries are published to https://oss.sonatype.org/#view-repositories;public~browsestorage~org/opencds/cqf/tooling
5. Update master to vNext-SNAPSHOT
6. Close all issues included in the release

Getting Help

Bugs and feature requests can be filed with Github Issues.

The implementers are active on the official FHIR Zulip chat for CQL.

Inquires for commercial support can be directed to [email protected].

Related Projects

Clinical Quality Language - Tooling in support of the CQL specification, including the CQL verifier/translator used in this project.

CQL Support for Atom - Open source CQL IDE with syntax highlighting, linting, and local CQL evaluation.

CQF Ruler - Integrates this project into the HAPI FHIR server, exposing some functionality as services.

License

Copyright 2019+ Dynamic Content Group, LLC (dba Alphora)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

cqf-tooling's Issues

Project Governance and other documentation

The project currently does not have issue templates, contribution guidelines, or a governance model documented. This needs to be done.

Add tooling to produce an executable version of a value set

Add a function of the tooling that takes a computable value set and produces an executable value set.

Add/update primary code paths in FHIR model info

Add or update the following primary code paths in the FHIR R4 Model Info generation:

DeviceRequest -> code
DetectedIssue -> code
BodyStructure -> location
PractitionerRole -> code
RelatedPerson -> relationship
AdverseEvent -> event
Location -> type

Better support for ValueSet generation from VSAC spreadsheets

Enhance the VSAC tooling to support CPG terminology profiles.

Parsing the CQL library directly, bypassing the ELM.

There was also an issue with the ELM back in the day that led to parsing the CQL of the library directly, bypassing the ELM.

Add NpmPackage reading capability

Delete the comments from the CodeSystemLookupDictionary

The comments at the top of the page:

https://github.com/cqframework/cqf-tooling/blob/master/src/main/java/org/opencds/cqf/terminology/CodeSystemLookupDictionary.java#L5

Are inconsistent with what's actually in the dictionary and should just be removed as unhelpful.

However, DO NOT REMOVE THE COMMENT THAT CAPTURES THE SOURCE AND VERSION FROM WHICH THIS CONTENT WAS PRODUCED.

Add HSLOC code system to CodeSystemLookupDictionary

The full May 2020 eCQM valuesets from VSAC include a handful of codes from HSLOC which is not found as a valid code system

Defining URL:	http://terminology.hl7.org/CodeSystem/hsloc
Version:	2.0.0
Name:	Hsloc
Title:	Healthcare Service Location
Status:	Active
Content:	None of the concepts defined by the code system are included in the code system resource
Definition:	A comprehensive classification of locations and settings where healthcare services are provided. This value set is based on the National Healthcare Safety Network (NHSN) location code system that has been developed over a number of years through CDC's interaction with a variety of healthcare facilities and is intended to serve a variety of reporting needs where coding of healthcare service locations is required.The HSLOC content, including relationships can be acced at the following location: http://www.cdc.gov/phin/activities/standards/vocabulary/index.html
Publisher:	TBD - External Body
OID:	2.16.840.1.113883.6.259 (for OID based terminology systems)

Tooling requires included library files to be named using their version number

Currently the tooling requires the included libraries to be named with name and version such as Hospice-2.0.000. If we remove the version numbers from the filenames it breaks when refreshing and bundling the measures

4 included cql Libraries not found:
Hospice-2.0.000 MISSING
AdultOutpatientEncounters-2.0.000 MISSING
MATGlobalCommonFunctions-5.0.000 MISSING
SupplementalDataElements-2.0.0 MISSING

We should be able to name the libraries without their version number embedded in the filename. For backward compatibility we might want to look for the library without version number and if found use it. If not found then look for the library with the version number.

Update to Java 11

Currently, setting source and target to 11 results in misconfigured modules.

Update org.hl7 dependencies to latest version

Is your feature request related to a problem? Please describe.
feature request - update dependencies

Describe the solution you'd like
The org.hl7 dependencies are at version 5.0.22, the latest is 5.2.16

Describe alternatives you've considered
N/A

Additional context
N/A

FHIRHelpers logic is incorrect

FHIRHelpers logic is incorrect, see the following github issue for more details:
cqframework/clinical_quality_language#557

HTML escape text fields

Spreadsheet contains "Post-partum (<6 weeks)" in Master Data Element Label column for a code able concept data element. When built and the IG generated, this turns into an error because of unescaped text.

Add switch to enable/disable narrative generation.

The Publisher is now capable of narrative generation. It will only generate narrative if the resource does not already contain it. This means that running the refresh tooling - which generates narrative - before running the Publisher will result in the Publisher not generating narrative. We need to add a switch to the refresh tooling to turn off narrative generation so that it can be left to the Publisher.

Add library refresh generated content routine

Add a command to refresh all generated content in a Library.

The publisher currently does this in the CqlSubSystem here:

https://github.com/HL7/fhir-ig-publisher/blob/master/org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/publisher/CqlSubSystem.java

The tooling should do the same.

Update model info generation for US Core and QI Core to derive from FHIR

Currently the USCore and QICore models create a flattened view of the model info and use translator mapping to compile CQL down to base FHIR. This doesn't work for all cases though; connectathon testing indicates that the mappings can't resolve without being able to be expressed in terms of FHIR, which means the USCore and QICore mappings need to derive from FHIR in order to map correctly.

This means in particular that the primary model info generation will drive off of the differential, rather than the snapshot.

Add short, definition, and comment content to ModelInfo

Add support for text descriptions of the elements, pull from the short, definition, and comment elements of the StructureDefinition.

IG - Scaffold IG Operation

Add an operation to the tooling that could scaffold an IG project from scratch.

Some possible options:

• base template
• include resource directories
• include sample resources
  etc.

What is the source of the entry for "SNOMED CT US Edition"

Why does the CodeSystemLookupDictionary have an entry for "SNOMED CT US Edition"? According to the rules for code system URIs, this would not be defined as a code system, it has to be referenced using a version, so this entry needs to be removed, and whatever is using it needs to be fixed.

AcceleratorKit - Set Observation.category where specified

The category may be specified in the 'HL7 FHIR R4 - Additional FHIR Mapping details' column. If it is, the tooling needs to set it on the resource.

AcceleratorKit - Observation.code warning when multiple code

An Observation's code should continue to be bound to a single, primary code. In the case that there are multiple codes specified the tooling should write a warning to the console. Long-term - preserve the mapped list via mappings or something.

Break existing implementation into separate operations

Includes creating operations and exposing argument processors for each of these:

Refresh generated content
Refresh Publication data
Validate everything is correct
Package
Deploy

IG Refresh Tooling

Definition of done: The tooling supports being added to the genonce for an IG project and that automatically regenerates narrative for all knowledge resources (including PlanDefinitions and ActivityDefinitions), adds/sets publishing metadata for all conformance and knowledge resources, bundles test cases, and bundles packaging artifacts, and the results of all that are included in the published IG.

AcceleratorKit - Support multiple codes on DataElement

DataElement - both profile and extension - needs to support value set binding rather than fixedCodeableConcept only.

AcceleratorKit - Use base profile when specified

Tooling expects cql to exist under input/pagecontent/cql

If the cql folder is not under input/pagecontent the tooling will break and not be able to refresh or bundle the measure packages.

08:30:55.335 [main] WARN org.opencds.cqf.utilities.LogUtils - IGProcessor.publishIG - refreshIG
Exception in thread "main" java.lang.RuntimeException: Convention requires the following directory:input/pagecontent/cql/
at org.opencds.cqf.processor.IGProcessor.ensureDirectory(IGProcessor.java:210)
at org.opencds.cqf.processor.IGProcessor.ensure(IGProcessor.java:171)
at org.opencds.cqf.processor.IGRefreshProcessor.refreshIG(IGRefreshProcessor.java:50)
at org.opencds.cqf.processor.IGProcessor.publishIG(IGProcessor.java:78)
at org.opencds.cqf.operation.RefreshIGOperation.execute(RefreshIGOperation.java:23)
at org.opencds.cqf.Main.main(Main.java:141)

we should be able to specify the cql directory rather than look for it in a hard coded location

Add documentation about mvn settings.xml

I needed to create %USERPROFILE%.m2\settings.xml with the following to get the tool to work

<profiles>
	<profile>
		<id>oss.sonatype.org-snapshot</id>
		<repositories>
			<repository>
				<id>oss.sonatype.org-snapshot</id>
				<url>https://oss.sonatype.org/content/repositories/snapshots</url>
				<releases>
					<enabled>false</enabled>
				</releases>
				<snapshots>
					<enabled>true</enabled>
				</snapshots>
			</repository>
		</repositories>
	</profile>
</profiles>
<activeProfiles>
	<activeProfile>oss.sonatype.org-snapshot</activeProfile>
</activeProfiles>

Suggest adding some documentation about mvn configuration.

Replace path delimiter with File.separator

Describe the bug
Throughout the project "/" is used as a delimiter for file paths. This is OS specific. The "/" is for Linux/Mac and the "" is for Windows. We need to replace the delimiter with File.separator which is not OS specific. I replaced it in BundleResources.java. We need to be careful to differentiate between url paths and file paths.

To Reproduce
Search the java files for "/"

Expected behavior
File paths will work regardless of the OS.

AcceleratorKit - Generate Extensions

The AcceleratorKit processing should be capable of generating Extension StructureDefinitions for elements that are labeled as requiring an extension in the data dictionary mapping spreadsheet.

Duplicate Value Set detection

Some 'Conformance' tooling for detection of multiple value sets that contain the same set of codes.

Update templates to use FHIRPath

If the templates can be updated to use FHIRPath instead of the HAPI structures, then we can submit them to the base

e.g.

<th:if="${res.activityDefinition.hasReference()}">

has to be

<th:if="${res.activityDefinition.reference.exists()}">

Add generation to the new refresh process

For CQL libraries that do not have Library resources, generate a stub that then gets the content refresh.

Update tooling to CQL 1.5

Update the tooling to work with CQL 1.5

Support executable deployment packaging

Add packaging to the tooling to support "executable" profile packaging

Additional accelerator kit data dictionary generation

Add to the data dictionary structure definition generation:

1. Activity ID - Add as usedInActivity extension
2. Data Element Code (STI) - Add as mapping content
3. Data Element Code (FP) - Add as mapping content
4. *Data Element Label - SD.title and root ED.short
5. *Data Element Name - SD.name and root ED.label
6. *Notes - root ED.comment

*Priority

Also, set StructureDefinition.purpose to:
This profile provides a FHIR representation of the {{Data Element Code}}: {{Data Element Label}} from the {{Accelerator Kit Source}}.

Also, add an extension to support identifying a relatedArtifact on the extension that identifies the guideline.

Add PlanDefinition Generation

Support PlanDefinition generation from the DecisionTable format that is used in WHO Smart Guideline L2 content

Support FHIR 4.0.1 models and CQL 1.4 translator

Add support for creating model info suitable for the CQL 1.4 translator, and using the FHIR 4.0.1 technical correction.

FlatMultiValueSetGenerator uses name for file name, should use id

Describe the bug
The FlatMultiValueSetGenerator uses name for the generated file, but name is not unique, so the files generated are not unique. The generator should use the id of the value set for generation.

To Reproduce
Run the FlatMultiValueSetGenerator with the May2020 Update, which has value sets that have the same name, but different OIDs

Expected behavior
ValueSet files should be generated with their OID as the name:
valueset-1.2.3.4.5.6.7.json

Additional context
The relevant line to be changed is here:
https://github.com/cqframework/cqf-tooling/blob/develop/src/main/java/org/opencds/cqf/tooling/terminology/FlatMultiValueSetGeneratorBase.java#L240

The VSACValueSetGenerator illustrates an example of using the id:
https://github.com/cqframework/cqf-tooling/blob/develop/src/main/java/org/opencds/cqf/tooling/terminology/VSACValueSetGenerator.java#L129

Add ability to export CQL and ELM files from a bundle

Given a MAT-on-FHIR package or an individual XML or JSON bundle which contains Measure and Library resources that contain base64 encoded CQL and ELM (JSON and/or XML), provide a command line option to export the content.data from Library resources (with contentType text/cql, application/elm+xml and application/elm+json).

AcceleratorKit - Consolidation of value sets

The AcceleratorKit processing should be capable of consolidating generated value set outputs for elements that re-use terminology.

Refresh IG fails on case-sensitive operating systems

If the IG has a structure such as:

input/resources/Library

instead of:

input/resources/library

It will fail to refresh. To repro:

1. check out the Opioid cds ig on mac or linux
2. Rename the library folder to Library
3. Run the refresh

AcceleratorKit - Support for slicing in profiles

The AcceleratorKit processing should be capable of generating slices in StructureDefinitions outputs for elements that are labeled as requiring a slice in the data dictionary mapping spreadsheet.

Refresh IG fails when measure or library folder is missing

Refresh IG appears to require that the following folders exist, even if no such resources are in the IG.
input/resources/library
input/resources/measure

To repro:

1. Check out the opioid cds IG repo
2. Delete everything under input/resources
3. Run refresh

Add SpreadsheetToCql operation

Given an arbitrary spreadsheet, convert it to a Cql expression.

Need to special case "id" in ModelInfo generation

Currently, the ModelInfo generation is typing the FHIR Resource.id element as System.String. According to the FHIR spec this is a FHIR.id, but the issue is that the source structure definitions are incorrect. Until that's fixed the tooling needs to special case that.

Implement templating

Ensure everything exists and create as much of things that don’t as possible

• JSON resources that are parameterized
  • Measure, PlanDefinition, ActivityDefinition, Test Case
    • Directory, Patient resource, ExpectedResult (MeasureReport resource
• Atom plugin exists for this?

Update tooling to use 1.4.9-SNAPSHOT translator

Update the tooling to use the new 1.4.9-SNAPSHOT of the translator

Two tests temporarily commented to fix CI build

NpmPackageManagerTests.TestSampleContentIG
NpmPackageManagerTests.TestLibrarySourceProvider

Modify Jurisdiction code system generation to set type of postal codes property to 'string' and omit Uri.

AcceleratorKit - Documentation

Documentation around how to use the CQF-Tooling AcceleratorKit processor.
Link back to the AcceleratorKit.