Understanding VMD Files

Understanding VMD Files

In the Iguana Translator, two built-in functions use a VMD file when processing incoming messages:

  • hl7.parse() uses the VMD file to parse the messages;
  • db.tables() uses the VMD file to determine what database tables to create.

To understand how the hl7.parse() function uses the VMD file to parse incoming messages, use Chameleon to open the demo.vmd file that the mapping script is using.

Tip: The demo.vmd file that this example uses is already included with the Iguana Translator. It is located in a directory named other in the Iguana Translator’s source code repository.

To access this file from the mapping script, position your cursor over the arrow next to the demo.vmd entry in the other section of the Project Manager panel. A popup menu appears:

Click Get to open demo.vmd.

You can also examine demo.vmd in Chameleon by following this link: demo.vmd

The three message definitions that are defined in this file – ADT, Lab and Catchall – are displayed in the workspace at the left of the Chameleon window:

Each message definition has an Identity defined for it. This determines what messages are to be processed by this message definition. To view the Identity for the ADT message definition, click its Identity link:

An Identity window appears:

Here, the Segment column indicates that the segment to be examined is the MSH segment. The Field column indicates that the first subfield of Field 9 of the MSH segment is to be examined. The Value column indicates that the message is processed if this subfield has the value ADT.

Tip: When you are creating a VMD file to be used by a Iguana Translator mapping script, and you are creating an Identity for a message definition for this VMD file, the Identity does not need to be too specific. For instance, specifying an Identity that matches the first subfield of Field 9 is usually sufficient. (In this example, this is ADT.)

If you are expecting to process two types of messages with the same message code (for example, ADT^A04 and ADT^A31), you can use the Iguana Translator mapping script to distinguish one type of message from another. You do not need to define a separate definition for each message type.

Each Message Definition also contains instructions for how a message that matches its Identity is to be processed. This set of instructions is called the Message Grammar. Each Message Grammar consists of two parts: the Segment Grammar, which indicates the segments that the vmd file is expecting the message to contain, and the Table Grammar. You will only need to look at the Segment Grammar.

To view the Segment Grammar for the ADT message definition, click its Message Grammar link.

A Message Grammar window appears, with the Segment Grammar displayed in the left panel of the window:

The Segment Grammar lists the segments that the ADT message definition is expecting its messages to contain. Segments whose type is enclosed in brackets [] (for example, [PV2]) are optional, and segments enclosed in angle brackets <> (for example, <OBX>) are repeating (may occur zero or more times). All segments not listed in the Segment Grammar are ignored if the Ignore segments not in grammar check box is selected.

The Segment Grammar may contain any number of segment groups. Each segment group consists of one or segments that are grouped together. In the Segment Grammar shown above, a segment group named PROCEDURE is defined. This segment group contains one PR1 segment and zero or more ROL segments.

Segment groups, like segments, can be either optional (enclosed in brackets []) or repeating (enclosed in angle brackets <>). In this example, both the PROCEDURE and INSURANCE segment groups are repeating, which means that they may occur zero or more times.

Tip: Chameleon uses the Table Grammar when it is mapping from message fields to database tables. Since you will be using the Iguana Translator mapping script, not Chameleon, to perform this mapping, you can ignore the Table Grammar.

To understand how db.tables() uses the VMD file to create the database tables to be mapped to, take a look at the Tables section of the Workspace panel of the demo.vmd file:

In this VMD file, two tables are defined: kin (for next-of-kin data) and patient (for patient data). These are the tables that db.tables() creates when it is called.

To view the fields defined in a table, click its entry in the Tables section to display a Table window. For example, here is the Table window for the patient table:

The Column Name column lists the fields that are defined in this table. The mapping script populates some or all of these fields with data mapped from the incoming message.

Examining the VMD structure [top]

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.

Creating the tables.vmd file using Chameleon [top]

