HL7 XML Validation Engine Manual

The HL7 XML validation engine is a Windows-based application that serves as a "test harness" for validating XML files. The test harness provides an environment in which individual file selections or "patches" of file selections can be validated using Xerces - a standard Java-based parser from the Apache Foundation.

The validation engine is based on previous application from Ramsey Systems of the UK. In its original form, the test harness supported a variety of different validators. The source code for the test harness was donated by Ramsey Systems, and has been placed in open source using the OHT license. If users wish re-extend the engine, should contact the HL7 Tooling Work Group.

Primary Window

When the HL7 XML Validation Engine, the opening screen scene at right is displayed. (Without, of course, the red and yellow annotations that are superimposed here.) The display is a standard Windows dialog, with a title bar and menus at top; a textual overview of the application the middle; entry boxes for the target files and target schemas; and execution buttons at bottom right. Specifically:

The application menus will be discussed in the following section The entry box for selecting the target files are displayed as a text box with a "Browse" button to the right. The file extensions for selected files selection will, by default, be any of "xml", "mif", and "coremif". When dealing with validation of HL7 V3 work products, these extensions cover almost all required files. The entry box for schemas, along with its "Browse" button are sensitive primarily to files whose extension is "xsd". The "checklist" in the lower left allows selection of three different releases of Xerces, although the first labeled "XERCES_2_11_0" is the most recent release. At lower right are two buttons to select for validation of: the selected schema alone, validated against the W3C schema specification; and the selected instance file, validated against the schema designated.

Newly started XML Validation Engine with notes

Menu Selections

The various menu options for this application are shown in the diagrams above.:

• The File menu is primarily related to the definition of project data. Projects permit a limited amount of tailoring of the application, and had not been fully explored.

• The Options menu provides for "tailoring" the application. Specifically:
  • the "Validator config" option permits the modification (by directory selection) of the third Xerces validator. (Manipulation of the other two Xerces entries his disabled.)

  • the "Schema locator config" option provides limited shortcuts to specific directories in the user space.

• The Report menu allows the selection of the current error report (as a result of either a batch or a single file validation) to be saved as either HTML, or XML.

• The Batch menu provides for the definition of a set of files to be validated in a batch; and for the execution of an existing batch file. These are considered in subsequent sections of this manual.

Validating a Single File

The image at right shows a set of selections targeted at validating a single XML file (in this case a "coremif" file) against the standard Model Interchange Format (MIF) schemas. Both the target file and the schema have been selected. Clicking the "Validate XML/MIF instance" button launches the validation.	Example of Single File Validation
During the time that the Xerces Java application is running, a popup, as seen at right, is displayed on the screen. It identifies the validator that is running and provides a "Cancel" button to terminate validation.	Popup Indicating Java Execution
The results of the validation are documented in the main pane, as at right. They identify the project, the specific instance file(s), schema file, and validator selection. The results are both summarized (at right) and listed in detail in the "gray background below.	Validation Results display

Saving Validation Results

