Creating a Lab Message VMD

Introduction

In this tutorial you will learn how to create a VMD file for an HL7 Lab (ORU) message.

We will start with a simple VMD (similar to demo.vmd) that already contains the ADT and Catchall message grammars. Then we will extend it by adding the Lab (ORU) message grammar, this will give it similar functionality to the example/demo.vmd. This way you can compare it to example/demo.vmd, and you can try it out in the basic tutorials.

Adding a different message to the VMD will follow the same general pattern, just use your own message definition.

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

Lab Message Definition [top]

This message definition is a simplified version of the message grammar from the example/demo.vmd, but it is sufficient to parse the sample Lab message included in our sample data.

Message Identity

  1. Message Type: ORU
  2. Events: All

Message Structure

  1. MSH segment (required)
  2. PATIENT segment group (optional)
    1. PID segment (required)
  3. ORDER segment group (repeating)
    1. ORDER_DETAIL group (optional)
      1. OBR segment segment (required)
      2. OBSERVATION segment group (optional, repeating)
        1. OBX segment

Note: If you are observant you will have noticed that the ORDER_DETAIL segment group is not required (because it is not repeating). Removing the ORDER_DETAIL group would improve the design, by simplifying the structure and still performing the same function.

However the world is not perfect and we are required to follow the specification we have been given (in this case the supplied example/demo.vmd structure). By not changing the design we are able to use the VMD we create as a “drop-in” replacement for the example/demo.vmd in our tutorials (if we had changed the structure it would require code changes when processing Lab messages).

Tutorial Instructions [top]

  1. Download the demo_lab.vmd VMD file:

    This is the file created in the Chameleon: Chameleon: Creating a simple ADT Message VMD tutorial, and does not yet contain the ORU Lab message.

  2. Double click on the file to open it in Chameleon:

    Chameleon is a Windows only program that is bundled with the Iguana for Windows install.

    You should see something like this:
    chameleon view vmd file

  3. Click the toolbar Message button to create a new message definition:
    chameleon new message definition
  4. Rename the message definition to Lab, click on the name twice (slowly) and type in Lab:
    chameleon rename message definition
  5. Double click Lab > Identity and enter “Unsolicited transmission of an observation message” in the Description:
  6. Add the OBR and OBX segments to the VMD:
    1. Choose menu option Workspace>Import Segments From Library…:
      chameleon import message segments
      This will open the “Import Segments From Library” wizard:
      chameleon import message segments
    2. Click Next, select the OBR and OBX segments, click Next and then Finish:
      chameleon import message segments
      The OBR and OBX segments should be added to the VMD:
      chameleon import message segments
  7. Build the message definition to match the Lab Message Definition.
    1. This is the Message Structure definition:
      1. MSH segment (required)
      2. PATIENT segment group (optional)
        1. PID segment (required)
      3. ORDER segment group (repeating)
        1. ORDER_DETAIL segment group (optional)
          1. OBR segment (required)
          2. OBSERVATION segment group (optional, repeating)
            1. OBX segment
    2. Double click the Lab Message Grammar to edit it:
    3. Add the MSH segment, by dragging it into the message grammar pane:
      chameleon add MSH segment
    4. Add the optional PATIENT group.
      1. Right click below MSH in the Segment Grammar pane and choose the Insert Group… menu option:
      2. Type in the group name PATIENT” and click Ok:
        chameleon add group
      3. Select the Optional check box:
        chameleon add group
        Note: If the PATIENT segment is out of order just drag it below the MSH segment.
    5. Add the PID segment by dragging it onto the PATIENT group.
    6. Insert the repeating ORDER group using the right click menu.
      1. Select the Repeating check box, and 0 for unlimited repeats:
    7. Insert the ORDER_DETAIL group.
      1. Right click on ORDER and choose the Insert Group… menu option.
      2. Select the Optional check box.
    8. Drag the OBR segment into the ORDER_DETAIL group.
    9. Insert the OBSERVATION group.
      1. Right click on ORDER and choose the Insert Group… menu option.
      2. Select the Optional check box.
      3. Select the Repeating check box, and 0 for unlimited repeats.
      4. Notice the angle brackets that indicate that <OBSERVATION> is optional & repeating:
    10. Drag the OBX segment into the OBSERVATION group.
    11. The finished Message Grammar should look this:
  8. Compare the new message grammar to example/demo.vmd.
    1. Download this version of demo.vmd for comparison.

      The demo.vmd file supplied with different versions of Iguana has changed over the years — so if you already have one on your system it may not exactly match the downloaded one (but it should be similar).

    2. Double click on the downloaded vmd file to open it in Chameleon.
    3. Comparing the two message grammars shows that the downloaded demo.vmd is considerably more complex, but the segments and groups in our file are in the same order (which is important):
      chameleon compare vmd files
  9. Change the Identity settings to match the Lab Message Definition.
    1. This is the Message Identity definition:
      1. Message Type: ORU
      2. Events: All
    2. Double click on Identity to open the settings dialog:
    3. Set the criteria to match the ORU message type.
      1. Click on the ellipsis (…) in the Segment column and select the MSH segment:
      2. Click on the ellipsis (…) in the Field column and choose the Message Code:
      3. Type “ORU” in Value column:
    4. Set the criteria to match all event.
      1. No action is required, the Identity will match all events by default.

        Tip: To constrain the Identity to only match certain events you would need to add a Trigger Event, like this:

        In this case only the two triggers R01 and R02 (separated by a vertical bar”|”) would be recognized.

  10. Save the changes to the VMD file.
  11. Test the demo_lab.vmd file in a project.
    1. Create a test channel:

      You can also use an existing test channel if you don’t mind replacing the main() module code.

      1. Add the demo.vmd file and the demo_message.vmd files to th eproject, using the [+] link:
        iguana add other files
      2. Paste this code into the main module:
        function main(Data)
           -- Parse an HL7 message
           local Msg, Name = hl7.parse{vmd = 'demo.vmd', data = Data}
           local Msg, Name = hl7.parse{vmd = 'demo_message.vmd', data = Data}
              
        end
      3. The channel should look like this:
        iguana main module code
    2. Add this Lab message to the sample data:
      MSH|^~\&|MESA_RPT_MGR|EAST_RADIOLOGY|REPOSITORY|XYZ|||ORU^R01|MESA3b781ae8|P|2.3.1||||||||
      PID|||CR3^^^ADT1||CRTHREE^PAUL|||||||||||||PatientAcct||||||||||||
      OBR|||||||20010501141500.0000||||||||||||||||||F||||||||||||||||||
      OBX|1|HD|SR Instance UID||1.113654.1.2001.30.2.1||||||F||||||
      OBX|2|TX|SR Text||Radiology Report History Cough Findings PA evaluation of the chest demonstrates the lungs to be expanded and clear.  Conclusions Normal PA chest x-ray.||||||F||||||
    3. Compare the both versions of the parsed ORU message.
      As you can see the parsing worked with both VMD files:
      iguana inspect variables

More Information [top]

Leave A Comment?