Emergency Department COVID-19 Severity Classification

This repository houses the source for building a CPG-on-FHIR content implementation guide for an Emergency Department COVID-19 Severity Classification. This logic represents an initial Minimum Viable Product (MVP) that implements a subset of the logic defined by the American College of Emergency Physicians (ACEP). Refer to the ACEP Guideline.

This MVP implementation is intended to align with, and eventually be replaced by, an equivalent logic library with substantially expanded functionality that is generated from OMG Business Process Modeling (BPM+) decision and case models, using an automated toolchain. Refer to the Open Clinical Practice Guidelines GitHub project.

The contents of this repository are licensed under an Apache 2.0 License with an additional healthcare related disclaimer and limitation of warranty. See the LICENSE page for details.

Content IG Walkthrough: Setup and Build

This repository provides a walkthrough of building a FHIR content implementation guide (content IG). A content IG is a FHIR implementation guide that primarily contains knowledge artifacts such as decision support rules and quality measures. By using the FHIR publication toolchain, these artifacts are made available as FHIR resources, published within websites for documentation and dissemination, and distributed as part of NPM packages for implementation.

This walkthrough consists of 5 main steps:

1. Setup: Setting up the IG and getting a basic build
2. Library: Including a simple Library for a specific recommendation
3. PlanDefinition: Adding a PlanDefinition to surface the recommendation as a decision support rule
4. Test Cases: Adding test cases to test the rule
5. Validation: Validating the content works as expected via the CDS Hooks Sandbox

Basic Setup

The first step is to get a local clone of the walkthrough repository.

Once you have a local clone, you'll need to build:

Dependencies

Before you're able to build this IG you'll need to install several dependencies

Java / IG Publisher

Go to https://adoptopenjdk.net/ and download the latest (version 8 or higher) JDK for your platform, and install it.

There are scripts in this repository that will download and run the latest HL7 IG Publisher.

Please make sure that the Java bin directory is added to your path.

This project includes scripts that will automatically download the correct version of the IG-Publisher.

Documentation for the IG-Publisher is available at https://confluence.hl7.org/display/FHIR/IG+Publisher+Documentation.

Ruby / Jekyll

FIRST, Install Ruby through a Ruby version manager (rvm/rbenv/chruby) and then install Jekyll. brew install rbenv rbnev init add eval "$(rbenv init - zsh)" to ~/.zshrc or where your profile settings are. rbenv install 3.1.0 rbenv global 3.1.0

Jekyll requires Ruby version 2.1 or greater. ruby -v

Jekyll gem install --user-install bundler jekyll If jekyll -v doesn't work, add export PATH="/Users/<your-username>/.gem/ruby/3.1.0/bin:$PATH" to your ~/.zshrc or where your profile settings are. Try bundle exec jekyll -v if jekyll -v still doesn't work.

If installing on a macOS: https://jekyllrb.com/docs/installation/macos/

Go to https://jekyllrb.com for more information.

Build

Once you have the dependencies installed, you can build the IG by first updating the publisher:

_updatePublisher

Once the publisher has been downloaded to your local environment, you can build the IG:

_genonce

Whenever you make changes to the source content, just rerun the _genonce script to rebuild the IG. The IG output will be in the output folder. Using a browser, open the index.html page to see the IG.

NOTE: This walkthrough uses "contentig" as the name of the implementation guide. The source ImplementationGuide resource is in the contentig.xml file, and the ig.ini file refers to it. To change the name of the ig, be sure to update all references to contentig within the ImplementationGuide resource. Note that this name serves as part of the basis for the canonical URL for your IG, which is used to uniquely identify the implementation guide and all the resources published within it, so it's important to choose your canonical URL appropriately. For more information see the Canonical URLs discussion topic in the FHIR specification.

Adding a Library

The next step in this walkthrough is to build the recommendation logic as expressions of Clinical Quality Language (CQL). CQL is a high-level, author-friendly language that is used to express clinical reasoning artifacts such as decision support rules, quality measurement population criteria, and public health reporting criteria.

Atom CQL Support

To validate and test CQL, use the Atom CQL Plugin. Follow the instructions there to install the plugin, then open Atom on the root folder of this content IG walkthrough.

Publishing as an NPM Package

The IG can be packaged as an npm package for use in JavaScript applications.

Setup Before Publishing

Please read the steps carefully before beginning.

You may be able to skip down to Step 4. Install jsonfile if you have already completed the Setup and Build steps above.

Relevant documentation:

• Creating and publishing scoped public packages
• Publishing packages using GitHub Actions
• Configuring NPM for use with GitHub Packages

Note: Currently only supported for Linux/macOS.

1. Permissions for Publishing

Verify that you are able to publish packages to your target repository. The specific steps will vary depending on where you are publishing the package.

If you are publishing through GitHub Actions, you will need:

• A personal access token
  • The token will need both the write:packages permissions (including the read:packages) and most or all of the repo permissions

2. Install jekyll

1. Install Ruby 2.X if not already installed
2. gem install bundler (installs bundle command)
3. bundle install (installs jekyll)

3. IG Build

1. Update the IG Publisher: bash _updatePublisher.sh --force --yes
   • --force and --yes are optional
2. Generate the IG: bash _genonce.sh

4. Install jsonfile

1. Install Node and NPM if not already installed
2. npm install jsonfile

5. Update the package version

1. Open library-package.json (at project root) and increment the semver value in the version attribute
   • e.g. 0.0.1 -> 0.0.2

6. Publication

1. Publish to the repository: bash _publishToRepo.sh

7. Completion

If every step was successful, then the _publishToRepo script should report that the package was published. You can now check your repository to verify that the new version of the package was published successfully.

Using the Published NPM Package

Once the IG (implementation guide) has been published to a package repository, it can be imported into your JavaScript application via its package manager.

Importing from GitHub Packages

You will need:

• A personal access token
  • The token will need the read:packages and the repo permissions

Importing via NPM

Either:

• Install from the command line, e.g. npm install @chronic-care/covid-ed-ig@latest
• Or, add it to your project's package.json, e.g. "@chronic-care/covid-ed-ig": "latest"

You can replace latest in either of the above with a specific version number (e.g. 0.0.5) if desired.

Testing

There are a couple of ways to test the CQL.

1. Atom Testing
2. Unit Testing via the JavaScript CQL Engine

Updating Valuesets

If new codes need to be added to a valueset, follow these steps to manually update the JSON and regenerate the valueset-db.json file:

1. Add new codes to the relevant JSON files in input/vocabulary/valueset. For labs, add to both the compose and expansion objects.
2. Run ./_updateValueSet.sh. This updates the CQF tooling, generates the new valueset, copies it to the ./input/cql folder and then updates healthCodes.json with the new codes as well.

CQL Development Resources

Getting Started with CQL

• CQL Author's Guide - high-level syntax of CQL
• CQL Developer's Guide - in-depth syntax and advanced CQL topics
• CQL Reference Guide - complete semantics to all functions in CQL (companion to the above 2 guides)
• Zulip FHIR Community - chat community to ask questions to people who use CQL every day and the creators

Atom

There are CQL plugins for the Atom text editor:

• https://atom.io/packages/language-cql
• https://github.com/cqframework/atom_cql_support

Helper Definitions

Various CQL helper definitions, such as MostRecent and FindDate, exist in files like CDSConnectCommons.cql and FHIRHelpers.cql.

Diagnostics

qa.html

When generating JSON/EML from CQL, you can find compilation notifications, warnings, and errors in the /output/qa.html file generated by the publisher program.