CQL Execution VSAC Code Service
This project establishes a VSAC-enabled code service module for use with the CQL Execution Engine. This allows the CQL Execution Engine to execute CQL containing references to Value Sets that are published in the National Library of Medicine's (NLM) Value Set Authority Center (VSAC). Value Set references can be defined using a valid VSAC identifying URL for the value set, a URN, or the oid itself. For example:
valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/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": '2.16.840.1.113883.3.464.1003.103.12.1001'
As of 1.1.1, this library supports Value Set versions, so the following is also supported:
valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315' // or valueset "Diabetes": 'urn:oid:2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315' // or valueset "Diabetes": '2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315'
When using the canonical URL as a Value Set identifier, it is also possible to embed the version directly in the URL, using a vertical bar (
|) to separate the identifier and version:
valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001|20190315'
The embedded version, however, is only supported for the canonical URL form of value sets. It is not supported for URN or OID identifiers.
This library requires that the credentials of a valid UMLS account be provided to it. If you do not have an UMLS account, you can request one here: https://uts.nlm.nih.gov/license.html
Setting Up the Environment
To use this project, you should perform the following steps:
Using the VSAC Code Service
The Local Cache
The VSAC Code Service is constructed with a file path pointing to the location where the cache should be stored. If
a file location is not passed into the constructor, it will default the cache to a folder called
vsac_cache in the
working directory. The cache is used to store value sets and their codes after retrieving them from VSAC. This
prevents the code service from having to make multiple calls to VSAC for the same value set.
The second argument to the
CodeService constructor is a boolean indicating if the code service should begin by
loading existing value sets from the cache. If true, it will initialize the code service from the cache (if the
cache exists and is populated). If false,
ensureValueSets will re-download any value sets passed to it, overwriting
Using UMLS Credentials
Downloading value set definitions from VSAC requires a valid UMLS account. The code service's
function allows a UMLS username and password to be passed in. Alternately, the UMLS username and password can be
UMLS_PASSWORD environment variables.
Downloading Value Set Definitions
ensureValueSetsInLibrary functions are the only functions that attempt to download value
sets from VSAC. Before they make a request to VSAC, they will check the cache. If the value set is already in the
cache, they will not make a request to VSAC. Otherwise, they will use VSAC's SVS2 API to download the expanded codes
from the value set.
findValueSets functions (including the legacy
findValueSetsByOid function) do not reach out
to VSAC, so implementations should call
ensureValueSets before attempting to execute
ensureValueSets is used, the implementor is responsible for passing in the OIDs / versions that will be
The following is a simple example of setting up the VSAC Code Service, calling
ensureValueSets, and passing the
Code Service into the CQL Execution engine:
const vsac = ;// Code setting up the CQL library, patient source, parameters, etc// ...// Set up the code service, loading from the cache if it existsconst codeService = '/path/to/vsac_cache' true;// Ensure value sets in the library and its dependencies, downloading any missing value setscodeService;
Linting the Code
To encourage quality and consistency within the code base, all code should pass eslint without any warnings. Many text editors can be configured to automatically flag eslint violations. We also provide an npm script for running eslint on the project. To run eslint, execute the following command:
$ yarn lint