Skip to end of metadata
Go to start of metadata

Education and Rollout Approach 

The educational and rollout approach for going live will be specialized for each group of individuals that need to be aware of UTG. The general public, the HL7 community, and HL7 vocabulary submitters all require varying levels of information about UTG. The sections below outline what notifications/information will be provided to each group. 

General Public

The general public will be provided high-level information about the UTG process. Requirements include:

  • A general announcement about the rollout of the HL7 terminology website and the UTG process for vocabulary maintenance (will be coordinated with HL7) 
  • A webinar that demonstrates how to access and browse HL7 family content


Title: The HL7 Terminology (~15 min)

Description: This webinar introduces the HL7 terminology publication website and shows how to view and access this published terminology content that is referenced in HL7 standards.

Topics:

  • The HL7 terminology website
  • Web page layout at terminology.hl7.org
    • Published versions and current (latest in development)
    • Terminology content and documentation
    • Content downloads
  • Published terminology artifacts
    • Code Systems, Value Sets, Concept Maps, Naming Systems
    • Product family grouping of listed artifacts
  • Brief introduction to the UTG update and release process

Internal Notes:

  • Should include a few slides and screenshots of the website.
    • Members of the HL7 community will be able to view changes that are in work and upcoming and have opportunities to get involved

HL7 Community


The HL7 Community will provided the same high-level information about the UTG process, but will also include more information. Requirements include:

  • The HL7 community will be notified that harmonization has officially been replaced with UTG
  • HL7 community members will be encouraged to get a Jira login if they do not already have one
  • Webinars will be provided to demonstrate
    • How to report vocabulary issues and content needs through the Jira workflow
    • How to review vocabulary change proposals in process
    • How to access and review vocabulary issues and content needs queue
    • Downloading HL7 terminology for local use

Title: Terminology Governance and Publishing at HL7 (~1 hour)

Description: This webinar introduces the HL7 terminology publication website and shows how to view and access this published terminology content that is referenced in HL7 standards. In addition, it will cover the publishing process for new releases and the update process for the current content.

Topics:

  • The HL7 terminology website
  • Web page layout at terminology.hl7.org
    • Published versions and current (latest in development)
    • Terminology content and documentation
    • Content downloads
  • Published terminology artifacts
    • Code Systems, Value Sets, Concept Maps, Naming Systems
    • Product family grouping of listed artifacts
  • Relationship of UTG model to terminology models in different HL7 product families
    • Representation of HL7 Version 2 Tables
    • Representation of Version 3 Concept Domains
    • Infrastructure Vocabulary
    • Extensions to support the representation
  • Content of downloads
    • UTG Terminology resources
  • UTG Governance
    • In scope/out of scope terminology
    • External (non-HL7) terminologies
    • Key highlights of governance process

Internal Notes:

  • Accessing terminology
    • How to get to current build and published releases, and download content
  • UTG Governance:
    • Access to governance through Jira workflow (consensus-based)
    • Where ticketing system is for change requests
    • The states of the changes, screenshot of workflow, see changes as things move through process in parallel
  • To get involved in either submitting or voting, take next set of webinars.
  • Relationship of UTG model to terminology models in different HL7 product families
    • The UTG model are the FHIR Code System and Value Set normative resources, and FHIR Naming System resource PLUS several extensions to support misalignment between normative FHIR and V2/V3 terminology
    • Coded concepts to support some of this are in a UTG Maintenance Infrastructure Code System 
    • There are also some specific differences in particular product family objects described in the bullets below
    • Representation of HL7 Version 2 Tables
      • In Version 2.9, a table is associated with zero to one each of Concept Domain, Code System, and Value Set and contains table-specific metadata
      • The underlying Code Systems and Value Sets from the V2 publishing tooling has been imported into UTG
      • In UTG, the V2 Tables Code System has one concept for each V2 Table with Concept Properties holding the table metadata and the references to the Code System, Value Set and Concept Domain where they are associated to that particular table
    • Representation of Version 3
      • All Code Systems and Value Sets published in the V3 Coremif have been imported to UTG, adding extensions and special concept properties to accommodate the differences in the V3 Vocabulary model and the FHIR vocabulary model including the HL7 Realm vocabulary used in binding realm
      • All Concept Domains published in the V3 Coremif have been imported to UTG into a single Concept Domains Code System
      • All bindings published in the Coremif have been converted to appropriately named concept properties in the Concept Domains Code System
      • The binding realms are two character country codes PLUS the special HL7 Realms that are part of the infrastructure codes
    • Infrastructure Vocabulary
      • UTG infrastructure includes the Concept Properties Code System and the HL7TermMaintInfra Code System, which are part of the unified set of Code Systems
      • Ballot-bound infrastructure vocabulary in the different product families is not yet consistently imported and handled in UTG pending some HL7 and WG Policy decisions

HL7 Terminology Reviewers

The HL7 terminology reviewer group will be provided the same information information as the general public/HL7 community, but will also require more in-depth information for utilizing UTG review and vote on proposed terminology changes. Requirements include:

  • Full UTG review/voting process documentation
    • Viewing proposed change details
    • Making comments on proposed changes
    • Reviewing and casting votes
  • Webinar to walk reviewers through the process of reviewing a change request and voting
    • Brief intro to UTG for change proposals
    • PLACEHOLDER - how to becomes a voter
    • Change proposals you are getting notifications about
    • Locating other change proposal
    • Reviewing Details of proposal and proposed changes in context
    • Voting on change proposals
    • Commenting on change proposals
    • Watching change proposals 
      • Frame this around responding to questions or comments so you can cast vote
    • Technical details on voting
      • Viewing voting groups and weights
      • Expediting approval of proposals
    • Change proposals workflow
      • Change proposal outcomes

