-
Notifications
You must be signed in to change notification settings - Fork 27
Revisions for Standards Updates
Bonnie (and/or dependencies listed in parentheses) needs to be kept up-to-date with changes in the following standards:
- Clinical Quality Language (CQL) (cql-execution)
- Quality Data Model (QDM) (cqm-models)
- Health Quality Measure Format (HQMF) (cqm-parsers)
- Quality Reporting Document Architecture (QRDA) (cqm-reports)
This document will guide developers in determining if Bonnie and/or its dependencies need updates and how to make those required revisions.
Clinical Quality Language Specification
In addition to viewing the diff between the whole spec and one of its previous versions, you can
look at the commits on https://github.com/HL7/cql/commits/master. These commits
are more likely to be grouped thematically. For example, the pattern to return
null instead of throw an error may affect several operators, but be one
thematic change.
Once the required changes are identified for the new version of CQL, this defines what needs to be verified or updated in cql-exeuction.
In some instances, there are existing unit tests in cql-execution that prove the current behavior matches the new spec. If this is the case, no updates are needed.
In other instances, cql-execution will match the new version spec, but there will not be unit tests to prove this. If this is the case, unit tests should be added (see testing section of the cql-execution README).
In most instances, it's likely that cql-execution will need to be modified to match the changes to the new version of the spec. If this is the case, both code and tests will need to be added to cql-execution to make the updates.
Developing in cql-execution See https://github.com/cqframework/cql-execution/blob/master/README.md for information on configuring cql-execution and developing tests.
The key steps are:
- Clone or fork https://github.com/cqframework/cql-execution
-
yarn install- Installs dependencies and generates cql4browsers.js (a browserified version of cql-execution) -
yarn test- Transpiles CoffeeScript to JavaScript and runs tests. -
yarn watch-all- Continuously transpile CoffeeScript to JavaScript or build test data from .cql files
cql-execution is loaded into Bonnie via an indirect route.
cql-execution is a direct dependency of cqm-models. cqm-models is a dependency
of cqm-execution. cqm-execution is browserified by running yarn run browser
inside of cqm-execution. This browserified version is loaded into bonnie as a
dependency. cqm-models is accessible in bonnie using the cqm.models namespace
in the browser. cql-execution is accessible via cqm.models.CQL in the
browser.
The steps for updating the QDM models that Bonnie uses for standards updates involve creating or modifying templates for any QDM attributes that follow a substantially new pattern and generating the updated models using the cqm-models generator.
In addition to the PDF QDM specification, a ModelInfo file is created which is a Data Model implementation of the QDM spec. Note: The PDF specification is the source of truth, review the changes in the ModelInfo to ensure they are correct. The cqm-models repository uses this data model to generate both the Ruby and JavaScript QDM classes that Bonnie uses. The process for updating the models is therefore primarily automatic, with only minor updates needing to be made manually. Tests for any new elements may be added as well.
modelinfo file link Note that you may have to checkout a different branch to download a future version of the modelinfo file.
These modelinfo files are then placed in the cqm-models/modelinfo/ directory to be used by the generator, this is discussed further below.
In addition to the QDM ModelInfo file, there is a map of qdm attribute to { hqmf_oid, qrda_oid, qdm_category, and qdm_status }
For hqmf_oid, refer to the HQMF spec: https://ecqi.healthit.gov/hqmf qdm_category and qdm_status can be derived from the QDM Spec.
https://github.com/projecttacoma/cqm-models/blob/master/data/oids_qdm_5.4.json
See Also: https://github.com/projecttacoma/cqm-models/blob/master/README.md The cqm-models repository generates the Ruby and JavaScript models from templates and information from the modelinfo file.
After updating the modelinfo file and oids map, the generator can be run with the command with the paths to the oid map and modelinfo file updated.
ruby lib/generate_models.rb modelinfo/qdm-modelinfo-5.4.xml data/oids_qdm_5.4.json
For an example of the changes involved in a version update (most changes are from the generator), this PR includes the updates from QDM 5.4 to QDM 5.5: https://github.com/projecttacoma/cqm-models/pull/124
Here is a step-by-step description of how those changes were made.
- The QDM 5.5 modelinfo file was added to the modelinfo directory
- The oids_qdm_5.5.json map was generated as described above
- The generator script was attempted:
ruby lib/generate_models.rb modelinfo/qdm-modelinfo-5.5.xml data/oids_qdm_5.5.json
Which resulted in an error:
lib/generate_models.rb:146:in `block (2 levels) in <main>': Unsupported type from modelinfo file for Ruby types: QDM.Identifierfrom: Entity (RuntimeError)
This indicates that there is a change from QDM 5.4 to 5.5 that the generator currently does not support, and the generator needs to be updated. In this case, QDM.Id was renamed to QDM.Identifier, so the TYPE_LOOKUP_RB and TYPE_LOOKUP_JS maps need to be updated. These maps contain the names of the types in the modelinfo mapped to the Ruby and JavaScript class names, respectively. Re-running the generator results in similar errors that act as cues for how to fix any remaining items in these maps. Once these maps are finished, The generator completes successfully.
NOTE: The ruby models do not automatically get overwritten unless you select y when the command line prompts you. Alternatively, you can pipe the generator into the yes process, which will respond yes automatically to all of these queries:
yes | ruby lib/generate_models.rb modelinfo/qdm-modelinfo-5.5.xml data/oids_qdm_5.5.json
Once the models are updated, run the unit tests:
yarn test for JavaScript tests,
bundle exec rake for Ruby tests.
The failing tests will serve as cues for things that need to be updated manually. For the case of QDM 5.4 to 5.5, the Id to Identifier change mentioned earlier resulted in this failing test:
ReferenceError: IdentifierSchema is not defined
Which can be resolved by modifying templates/id_template.js.erb to use the new Identifier name and updating the reference in generate_models.rb:
- Id: 'templates/id_template.js.erb'
+ Identifier: 'templates/identifier_template.js.erb'
The new require statements in mongoose_template.js.erb also needs to be added:
const { IdentifierSchema } = require('./Identifier');
const QDMDate = require('../basetypes/QDMDate');
QDMDate was added as a wrapper for CQL Date to resolve the name conflict with JavaScripts Date class. This is a one-off addition that will not likely need to be repeated in future updates.
Another one-off change that resulted from the 5.4 to 5.5 update was the implementation of inheritance in the cqm-models generator. The new Entity attribute of QDM 5.5 required this change. Looking at the changes in the pull request above will give you a sense of how this was implemented, but it is not expected that this change will need to be repeated. If other attributes are added that use inheritance, the pattern of Entity can be used. As this change involved some modifications to the directory structure of cqm-models and updates to the models_template.rb.erb and mongoose_template.js.erb files.
Bonnie relies on the models in cqm-models for both calculation of eCQMs and for generating parts of the Patient Builder UI.
cqm-execution is the interface between Bonnie, cqm-models, and cql-execution that enables calculation of cqm patients. It has cqm-models as both a direct and indirect (via bonnie for test fixtures) dependency. Updating cqm-execution for new models involves pointing to the updated branch of cqm-models as well as using test fixtures that have been either newly created using the new models, or otherwise converted from older models. Once these changes have been made, running the unit tests should tell you if there are any updates that need to be made to this repository related to the standards update and help guide the revision process.
Bonnie uses cqm-models to determine which views to display on QDM attribute input dialogs. It looks at the schema for a QDM attribute and determines which timing elements to display as well as adding other inputs dynamically. There are views implemented in bonnie for all QDM basetypes in app/assets/javascripts/views/patient_builder/inputs/, so if any new QDM basetypes are added or the name of a QDM basetype changes (e.g. Id -> Identifier), a new view will need to be added following the pattern of the views already there. Other than that, Bonnie should be able to automatically deal with updates to the QDM Data model without any modifications. Unit tests may need to be updated to reflect the changes.
New attributes will need a user friendly name to show in the UI. These can be added to the @ATTRIBUTE_TITLE_MAP
in app/assets/javascripts/models/data_criteria.js.coffee. Optional attributes of composite types, such as coded fields of entities, can be added to the @OPTIONAL_ATTRS map in
app/assets/javascripts/views/patient_builder/inputs/composite.js.coffee.