Understanding VMD Files
Contents
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.