This Quickstart can be used to:

1. Setting up
   • Atom and CQL package
   • Cloning the git repo
   • Executing the CQL
2. Initial build
   • Refreshing the IG
3. Access a FHIR server
   • Use the hosted cqf-ruler sandbox
   • Clone and run cqf-ruler locally
   • Start a cqf-ruler docker container
   • Bring your own FHIR server
4. Load and Run content on FHIR Server
   • CMS130 is used as an example in this Quickstart
5. Develop content locally

1. Download and Install Atom, a free and open source text editor

2. Install CQL package within Atom https://atom.io/packages/language-cql

Click on File > Settings. This will bring up the Settings View. Here, select Install and type the name of the package "cql-lanaguage" within the search box. Click on the install button for the cql-language package.

1. Clone the Connectathon repository: https://github.com/DBCG/connectathon.

You clone a repository with git clone . For example, if you want to clone connectathon repo, you can do so via the command:

$ git clone https://github.com/DBCG/connectathon

2. Navigate to the desired FHIR version and open via Atom. (i.e. FHIR3, FHIR4, FHIR401)

Note: A specific FHIR version folder should be opened and and not the "connecthaton" folder containing all FHIR versions

Each FHIR version contains the measure artifacts for all FHIR based eCQMs. It is setup like any HL7 FHIR IG project but also includes the CQL files and test data which means the file structure will be as follows:

   |-- _genonce.bat
   |-- _genonce.sh
   |-- _refresh.bat
   |-- _refresh.sh
   |-- _updatePublisher.bat
   |-- _updatePublisher.sh
   |-- _updateCQFTooling.bat
   |-- _updateCQFTooling.sh
   |-- ig.ini
   |-- bundles
       |-- measure
           |--EXM124
   |-- input
       |-- connectathon.xml
       |-- pagecontent
           |-- cql
               |-- EXM124.cql
       |-- resources
           |-- library
               |-- EXM124.json
           |-- measure
               |-- EXM124.json
       |-- tests
           |-- measure
               |-- EXM124
       |-- vocabulary
           |-- valueset

The CQL support in Atom adds syntax highlighting, semantic (error) highlighting, and local execution to CQL files. The .cql files should be located within input>pagecontent>cql directory:

   |-- _genonce.bat
   |-- _genonce.sh
   |-- _refresh.bat
   |-- _refresh.sh
   |-- _updatePublisher.bat
   |-- _updatePublisher.sh
   |-- _updateCQFTooling.bat
   |-- _updateCQFTooling.sh
   |-- ig.ini
   |-- bundles
   |-- input
       |-- connectathon.xml
       |-- pagecontent
           |-- cql
               |-- EXM124.cql
       |-- resources
       |-- tests
       |-- vocabulary

When opening the .cql file, syntax and error highlighting will be automatically applied.

1. To execute the CQL against known test data results, right-click IN the CQL Editor Windows of the specific CQL being worked on (i.e. EXM124.cql). A drop down menu will appear and you should be able to find and select CQL -> Execute or press F5

2. The translation and execution capabilities of the plugin will run testing of the CQL against both the data and terminology path which are located in the directory:

   Data path: input/tests/measure/<cql-library-name>
   Terminology path: input/vocabulary/valueset

Within the tests folder, there is a folder for each CQL library, by name (note that the name of the file must match the name of the library in order for the evaluator to properly execute the CQL (i.e. EXM124.cql -> EXM124)).

Refreshing the IG includes two steps:

(note that the first step is only required periodically, to get the latest version of the tooling that refreshes the IG)

1. Navigate to the root of the desired FHIR version (i.e. FHIR3, FHIR4, FHIR401)

2. run _updateRefreshIG: as noted, this will download the latestest version of the CQF Tooling to the input-cache directory, in the form of a java jar.

3. run _refresh: by default, this uses the CQF Tooling to perform the following steps:

   • for each .cql and Measure resource combination in the IG:
     • create or update the Library resource
     • bundle the associated Patient Scenario resources
     • create a "master" bundle that includes:
       • primary Library resource
       • Measure resource
       • Library resource dependencies
       • ValueSet resource dependencies
       • associated Patient Scenario resources bundles
     • post the "master" bundle to the Connectathon FHIR Server (http://cqm-sandbox.alphora.com/)
     • save the following to the bundles directory of the IG:
       • "master" bundle
       • .cql file
       • primary Library resource
       • Measure resource
       • Library resource dependencies bundle
       • ValueSet resource dependencies bundle
       • a separate bundle for each set of associated Patient Scenario resources
       • a separate MeasureReport resource for each assocaited Patient Scenario (if present)

The default behavior of running _refresh can be adjusted by changing the options in the _refresh file. One such usage is to post to a differnt FHIR Server (ex: local). To do so, modify the -fs (FHIR Server) option in _refresh. For more details on other options, run the CQF Tooling from the command line with -RefreshIG -help.

Endpoint: http://cqm-sandbox.alphora.com/cqf-ruler-r4/fhir/

Note: the sandbox only supports FHIR401. You will need to host your own copy for work with FHIR3 or FHIR4. Note: Requests can be submitted via any tool or client that allows you to interact with an HTTP API. One popular client is Postman, available at https://www.getpostman.com/.

The _refresh scripts for the Connectathon repository default to the respective locations instances. Don't forget to update them if you are editing content locally and running a local FHIR 4.0.1 Server.

Pre-requisites:

• Java JDK installed
  • https://www.oracle.com/technetwork/java/javase/downloads/jdk12-downloads-5295953.html
• Apache Maven installed
  • https://maven.apache.org/install.html
• Maven Jetty plugin installed
  • https://www.eclipse.org/jetty/documentation/9.4.x/jetty-maven-plugin.html
• Clone CQF Ruler
  • FHIR401: https://github.com/DBCG/cqf-ruler develop branch
  • FHIR3/FHIR4: https://github.com/DBCG/cqf-ruler master branch

The CQF Ruler is packaged with an embedded Jetty server, which can be easily started using the Maven Jetty plugin. The simplest example of spinning up the Jetty server can be done with the following command:

FHIR Stu3 Measures mvn jetty:run -am --projects cqf-ruler-dstu3

FHIR R4/R4.0.1 Measures mvn jetty:run -am --projects cqf-ruler-r4

After running that command the CQF Ruler will be available at the default endpoint:

FHIR Stu3 Measures http://localhost:8080/cqf-ruler-dstu3

FHIR R4/R4.0.1 Measures http://localhost:8080/cqf-ruler-r4

You can change the port with the jetty.http.port property:

mvn -Djetty.http.port=8081 jetty:run

Pre-requisites:

• Docker installed
  • https://hub.docker.com/

Select a Docker Container that is appropriate for the version of FHIR you are working with:

DSTU3/R4

docker pull contentgroup/cqf-ruler
docker run -p 8080:8080 contentgroup/cqf-ruler

R4.0.1

docker pull contentgroup/cqf-ruler:develop
docker run -p 8080:8080 contentgroup/cqf-ruler:develop

After running that command a CQF Ruler container will be available at the default endpoint:

FHIR Stu3 Measures http://localhost:8080/cqf-ruler-dstu3

FHIR R4/R4.0.1 Measures http://localhost:8080/cqf-ruler-r4

FHIR server must implement $evaluate-measure operation (https://www.hl7.org/fhir/measure-operation-evaluate-measure.html)

These steps can be performed for any Measure. We'll be using the exm130 measure as an example. Don't forget to set the Body Content-Type to "JSON (application/json)" when doing a PUT or a POST. You'll get an error like the following if you have the wrong Content-Type:

Incorrect Content-Type header value of "text/plain" was provided in the request. A FHIR Content-Type is required for "EXTENDED_OPERATION_SERVER" operation.

Note: Instead of loading the content separately, as described below, you can access a premade Postman collection:

FHIR401: Postman Collection

As of the time of the posting of the Postman collection, the following Measures return expected results. The remaining entries are provided for convenience. As the Postman collection may get out of sync with the repository, please check with the track lead for the current status.

Returning expected results from Postman collection:

• R401
  • EXM108
  • EXM124
  • EXM125
  • EXM130
  • EXM506
  • EXM529

Use an HTTP client to load the following Bundle into your local cqf-ruler instance:

EXM130 Bundle

Bundle Request: POST: http://localhost:8080/cqf-ruler-r4/fhir

For more information on how to load resources into the cqf-ruler, refer to the following wiki page

The bundle linked above includes:

• The Measure resource for the definition of the EXM130 eCQM
• The Primary Library resource for the population criteria of the EXM130 eCQM
• Dependent libraries referenced by the Primary Library necessary to evaluate the population criteria
• ValueSet resources referenced by the primary library or any dependent libraries necessary to evaluate the population criteria
• Test Cases in the form of MeasureReport and example patient data resources

To view the loaded resources, use an HTTP client to issue the following requests:

GET: http://localhost:8080/cqf-ruler-r4/fhir/Measure/measure-EXM130-7.3.000
GET: http://localhost:8080/cqf-ruler-r4/fhir/Library/library-EXM130-7.3.000
GET: http://localhost:8080/cqf-ruler-r4/fhir/ValueSet
GET: http://localhost:8080/cqf-ruler-r4/fhir/MeasureReport

The CQF Ruler uses the build-in terminology server in the HAPI FHIR reference implementation to support terminology evaluation used by the measure reporting. To ensure this terminology server has the information it needs for code systems referenced by the value sets used, the CQF Ruler has an updateCodeSystems operation.

Use an HTTP client (such as Postman) to execute the updateCodeSystems operation to update the Code Systems in your local cqf-ruler instance:

GET: http://localhost:8080/cqf-ruler-r4/fhir/$updateCodeSystems

Once all the content has been loaded (Measure, Libraries and test Bundles), run the following requests from an HTTP client:

• Patient "out" test (not included in measure numerator): GET: http://cqm-sandbox.alphora.com/cqf-ruler-r4/fhir/Measure/measure-EXM130-8.0.000/$evaluate-measure?patient=denom-EXM130&periodStart=2019-01-01&periodEnd=2019-12-31

The expected result is:

measurereport-EXM130-7.3.000-denom.json

Initial Population: true (count: 1)

Numerator: false (count 0)

Denominator: true (count 1)

Denominator Exclusion: false (count 0)

• Patient "in" test (included in measure numerator): GET: http://cqm-sandbox.alphora.com/cqf-ruler-r4/fhir/Measure/measure-EXM130-7.3.000/$evaluate-measure?patient=numer-EXM130&periodStart=2019-01-01&periodEnd=2019-12-31

The expected result is:

measurereport-EXM130-7.3.000-numer.json

Initial Population: true (count: 1)

Numerator: true (count 1)

Denominator: true (count 1)

Denominator Exclusion: false (count 0)

Follow the same steps above to load content for other measures and evaluate. To evaluate for other measures, just replace the measure number with the measure you would like to run and the id of the test patient for the test case.

The ReadMe page includes available measures and links for the bundles.

1. Clone the Connectathon repository: https://github.com/DBCG/connectathon.

2. Navigate to the desired FHIR version.

3. Edit content in the cql directory (or any of the other content, except Library resources. Those, are maintained by the tooling).

4. Once your edits are complete:

   • Navigate to the root of the desired FHIR version.
   • If you haven't already, run _updateRefreshIG to get the refresh tooling.
   • Run _refresh to update the local content with your changes
   • The results will be posted to the configured FHIR Server (the Connectathon sandbox or localhost, by default, depending on the FHIR version).
     • Alternatively, you can navigate to the bundles directory and manually employ the associated files.