(Vocab Motion: Approve the process, as documented below during the May WGM Vocab joint session with TSMG: DG moves, CC seconds: 16-0-0)

(TSMG Motion: Approve the process, as documented below during the May WGM TSMG session: RM moves, RD seconds: 9-0-0)

(TSC Approved via TSC e-Vote 2022-06-20)

Purpose

The purpose of this page is to provide information for IG authors (Requestors) on the necessary steps to validate, request and/or obtain a CodeSystem or Identifier System identifier (url) defined by an entity external to HL7. AdmitSource is an example of an internal to HL7 CodeSystem. 

A code system is a managed collection of concepts wherein at least one internally unique code represents each concept. Code Systems define concepts through formal definition and assign a unique identifier for each unique conceptual meaning captured as a code. Code Systems may be referred to as terminologies, vocabularies, or coding schemes, HL7 considers all such collections ‘Code Systems’. Examples of external CodeSystems are SNOMED CT, LOINC, ICD-11, etc. 

Identifier systems are composed of non-coded strings (typically numeric or alphanumeric) that have a common purpose and/or context. Typically, identifiers are used to connect content in resources to external content available in other frameworks or protocols. The Global Trade Item Number (GTIN) system and US state driver's license number systems, country passport number systems are examples of external Identifier Systems.

It is highly recommended that this process be started as soon as you know your IG requires terminology content from an external source. Do not wait until you're ready to publish the IG for ballot. HTA recommends you start this process at least 3 months before you plan to ballot your IG.

Please note that adjudication of requests and/or conflicts outside of the process outlined here via Zulip is not sanctioned by the TSMG, HTA, Vocabulary Work Group and FMG. If an implementer has concerns that are not addressed via the process below, please contact TSMG.

Validate a Identifier System or Code System or Identifier

(Current, with the migration of data from HTA Confluence and FHIR Terminology pages to terminology.hl7.org still in progress)