This page shows you how to create our tables.vmd file from scratch, using Chameleon

  1. Run Chameleon, you should see an empty VMD, like this:
    If you don’t see a new empty VMD just click the New button to create one.
  2. Add the Person and Relationship tables
    • Right click on Tables and select New Table from the menu:

      “Table0” will be created:
    • Click on “Table0” and rename it to Person:
    • Enter the Person table definition as shown:
    • Repeat the same steps for the Relationship table, it should look like this:
  3. Create the Message Definition
    • Right click on Message Definition and select New Message Definition from the menu:

      “Message1” will be created
    • Click on “Message1” and rename it to Message:

      Note
      : You could use a more descriptive name (but our example uses the name “Message”, so we will use the same)
    • Double click on on Message Grammar to open the editing dialog
    • Add the Relationship table to the Message DefinitionClick on Insert Table:

      Select the Relationship table:
    • Repeat for the Person table
    • The Message Grammar should now look like this

      You can safely ignore the “Grammar root is not set” error, and the red (!) error
  4. Save the file as tables.vmd and you are done

Using Multiple VMD files [top]

Using multiple VMD files in a single channel is a useful technique for separating different uses of VMD files. For example you may want to use one VMD for messages and and another for database table structures, or you can use two VMD files to map to two different databases.

Use different VMD files for message and table mapping

We recommend using different VMD files for the message structure and the table mapping. It is best practice to use different VMD files to separate the message structure (VMD Message Grammar) and the database table mappings (VMD Table Grammar).

Many organizations need to map various different HL7 messages to a single database. Generally it is best practice to structure code to reflect business process. By using a separate table schema VMD and multiple HL7 messages VMDs (one for each message type) we create a structure that better reflects what the organization does. Also if some messages use different versions of HL7 you can tailor the VMDs to use that specific version of HL7.

How it Works

This example code uses the same VMD file for hl7.parse() and db.tables():

The resulting code would look something like this:

Using multiple VMD files to map to different databases

Another scenario would be migrating from a legacy system, in this case you have multiple databases and multiple messages. This example shows a single message mapped to two databases using a separate VMD file to map to the legacy system.

An example of the power and flexibility of Iguana is that you can use different VMD files for hl7.parse() and db.tables(). In fact we recommend it as best practice to use different VMD files to separate the message structure (VMD Message Grammar) and the database table mappings (VMD Table Grammar) – particularly for more complex systems.

If you are introducing a new system and phasing out a legacy system with a different database structure you could use a second VMD file to map to the legacy system. This could all be achieved in a single channel with multiple calls to db.tables() and conn:merge().

This is the mapping for the new system:

This is the mapping for the (fictional) legacy system, which has a very dodgy database structure:

There are two conn:merge{} calls one for each database:

When the legacy system is no longer needed you can simply remove (or comment out) the second conn:merge{} call. If you like clean code like me you can remove every legacy reference, and still revert at anytime using the Iguana milestones.

This is not intended as a recipe, it is intended to hint at the potential of what you can do with Iguana when you start to think outside the box. I certainly find it to be a revolutionary product, I have not used anything else that combines such power, flexibility and ease of use.

Use Iguana to create database tables from vmd file definitions [top]

The Importing table definitions directly into the vmd file page describes how to import table definitions from a database into a vmd file. You can also go the other way: from the Translator, you can create tables in a database, by using table definitions from a vmd file.

How It Works

To create database tables, do the following:

  1. From the Translator, in the other folder, locate the name of the vmd file that you want to use to create the database tables. Position the cursor over the arrow next to the name. A popup menu appears:
  2. From this popup menu, select Create DB Tables. An Export Tables screen appears:

    Note: If MySQL is not available in Windows you will need to add the MySQL install directory to the Windows PATH variable, see Making the MySQL Database Option Visible in Windows.

  3. From the Database API list box, select the database API to use.
  4. In the Database field, type the name of the database.
  5. In the Username field, type the username to use when accessing the database.
  6. In the Password field, type the password to use when accessing the database (if needed).
  7. Click Preview Create Statements. The SQL statements that will be executed are displayed in the Preview Results/SQL Statements panel:
  8. Examine these statements. If they are correct, click Execute Statements. The results of the executed statements are displayed in the Execute Results panel.
  9. Click Close to close this window.

Importing table definitions directly into the vmd file [top]

One of the easiest ways to get table definitions into a Chameleon vmd file is to import them directly from a database.

How It Works

