Stream: terminology
Topic: Code System and Value Set changes
Ted Klein (May 27 2020 at 12:59):
A number of code systems and value sets whose canonical URLs are rooted at terminology.hl7.org have had copies of their content added to the UTG publish and current builld space. The question has arisen as to whether now is the time - or are we not yet ready - to begin to make changes in these through the UTG maintenance process, or to continue updating them in the FHIR ecosystem as has been done up to now. The UTG Pilot has started and we expect to have a full membership rollout no later than early July, but some code systems (such as hl7workgroups) have already been undergoing updates in UTG. What is the sense of the group on this? @Grahame Grieve @Lloyd McKenzie @Rob Hausam ?
Grahame Grieve (May 27 2020 at 12:59):
the original intent was that once UTG is up, they'll be removed from FHIR and maintained through UTG.
Grahame Grieve (May 27 2020 at 13:00):
I don't think that anything has changed with that; the main question is at what stage UTG is considered to be 'up'
Ted Klein (May 27 2020 at 13:03):
Yes exactly. All about timing. And part of this is then turning on the process of making sure the correct version of the resources is the one that folks get to mostly. We have a process now, but it has only just begun. I would love if someone has some small simple changes to put them through the tug Pilot to help flesh out any issues, I am ready to keep on top of it to address anything that arises.
Carol Macumber (May 27 2020 at 13:51):
@Jessica Snell and the UTG testing associated with the Pilot Phase should include test cases to ensure we are ready to transition maintanence to UTG. @Rob Hausam when this occurs, if copies will remain in FHIR, we need to add some verbiage pointing users to the UTG process for maintance requests as FHIR will now be showing the "Convienence Copies"
Lloyd McKenzie (May 27 2020 at 14:13):
The actual rule is that they'll be removed from FHIR once any of the resources that use them hit FMM3+. However, I'm in favor of all of the code systems for those that aren't yet FMM3+being flagged as 'temporary' so it's clear those codes will have to move. (We don't actually want to start sticking stuff in UTG when the community doesn't have enough implementation experience to be confident about what the terminology should actually be...)
John Moehrke (May 27 2020 at 16:51):
Could we itemize these codesystems and let the author know? I suspect that I would be impacted but have no idea if that is true or not. I am very confused on what terminology is vs UTG vs HTA vs any other term that vocabulary invents
Ted Klein (May 28 2020 at 13:58):
ok. since the questions was raised relative to one of the ECQM objects, can @Bryn Rhodes perhaps be convinced to make the changes to measurePopulationType as part of the Pilot in UTG in the next couple days? That might help to kill several birds with one stone
Ted Klein (May 28 2020 at 22:01):
Things became more complicated on today's Vocabulary WG call. As of right now, it is my understanding that V2 and V3 and Unified code systems and value sets rooted in UTG (terminology.hl7.org URLs) are changed through the UTG process, and any needed in the FHIR Build space must be updated in FHIR from UTG. Changed objects listed in the FHIR Code Systems and Value Sets tabs on UTG are updated in the FHIR Build space, and any changes done there must be copied into UTG. Unless this can be handled by the Publisher based on Versions of the Code Systems and Value Set resources. In a more perfect world :-) folks could update them wherever they need to in the next couple weeks while we are doing the transition and it will come out in the wash. But we will still need to migrate the more recent changed items rooted in UTG to there from FHIR back to UTG once we declare it officially 'up'. This needs to be decided and communicated as soon as possible to those that are asking the question.
Grahame Grieve (May 29 2020 at 02:59):
it was my intent to remove anything from terminology.hl7.org from the build, and to use UTG directly
Grahame Grieve (May 29 2020 at 03:00):
as soon as UTG is the operational naster
Ted Klein (May 29 2020 at 13:10):
so we only need to figure out what the definition characteristics must be to declare it the 'operational master'.
Ted Klein (May 29 2020 at 13:11):
in the meantime, is there aa way to know what may have been pushed in the FHIR ecosystem since the UTG snapshot of version 4.2.0 of those code system and value set resources rooted in terminology.hl7.org?
Bryn Rhodes (May 29 2020 at 15:13):
From the editor's perspective, what is the process for making changes to terminology that is included in the UTG? I know exactly how to make the changes to code systems included in the FHIR build, is there a similar process associated with UTG content?
Bryn Rhodes (May 29 2020 at 15:14):
I'm happy to make the changes as part of a pilot here, and we have a very simple candidate change that fits nicely, I just need to know where/how to make that change in UTG content.
Robert McClure (May 29 2020 at 17:16):
@Bryn Rhodes The UTG process requires creating a forked version of the UTG content, modifying it, putting that change out for viewing via the UTG review process, then when that review process completes, if passed the fork is merged into the source of truth as an update. If you are willing, I'll work with you to be in the pilot. Remind me - what code system are we changing? Have you pushed it out into the build (I assume not?)
Ted Klein (May 29 2020 at 21:34):
Yes Rob has it correct, and it is all pretty fully documented on the UTG Confluence pages for the Pilot at https://confluence.hl7.org/display/VOC/Participating+in+UTG+Pilot+Testing and https://confluence.hl7.org/display/VOC/UTG+Tooling+and+Proposal+Documentation. We have one proposal with changes out for consensus review right now, and I am waiting for the build to complete on the second one which will be passed to consensus review state as soon as the publisher finishes. Except for a few control buttons on the Jira screens for the workflow which should not be viewed by submitters (permissions settings I am working on the fix for this weekend) it all seems to be working reasonably. Would really love to have you try it out and let me know what is broken :-)
Ted Klein (May 29 2020 at 21:39):
note that the UTG process is only for those code systems and value sets with canonical URLs at terminology.hl7.org, and that are NOT ballot bound (schema bound) ie used in FHIR elements of 'code' datatype (ok for codeable concept)
Ted Klein (May 29 2020 at 21:39):
and also PLEASE update the <version> element!
Khalid Shahin (Jun 03 2020 at 16:25):
We also want to change the name of two code systems that we're managing under our Evidence resource, and add a new code to one of them: https://jira.hl7.org/browse/FHIR-27744
What would the UTG process be for making this updates?
Lloyd McKenzie (Jun 03 2020 at 17:58):
Until your resources hit maturity level 2, you shouldn't be using UTG for your terminologies. The UTG terminologies have to follow "good terminology practices" - so once a code exists, you can't get rid of it, you can't make significant changes to the definitions, refactor the hierarchy, etc. When we're in the early STU stages, we often aren't completely confident in what the codes should be and need some implementation experience to confirm our terminology needs. FHIR-specific terminologies should be used at this stage, with a clear expectation set that we'll move to other more 'robust' terminologies (ideally ones maintained outside HL7) once we're more confident in the requirements.
Bryn Rhodes (Jun 03 2020 at 18:39):
Okay, that's good to know, @Khalid Shahin , given the maturity level, I think what I hear Lloyd saying is that we should continue to make those changes in the FHIR build directly.
Bryn Rhodes (Jun 07 2020 at 19:38):
Where do I ask specific questions about this process? Just keep them coming in this thread? @Robert McClure @Ted Klein ? For example, why are we using bitbucket?
Lloyd McKenzie (Jun 07 2020 at 19:55):
Using BitBucket because it integrates more easily w/Jira - but still works with standard Git tooling
Bryn Rhodes (Jun 07 2020 at 20:08):
So I don't _have_ to install SourceTree, yes?
Bryn Rhodes (Jun 07 2020 at 20:09):
From the pilot document:
Sourcetree is required to manage your local vocabulary changes and push those changes back to the branch that you are using to submit your proposal.
Bryn Rhodes (Jun 07 2020 at 20:09):
But that could say "A git client such as SourceTree is required to manage...."
Rob Hausam (Jun 07 2020 at 20:14):
They are trying to keep things as simple and consistent as possible for everyone - particularly those who aren't used to using git. I have the same inclination to use my current setup and tools (primarily command line) for updates, without dealing with SourceTree, but I haven't finished fully exploring that yet.
Bryn Rhodes (Jun 07 2020 at 20:27):
Yes, that's fine to document with Sourcetree, but I'd really prefer not to have to install another git client :)
Ted Klein (Jun 07 2020 at 20:47):
Exactly right. We have an awful lot of folks who cannot spell 'git', and we need to give step by step exact directions. Basically what the Jira automation does is create a UTG Bitbucket branch for your proposal making sure it does a Pull for the latest current build so you always work again st 'current', and you play with it however you like. The 'Submit' of a proposal causes a validation of content and a replication of the branch in the UTG Git, which is a highly protected environment, and forces a build of the branch. The URL to the branch is then inserted into the proposal so that reviewers see the proposed changes in context, browsing just like the main site. I myself only really use the SourceTree tooling to debug the workflow and script operations; I normally use my git CLI in my unix environment. It is all about what makes you most comfortable. Note that some content changes are done by the scripting after Submit to modify the Bitbucket and Git branches (labeling in the IG control file mainly) for Consensus Review, then we are working on automating the generation of the Provenance bundle for history tracking which gets added after a proposal is Approved and gets implemented into the source of truth. If you are sued to doing IG builds that is wonderful, as most of the error valuation is making sure the changes build without errors - most of our submitters are not ready to or capable of doing a local IG build with their changes. If you are good with that, I need to give you some additional parameters for the java command to do the build, since without them the UTG build usually segfaults.
Bryn Rhodes (Jun 08 2020 at 01:33):
Yes, I’m used to doing local ig builds
Bryn Rhodes (Jun 08 2020 at 15:46):
Trying to get the terminology server started and connected from the FHIR Toolkit, the server is running locally as expected, but the FHIR Toolkit cannot connect to it because it has an unknown value in the fhirVersion list:
Bryn Rhodes (Jun 08 2020 at 15:46):
Bryn Rhodes (Jun 08 2020 at 17:39):
So I'm trying to characterize the change I'm actually making, it is a clarification to the definition of two existing concepts in a code system. Looking at the (not yet approved) code system versioning policies here, would that be a patch version change, since it is a clarification?
Grahame Grieve (Jun 08 2020 at 18:47):
which terminology server?
Bryn Rhodes (Jun 08 2020 at 19:08):
The local one that I installed as part of this pilot, downloaded from http://www.healthintersections.com.au/FhirServer/vocabpoc-install-0.0.6.exe
Grahame Grieve (Jun 08 2020 at 19:39):
hmm. I'll have to do something about that
Bryn Rhodes (Jun 08 2020 at 20:01):
Just reporting it as an issue, it's not stopping me at this point
Bryn Rhodes (Jun 08 2020 at 20:01):
Should I log an issue somewhere?
Grahame Grieve (Jun 08 2020 at 20:13):
here, I guess: https://github.com/grahamegrieve/fhirserver/issues
Bryn Rhodes (Jun 14 2020 at 21:19):
I note that the CodeSystem resources in the sourceOfTruth include generated narrative. Will that narrative be refreshed by the tooling, or does my change proposal need to include the change reflected in the narrative?
Grahame Grieve (Jun 15 2020 at 00:30):
@Ted Klein source of truth should not include narrative
Ted Klein (Jun 15 2020 at 01:39):
Not sure what you mean. I think when the FHIR code system resources were inported they were pulled in by Dave T fro the FHIR pages generated maybe not from the package? Not sure. I think all the FHIR ones look like this, no idea what needs to be done to fix. @Grahame Grieve please advise
Michael Lawley (Jun 15 2020 at 01:45):
Given that such narrative should have status=generated, does it matter that it's present?
Grahame Grieve (Jun 15 2020 at 01:55):
process problem. We should delete all of them
Last updated: Apr 12 2022 at 19:14 UTC
