-
Notifications
You must be signed in to change notification settings - Fork 19
Atom User Instructions
This guide has been developed to inform users on best practices for using the Atom text editor with CQL to convert electronic clinical quality measures. A plug-in has been developed for Atom that is capable of highlighting proper syntax and usage of Clinical Quality Language (CQL) as well as several data models including Quality Data Model (QDM), Quality Improvement Core (QI-Core), and FHIR.
Please note, version numbers are used throughout this guide to describe various standards, models, software, and artifacts. Depending on the date of usage, some of these may be out of date. To confirm any correct version numbers, please email fhir-esac@esacinc.com.
Atom is an easy to use text editor that utilizes a package to perform syntax highlighting for CQL and data model validation, eCQM evaluation, and integration with GitHub. In order to use many of these features, some additional system set-up and access is needed.
To install Atom, navigate to https://atom.io/. Select ‘Download’ from the homepage and complete the installation per the installation wizard. The default download should match your operating system (i.e. Windows, Mac.) Other versions are available on the Atom GitHub page by selecting ‘Other Platforms’. Additional installation instructions are available through Atom Support.
The CQL language package delivers many of the features used for writing or converting eCQMs. Java 11 or later is required for the language-CQL package. Prior to setting up the language-CQL package, it is important for the user to verify the version of Java installed on their local machine. Java version can be determined by opening a command prompt and typing: Java -version. If you do not have Java version 11 or later installed, it is recommended to install it from Open JDK located here: https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=openj9
From the Atom homepage, select the ‘Settings’ tab at the top, then select ‘Install’. If settings tab is not open, select File>Settings to open. Type into the search box ‘language-cql’ and select this package from the list. From the Atom editor application, select 'Install'. Follow the prompts for installation including the installation of 'atom-ide-ui' which should launch as part of the installation process. Once installation is complete, close and reopen Atom before testing.
The first step in validating set-up is to perform a simple test that will show validation highlighting. Files should be contained in an Atom project folder, which can be created from the ‘File’ tab.
From Atom, navigate to 'File' and select 'Add Project Folder'. A prompt will appear to select a file from a local directory, or a new file can be created. Select 'file' then 'new file'. A new tab will appear within Atom. In the first line of this new file type 'an invalid library'. Save this file as test.cql. Note: it is necessary to save the file with a .cql extension for the validation service to recognize it. Files with extensions other than .cql will not work. Once this file is saved, a red dot should appear next to the first line denoting a syntax error.
The language-cql package supports a number of data models. Existing eCQMs written in CQL can be copied into the Atom text editor, opened locally from a project directory, or from the draft-measures repository (see below for using GitHub with Atom).
When using Atom to author or convert eCQMs, a data model must be specified. This is done by typing in an expression such as: using FHIR version '4.0.0'. It is also necessary to ensure that any dependency libraries, such as FHIR Helpers or common functions libraries are contained within the same directory as the eCQM file.
Atom has GitHub functionality built in when installed. In order to use this functionality, it is first necessary to create a repository file within the Atom project space. To do so, hit the control, shift, and “p” keys in Atom to bring up a list of commands*. Click on “GitHub: Clone”
In 'Clone From' box, enter in the location of the github directory. This URL is available on the GitHub site under the green 'Clone or download' box. For draft measures repo, the URL is: https://github.com/cqframework/draft-measures.git
In the 'To directory' box, enter the location on your local machine where you want to store the repository.
Once the repository is set-up within Atom, users are able to make changes to files and commit them directly to GitHub. Within Atom, any file within the repository that has been changed by the user will be highlighted in yellow. Once changes are ready to commit, be sure to save the file, then complete the following steps.
Click the ‘fetch’ button to determine if the master repository has changed. If there are changes, the fetch button will change to ‘pull’ with the number of changes on the repository. Click ‘pull’ which downloads any changes. This step helps to reduce possibility of merge conflicts. Next, select the ‘Git’ pane in the lower right hand corner. The changes should now show in ‘Unstaged Changes.’ Select ‘Stage All’ and the file(s) will move to ‘Staged Changes’ box You will need to include a commit message such as ‘EXM123 Draft’ or ‘EXM123 initial commit’. Once the message is entered, click ‘Commit to master’. Select ‘Commit to Master’. You will now see your update listed below. If you would like to undo the commit, click ‘undo’ and the repository will revert to the previous version.
Please note, permissions need to be granted to the draft measures repository before being able to commit. To gain access, please email your GitHub user ID to robert.samples@esacinc.com with your request.
The Atom plug-in now contains a function to validate cql against a test patient. Performing validation requires a specifc file structure to execute which is contained in the Connectathon Repository. Atom also requires the folder used for testing to be its own project folder. To set this up, within Atom select 'File> Open Folder'. Select the folder from the repository by FHIR version. This will open a new Atom window with just the project folder. To execute, select a CQL file within the connectathon repository. Right click and select 'Execute CQL' from the menu. A new text file will open with 'Running tests' at the top. The plug-in will validate the path for test data and dependency terminology library. When the test completes, each validated line, an output will be contained within the bracket for that line. If no data was found, the bracket will be empty. By reviewing the resources generated, the user can determine if the expected result was met.