To import table definitions from a database, perform the following steps:

  1. Start Chameleon.
  2. From the Workspace menu, select Import Tables From Database. The Database Table Importing Wizard appears:
  3. From the Database API list box, select the API for your database.
  4. From the Data Source list box, select the data source to use.
  5. In the User Name field, type the user name that you use to access the database.
  6. In the Password field, type the password for your user name (if needed).
  7. Click Next. The wizard will attempt to access the database. If it is successful, the Database Table Importing Wizard window displays a list of the tables defined in the database:
  8. Select the tables that you want to import. When you select a table, all columns are imported by default. If you only want to import some of the columns, unselect the columns that you do not want.
  9. When you have finished selecting tables, click Next.
  10. Click Finish to confirm that you want to import the tables.

The tables are now added to the VMD file.

Creating a Custom VMD File For ACK Verification [top]

If you are creating a channel whose destination component is LLP Client, and you have selected Verified ACK Message from the ACK verification list box to indicate that you want to verify the acknowledgment message, you can create a custom VMD file that specifies how acknowledgment verification is to be performed.

The easiest way to do this is to make a copy of the ack_verify.vmd file that is included with Iguana and then change it to perform the acknowledgment verification that you want. To do this:

  • Copy the ack_verify.vmd file from the directory in which Iguana is installed to another location on your system. Or, alternatively, leave the copy of ack_verify.vmd in the directory in which Iguana is installed and rename it.
  • Using Chameleon, open the VMD file copy that you have just created.
  • In the Workspace, double-click the MSH table. This table contains a list of the fields to be matched during the verification process:

In this table, add the fields that you want to use to perform additional verification. For example, if you want to ensure that the Receiving Application field (the fifth field of the MSH segment, also referred to as MSH.5) of the original message matches the Sending Application field (MSH.3) of the acknowledgment message, you can add a ReceivingApplication field to the MSH table in the VMD file:

  • In the Workspace, locate the ACK (Acknowledgment) message definition, and double-click Message Grammar.
  • In the Table Grammar panel, double-click MSH. The Table Mapping window appears.
  • In the Table Mapping window, click the (ellipsis) button at the bottom right (next to the Grammar Root list box). The Grammar Root Selection window appears.
  • In the Grammar Root Selection window, select Message. Click OK to close this window.

    Note: By default, the grammar root for the ACK message definition’s table grammar is the MSA segment. If the additional fields that you are using for ACK verification are contained in the MSA segment, you do not need to change the grammar root for the ACK message definition.

    The example outlined in this section uses the Receiving Application and Sending Application fields for additional verification. Since these fields are in the MSH segment, the grammar root must be changed to allow mapping from fields other than the MSA segment.

  • In the Table Mapping window, locate the segment containing the field that you want to use for verification and expand it. Drag the field from the right panel to the Mapping column of the table. Repeat if necessary.

  • In the Workspace, locate the Default message definition, which matches the original message that was sent. In this message definition, double-click Message Grammar. The Message Grammar window appears.
  • In the Message Grammar window, in the Table Grammar panel, double-click MSH. The Table Mapping window appears.
  • In the Table Mapping window, from the right panel, which lists all of the fields in the MSH segment, expand the segment and locate the field that you want to use for verification. Drag the field from the right panel to the Mapping column of the table. Repeat if necessary.

Note: In the Default message definition, the grammar root is the MSH segment. Since, in most cases, the fields that you will want to use for ACK verification can be found in this segment, you normally do not need to change the grammar root. However, if you want to use a field from another segment as part of your ACK verification, you can set the grammar root for this table grammar to be the entire message by following the procedure described above for the ACK message definition.

  • In the main Chameleon window, from the File menu, select Save to save your file.
  • In Iguana, edit your channel. In the Destination tab of the channel, update the ACK VMD path field to specify the location and file name of the VMD file that you have just created.

Your channel will now perform the ACK verification that you have specified in this file. ACK verification consists of the following steps:

  • The acknowledgment message is processed by the ACK message definition, and the values of the fields specified in the ACK message definition’s Table Mapping window are retrieved.
  • The original message is processed by the default message definition, and the values of the fields specified in the default message definition’s Table Mapping window are also retrieved.
  • Each retrieved value from the original message is compared to its corresponding value in the acknowledgment message. If all corresponding values match, the acknowledgment message is considered successfully verified.

Additional Information?

Leave a Reply