How to create an HL7 message profile with Messaging Workbench (MWB)

Pre-Requisites

  • Install MWB (see section of this tutorial named "How install Messaging Workbench" for further details about the MWB installation.)
  • To correctly use Messaging Workbench, you should have good knowledge of the HL7 standard.
  • This tutorial will help you to generate your own HL7 message profiles according to IHE. Please read the IHE Technical Framework first of all. 
  • It is very important to follow this tutorial without skip steps.

Notes: This tutorial can help you to create new HL7 Message Profile. This is not a tutorial to understand all functionalities of Messaging Workbench.

 

How to install Messaging Workbench. 

First at all, MWB runs only on Windows.

MWB installation: 

  1. First at all, you will need to install the Messaging Workbench software. You will find it at this location: http://www.hl7.org/participate/toolsandresources.cfm, in the "V2 Tools" section.
  2. Get our MWB librairies and pojects at this location: http://sumo.irisa.fr/~epoiseau/IHE_Messaging_Workbench_Lib_And_Project.zip. It will present to you as a zip file. 
  3. Unzip the file named “IHE_Messaging_Workbench_Lib_And_Project.zip”. In the unzipped folder, you should find :

    • The IHE Libraries folder, named "IHE_Lib_2012".
    • The IHE Projects folder, named "IHE_Projects_2012".
    • The IHE XSLT files, in the "xslTransformTools" folder. See the last part of this tutorial for further details about theses files.
  4. Enter in the "IHE_Lib_2012" folder, move all files and folders to the Lib folder of MWB (default  "C:\program files\Messaging Workbench\Lib").  (Windows will ask you if you desire replace files and folders, say YES).
  5. Enter in the "IHE_Projects_2012" folder, move all files to the Projects folder of MWB (default  "C:\program files\Messaging Workbench\Projects").
  6. When it is finished, you can begin to use Messaging Workbench.

Create DataType specific to your profile

If for the IHE domain there is specific data type, you should create a specific data type file from the default data type files defined by MWB. 

If not, you can use the default data type file defined by MWB.

To create your own data type file :

On MWB choose on the Menu the tab: 

Maint --> Datatypes --> Add/Edit datatype File

MWB Lib Menu screenshot.

In the frame open, choose the tab:

File  --> Open

Choose the data type default file chich is stored in the directory: MessagingWorkbench_Home/lib/ 

MWB DT

Open the data type file specific to your HL7 version, then choose the tab :

Datatype --> Edit

MWB DT customize

Select the specific data type you want to change, make the changes and save the new data type file with another Name (By convention, the name should indicate which domain changes is stored in the data type file: for example «LTW-DT-2.5.mdf »).

Attention, try to not modify the source data type file.  

 

Create library with the previous DataType file

On MWB choose on the Menu the tab: 

Maint --> Libraries --> Edit library File

You can choose for example « HL7 2-5.mcf » in the directory  “MessagingWorkbench_Home/lib/“. You must choose an existing library to construct your own.

MWB Lib Selection

In the frame, change the current Data type with your own (for example « LTW-DT-2.5.mdf »). To do that, hit the “Attach DT” button and choose the corresponding DT file.

Then, press the “Compile” button and “Save as” the compile file as a new library in a file called for example «LTW-HL7 2-5.mcf ».

MWB Lib Compilation

At least, close the library configuration window by hitting the “Done” button.

This library represents the base of the creation of your profile. If the IHE Technical Framework doesn’t define specific Data Types, you can use the IHE libraries present in the “PHARMA”, “ITI_LIB”, “LTF_LIB” or “PCD-LIB” folders in the “MessagingWorkbench_Home/lib” folder.

 

Set the specific library which will be used

On MWB choose on the Menu the tab: 

Maint --> Options...

  • Go to the “General” tab.
  • You can set the library you want to use by default. To do that, at the bottom of the page, hit the “…” button corresponding to the “Select Default Conformance File” section and choose your desire library.
  • You can also set the HL7 Table file to use. To do that, at the bottom of the page, hit the “…” button corresponding to the “HL7 Table file” section and choose your desire HL7 table file. Try to choose an HL7 table file according your HL7 version. Find these file in the “MessagingWorkbench_Home/Lib” folder.
  • Now, Go to the “Directories” tab.
  • Just verify that the “Current Projects directory” is set, for example to “Messaging Workbench_HOME\Projects” and that the “Current library directory” is set to “MessagingWorkbench_HOME\Lib”.
  • At least, hit the “OK” button.

MWB Options

On MWB choose on the Menu the tab: 

Maint --> Librairies --> Select Conformance Files

  • The “Prioritized Conformance” panel references all selected libraries. Your library must appears in this panel. To do that, select the library in the “Msg Library Files” panel and hit the “>” button.  Attention, this panel only shows the libraries which have been saved in the directory “MessagingWorkbench_HOME\Lib”.
  • When you have finished, press “OK”.

MWB conf spec

Create the HL7 message profile from the library

If you have some segments which are defined commonly in the TF for the all domain, you may create a specific library which have this definition for the segment.

 

To construct your HL7 message profile :

  • Go to the Menu: File --> New
  • Fill the header of the file. See the example below :
    • Specification: “RGV_O15”
    • Msg Type: “RGV”
    • Event Type: “O15”
    • Ord Cntrl: “”
    • StructID: “RGV_O15”
    • Organization: “IHE”
    • Event Description: “RGV - Pharmacy/treatment give”
    • HL7 version: “2.6”
    • Structure: See the section below to get further information on this field.
    • Status: “DRAFT”
    • Spec Version: “TRIAL”
    • Role: “Sender”
    • Conformance Type: “Constrain”

In the “Structure” field, you must write the structure of your HL7 message. See the example below :

MSH,{[SFT]},[UAC],{[NTE]}[(PATIENT),PID,{[NTE]},{[AL1]}[(PATIENT_VISIT),PV1,[PV2]]]{(ORDER),ORC[{(TIMING),TQ1,{[TQ2]}}][(ORDER_DETAIL),RXO[(ORDER_DETAIL_SUPPLEMENT),{NTE},{RXR}[{(COMPONENTS),RXC,{[NTE]}}]]][(ENCODING),RXE{(TIMING_ENCODED),TQ1,{[TQ2]}},{RXR},{[RXC]}]{(GIVE),RXG{(TIMING_GIVE),TQ1,{[TQ2]}},{RXR},{[RXC]}{(OBSERVATION),[OBX],{[NTE]}}}}

 

MWB Message conf

Then press the COMPILE MESSAGE button (represented by a yellow wheel) which is between the “save file” button and the “+F” button in MWB tool bar.

A message panel should open at the end of the compilation.

You may select all the items and select the “Not Supported” Option. Then hit the “Make Change” button.

This will change in the profile all “Backward” usage by “Not Supported”.

Close the panel.

MWB Usage discrepancy List

Finally, hit the “Save” button to save your project in “MessagingWorkbench_HOME\Projects\Your_Message_Name.mwb”

 

Now, click on the Menu : Tools --> Select Conformance Lib

  • The “Prioritized Conformance” panel references all selected libraries. Your library must appears in this panel. To do that, select the library in the “Msg Library Files” panel and hit the “>” button.  Attention, this panel only shows the libraries which have been saved in the directory “MessagingWorkbench_HOME\Lib”.
  • When you have finished, press “OK”.

Then choose the tab : Display/Reports

  • In the bar tool menu, on the right of the printer button, select “Spec XML” in the list.
  • The generation will run automatically. 

MWB XML generation

At the end of the generation, on the “HL7” button (on the right). A message panel will be appear. Say “NO” and hit the “save” button (on the left). Your HL7 message profile will be saved as an XML file.

If some of the segment used are empty you should add a segment and set the previous library you create for the domain or the default one by HL7 version for example : “MessagingWorkbench_Home/lib/IHE-HL7 2.5.mcf “

 

Make the XSL transform to get a correct profile

The XML file generates by MWB is not correct, and it is necessary to do some transformations. Return to the unzipped folder (See the step 2 of the section "How install Messaging Workbench.") You shoud find a folder named "xslTransformTools".

First at all, you will need to download the Xalan parser at this location: http://xalan.apache.org/index.html

Xalan is an XSLT processor for transforming XML documents into HTML, text, or other XML document types.

We will use Xalan to apply the XSL style sheets to our HL7 message profile. 

 

To copy the xmlfile to his specific profile directory in“Data/Hl7MessageProfiles”, you may:

  1. CREATE all the PATH directories conform to this structure for the message: Actor/Transaction/Message_Profile/profile, table, result, sample, work, done
  2. COPY the file C:\Data\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType.xml in the directory “Data_HOME/Hl7MessageProfiles/Actor/Transaction/Message_Profile/profile” 

Now check you should execute this xsl transform:

  • xsltproc Data_HOME/outils/XsltProfileTransformer.xsl Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType.xml > Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-CorrectGenericError.xml 
  • xsltproc Data_HOME/outils/predicate_transform.xsl Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-CorrectGenericError.xml > Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-PredicateTransform.xml 
  • xsltproc Data_HOME/outils/correction_schema.xsl Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-PredicateTransform.xml > Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-SchemaError.xml 
  • xsltproc Data_HOME/outils/correct_table.xsl Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-SchemaError..xml > Data_HOME\HL7\Message_Profiles\2.3\Transaction\Specification_msgType_eventType-CorrectTable.xml 

At least, replace all  “Usage="B"” in the corrected HL7 message profile by “Usage="X"”.