Introduction

In this tutorial you will learn how to create a VMD file for an HL7 ADT message.

We will create a file that uses similar HL7 message structures to the demo.vmd files that are included supplied with Iguana. This way you have something to compare to, and you can try it in the basic tutorials.

To create a custom VMD file to match your HL7 message structure, just follow the same steps using your own sample message. Substitute your own message requirements in the steps that copy/compare the supplied message or demo.vmd.

If you have any questions about using Chameleon please contact us at support@interfaceware.com.

Note: The demo.vmd file supplied with different versions of Iguana has changed over the years — so yours may not exactly match the one used here (but it will be similar).

You can download this version of demo.vmd which is the one we use on this page.

Tutorial Instructions [top]

Run Chameleon
For example you can search for “chameleon” in Windows 10:

Note: Chameleon is a Windows only program that is bundled with the Iguana for Windows install.
Close the Chameleon welcome screen.
Create an empty VMD by clicking the New button on the toolbar:
Click Browse to open the Message Browser:

You should see the empty Message Browser window:

Paste this sample HL7 Message into the top pane of the message browser window:
Note: To create a custom Message VMD use your own sample HL7 message instead.

MSH|^~\&|iNTERFACEWARE|Lab|Main HIS|St. Micheals|20110213144932||ADT^A03|9B38584D9903051F0D2B52CC0148965775D2D23FE4C51BE060B33B6ED27DA820|P|2.6|
PID|||4525285^^^ADT1||iNTERFACEWARE^Tracy||19980210|female||EU|86 Yonge St.^^ST. LOUIS^MO^51460||1185438871|8530031194||||10-346-6|284-517-569|
NK1|1|Smith^Gary|Second Cousin|
PV1||E||||||5101^Garland^Mary^F^^DR|||||||||||1318095^^^ADT1|||||||||||||||||||||||||20110213144956|

Tip: You may get this error when you copy a message from the Iguana sample data editor. The solution is to remove the extra backslash at the start of the MSH segment:

Parse the message
Click the Parse button, the result should look like this:
Import the “unrecognized segments”.
1. Click the link to run the segment import wizard:
  
  You should see the import segments wizard:
2. Click the Next button three times to import the segments (using the default settings).
  The segments should change from red to green to indicate that they are now recognized:
  
  Tip: Use the defaults when you are creating a custom VMD from your own message.
Import the “unrecognized message”.
1. Click the link to run the message import wizard:
  
  You should see the create message definition wizard:
2. Choose a suitable Name and Description for the message.
  Enter the following then click Finish:
  - Name: ADT
  - Description: ADT Event
Add the remaining recognized segments to the new message definition.
The message wizard only adds the MSH segment, you need to add all the other message segments manually.
1. Edit the ADT Message Grammar by double clicking on it:
  
  This will open the message grammar dialog:
2. Click and drag the remaining segments into the Segment Grammar pane:
  
  The grammar should now contain all the message segments:
Change the order of the segments to match the HL7 message.
1. Comparing the segment grammar to the sample message, you can see the segments are in a different order:
2. Click and drag the segments into the same order as the demo.vmd:
Change the PV1 segment to optional.
Select the Optional check box:
Change the NK1 segment to repeating and optional.
1. Select the Repeating check box, with 0 for for unlimited repeats:
2. Select the Optional check box:
Compare the new message grammar to demo.vmd.
When using your own message data check that the segments, order, repeats and optionality match your requirements.
1. Open the supplied demo.vmd (<install dir>\edit\admin\other\demo.vmd) in Chameleon.
  Get the demo.vmd from the Translator project file pane:
2. Then click Open to open it in Chameleon:
3. Comparing the two message grammars shows they are the same:
The demo.vmd contains the extra segment EVN that is not being used in the message. Because it is best practice to keep our VMD as simple as possible we will not add the EVN segment.
Here you can see the extra (unused) EVN segment:

Note: Keeping the VMD as simple as possible (minimum number of messages, no unused segments) helps to reduce overheads and improve performance.
Change the Identity settings to match ADT messages for all triggering events.
1. Currently the message identity is set to patient discharges (ADT^A03).
  This is shown in the bracketed description of the Identity:
2. Double click on Identity to open the settings dialog:
3. Remove the second field (trigger event) from the Identity list.
  Click in the grey square at the left of the column to highlight the row:
  
  Then choose Delete Field from the right-click menu (or press the keyboard delete key):
4. The trigger event (A03) should now be removed from the Identity:
Add the Catchall message to handle unrecognized messages.
Note: If you are creating a custom VMD you may prefer another name like “Unknown”.
1. Click Message on the toolbar to create a new message definition:
2. Click on the message name and rename it to “Catchall”:
3. Double click on Identity to open the settings dialog:
4. Click on Change to open the Message Definition Matching Order dialog:
5. Check the box to match all unrecognized messages:
Parsing messages with variable segment order:
We have not selected the the “Disregard Segment Order” option in the message grammar. This means that segments will not be parsed if they in a different order from the message grammar definition.
1. If the segments are in the same order as our new VMD then all segments are parsed:
2. If we change the segment order in the same message then some segments are not recognized:
3. To change this behaviour open the VMD Message Grammar and check the “Disregard Segment Order” option:
4. As you can see our “re-ordered” message is now parsed correctly:
  
  Tip: We generally recommend enabling “Disregard Segment Order” option. If you do not choose this option it is best practice to test for messages with incorrect segment order and raise errors or do other special processing.
Save your new VMD file as demo_message.vmd.
Test the demo_message.vmd file in a project:
1. Create a channel.
2. Add the demo.vmd and the your new demo_message.vmd to other, using the [+]:
  You can download the version of demo.vmd that we use on this page.
3. Add this Lua code:
```
function main(Data)
   -- Parse an HL7 message
   local Msg1, Name = hl7.parse{vmd = 'demo.vmd', data = Data}
   local Msg2, Name = hl7.parse{vmd = 'demo_message.vmd', data = Data}
end
```
4. Comparing both the parsed messages, shows that they both work with our “re-ordered” message:
5. You can change the order of the fields in the parsed message — by changing the segment order in the message grammar:
  This can be used to create an HL7 output message with segments in a different order — this can be useful if you are sending to a (legacy) system that requires a different order from your input messages.
  1. We created a demo_message1.vmd file with a different segment order than demo_message.vmd:
    In this case we simply reversed the order of the the PV1 and NK1 segments.
  2. As you can see order of the the PV1 and NK1 segments is reversed in the parsed messages:
  3. And this is how to create corresponding HL7 (text) output messages:
  4. And this is the code for you to try:
    You will also need to create the demo_message1.vmd and add it to your project.
```
function main(Data)
   -- Parse an HL7 message
   local Msg1, Name = hl7.parse{vmd = 'demo.vmd', data = Data}
   local Msg2, Name = hl7.parse{vmd = 'demo_message.vmd', data = Data}
   local Msg3, Name = hl7.parse{vmd = 'demo_message1.vmd', data = Data}
   
   local Out1 = Msg2:S()
   local Out1 = Msg3:S()
   
end
```

Iguana Documentation

Creating a simple ADT Message VMD

Introduction

Tutorial Instructions [top]

More Information [top]