HL7v2 Delimited (Pipe-and-Hat) / XML Conversion Tools for ITK

Damian Murphy (damian.murphy@nhs.net)
20th April 2012

This package contains an implementation of conversions between the delimited
form for HL7v2 messages ("pipe-and-hat" or "vertical bar encoding"), and XML
as described in "HL7 Version 2: XML Encoding Syntax Release 1" (ANSI/HL7 V2
XML-2003, June 4th 2003). It is an evolution of the conversion routines
built into the ITK Testbench (TKW-v2.0.0-Open): these have been un-bundled
and provided as a separate class library. This release also includes a class 
to implement a command-line, bi-directional transform which also serves to
illustrate integration of the conversion library with other code.

It is intended that this project become authoritative for those parts of the
ITK suite that need such conversion services. As such the TKW open source
project itself, and accreditation packs for ITK and related programmes, will
use the sources published here. This includes future versions of the 
"PHXMLconverter" tool that has been published in binary form, in the ITK
accreditation packs, for some time.

Test cases may be found in the accreditation packs, and those released from
late April/Early May 2012 will include tools and TKW based on this code.
TKW itself uses the code internally in two cases:

- In "simulator" mode, to translate "pipe-and-hat" messages to XML so that 
  they can use the same rule sets and response templates as XML-based HL7v2
  simulations. TKW also uses the converter to turn responses based on HL7v2
  XML, to "pipe-and-hat".
  
- In "validate" mode, to convert messages in pipe-and-hat form, to XML so
  that the XML-based validation scripts can be run on them.
  
Future uses may include the provision of test automation services.
  
The code is licenced under the Apache Licence, version 2.0:

Copyright 2011 Damian Murphy <murff@warlock.org>

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

What is in the pack:

Sources and Javadoc for PHXMLadapter-v1.0.0-Open. For  test cases, see t
he released ITK and other programme accreditation packs at
http://www.connectingforhealth.nhs.uk/industry/liaison/validator using the
download link under "Interoperability Toolkit (ITK) Testbench". The "ITK
Testbench" project available from the E-Health Open Source portal at
http://forge.tactix4.net has use and integration examples from version
v2.0.1-Open onwards.

The dependencies are:

- Java JDK 1.6 or later (it should build with 1.5, but nothing earlier due 
to extensive use of generics)

What is implemented:

1. Class library with singleton "phxmlconverter" class supporting two
conversion methods:

public String convert(org.w3c.dom.Element x)

converts parsed HL7v2 XML to a string containing a "pipe-and-hat" form of
the input.

public String convert(String mtype, String msg)

converts a pipe-and-hat message "msg" of type "mtype", into serialised XML
form. A convenience method which takes only the HL7v2 message as an
argument, and determines the message type internally, is also provided.

Also a static helper method findMessageType(String msg) for extracting
the message structure and event type from MSG.9.3 of a pipe-and-hat
format message.

2. "Main" class PHXMLadapter which provides a command-line interface to
the adapter for converting files. This is also intended as a "worked 
example" on calling the adapter functions in code. To convert pipe-and
hat to XML:

java -jar PHXMLAdapter.jar [-h] -px infile outfile

where "infile" is the pipe-and-hat format message (note that the XML
may need "pretty-printing" for human reading). To convert XML to pipe-
and-hat:

java -jar PHXMLAdapter.jar [-h] -xp infile outfile

In this case "infile" is a bare XML format HL7v2 message. In both 
cases "outfile" is the converted form of the message. The initial 
"-h" option will report version and usage.