The results of the validation may be persisted by saving them with one of the two options under the Reports menu selection. Note that xml files are saved with an rxml extension in order to avoid conflict with the source files. De[ending on your XML viewer selections, files with this extension may not be displayed in the file selection browser.

Creating Batch Validation Sets

The XML Validation Engine has two primary functions - to provide easy access to Xerces and other Java-based validators, and to support the batch validation of files in support of work group, ballot and Normative Edition quality analysis. In these settings, there is, at times, the requirement to validate over a thousand individual schemas and/or instances. Selection of the menu item "Menu:Batch:Create Batch Validation" switches to the dialog seen at right. Specifics of the dialog include: The upper, display pane is switched using three tabs: Current Batch displays a tree view of the content of the currently selected batch set; Add instance provides controls for the selection of file(s) to be added for file instance validation; and Add Schema provides controls for the selection of schema(s) for validation. Beneath that pane is a selection box to choose one or more validators to be used with the bacth. The row of buttons at the bottom provide for: Loading (and saving) XML files. Executing the currently displayed (loaded) batch Removing one or all nodes (items to be vaidated) from the batch set Exiting the batch dialog

Dosplay pane for Batch Creation

Adding XML Instance Files to Batch

The diagram at right illustrates and documents sparsely the controls available for selecting instance files for validation and the schema(s) against which to validate them. In order to establish a new batch item, you must select: at least one instance file; at least (and usually only) one schema file that to validate the instance, and at least one validator. Of particular utility is the ability to select multiple instances from a single directory. This is done by: Choose at least one instance file from the directory in question; Select the radio button to do "All the instances in this directory"; Note: the algorithm will select all files whose extensions are "*.xml", *.mif", "*.coremif". Optionally to add a text string that must be matched by some part of the file name for files to be included. Note, The matching algorithm: Will be case insensitive; Does not accept wild-card characters; and Will match anywhere within the string that is the file name plus extension. When complete, click on the Add to batch button.	Selection Controls for Adding Instances to a Batch Set
As an example of selecting some but not all files in a directory, consider the file set shown in the diagram at right.	Example File Directory with "coremif" Instances to be Validated
The panel at right illustrates the control settings that will select only the Universal (file name contains "=UV=") instances from the file set in the directory shown above. Note that the "PORP_..." instance was selected to point to the directory, but that that file will be excluded by the selected name filter of "=uv=". The results of this selection are shown in the section Reviewing Batch Definition Content below.	Example to Include Only Universal (UV) Instances in Set

Adding Schemas to be Validated to Batch

A batch set may include both XML instances to be validated agaist a selected schema, and XML schemas (*.xsd) to be validated against the W3C specifications. The diagram at right shows the controls that are used to define one or more schemas to be included in the batch. Elements to be specified include: The selection (by text entry or browsing) of a single schema that either is the single schema to validate, or points to a directory of schemas to be validated; Radio button selection as to whether to validate just the single schema selected or potentially All schemas in the directory; and Optionally the inclusion of a name fragment that will be used to select only those schemas whose name includes that fragment. Note, as with the selection of instances: The matching algorithm Will be case insensitive; Does not accept wild-card characters; and Will match anywhere within the string that is the file name plus extension. The selection process requires selection of one or more validators from the list in the bottom section of the dialog, and the process is completed by clicking the Add to batch button. The selections in this example include all schemas form a particular directory whose name includes a match to "-CORE-". The results of this selection are shown in Reviewing Batch Definition Content below.

Controls for Adding Schemas to be Validated to a Batch Set

Reviewing Batch Definition Content

Once instance files and/or schemas have been added to a batch validation set, the contents of that set can be reviewed on the Current Batch tab of the Create Batch dialog. In this view, each item that has been selected for validation in the set is shown as an individual node in this pane. The nodes can be: Expanded to show the validator to be used, and, in the case of instance files, the schema that will be used to validate it. Removed by selecting a node, and then clicking button Remove Node Cleared by clicking button Remove All Saved in an XML file for future recovery and reuse by clicking button Save Batch Loaded from a saved XML file. This action will replace any batch nodes that were previously in the tree. Executed as a batch job by clicking button Execute Batch. Note that for a batch set that was saved to XML, this action can also be initiated directly using Menu:Batch.Execute Batch File.

Tree-view Display of Items Included in a Batch Set

Saving and Executing Batch Sets

As noted above, a defined batch set can be saved as an XML file for subsequent execution. Moreover, these batch files can be readily edited in XML to add or remove items; change schemas, etc. Once a batch file is loaded, it can be executed from the Create Batch dialog (Menu:Batch.Create Batch Validation) or executed directly from the menu bar (Menu:Batch.Execute Batch File).

As with the single validation illustrated above the execution of the batch set will activate "popup" windows to monitor the progress of the Java-based execution of the validation set. The illustration at right shows the two popups that will appear: The lower of these two indicates the execution of a single validation pass against one validator type (identified in bold font). The Cancel button on that popup will cancel only the single validation instance, not the whole batch. The upper popup is a simple progress bar that advances one step for each instance that has been validated. The progress bar graphs the fraction of the validation items that have been completed. Both popups will disappear when validation is complete, and will be replaced by the Results display discussed below.

Popup Dialogs for Batch Validation

Results from Batch Processing

The results of batch processing are displayed on the main pane of the HL7 XML Validation application just as for a single validation. The scrollable result is displayed in two sections. The upper, "summary" report provides four or more lines: The specific file being validated; The type of validation (instance vs. schema) A set of error listing column headers; and For each validator used, a row of data showing The validator that was used; The schema against which the instance was validated; The outcome (success or failure) (scrolled off right in this image, but also indicated by color high-lighting) The number of errors found (scrolled off right in this image); and The number of warnings included (scrolled off right in this image). Detailed listings of each validation error and warning are reported in the second (scrolled off bottom) section of the report. The detailed content is also captured in the XML error listing that can be saved using Menu:Report.Save report as XML (see below).

Summary Report For a Batch Validation as Displayed in Main Pane

If the above error report is saved using Menu:Report.Save report as XML, the resulting XML report appears as at right. Specifics to note about this content include: There is a description of the "project" if one has been entered. Following that there is a single element for each item that was to be validated in the batch as: <validateSchema/> for schemas or <validateInstance/> for instances. Each of these elements has an outcome attribute indicating whether the validation was successful or whether it failed by generating one or more errors and warnings. Inside these elements are sub-elements to identify the validator used, the schema file name and location, and the instance file name and location. Following the identification elements there are one or more <error/> or <warning/> elements. Note: Each error provides the location of the error - line and character position; Each includes a detailed description of the error; and All errors are listed for each file, not just the first error encountered. As a point of interest, the third error in this example listing (at lineNo="2" charNo="286") reveals the source of all of the errors - the file in question conforms to MIF schema version 2.1.6, while the schema used to validate it was schema version 2.2.0.

Cropped XML Display of Error Report Shown Above

Installation

The HL7 XML Validation application is delivered as a GForge download with package anem "XMLValidationEngine". The download is a single Microsoft installer (MSI) file. Installation has been tested on Windows XP, Vista, and Windows 7. By default, it will attempt to install in directory "Program Files\HL7\hl7XMLvalidation".

Owing to the fact that the program invokes Java-based parsing from the command line, it needs to create and read temporary files from the file system. In order to do so, it also creates a directory named hl7-XMLvalidation in the directory "[User]\Application Data" (in Windows XP) or "[User]AppData\Roaming (in Windows 7). (Note:If files accumulate in this directory, they may be deleted once the application is closed. A BUG report requesting that the application automatically delete these files has been posted on GForge, but was not implemented as of release 3.0.1.)

Updating the Xerces Release

Installation directories for HL7 XML Validation

Although the validation engine installer includes the latest Xerces release, it may be desirable to update that release prior to the next update of the application. The following figure shows the directory structure created by the installation, along with the files in the xerces-2_11_0 sub-directory.

With the exception of the five files that are highlighted in yellow or gray, all of the files in this directory are part of the standard download/distribution from the Apache Foundation site. In order to update the release, it is simply necessary to download the new Xerces release and replace the files in the designated directory with the updated ones. Although the old release number will continue to be displayed in menus and selection boxes, the validation itself will be performed with the new files, and the validation results will correctly indicate that the new release was used.