To validate if an external code system or identifier system has been registered with the HTA, FMG or THO (and therefore a URL for use within HL7 products already exists), the following process should be followed. 

  1. HL7 will only create a new identifier when an appropriate existing identifier is not available for use in HL7. Requestors must read the FHIR introduction to Terminology resources here that further describes what a code system and identifier system are as defined by HL7 FHIR. Keep in mind that the description and/or name registered with HL7 may differ from what the requestor may know of the code system (US Tax Code, also know as US EIN etc..) or identifier system.
  2. Requestor searches available resources to determine if HL7 has recorded an identifier for the CodeSystem or Identifier System - searching of existing information (e.g., THO - terminology.hl7.org, OID Registry, HTA External Terminologies Registry, https://oidref.com) PRIOR to contacting HTA for assistance.
    1. If found in FHIR External Terminologies most recent published version, use the canonical URL for the CodeSystem or Identifier System as identified there
    2. If not found in previous step, check THO's most recent published version and use the canonical URL for the CodeSystem or Identifier System as identified there
    3. If not found in THO's most recent published version, check the current build of THO.
      1. If found in the current build of THO, use the canonical URL for the CodeSystem or Identifier System as identified there
        1. Requestors should note that THO includes retired CodeSystem information, please see the Vocab Work Group's policy on The Use of Retired and Legacy Code Systems
      2. If not found in the current build of THO build - 
        1. Check the HTA External Terminologies Registry to determine if someone has initiated a request for the CodeSystem or Identifier System in question
          1. If you see an entry for the CodeSystem or Identifier System in question, scroll down to the section for Technical Identifiers. If a URL has been assigned and is endorsed for use by HTA, use it. 
          2. Contact HTA members to find out the status of the request if its not clear.  
        2. Check the HTA JIRA project to see if someone submitted a JIRA ticket for the CodeSystem or Identifier System in question; follow the ticket's progress to obtain the URL
          1. https://jira.hl7.org/projects/HTA/summary
    4. If not found in any of the locations above, then move to the Request the CodeSystem or Identifier System Identifier process shown below.
      1. NOTE: If found in any related OID registry, include the information in the request

(Future - when THO has been established as single source of truth. All other places utilize references to THO)

To validate if an external code system has been registered with the HTA (and therefore a URL for use within HL7 products already exists), the following process should be followed. 

  1. Code systems may be referred to as terminologies, vocabularies, or coding schemes, HL7 considers all such collections ‘Code Systems’. HL7 will only create a new code system when an appropriate existing code system is not available for use in HL7. Requestors must read the FHIR introduction to Terminology resources here that further describes what a code system is as defined by HL7 FHIR. Keep in mind that the code system description and/or name registered with HL7 may differ from what the requestor may know of the code system (US Tax Code, also know as US EIN etc..).
  2. Requestor searches THO's most recent published version as the single source of truth for code system metadata to determine if HL7 has recorded an identifier for the CodeSystem PRIOR to contacting HTA for assistance
    1. If found in THO's most recent published version (from link above), use the canonical URL for the CodeSystem as identified there
    2. If not found in THO most recent published version, check the current build of THO.
      1. If found in the current build of THO, use the canonical URL for the CodeSystem as identified there
        1. Requestors should note that THO includes retired CodeSystem information, please see the Vocab Work Group's policy on The Use of Retired and Legacy Code Systems
      2. If not found in the current build of THO - 
        1. Check the HTA JIRA project to see if someone submitted a JIRA ticket for the CodeSystem in question; follow the ticket's progress to obtain the URL
          1. https://jira.hl7.org/projects/HTA/summary
    3. If not found in any of the locations above, then move to the Request the CodeSystem Identifier process shown below.
      1. NOTE: If found in any related OID registry, include the information in the request

Request the Code System or Identifier System Identifier 

(Current, with the migration of data from HTA Confluence and FHIR Terminology pages to terminology.hl7.org still in progress)

  1. Initiate a request by: 
    1. Open a ticket in the HTA JIRA Project
      1. Instructions on how to enter an HTA JIRA ticket can be found here:  JIRA workflow for creation and management of External Code or Identifier System Owner Engagement requests for new code or identifier system canonical URLs (this needs to be checked and/or updated to ensure it covers identifier systems)
  2. HTA reviews the request and confirms that the external code system identifier has not been assigned 
    1. HTA will notify the HL7 community of the request via Implementers and Terminology Zulip channels
    2. If HTA is aware of, or identifies, an agreed upon URI, it will be provided to the Requestor and communicated via the Implementers and Terminology Zulip channels
    3. If b is not possible, HTA will provide the requestor with a temporary placeholder URI using the following syntax http://terminology.hl7.org/temporary-uri/codeSystem/xxx or http://terminology.hl7.org/temporary-uri/NamingSystem/xxx, and update the JIRA ticket with this information
      1. where xxx = is an established short symbolic name.
      2. OIDs for V3/CDA (temporary OID may also be assigned) and if the V2 Management Group desires that a V2 mnemonic be created for an external code system then that request shall be made directly to HTA with an addition to the  https://terminology.hl7.org/ValueSet-v2-0396.html code system as a pro-forma addition.
  3. HTA contacts the external Code System or Identifier System owner, and provides guidance if necessary on good practices for URLs. 
    1. If a response is received by HTA within the stated timeframe, (typically two weeks) HTA will
      1. Proceed with resolving the request, collaborating with the Requestor and Code or Identifier System owner
    2. If a response is NOT received by the HTA within the stated timeframe. HTA will:
      1. Work with the Requestor and other required parties to create the required Code System or Identifier System Information for use within HL7 products.
        1. If creating a new URI, HTA will use a standard syntax (http://terminology.hl7.org/CodeSystem/xxx or http://terminology.hl7.org/NamingSystem/xxx) where xxx is an established short symbolic name (which cannot contain spaces, but can include hyphens)
          1. Note, that HL7 publishing tools require that the xxx not contain an additional / as everything after "CodeSystem/" or "NamingSystem/" is used as the ID 
  4. Start the UTG process to create the CodeSystem and/or NamingSystem resource in THO, linking the UP JIRA ticket to the original HTA JIRA ticket
  5. Upon resolution, HTA will close any open tickets, attaching pertinent correspondence and documenting the resolution. Steps include
    1. Creation of an informational page under External Terminologies - Information
    2. Notify Requestor and/or known interested parties
      1. If a temporary URI was created, that URI will need to be changed to the final URI wherever it exists.
      2. The temporary placeholder URI will be maintained as a non-preferred identifier using a NamingSystem artifact that is made for the new code system (does not apply to Identifier Systems).
    3. Update the original HTA JIRA ticket with the resolution
    4. Notify the HL7 community of the resolution via Implementers and Terminology Zulip channels
    5. Notify the Vocabulary Work Group

(Future - when THO has been established as single source of truth. All other places utilizes references to THO)

  1. Initiate a request by: 
    1. Open a ticket in the HTA JIRA Project
      1. Instructions on how to enter an HTA JIRA ticket can be found here:  JIRA workflow for creation and management of External Code or Identifier System Owner Engagement requests for new code or identifier system canonical URLs
  2. HTA reviews the request and confirm that the external Code System or Identifier System identifier has not been assigned 
    1. HTA will notify the HL7 community of the request via Implementers and Terminology Zulip channels
    2. HTA will provide the requestor with a temporary URI using the following syntax http://terminology.hl7.org/temporary-uri/codeSystem/xxx or http://terminology.hl7.org/temporary-uri/NamingSystem/xxx, and update the JIRA ticket with this information
      1. where xxx = is an established short symbolic name.
      2. OIDs for V3/CDA (temporary OID may also be assigned) and if the V2 Management Group desires that a V2 mnemonic be created for an external code system then that request shall be made directly to HTA with an addition to the  https://terminology.hl7.org/ValueSet-v2-0396.html code system as a pro-forma addition.
  3. HTA contacts the external Code System or Identifier System owner, and provide guidance if necessary on good practices for URLs. 
    1. If a response from the Code System or Identifier System owner is received by HTA within the stated timeframe, (typically two weeks) HTA will
      1. Proceed with resolving the request, collaborating with the Requestor and Code System or Identifier System owner
      2. Start the UTG process to create the CodeSystem or NamingSystem resource in THO, tagging the Requestor on the ticket (UP JIRA project)
    2. If a response is NOT received by the HTA within the stated timeframe. HTA will:
      1. Work with the Requestor and other required parties to create the required Code System or Identifier System Information for use within HL7 products.
        1. If creating a new URI, HTA will use a standard syntax (http://terminology.hl7.org/CodeSystem/xxx or http://terminology.hl7.org/NamingSystem/xxx) where xxx is an established short symbolic name (which cannot contain spaces, but can include hyphens)
          1. (Note, that HL7 publishing tools require that the xxx not contain an additional / as everything after "CodeSystem/" or "NamingSystem/is used as the ID)
  4. Start the UTG process to create the CodeSystem and/or NamingSystem resource in THO, tagging the Requestor on the ticket (UP JIRA project)
  5. Upon resolution, HTA will close any open tickets, attaching pertinent correspondence and documenting the resolution. Steps include
    1. Notify Requestor and/or known interested parties
      1. If a temporary URI was created, that URI will need to be changed to the final URI wherever it exists.
      2. The temporary placeholder URI will be maintained as a non-preferred identifier using a NamingSystem artifact that is made for the new code system (does not apply to Identifier Systems).
    2. Update the original JIRA ticket with the resolution
    3. Notify the HL7 community of the resolution via Implementers and Terminology Zulip channels
    4. Notify the Vocabulary Work Group


  • No labels

17 Comments

  1. Joan Harper

    Carmela A. Couderc I have reviewed the draft and have the following questions.

    Step 1 says to search THO, OID Registry, and HTA.  If the Code System is found in the OID Registry, but not at HTA or THO, what should be done?  As far as I can tell, there is no canonical URL in the OID registry.

    Step 2 - It would be helpful if this process and the instructions on creating the Jira Ticket could be combined into a single document at some point in time.  I can see it being aggravating for users if they have to go to multiple places to get a single thing done.

    Step 3 - Does this mean that implementers get a temporary URI and then later get a permanent URI?  Why wouldn't it just be the permanent URI?  Are there potential issues with IGs not being properly updated from the temporary URI to the permanent URI?  Does this create another layer of overhead for implementers?

    Step 4 - Does the UTG process create the Code System using the temporary URI or should the UTG process wait until the permanent URI has been provided?


    Where does completing the HTA template occur in this process?  Is that step 5a?  If so, is filling in the templates supposed to be done by HTA or by the requestor?


    Where does this conversation continue so that I can be part of working through to the solution?

    1. Carmela A. Couderc

      Thanks Joan Harper  

      Step 1:  It seems to me that if the Code System is found in the OID registry, but not HTA or THO, an HTA request should be entered to obtain a URL from the code system owner.  Interested to see what HTA thinks.

      Step 2: Just my opinion, but once someone is familiar with JIRA, including detailed instructions on how to create a JIRA ticket in-line would be a nuisance to people. We might be able to figure out a way to collapse those instructions and people could expand if they want to. Thoughts HTA folks?

      Step 3: Yes, implementers/testers would use a temporary URI until one is available from the Code System owner. Yes, they would have to change it later, but that would also be the case if they make one up, and then an authoritative one is defined by the Code System owner once they go through the HTA process.  We need to make it clear to IG authors that they are responsible for requesting, and monitoring the progress of their request for an external Code System url and to update their specifications accordingly. 

      Step 4: Good question - I think that the CodeSystem isn't in UTG until HTA has received an an answer from the Code System owner - but it is worth discussing whether a "pending code system" should be created with the temporary URL  (pending code systems have been discussed for internal code systems), and then updated with the authoritative one once received.  A Code System identifier must be established so people can test - for example at connectathons - so some value is necessary before the authoritative one is determined.

      Thoughts? Caroline Macumber Julie James Reuben Daniels Roel Barelds Susan Matney Davera Gabriel Sylvia Thun

      Completion of the HTA template - not until 5a. HTA is responsible for the HTA page. 

      HTA owns the process for obtaining and managing identifiers and metadata for external Code Systems. 

      I created this page, but the material is owned by HTA. I suggest you reach out to the HTA members. 


      1. Roel Barelds

        but it is worth discussing whether a "pending code system" should be created with the temporary URL: I'm not a fan of a temporary URL. Before you know it, it is used in solution and you won't get rid of it. Beter to let the "pending code system" be created without an URL and just stating the text "waiting for the URL of the Code System owner.

        1. Caroline Macumber

          Roel Barelds I believe the publishing tools are being updated to ensure that anything with the temporary syntax does not get into any final publications. Lloyd McKenzie is that still accurate?

          1. Lloyd McKenzie

            The expectation is that tools will prevent 'temporary' URLs from showing up in artifacts that are FMM3+.

            If you're using a temporary URL, then it's a firm commitment that "This WILL move".  It might change to LOINC or SNOMED or THO or even to an TSMG-approved IG-maintained code system.  We don't know what it'll be, so design your system to account for the change.

            It the URL says "http://hl7.org/fhir/us/some-ig/CodeSystem/temporary-codes-will-change", it's pretty hard for implementers to get up in arms when in a future release, the code system changes.

            We don't want  to create a pending URL because that implies that we know we're actually going to create a new code system - when actually the default assumption should be the reverse.  Much better to stick the concept into an existing code system if we can find an appropriate home - but only once we know for sure what's needed.

    2. Lloyd McKenzie

      Until such time as THO is fully reconciled with the FHIR list, the correct order is "FHIR first", then THO.  Obviously, getting THO reconciled with FHIR should be a high priority.

  2. Davera Gabriel

    RE:  Step 2 - why choose?  it would cover both novice and experienced users if a step-by-step workflow mini-tutorial were created that provides detailed instructions.  

  3. Lloyd McKenzie

    1. FHIR should trump THO until reconciliation has occurred between the two.
    2. Temporary URIs or OIDs should only be created if the requester indicates the need is urgent and can't wait for the (3 months?) needed to work through the official process.
    3. What happens to the OID registry once all code systems from the OID registry are in THO?

  4. Carmela A. Couderc

    Since we know there are errors on the terminologies page that have been fixed in THO, it makes sense to me that IG authors should be directed to look in THO first, then the terminologies page - why continue to use something that is incorrect when the correct value is available? When there is a mis-match the person can reach out to HTA for clarification.

    1. Lloyd McKenzie

      FHIR is the normative source for information and what will have been implemented.  "Corrections" can only be made with the consent of the implementer community.  Only once we've reconciled THO with all of the information that was exposed on the FHIR pages can we treat it as source of truth.  Obviously doing that is an urgent task.

  5. Caroline Macumber

    From previous sub-committee meeting:

    LM: How do we handle situations where we can't come to a resolution with code system owner? Implementer needs trump IP source. Need to have a going in position...

    1. Caroline Macumber

      Per Wed Q3 Vocab joint with TSMG: Data in finalized code system metadata records in THO may need to be changed subject to HQ's deliberations with code system owner

  6. Joan Harper

    In the 'Validate a Code System' section, the OID registry is mentioned as a place to look but none of the steps in that section refer to the OID Registry.

  7. Craig Newman

    In Step 2 of creating a new code system it says:

    OIDs for V3/CDA and V2 mnemonic may also be created  (temporary OID may also be assigned) 

    The v2 Management Group isn't sure what is meant by "V2 mnemonic". Please elaborate on the meaning of that. Given the wording, we aren't sure if there will be separate OIDs for V3/CDA and V2 or if the OID is only for V3 and the v2 mnemonic is something different. Please clarify.

    We also recommend maintaining all necessary identifiers for any given external code system across all product families in an easily digestable form.

    1. Caroline Macumber

      Hi Craig - we've attempted to address via updated text, shown here for convenience:

      "OIDs for V3/CDA (temporary OID may also be assigned) and if the V2 Management Group desires that a V2 mnemonic be created for an external code system then that request shall be made directly to HTA with an addition to the  https://terminology.hl7.org/ValueSet-v2-0396.html code system as a pro-forma addition."


  8. Stan Rankins

    Please clarify that this process is to be applied to both code system identifier request and identifier system identifier request. Please also provide a definition for each type.

    1. Caroline Macumber

      Applies to both. When we originally wrote the policy, the support for external identifier systems wasn't available in THO or via the UTG process. Now that it is supported, the policy should apply to identifier systems also, the text has been updated to reflect this.