CQL Services 3.2.0

CQL Services 3.2.0 adds support for configuring prefetch templates for CDS Hooks services. This allows implementers to add, remove, or override prefetch keys in the prefetch template generated from a service's CQL. To do this, implementers specify a prefetch object in the service's CQL Hooks configuration. For each key in that prefetch configuration object:

• If the key does not exist in the prefetch template generated from the CQL, it will be added to the generated prefetch template.
• If the key matches a key in the generated prefetch template, then...
  • If the key's value is a non-empty string, it will override the generated prefetch value for that key in the prefetch template.
  • If the key's value is null or an empty string (""), then that prefetch key will be removed from the prefetch template.

Any keys in the generated prefetch template that are not in the prefetch configuration object will remain in the prefetch template as-is.

For example, the following configuration specifies that although the CQL contains a Retrieve for the Medication resource, the prefetch template should not include a query for Medication. This will result in the CQL being executed without any Medication resource data. In this specific case, this avoids an unfiltered query for all Medication resources, but also means that MedicationRequest resources must specify the medication using medicationCodeableConcept rather than medicationReference. Implementers are responsible for ensuring that overridden and removed prefetch keys do not adversely impact the validity of the CQL logic execution.

{
  "id": "statin-use",
  "hook": "patient-view",
  "title": "Statin Use for the Primary Prevention of CVD in Adults",
  "description": "Presents a United States Preventive Services Task Force (USPSTF) statin therapy recommendation for adults aged 40 to 75 years without a history of cardiovascular disease (CVD) who have 1 or more CVD risk factors (i.e., dyslipidemia, diabetes, hypertension, or smoking) and a calculated 10-year CVD event risk score of 7.5% or greater.",
  "usageRequirements": "NOTE: This service requires a pre-calculated CVD 10-year risk score stored as an Observation w/ code: LOINC 79423-0",
  "prefetch": {
    "Medication": null
  },
  "_config": {
    "cards": [{
      "conditionExpression": "InPopulation",
      "card": {
        "summary": "Statin Use for the Primary Prevention of CVD in Adults",
        "indicator": "info",
        "detail": "${Recommendation}",
        "source": {
          "label": "CDS Connect: Statin Use for the Primary Prevention of CVD in Adults",
          "url": "https://cds.ahrq.gov/cdsconnect/artifact/statin-use-primary-prevention-cvd-adults"
        },
        "extension": {
          "grade": "${RecommendationGrade}",
          "rationale": "${Rationale}"
        }
      }
    }],
    "cql": {
      "library": {
        "id": "USPSTFStatinUseForPrimaryPreventionOfCVDInAdultsFHIRv401",
        "version": "2.0.0"
      }
    }
  }
}

Full Changelog: v3.1.0...v3.2.0

CQL Services 3.1.0

CQL Services 3.1.0 includes the following changes:

• Support for CDS Hooks 2.0 features, including system actions and card feedback
• Hooks responses now generate UUIDs for cards and suggestions
• Implementers can use a CARD_LOGGING environment variable to log Hooks cards and feedback to files or to the console
• The simple client was updated to support sending feedback
• All dependencies were updated to their latest versions
• Documentation was updated as appropriate

See the README for more information.

Full Changelog: v3.0.0...v3.1.0

CQL Services 3.0.0

CQL Services 3.0.0 includes the following changes:

• Breaking Change: CQL Services now requires Node 18
• Breaking Change: UMLS username/password is no longer supported. Only UMLS API keys are supported.
• CQL execution has been updated to v3.0.1, which uses an asynchronous API
• Other dependencies have been updated to their latest versions
• Yarn has been replaced by npm for project development
• Example libraries have been updated

For an understanding of changes to the underlying CQL execution engine, see the release notes for CQL Execution 2.4.0, 2.4.1, 2.4.2, 2.4.3, 2.4.4, 2.4.5, 2.4.6, 3.0.0, and 3.0.1.

Full Changelog: v2.0.1...v3.0.0

CQL Services 2.0.1

CQL Services 2.0.0 is a patch release that updates the CQL execution libraries that are used as well as updates other dependencies to their latest compatible versions.

For an understanding of changes to the underlying CQL execution engine, see the release notes for CQL Execution 2.3.0, 2.3.1, 2.3.2, and 2.3.3.

CQL Services 2.0.0

CQL Services 2.0.0 is a major release containing the following updates:

• Introduces support for calling back to the FHIR server if the request does not provide all of the prefetch keys
• Introduces support for CQL based on the FHIR 4.0.1 data model
• Uses the new cql-execution 2.x and cql-exec-fhir 2.x libraries, with improved support for CQL 1.4/1.5
• Updates the docker image to use Node 12

Breaking Changes

The CQL execution engine that CQL Services uses is now compliant w/ CQL 1.4 and 1.5 specifications (although it does not provide complete support for all of the spec). CQL Services 1.x used a CQL Execution engine based on the CQL 1.3 specification. The behavior of some CQL operations was modifed between versions of the spec and therefore may result in differences in execution results. See the CQL Specification for more specific information about changes in each specification version.

The FHIR data model plugin that CQL Services 2.0.0 leverages has updated its internal FHIR models. This is a breaking change because the updated models changed the type of Extension.url from System.String to FHIR.uri. As a result, this version of CQL Services will only work correctly with CQL that was compiled using CQL-to-ELM translator versions that also use the updated models. These versions are:

• CQL 1.3: CQL-to-ELM 1.3.21 and above
• CQL 1.4: CQL-to-ELM 1.4.9 and above
• CQL 1.5: CQL-to-ELM 1.5.0 and above

CQL Services 1.7.0

CQL Services 1.7.0 adds support for authenticating to VSAC using a UMLS API key. Starting January 1, the VSAC service that this library uses will only support authentication via UMLS API key. Until then, you can authenticate using username/password or API key.

To authenticate using a UMLS API key, set the UMLS_API_KEY environment variable with your API key. See the README for more information.

CQL Services 1.6.1

CQL Services 1.6.1 fixes support for version-specific value sets. If a CQL library declares a value set with a specific version, CQL Testing will download that specific version of the ValueSet from VSAC. Prior to this release, CQL Testing ignored the value set version when downloading value sets from VSAC.

CQL Services 1.6.0

CQL Services 1.6.0 adds support for VSAC value sets identified using their FHIR URLs or URNs. For example, all of the following are supported now:

valueset "Diabetes": '2.16.840.1.113883.3.464.1003.103.12.1001'

or

valueset "Diabetes": 'urn:oid:2.16.840.1.113883.3.464.1003.103.12.1001'

or

valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001'

Previous versions only supported the first case (OID).

1.5.0

Version 1.5.0 adds support for FHIR STU3 and R4. Now CQL services will automatically detect the version of FHIR from the loaded CQL and configure execution appropriately.

Support CQL Data Models:

• FHIR 1.0.2
• FHIR 3.0.0
• FHIR 4.0.0

1.4.5

v1.4.5

v1.4.5