VocApp-Proposal/Management

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