Viewing a VMD file

Introduction

In this article we will show you how examine the contents of a VMD file, using Chameleon. In this tutorial we will inspect the demo.vmd that is bundled with the Iguana install, but the same procedure applies for any VMD file.

These are the steps:

  1. Preparation: Use a copy of Iguana running on a Windows machine (or virtual machine)
    • Note: Chameleon is a Windows program that is bundled with the Iguana install
  2. Open the VMD using Chameleon
  3. Examine the VMD structure

This tutorial only addresses the last two steps. See our installation section if you need to install Iguana (and Chameleon) on a Windows machine

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

Tutorial Instructions [top]

  1. Open the VMD file from within Iguana.
    1. Open any channel that uses demo.vmd, for example Mapping HL7 to HL7.
    2. Hover over the small “arrow” to the right of the demo.vmd and choose Get from the menu:
      get VMD
    3. Choose the Open option to open the file with Chameleon:
      open VMD
    4. Alternatively you can download the demo.vmd file and open it from file explorer:
      demo.vmd
    5. The file will open in Chameleon, you should see something like this:
      chameleon
  2. The three most important Configuration sections to look at are:
    • The messages defined in Message Definitions
    • The table structure defined in Tables
    • The Message Grammar for each message
      message grammar
  3. Message Definitions: There are three messages defined in this VMD:
    • ADT which matches HL7 ADT messages (matches messages with MSH.9.1 set to ADT)
    • Lab which matches HL7 ORU (lab) messages (matches messages with MSH.9.1 set to ORU)
    • Catchall to “catch” any unrecognized messages (matches everything else)
      message definitions
  4. Tables: There are two tables defined in this VMD:
    • patient for storing patient demographic information
    • kin for details of relatives to the patient
      VMD tables
  5. Double click on the patient table to view its structure:
    VMD patient table
    Note: These table structures are used by Iguana when creating database tables.
  6. Double click the ADT Message Grammar to inspect it.
    The most important parts are:

    • The Segment Grammar that defines the structure of the message
    • The Table Grammar that shows the tables for the message
      VMD segment and table grammar

      Note: You can safely ignore the red (!) errors on the tables in the Table Grammar as they refer to a legacy VMD feature than is not used with Iguana.

  7. Double click the PID segment in the Segment Grammar to view the definition of its structure:
    VMD PID segment structure definition
    Note: You can also find and view the PID segment in the Segments section below the Tables.
  8. Examine the Identity matching rules.
    • The ADT message Identity is checked first and matches messages with MSH.9.1 set to ADT
    • The Lab message Identity is checked second and matches MSH.9.1 set to ORU
    • The Catchall message Identity is checked last and matches all other messages
    • Double click the Identity for ADT, Lab and Catchall to view the settings:
      VMD identity
  9. Using the hl7.parse{} and hl7.message{} functions with the messages defined in the VMD
    • The hl7.parse{} function creates a node tree that matches the Segment Grammar for the message type it receives, in this case one of: ADT, Lab or Catchall
    • The hl7.message{} function creates a node tree that matches the message type specified in its name parameter, for example:
      • hl7.message{vmd = 'example/demo.vmd', name = 'ADT'} will create an ADT node tree that corresponds to the Segment Grammar for ADT (that we saw above)
    • View the Lab Message Grammar, and you will see that it has a different Segment Grammar structure to ADT
    • View the Catchall Message Grammar, and you will that the Segment Grammar only contains the MSH (message header) segment
  10. Using the db.tables{} function with the messages defined in the VMD
    • The simplest way to update a database in the Translator is to use the merge functionality:
      • Create a table node tree using db.tables{}
      • Map data to the table node tree
      • Merge the data into the database using conn:merge{}
    • The db.tables{} function will create the tables that are specified in the Table Grammar for the message, for example:
      • db.tables{vmd = 'example/demo.vmd', name = 'ADT'} creates the tables patient, kin and visitinformation (as we saw in its Table Grammar above)
    • View the Lab Message Grammar, there are two tables patient and kin in the Table Grammar, so its table node tree would contain these two tables
    • View the Catchall Message Grammar, there are no tables, so it cannot be used to create a table node tree
  11. The other three Configuration sections (Segment, Composites and Date Time Formats) are only used when creating a new VMD, and are beyond the scope of this tutorial.
    VMD Segment, Composites and Date Time Formats

More Information [top]

Tagged: