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.

Select Menu...File...Create New Vocabulary Change Request or select the equivalent icon on the tool bar. The wizard opens the New HL7 Vocabulary Change Request Wizard page (as at right) This is the panel in which you enter the primary proposal identification data Specific examples are on the next figure

First Proposal Definition dialog

The version of the New HL7 Vocabulary Change Request Wizard at right shows example data The submitting committee is selected from a drop-down. If your committee is not represented, select TSC. Tool tips appear when you hover over a field, as shown for the name field at right. Finally the Description field must have text entered as a proposal without data here will not be processed. (The wizard does not currently enforce this rule.) When the form is complete: Click Next if you plan to add supporting text, which is strongly recommended as this text supports the approval of the proposal. (see next figure) Click Finish to establish the proposal without supporting text. (The text can be added later by modifying the proposal once it is created.

Proposal data filled in, also showing tool tip

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.

The first Supporting Text pane is the Main Issue For Proposal page (as at right) This page is one of four such forms that will be presented in sequence and that allow documentation of: the Main Issue that this proposal is addressing. summary of the Current State of the vocabulary, presentation of the Alternative Options considered, and the Rationale for the option chosen. Use the text box on this page to enter the documentation When complete: Click Next to see the next supporting text page Click Finish to establish the proposal

Proposal Text dialog for Main Issue (and others)

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.

The proposal appears in the application's ProposalView (as at right) The proposal can be viewed in its entirety by clicking View This page is discussed in more detail under proposal management	Proposal view frame with new proposal shown and activated
Proposal viewing uses the Change Request Browser (as at right) To modify the proposal header data, click Edit Meta-data Wizard which will take you back to the wizard pages above. After editing, exit this page by clicking Close This page is discussed in more detail under proposal management	Change Request Browser showing new proposal

Jump to top of page

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:

1. The vocabulary data must have been loaded from the data base.
2. 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)

Concept Domain Revisions are:

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.

Code System Revisions are:

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 Dependencies Domain 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).

Change request XML for a value set change color-coded to show three classes of changes.

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.

Jump to top of page

Proposal Management

The functions for managing the life cycle of vocabulary change proposals centers around the ProposalView pane shown below.

ProposalView pane of editor

This pane has three sections. From top to bottom, they are:

1. 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.

2. 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.

3. 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:

Change Request Browser showing a proposal

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:

1. 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.
2. A log of the update process will appear as in the pane below.

Start of log from Applying update showing steps

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:

End of log from Applying update showing successful completion

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.

Errors parsing Change request XML

JVM Terminated. Exit code=1

The application vanishes from your screen, and the message box at right appears if you try to Apply the changes in an incomplete change request file. Specifically, this will occur if you define a new change proposal and then try to apply it before you have added any change content. It occurs if the file has only the editDescription element and no revision elements.

JVM Crash message due to incomplete Change request XML

[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.

Application log shows repeated "[INFO] Timeout..." messages.

[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.

Application log showing "fatal" error and update termination

[WARN]----> Warning - inserting PROPOSED item

This warning message occurs frequently, but if it is the last entry in the log (as at right), and the log appeared quickly the processing terminated abnormally but without logging an error. In all likelihood this is because the application failed to release a "lock" on the data base after a previous unsuccessful run. (See note above). To free this lock, exit the application and restart it and then try the apply again.

Application log terminates early, probably due to DB lock

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.

Dialog to verify change proposal deletion

Jump to top of page

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:

1. Remove the code from the first value set, and
2. 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:

1. Create a change proposal to accomplish step 1 above
2. Apply this first change proposal to the database, thus freeing the restriction
3. Create A second change proposal to do Step 2
4. 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:

1. Create a change proposal to accomplish step 1 above
2. Apply this first change proposal to the database, thus freeing the restriction
3. Add the second revision to the change proposal created in Step 1
4. Restore the database
5. 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.

Jump to top of page