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