Creating a Lab Message VMD

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.

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.
    Note: This is the file created in the 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.
    Note: Chameleon is a Windows only program that is bundled with the Iguana for Windows install.
    You should see something like this:
  3. Click the toolbar Message button to create a new message definition:
  4. Rename the message definition to Lab.
    Click on the name twice (slowly) and type in “Lab”:
  5. Double click the 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…:

      This will open the “Import Segments From Library” wizard:
    2. Click Next, select the OBR and OBX segments, click Next and then Finish:

      The OBR and OBX segments should be added to the VMD:
  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:
    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:
      3. Select the Optional check box:

        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. Open the supplied example/demo.vmd (<install dir>\edit\admin\other\example\demo.vmd) in Chameleon.
      Get the example/demo.vmd from the Translator project file pane:

      Then click OK to open it in Chameleon:
    2. Comparing the two message grammars shows that the example/demo.vmd is considerably more complex, but the segments and groups in our file are in the same order (which is important):
  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 need to add the Trigger Event, like this:

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

  10. Save the changes to the VMD file.
  11. Test the demo_lab.vmd file in a project.
    1. Open a basic channel that uses the example/demo.vmd.
      We used our “Mapping HL7 to HL7” channel from the Mapping Messages: HL7 to HL7 tutorial:
    2. Add this Lab message to the sample data:
      MSH|^~\\&|MESA_RPT_MGR|EAST_RADIOLOGY|REPOSITORY|XYZ|||ORU^R01|MESA3b781ae8|P|2.3.1||||||||\r
      PID|||CR3^^^ADT1||CRTHREE^PAUL|||||||||||||PatientAcct||||||||||||\r
      OBR|||||||20010501141500.0000||||||||||||||||||F||||||||||||||||||\r
      OBX|1|HD|SR Instance UID||1.113654.1.2001.30.2.1||||||F||||||\r
      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||||||\r
    3. Add demo_lab.vmd to the project, using the [Add…] link:
    4. Duplicate the hl7.parse{} statement using demo_lab.vmd:
    5. Compare the both versions of the parsed ORU message.
      As you can see the parsing worked with both VMD files:

More Information [top]

Leave A Comment?