Skip to content

Quickstart

Jump to bottom
Jack Levitt edited this page Sep 10, 2020 · 125 revisions

Introduction

This Quickstart can be used to:

  1. 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

  2. Load and Run content on FHIR Server

    • CMS130 is used as an example in this Quickstart

  3. Develop content locally

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/.

Access a FHIR Server

Option 1: Use the hosted cqf-ruler sandbox

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.

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.

Option 2: Clone and run cqf-ruler locally

Pre-requisites:

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

Option 3: Start a cqf-ruler docker container

Pre-requisites:

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

Option 4: Bring your own FHIR server

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

Load and Execute Content

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

How to load Content for CMS130 401

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

Ensuring Terminology Content is consistent for CMS130 R4

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

How to Evaluate CMS130 401

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)

How to Evaluate Other Measures

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.

Develop Content Locally

  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.
Clone this wiki locally