Vocabulary Maintenance at HL7
Page tree
Skip to end of metadata
Go to start of metadata

Vocabulary Maintenance at HL7

This is the place to find information on the maintenance of vocabulary at HL7 including the Unified Terminology Governance (UTG) process and operations:

  • sign up to watch proposals for changes in vocabulary;
  • comment on proposed changes; and
  • vote on proposed changed


All of the Code Systems and Value Sets for the Code Systems that are not ballot-bound are maintained through this UTG process as of Q2/Q3 2020. For a list of ballot-bound Code Systems and Value Sets, click here.



Overview

HL7 maintains multiple terminologies - v2, v3, CDA value sets and FHIR(R).

The ongoing maintenance of these terminologies is resource intensive and quite opaque to much of the community and as a result, a need for a uniform vocabulary governance process or strategy across all the HL7 product lines was identified. The growing popularity of HL7 FHIR(R) and the associated implementation guides and the increase in participation of the FHIR Community escalated the need for such a process. 

There is a need to maintain the terminologies that support all of HL7’s products (v2, v3, FHIR, CDA, etc.) in a way that is responsive and improves quality while reducing the resources that both HL7 and its' volunteers put into the process.  As well, there’s a need for the process to align with the community’s expectations for a more modern, continuous peer-feedback related process.

The UTG project is scheduled to replace existing vocabulary maintenance processes (including harmonization) for HL7 internationally published normative standards in mid 2020. Additional information about project details, requirements, project management, and documentation can be accessed at the Unified Terminology Governance Project (UTG) Page

Education Materials

Maintenance of HL7 Terminology

This section provides a high-level overview of the workflow process for submitting a proposal and participating in consensus review. 

  • SUBMISSION: submit a proposal for changes that contain all technical details to the vocabulary
  • VALIDATION: to ensure the proposal includes required information
  • CONSENSUS REVIEW: voted on by the community
  • PUBLISH: approved changes by a majority vote are implemented to the the current build of the terminology

The UTG process decreases the burden on HL7 resources by having the proposal submitter create and submit the content that they needed added, modified, or deleted in their own development branch (via BitBucket directly through Jira). Proposals are submitted using a Jira-based workflow that is open to the community (both submitting and voting). Automated checks and validations ensure that the content meets proposal requirements. The proposal goes through a consensus workflow to come to a resolution. If approved, the use of the Bitbucket branching allows simplified integration into the master repository.

The sections below provide a high-level overview of the Change Proposal Submission and Consensus Review Process.

Change Proposal Submission

The steps below describe the process for submitting a proposal. More detailed information on the process is documented at UTG Tooling and Proposal Documentation.

Don't know if you have permissions to be a Submitter of Vocabulary Change Proposals?  When you create a proposal and it goes into the Environment Setup state, if you see a button on the top "Draft A Proposal" then you ARE a Submitter!   If you don't see that button, you can become a Submitter by clicking this link (do not open in new tab): 

Request to become UTG Submitter

The basic steps to submit a change proposal are:

  1. Get access to HL7 Jira by requesting an account on https://jira.hl7.org/secure/Dashboard.jspa

  2. Request Submitter permissions by filling out the following form: 

    Request to become UTG Submitter

    1. If you are NOT an HL7 member, please add a comment in the 'Note' field explaining why you want to become a submitter and describe your relationship to HL7 and/or UTG
  3. Install required tooling (Vocabulary Server, UTG Editor, and Sourcetree)
  4. Draft the proposal (written information) on the UTG Jira Project
  5. Create and download a branch to edit content using Sourcetree
  6. Use Vocabulary Server and Editor to create content change(s) for the proposal - changes to the UTG resources
  7. Commit new or changes resources to branch using Sourcetree and Push the changes to BitBucket
  8. Submit proposal in Jira

Detailed step-by-step instructions can be found at: How To Submit a UTG Change Proposal

Consensus Review

Anyone wishing to participate in the Consensus Review of proposed change proposals are welcome to participate. No tooling is required to participate - to become a reviewer/voter on vocabulary change proposals and you are not one already, click this link below (do not open in new tab): 

Request Reviewer Permissions

All change proposals are validated and formatted for a consensus review. Votes are weighted and there are several requirements (i.e. votes from specific users and groups) that must be met for the content to be approved or rejected.

The basic steps to to the review/voting process are:

  1. Get access to HL7 Jira by requesting an account on https://jira.hl7.org/secure/Dashboard.jspa

  2. Request reviewer/voter permissions by filling out the following form: 

    Request Reviewer Permissions

    1. If you are NOT an HL7 member, please add a comment in the 'Note' field explaining why you want to become a reviewer and describe your relationship to HL7 and/or UTG
    2. If your Work Group has appointed you as an Oversight Voter (someone required to represent the WG by voting on UTG proposals in your area then please explain this in the 'Note' field and add a link to the Meeting Minutes and decision where the Work Group decided that
  3. Open issues can be viewed in the UP project on the UTG Jira Project
  4. Review details of proposal and view rendered version of proposed content via link on ticket
  5. Use comments to discuss the proposal if necessary.
  6. Vote Affirmative or Negative

If approved, the proposal enters the UPSM project workflow to be integrated with the source of truth and published.

Detailed step-by-step instructions can be found at: Consensus Review and Voting Process


Setting Up Notifications for UTG Proposals

The UTG issue tracking system (JIRA) is set up so that reviewers must opt-in to subscribe to notifications.  

The system has been initially configured for FIVE (5) different types of notifications or "filters":

Opting-in will trigger emails to be sent to you when any change proposal enters the subscribed "State" in the UTG workflow (the names above are the State names).

Here is a helpful Jira quickstart guide on using filters/subscriptions which can help you to better understand how to use this system in a way that works best for you personally: 

Create New Notification

  1.  In order to opt-in for one or more of these notifications, you must login to your account on https://jira.hl7.org and go to the identified link in the list above.  The link will show subscribe (or unsubscribe if you are already setup).
  2. Click the filter link for the type of notification you are interested in and then click on ‘Details’ on the top-middle of the page and select ‘New subscription’.



  3. Customize the notifications per your liking and click ‘Subscribe’.

  4. Once you have subscribed to these notification filters, you will begin to get email messages from the hl7 webmaster account when a proposal enters the State that you subscribed too.   

Opt-out of Notification

  1. To opt-out, you can select that option on any of the filter links in the list above, click 'Details' and then 'Manage Subscription'.
  2. Click 'Delete' on the row of the filter(s) you would like to opt-out of.




  • No labels