Examining the VMD structure
Contents
On this page we will show you how to examine the structure of a VMD file, using Chameleon. We also describe the best practice for the structure of a VMD file to use with Iguana.
Before You Start
If you are creating a VMD file to use with db.tables{} and conn:merge{}, the best practice is to define only one message and create one instance of every table that you might want to map data into. We also recommend that you use separate VMD files for the source and target databases (this is particularly helpful when you are mapping multiple source databases to a single target database). Decisions as to what rows to populate, and with what data, will be made using Lua code in the Translator. This keeps the VMD file for out target database very simple, just a few table definitions, nothing else is needed.
Note: Because VMD files were used historically with Chameleon they contain many features that are not used by Iguana. These legacy features are not discussed as you will never use them with Iguana.
How It Works
The top-level object in a VMD file is a Message Definition that represents an HL7 event. Each message definition has its own Table Grammar defined, which consists of the tables that data from the message is mapped into or out of.
These are minimum requirements for a VMD to map to a database:
- Table definitions for the tables that you will map to
- A message definition containing only those tables
Note: If you were creating a VMD to parse an HL7 message the message definition would need to contain the HL7 message structure, but according to our best practices (above) this should be in a separate VMD (so it is not included).
Here’s an example of a simple VMD file that follows our recommended best practice: tables.vmd. , and here is how to create the tables.vmd file from scratch using Chameleon.
When you open this file in Chameleon, you will notice one message definition and two table definitions:
Notice that the only things defined are two Tables and a Message Definition.
If you double-click a Table definition, you can display the columns that are defined for each table:
The VMD file also contains a Message Grammar that associates the Table definitions with the Message definition. To view this double-click the Message Grammar link in the Message definition:
A Message Grammar window appears:
The Message Grammar panel indicates that the Person and Relationship tables are associated with the Message definition.
You do not need to worry about the red error icons next to the table names, as they relate to a legacy feature that is not used by Iguana.
The Segment Grammar panel is empty because this VMD will not be used to parse HL7 messages. Remember it is best practice to separate source and target mappings, so if the source is an HL7 message it should be defined in a separate VMD.
Additional Information?
We showed you how to use the examine the a VMD file, and described the best practice for the structure of a VMD file to use with Iguana. We also showed you how create the tables.vmd file from scratch using Chameleon.
For more information see these links: