Harmonization Editor Manual (Proposal)
| GetStarted | DataBase | Browsing | Proposals | CodeSystems | Domains | ValueSets | Tutorial | Installation |
Intro · CreateHeader (Id · SupportText · Modify) · AddVocRevisions (RevisionDependency) · ManageProposals (ApplyChanges · MultiStepProps)
Introduction
The central purpose of this application is to act as an editor that allows facilitators to create, modify, apply and/or delete Change Proposals to be considered at harmonization. This section of the manual provides an overview of how to establish a proposal and manage it and how to create complex multi-step change proposals. Other sections of the document provide detailed discussion on responding to the particular panes (wizards) that are presented for defining code systems changes, domain changes and or value set changes.
Creating and Modifying Proposal Header
The following subsections provide step-by-step sequences for creating a new change proposal and modifying the header data.
Identifying Data
The identification data and related header data serve to characterize a file containing one or more vocabulary revisions. These data are defined in the HL7 Vocabulary Maintenance Language. To create a proposal and its header data, use the following sequence.
|
|
|
Supporting Text
Supporting text for the proposal provides the rationale and justification for making and approving the proposal. These fields correspond to the standard HL7 Change Proposal format in Word. The supporting text is entered in a series of identical screens with differing captions.
|
Modify Proposal Data
Once a proposal has been established, it is added to the ProposalView as the Active Proposal (see following figure). From there it can be managed and used. The header data can be modified by the following sequence.
|
|
|
Adding Vocabulary Revisions to Proposal
Once the meta data for a proposal has been defined, and the file has been created, it is possible to add as many vocabulary revisions as one wishes to the file. These are added by selecting one of the nodes displayed in the application, right-clicking on the node to get a revision menu and selecting the desired revision.
Prerequisites for this step:
- The vocabulary data must have been loaded from the data base.
- A valid proposal file must have been created and activated.
For this reason, the documentation of the revisions is divided into the kinds of nodes that can be selected in the application. The details are covered in sections of the document devoted to each group of revisions. The revision groupings and hyper links to the sections follow.
Value Set Revisions are:
- Those revisions that are applied to a node selected from the Value Set Navigator tree in the application.
- For the most part these revisions affect the Value Sets in HL7 vocabulary, their contents (including Coded Concepts from Code Systems, and their binding to Concept Domains. This is the only complete set of revisions as of 08:41, 10 October 2007 (CDT)
- Those revisions that are applied to a node selected from the Concept Domain Tree in the application.
- For the most part these revisions affect the definition and hierarchical relationships between Concept Domains. There are no revisions of this type as of 08:41, 10 October 2007 (CDT), although several of the Value Set Revisions effect revisions to the Concept Domains.
- Those revisions that are applied to a node selected from the Code System Table in the application.
- For the most part these revisions affect the creation and definition of new Code Systems, the addition of Coded Concepts, and the definition of hierarchical relationships between the Coded Concepts. There are no revisions of this type as of 08:41, 10 October 2007 (CDT), although several of the Value Set Revisions effect revisions to the Coded Concepts within previously defined Code Systems.
Revision Interdependencies
- TRUTH: it is extremely rare that a simple desired revision affects only one of the three categories, and it is extremely common that most useful revisions involve more than one of them.
Consider the following simple example. Assume we expanded the tutorial example. Suppose we want to add a specializable value set with head code of ANT, print name ant eater and named ActClassAnteater, and under that we wanted to add aardvark (AAR) as a specialization. Finally, we also want to have ActClassAnteater be a binding for a concept domain named ActClassBeastsThatEatAnts under the domain ActClass. Note that this might normally be presented by a committee as a "Value Set change".
| This example is fairly easy to do with the application, but when we look at the resulting change request proposal in XML (at right), it is hardly "just a value set revision". The XML has been highlighted in three colors -- green for code system revisions, violet for domain revisions and yellow for value set revisions. Note that the value set revisions are much less than half the total.
The sequencing of the changes is automatically managed by the application. In the example at right, I started with a "Create value Set" operation and worked through the forms. The application took care of sequencing the operations as shown. Nevertheless, it to understand the fairly simple rules that apply. These are summarized below. Vocabulary Revision DependenciesDomain Revisions Domain revisions are not dependent on any other revision, but the revision that adds a domain must occur before a value set can be bound to it, as this binding is considered value set revision. Code System Revisions Code System revisions are not dependent upon other any other revisions, but usually any codes to be added to a value set must have been defined before the value set revision commences (as above). |
Value Set Revisions Because value sets are defined from the codes in one or more code systems, Value Set revisions are always dependent on the prior establishment of the code system elements (codes) that are in the value set.
Proposal Management
The functions for managing the life cycle of vocabulary change proposals centers around the ProposalView pane shown below.
This pane has three sections. From top to bottom, they are:
- Active Proposal shows which proposal, if any is active at the moment.
- The active proposal is the one that will be updated with new changes defined from the "right-click" menus in the navigator/browsers.
- The active proposal is not the proposal to which the buttons below apply.
- Proposed Change Requests is a list of the vocabulary change proposal files currently in the directory managed by the application. Any of these may be selected by clicking on it.
- The selected item is the proposal that is the target for the actions of the buttons at the bottom.
- Double-clicking on a selected item will open it in the proposal viewer.
- Five action buttons. Their functions act upon the proposal selected in the Proposed Change requests list not on the Active Proposal. These functions are the topics for the sections that follow.
View Proposal
Clicking the View button causes the Change Request Browser pane to open, with the selected proposal as its contents, as below:
This is an XML viewer that will allow you to review the content of a proposal. At present (October 2007) the Edit button and Edit XML tab do not do anything. If you wish to edit the meta-data for the proposal (name, id, author, committee, description, supporting text) the Edit Meta-data Wizard button will open the same wizard used to create the proposal, leaving the Change Request Browser in the background.
- CAUTION: If you use the Meta-Data Wizard from the viewer (the only way to edit this data) the following may/will occur:
- Changing the proposal name, committee or date will change the file name and result in a new file being written
- When you close the wizard, the file will be updated (or a new one created) and control will return to the Change Proposal Browser, but the content of the browser will not have been updated. You must close the browser and open it again to see the changes
- When the wizard closes, it activates the proposal just edited also, thereby, deactivating the previously active proposal.
Activate/Deactivate Proposal
As its name suggests, the Activate button makes the proposal selected in the list the Active Proposal.
Similarly, the Deactivate button empties the Active Proposal field, thereby disabling the menus that initiate the addition of change content to the proposal.
- CAUTION: When the Meta-Data Wizard closes, the proposal it was working with (creating or modifying) will automatically become the Active Proposal
Apply Proposed Changes
The Apply button on the ProposalView pane is in some ways the raison d'etre for this application. This is the step that actually takes a Change Proposal and applies its changes to the database. As with the other buttons, this button applies the changes in the proposal selected in the list, which is not necessarily the Active Request.
With the correct proposal selected in the list, click Apply. The Apply button should appear to remain depressed and after a bit of grinding two things will happen:
- In the background, the data panels of the application will refresh in order to show the changes. The Value Set Navigator pane is refreshed by an "automatic" selection of the same Concept Domain that was used to populate the navigator.
- A log of the update process will appear as in the pane below.
This pane is a display of the process log that applied the selected changes against your data base.
If this pane does not appear after 30-60 seconds, or if the Apply button no longer appears depressed, or the pane content looks suspicious, see the entries in the Apply Changes Errors sub-section.
If the pane does appear, the title bar will tell whether the update was successful. You can also scroll down to the bottom to verify that the update was successful, as shown below:
Apply Changes Errors
As with any application, not all updates are successful, sometimes because the request was invalid, sometimes because of other errors. This section looks at a number of potential errors (or apparent errors) that have been observed. With the exception of the first, these are labeled with an error messages that appears in the log.
Log starts with Castor error
Castor is the basis for the engine that parses the Change Proposal XML. As such some update runs will start with an error message in the log as below.
| As noted in the log, the most likely reason for this error is that you did not fill in one of the fields on the first panel meta-data entry wizard, or an error was made when manually editing the proposal. |
JVM Terminated. Exit code=1
[INFO] Timeout not implemented on database
| If this message fills several pages of the log, as at right, there may actually be no error. Rather scroll down to the bottom of the log to see if the "INFO" error messages stopped and normal processing began. This seems to represent a longer than expected delay for a response from the data base to a particular request from the application that eventually resolves and allows processing to resume. |
[ERROR]********* Update session terminated
| This error message is the last entry in the log. as at right. Another [ERROR] message occurs further up detailing what is wrong with the proposal. The data base has not been changed as noted in the title bar. |
[WARN]----> Warning - inserting PROPOSED item
Delete Proposal
The Delete button instructs the application to delete the file for the selected proposal. This action will be "verified" with the dialog box that follows. Clock OK to proceed with the deletion.
Creating Multi-step Change Proposals
Virtually all change proposals involve multiple revisions that are executed sequentially. This is not what is meant by a Multi-step Change Proposal in this context.
A Multi-step Change Proposal is:
- a proposal that involves several revisions some of which cannot be defined with this tool until the earlier revision(s) have been applied to the database
This dependency does not exist for most compound proposals. One can define many "additive" revisions without encountering the problem. The problem here is not the execution of the revisions, because the database will have been updated by the earlier revisions, but rather is the difficulty of defining the later revisions with the tool.
Multi-step Illustration
Suppose you have reason to move a previously defined Coded Concept from one Value Set to its parent value set. The steps are easy to figure:
- Remove the code from the first value set, and
- Add it to the second value set.
The problem arises with defining these steps with the tool. It is easy enough to use the Remove Codes from a Value Set revision to accomplish the first step. However when you try to use the Add Codes to Value Set revision to accomplish the second step, the tool blocks you because it recognizes that the code is "already" a member of the parent because it is (still) a member of the child.
Solution 1: Create Two Change Proposals
The simplest way to address this problem is to:
- Create a change proposal to accomplish step 1 above
- Apply this first change proposal to the database, thus freeing the restriction
- Create A second change proposal to do Step 2
- Apply the second change proposal to the database.
The challenge with this process is that you now have two change proposals to accomplish one task, and if you need to redo these, for example after a database restore, you will need to apply both change proposals in sequence.
Solution 2: Edit a Single Proposal in XML
The limitations cited above can be overcome by opening the two change proposals in an XML editor, and copying the "revisions" from the second file into the first file following the last of the "revisions" in the first file. Although it requires manual intervention, this method can be used to combine several proposal sets into one.
Solution 3: Create a Single Multi-step Proposal
This can be done by sequentially updating the data base as the process proceeds:
- Create a change proposal to accomplish step 1 above
- Apply this first change proposal to the database, thus freeing the restriction
- Add the second revision to the change proposal created in Step 1
- Restore the database
- Apply the compound proposal to the database.
The last three steps can be repeated again to deal with serial revision dependencies. The advantage of this approach (and of the approach to edit the XML files) is that it assures that related changes are kept together and that they are executed together or not at all.
Tool Enhancement
Note that the tool might also be enhanced to flag the conflict noted in the example, but to allow the second step to be defined anyway. After all, the conflict will not arise when the proposal is executed as a set of serial revisions. This enhancement will be entered as a "feature request" in Gforge.
