• Introduction
• Task
• Procedure
• How it works
• More information

Introduction

This article describes the basic process for creating VMD files and explains how the different sections in a VMD work. A VMD is a framework which Iguana uses in order to understand the structure of an HL7 or EDI message.

Chameleon is a necessary component when writing interfaces as it is the only way to create a VMD file. For this article we will assume that Chameleon is already installed and licensed properly (Chameleon is automatically included when you install Iguana on Windows).

Before you begin creating a VMD, you should identify:

• Which version of HL7 you are using
• Which message type(s) you are using,
• Any non-standard message structure in your HL7 message.

Recommended best practice when creating VMDs are:

• Use one specific VMD for each source or destination system:

  For example if we are parsing an incoming message from vendor “X” and sending it out to vendor “Y” then we should have one VMD for each vendor.

• VMDs should be divided based on the message type:

  So you could have one VMD per vendor for ADT messages, and another for Lab messages.

• VMDs can match all varieties of a message type, or only specific ones, depending on the needs of the project:

  For example a VMD can be made to match all ADT messages, or it could match ADT A08 or A31 only. When creating HL7 messages, always have a message definition for each message type that the workflow can create. For parsing HL7 messages, unless you can ensure that the incoming messages will always be the types of messages that you are expecting, it is always a better idea to all each message types that you expect.

Task [top]

Overview of how to create VMDs using Chameleon.

Procedure [top]

This section shows you how to create a VMD using the

1. Open a fresh project in Chameleon.
2. Import a new message definition
   1. Click Workspace > Import Message Definition From Library.

      This will start up a wizard to import a standard HL7 message definition which can be modified to suit your needs.

      

      Note: If you want to build a message from scratch you can use the Message button on the toolbar. See Creating a Lab Message VMD for an example that shows how to add a Lab Message to an existing VMD.

      

3. Give the message a descriptive Name:

   This is how the message will be called from code in Iguana. Note that the name can also be changed later if required.

   

4. Select the HL7 version that you will be using, then click Next:

   You can also choose to import a VMD message from another VMD — this could be useful if you already have a similar VMD that you can modify.

   

5. Select the Message Type, then click Next:

   If the message that you are looking for is not in the list then there is a good chance that the version of HL7 you’ve selected does not support the message type that you are looking for. If this happens then stop and make sure that you are using the correct HL7 version.

   

6. Click Finish to complete the wizard.
7. Now you will notice that there is a message definition present under the name you’ve supplied:

   There are two parts that are important here: the Message Grammar section, and the Identity section. See How it works below for more information about the Message Grammar, and the Identity sections Notice that there are several related message definitions this is a common practice.

   

   Note: The third section Transformation Script can be ignored — it is a legacy feature that is never used in Iguana.

8. Create the Catchall message:

   This message will be responsible for catching any unidentified message types. So if the channel is supplied with any message type that is not specified in the VMD, it will be caught and can be dealt with appropriately.

   1. Click Workspace > New > Message Definition in order to add a new Message Definition:
      
   2. Alternatively click the Message button on the toolbar:
      
   3. Now open up the Identity and give your message the name Catchall:

      This message is intended to catch all other messages that are not matched by any previous message definitions. We strongly recommend calling it Catchall as this has been used historically (though “other” or “unmatched” would reflect the intention equally well).

      

   4. Click the Matched > Change button:
      
   5. Check the option to Make last definition match any message.

      Here you can also reorder the message definitions, but we don’t need to as we want Catchall to be last.

      

   6. Now you Identity will look like this:
      
9. Add any further message types that you need to process:

   Make sure that the Catchall message remains as the last item in the Matching Order.

10. Save your VMD using a descriptive name and it is ready to use.

How it works [top]

A VMD file contains one or more Message Definitions. Message Definitions are composed of Segments or Segment Groups. Segments use Composites as data types, Composites use Composites as data types.

This structure allows nesting of structures for HL7 definitions:

• HL7 Segment Groups: Map to Groups
• HL7 Segments: Map to Segments
• HL7 Elements: Map to Fields (within a Segment)
• HL7 Components: Map to Composites (segment field data type)
• HL7 Subcomponents: Map to Composites (composite field data type)

Message Definition:

A Message Definition corresponds to one or more HL7 (or EDI) message types. You can import standard Message Definitions for HL7 using the included libraries for HL7 versions 2.1 to 2.7. You can also create your own custom Message Definitions if required. A VMD file can contain one or more Message Definitions.

A Message Definition is composed of three parts:

• Message Grammar:  This describes the structure of the message.
• Identity: This corresponds to an HL7 message type.
• Transformation Script: This is a legacy feature that is not used with Iguana.

Message Grammar:

The Message Grammar section shows you what Segments are present in the message and in which order, as well as if they are optional or repeating. In addition each segment can be opened and edited to suit you needs. To make a segment repeat indefinitely select the repeating option for it and set it to 0 repeats.

Here is is an OBX Segment in the Admit message — with unlimited repeats:

And this is the structure of the OBX Segment:

Segments and Composites:

It is possible to create your own Segments or Composites. Composites are used as the Data Types for the fields in a Segment or another Composite. Using a Composite as a (nested) Data Type in another Composite is what allows us to have (nested) sub-fields.

In most cases you will not have to create your own Segments or Composites or make changes to them. The main thing that would be modified here is the Required value or the Repeat value. To make something repeat indefinitely here, the value of -1 is used.

This is the PID (Patient Identification) Segment from the Admit message:

An example of a Composite is XPN, which is used in the Patient Name component PID-5.

And this is the XPN Composite structure:

Composites are what allow us to have sub-fields, like PID-5.1 (Family Name) for example — which is also a Composite of type FN.

And this is the FN Composite structure:
Note: There is no further nesting as all simple ST (string) Composite types are used.

This is the SH (string) Composite:

Identity:

The Identity allows Iguana to identify which type of message is being supplied.

This works by setting the first value MSH-9.1 to the message class (ADT,ORU,ORM etc), and MSH-9.2 to the message type (A01,A02,… A62) . If you do not specify the message type (MSH-9.2) then it will match all ADT values. If you have imported a message from the HL7 library then this will come preloaded with the appropriate values.

For example the ACK message matches all ACK messages and Admit message matches ADT-A01 (Admit):

Catchall:

For error handling purposes it is important to handle any unexpected messages types that your channel might process. The best way to do this is to use a “general” Message Definition that will match any message. When an unknown message arrives it will match the “general” definition and you can take the appropriate action (like making a log entry etc.). We recommend using the name Catchall for this “general” message definition — as this is what we have always called this message historically.

The Catchall message requires the following:

• The Make last message definition match any message option must be checked

  This forces the last Message Definition to match any messages not matched by the earlier definitions in the Message Definition Matching Order.

• It must be the last message in the Message Definition Matching Order:

  Iguana processes Message Definitions in the order specified in the Message Definition Matching Order dialog. Therefore you want the Catchall definition to be last so all other definitions are tried first.

This is how the Message Definition Matching Order dialog should look:

And this is how the Catchall identity definition looks:

More information [top]

• The Chameleon reference section
• The Chameleon FAQs section
• The Chameleon TIPs section
• Features Disabled in Chameleon Toolkit after Chameleon 6.0