HL7 Terminology Submitters

The HL7 vocabulary submitter group will be provided the same information information as the general public/HL7 community, but will also require more in-depth information for utilizing UTG to request new vocabulary objects or vocabulary changes. Requirements include:

  • Full UTG change process documentation
    • Getting access
    • Install of tooling
    • Submitting a proposal
    • Creating proposed vocabulary changes
    • Reviewing and responding to reviewer's comments
    • Structured guidance for UTG resources to support V2, V3, CDA, and FHIR
  • Webinar to walk submitter through the process of installing tooling 
  • Webinar to walk submitter through process of submitting a vocabulary change request

It is likely that this will be broken into three separate sessions due to the large amount of info that must be covered for this group. The sessions will include:

  1. Process (need to mention BitBucket)
    1. UTG Overview
    2. Change Proposal Overall Process 
      1. Mention the UP project on Jira and that everything is managed there
    3. UTG Workflow
    4. Becoming a Submitter
      1. Anyone can become a submitter, non-HL7 members need TSC approval (upon submitting form)
      2. Qualifications: former vocabulary facilitator role + additional skills
        1. Some familiarity with technical change management
        2. Some terminology expertise
        3. Ability to work on HL7 material on your local machine
    5. UTG Jira Project
    6. Creating a proposal
      1. Get Jira account 
      2. Becomes a submitter
      3. Create a change request
      4. Download current copy of content
      5. Make changes to the content and commit
      6. Submit changes for consensus review
        1. Certain items are required: Need sponsor approval date, links to change objects, included edited content changes
    7. Monitoring Consensus Review as a Submitter
      1. Receiving notifications
      2. Commenting on a proposal
      3. Expediting proposals
      4. Pulling proposal back to Draft, making suggested or required changes, and resubmitting
    8. Proposal Outcomes (refer to voting session for information on voting requirements)
      1. Approved - notification, goes into Curator workflow, and within some days depending on queue it will be implemented (current build)
      2. Rejected - notification, ticket is archived
      3. Meeting Needed - on submitter to set up a consensus group to decide how to triage proposal
      4. Withdrawn - submitter decides it is not necessary or what is being suggested doesn't make sense after clarifying comments (submitter rejects their own proposal)
      5. Tabled - the current solution is unclear and more time is needed to fully discuss and understand the material (pauses Consensus Review - like pulling to draft and resubmitting with no changes), may be to wait on people to come back from vacation, halts voting, many use cases, may be removed in the future if never used
  2. Content 
    1. Overview of the content
      1. Git archive, terminology source of truth, and Bitbucket change archive
      2. Terminology content (CS, VS, NS, concept domains, v2 tables, folder layout)
      3. Documentation content (IG control file (utg.xml), pagecontent folder and lists/manifests)
      4. Infrastructure content (templates and framework) - only certain people/circumstances allowed
      5. What folders contain the different bits of content
    2. Getting a local copy of the content
      1. From Bitbucket
        1. This is a Git archive database and it contains all of the changes from all submitters to the content
        2. It is accessible by the community
        3. When approved proposals are implemented and a new current build is validated, the Bitbucket change archive master is manually updated
    3. Making changes to the terminology content
      1. All the terminology content are XML files
      2. Any tool can be used to edit the XML files
        1. Can use text editor, XML aware editors, branch aware editors, etc. 
        2. Scripts and transforms
      3. Best way to describe overall process without looking at each element?
        1. All requirements for the four types of FHIR terminology resources that UTG employs (CS, VS, NS, list) must be adhered to
        2. Additional to support UTG
          1. Vocabulary WG versioning policy for types of resources
          2. Naming conventions
          3. UTG-specific extensions for CS/VS/NS (primarily for V3)
          4. UTG-specific properties for concepts
            1. Extended properties for V2 Tables
            2. Extended properties for Concept Domains (including bindings)
          5. Relationship between CS, VS, and V2 Tables for V2 content
    4. Reviewing and validating your changes
      1. XML syntax must be legal and valid
      2. Content changes may be viewed in their XML form
      3. Content changes may be built locally (generally for experienced FHIR IG developers)
    5. Saving/uploading changes and submitting for Consensus Review
      1. Local saves are only on your local machine
      2. Your change set in Bitbucket must be saved to the Bitbucket server before submitting
        1. There are fully documented specific tools that we have in the UTG project but some want to use tools that they are more familiar with. 3rd tutorial will discuss that. 
  3. Custom tools (developed as part of FHIR dev work)
    1. Setting up the environment and tooling
    2. Sourcetree
    3. Vocabulary Server
    4. Vocabulary Editor
      1. Expanding a VS
      2. Detailed walk-through of creating/editing artifacts and editing lists (manifest entries)

Questions:

  1. Best way to flow from creating a proposal, to content, and back to submitting a proposal?

Other Rollout Requirements

  • Complete Pilot Testing
  • Define Terminology Curator
  • Obtain and configure final voting weights and requirements
  • Turn on Jira notifications
  • TSC and EC signoff


  • No labels