Chameleon: Creating a simple ADT Message VMD

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.

Tutorial Instructions [top]

  1. Run Chameleon
    For example from the Windows 7 start menu:

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

    You should see the empty Message Browser window:
  5. 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:

  6. Parse the message
    Click the Parse button, the result should look like this:
  7. 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.

  8. 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
  9. Add the remaining recognized segments to the new message definition.
    Note: 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:
  10. 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:

  11. Change the PV1 segment to optional.
    Select the Optional check box:
    Screen Shot 2014-11-25 at 18.18.50
  12. 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:
  13. Compare the new message grammar to demo.vmd.
    Note: 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:

      Then click OK to open it in Chameleon:
    2. Comparing the two message grammars shows they are the same:
  14. 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.
  15. 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:
  16. 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:
  17. Parsing messages with variable segment order.
    1. For example if we change the segment order in the same message.
      In the original message all segments are parsed correctly:

      However when we move the PV1 segment (the last in the VMD) into the second position, then all other segments are not recognized:
    2. To change this behaviour open the VMD Message Grammar and check the “Disregard Segment Order” option:
    3. 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.

  18. Save your new VMD file as demo_message.vmd.
  19. Test the demo_message.vmd file in a project.
    1. Open a basic channel that uses the demo.vmd (or example/demo.vmd)
      We used our “Mapping HL7 to HL7” channel from the Mapping Messages: HL7 to HL7 tutorial:
    2. Add demo_message.vmd to the project, using the [Add…] link:
    3. Duplicate the hl7.parse{} statement using demo_message.vmd:
    4. Compare the both the parsed messages.
      As you can see the parsing worked with both VMD files:

      Tip: The order of the NK1 and PV1 segments is reversed, this is because the segment order is reversed in the VMD files. If you try the demo.vmd file it will produce the same order as demo_message.vmd.

      Note: The reversed order makes no difference in code as the segments are always specified by name, e.g., Msg.PID[19], Msg.PV1[2], Msg.NK1[1][1] etc.

More Information [top]