Vocabulary Maintenance at HL7

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

• Webinars

  • The HL7 Terminology - brief introduction to the HL7 Terminology

  • Terminology Governance and Publishing at HL7 - a more in depth session on the HL7 Terminology, including the representation of HL7 product family content and an introduction to the UTG process. No need to check out the first video if you watch this one, as it builds upon the first video!

  • Reviewing and Voting on HL7 Vocabulary Change Proposals - walks through UTG review and governance process for vocabulary maintenance at HL7 for the HL7 Terminology Review audience.  The Terminology Governance and Publishing at HL7 Webinar is a pre-requisite.

  • Overall Process for Submitting HL7 Vocabulary Change Proposals - provides overview of change proposal submission, including how to create a change proposal ticket. The Terminology Governance and Publishing at HL7 Webinar is a pre-requisite. Future tutorials are planned to discuss the technical details of creating the content changes and using the UTG custom tooling.
• General Architecture of UTG

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): 

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: 

   First Name
   Last Name
   Email
   Note

   Submit
   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. Contact the UTG team for current status of tooling, process, sign-up, and permissions settings to be able to draft and submit a change proposal.

4. Install required tooling (Vocabulary Server, UTG Editor, and Sourcetree)
5. Draft the proposal (written information) on the UTG Jira Project
6. Create and download a branch to edit content using Sourcetree
7. Use Vocabulary Server and Editor to create content change(s) for the proposal - changes to the UTG resources
8. Commit new or changes resources to branch using Sourcetree and Push the changes to BitBucket
9. 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): 

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: 

   First Name
   Last Name
   Email
   Note

   Submit
   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