XQuery TUTORIAL

Converting From HL7 2.X to HL7 3.X With DataDirect XML Converters

Updated: 26 Feb 2021

Introduction

HL7 versions 2.x and 3.x use completely different models for mapping information. It isn't just that 2.x is primarily EDI-based, and 3.x primarily XML-based, but the concepts behind them are different. Whereas 2.x is a "working class" version, stripped down to the bare bones, 3.x is more of a "highbrow" look at things, with lots of rigorous structure and extra markup.

While HL7 2.x covers about 80% of what is needed for good communication, it leaves lots up to individual implementations. So the first use of a mapping tool is to get my definition of HL7 2.x to match up with your definition.

HL7 3.x tries to avoid that by being more complete. As a result, there are some things that the 3.x version of the message will need that the 2.x version won't supply, so our transformation is going to have to add them.

A quick look at the standards documentation will show that there is not a one-to-one mapping between HL7 2.x and HL7 3.x messages. But in many cases, there are equivalents that will get the job done — and that's what we're going to do.

Attached is an example to show how it is possible to go from one to the other, using the DataDirect XQuery engine along with the DataDirect XML Converters for HL7.

A Sample HL7 2.x Message

Here's a simple "observation results" message. In this example, Dr. Levin-Epstein ordered a glucose test for her patient Ms. Estherhaus, which was done by Dr. Honeywell.

MSH|^~\&|DDTEK LAB|ELAB-1|DDTEK OE|BLDG14|200502150930||ORU^R01^ORU_R01|CTRL-9876|P|2.4 CR
PID|||010-11-1111||Estherhaus^Eva^E^^^^L|Smith|19720520|F|||256 Sherwood Forest Dr.^^Baton
Rouge^LA^70809||(225)334-5232|(225)752-1213||||AC010111111||76-B4335^LA^20070520 CR
OBR|1|948642^DDTEK OE|917363^DDTEK LAB|1554-5^GLUCOSE|||200502150730|||||||||020-22-2222^
Levin-Epstein^Anna^^^^MD^^Micro-Managed Health Associates|||||||||F|||||||030-33-3333&
Honeywell&Carson&&&&MD CR
OBX|1|SN|1554-5^GLUCOSE^^^POST 12H CFST:MCNC:PT:SER/PLAS:QN||^175|mg/dl|70_105|H|||F CR

 

Using XQuery to Map from the HL7 V2 EDI to the HL7 V3 XML

First, we create a new XQuery program with "File"->"New"->"XQuery File".

Second, we switch to the "Mapper" view, and click on the "Add Source Document" button. Choose the file oru_r01.hl7, check the "Open using XML Converter" box. Next, we choose the EDI converter, and set the "Use long element names" option to "yes". Also, to make mapping easier, we're going to add a namespace prefix to the input file, since the output file will use a default namespace. So the "Namespace prefix" option gets set to "h", and the "Namespace URI" option to "hl7-2.4".

At this point, we're dealing with an EDI document, but as far as our tools are concerned (and thanks to the transparent operation of the XML Converter), it behaves just as any other XML document.

Third, we need a target schema. we just happened to have a sample HL7 V3 document lying around, but you can use the HL7 V3 schemas that are included in the standard.

Now it's mostly a matter of drawing lines. In a couple of places dates needed to be converted, so we added a date/time helper function.

Many of the values we just hard-coded in our sample XQuery program. In the real world, they would be set either as parameters to the XQuery, as constants you would configure yourself, or as data drawn from another XML file or a relational database.

Below is the portion of the hl7-v2-to-v3.xquery program that is responsible for producing the XML fragment above.

...
for $oru in /h:HL7/h:ORU_R01
return
<Message xmlns:h="hl7-2.4" xmlns="urn:hl7-org:v3" xmlns:dt="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<id root="{$rid}" extension="{$oru/h:MSH/h:MSH.10-MessageControlId}"/>
<creation_time value="{local:datetime($oru/h:MSH/h:MSH.7-DateTimeOfMessage)}"/>
<version_id>3.0</version_id>
<interaction_id root="{$iid}" extension="POLB_IN004410"/>
<processing_cd code="{$oru/h:MSH/h:MSH.11-ProcessingId/h:MSH.11.1-ProcessingId}"/>
<accept_ack_cd code="ER"/>
...
<interactionTarget xsi:type="POLB_MT004101">
<ObservationEvent>
<id root="{$rid}" extension="{$oru/h:GROUP_1/h:GROUP_4/h:OBR/h:OBR.3-FillerOrderNumber/h:OBR.3.1-EntityIdentifier}" assigningAuthorityName="{$oru/h:GROUP_1/h:GROUP_4/h:OBR/h:OBR.3-FillerOrderNumber/h:OBR.3.2-NamespaceId}"/>
<cd code="{$oru/h:GROUP_1/h:GROUP_4/h:GROUP_6/h:OBX/h:OBX.3-ObservationIdentifier/h:OBX.3.1-Identifier}" codeSystemName="LN" displayName="{concat($oru/h:GROUP_1/h:GROUP_4/h:GROUP_6/h:OBX/h:OBX.3-ObservationIdentifier/h:OBX.3.2-Text,' ',$oru/h:GROUP_1/h:GROUP_4/h:GROUP_6/h:OBX/h:OBX.3-ObservationIdentifier/h:OBX.3.5-AlternateText)}"/>
<status_cd code="completed"/>
<effective_time>
<center value="{local:datetime($oru/h:GROUP_1/h:GROUP_4/h:OBR/h:OBR.7-ObservationDateTime)}"/>
</effective_time>
<activity_time>
<center value=""/>
</activity_time>
<priority_cd code="R"/>
<value xsi:type="dt:PQ" value="{$oru/h:GROUP_1/h:GROUP_4/h:GROUP_6/h:OBX/h:OBX.5-ObservationValue/h:OBX.5.2-Value2}" unit="{$oru/h:GROUP_1/h:GROUP_4/h:GROUP_6/h:OBX/h:OBX.6-Units/h:OBX.6.1-Identifier}"/>
...

 


HL7, XQuery and Databases

Not all of the values in your message are going to come from the input document, and not all can be defined statically. Some may come from external documents or directly from a database.

Using DataDirect XQuery, it is a simple matter to reach into the database to pull out one-off or tabular data. For example, to pull the value for the <telecom> element from a MySQL "settings" table, you could replace this code:

<telecom value="127.127.127.255"/>
with this:
<telecom value="{ collection("stylus_3306:settings")/settings[key = "telecom"]/value/text() }"/>

It is just as easy to iterate over larger sets of relational data by using the powerful collection() function provided by the XQuery standard, and implemented on top of relational and filesystem drivers as in DataDirect XQuery.

Health Level Seven — HL7 Mapping Example Completed

Transformations which used to require separate stages or separate tools can now be done in one place.

The DataDirect XML Converters package handles the mapping between the non-XML world of HL7 EDI and the universe of XML mapping tools.

DataDirect XQuery provides an engine that knows more than just simple XQuery syntax — it includes the tools necessary to bridge the gap from documents to databases, and to operate on multiple input and multiple output files. It can write XML, EDI and relation data with equal facility, and was built to scale into the arena where data is measured in gigabytes.

Finally, Stylus Studio is the front end that lets you combine these seamlessly. It includes both the above products within it as well as the sophisticated mapping and debugging tools necessary to design powerful transformations.

Connect any application to any data source anywhere

Explore all DataDirect Connectors

Need additional help with your product?

Get Customer Support