####### ![](media/image1.png){width="5.5569444444444445in" height="4.167361111111111in"} {#section .unnumbered}

#######  {#section-1 .unnumbered}

#######  {#section-2 .unnumbered}

#######  {#section-3 .unnumbered}

#######  {#section-4 .unnumbered}

#######  {#section-5 .unnumbered}

#######  {#section-6 .unnumbered}

#######  {#section-7 .unnumbered}

#######  {#section-8 .unnumbered}

#######  {#section-9 .unnumbered}

**Table of Contents**

[1 Background 3](#background)

[2 Installation 4](#installation)

[2.1 Download 4](#download)

[2.2 System Requirements 5](#system-requirements)

[2.3 Installing Message Maker 5](#installing-message-maker)

[2.4 Running Message Maker 6](#running-message-maker)

[3 Overview of Message Creation 6](#overview-of-message-creation)

[4 Initialization 7](#initialization)

[4.1 Selecting a Profile 7](#selecting-a-profile)

[4.2 Test Options 8](#test-options)

[4.2.1 Predetermined Message Generation Sets
8](#predetermined-message-generation-sets)

[4.2.2 Select the Number of Messages to Create
9](#select-the-number-of-messages-to-create)

[4.2.3 Customize Message Creation 9](#customize-message-creation)

[4.2.4 Customized Message Creation at the Element Level
11](#customized-message-creation-at-the-element-level)

[4.2.5 Message Generation Characteristics
14](#message-generation-characteristics)

[4.3 Data File and Configuration 14](#data-file-and-configuration)

[4.3.1 Data Files 14](#data-files)

[4.3.2 MSH Segment Data Initialization
17](#msh-segment-data-initialization)

[4.3.3 Table Data Initialization 18](#table-data-initialization)

[4.3.4 Data Configuration Panel 18](#data-configuration-panel)

[4.4 Data for Z Segments 21](#data-for-z-segments)

[4.5 Identifying Elements with Missing Data Values
23](#identifying-elements-with-missing-data-values)

[5 Message Generation 23](#message-generation)

[5.1 How Message Elements are Populated with Data
23](#how-message-elements-are-populated-with-data)

[6 Message Browsing and Editing 25](#message-browsing-and-editing)

[6.1 Viewing Previously Generated Messages
27](#viewing-previously-generated-messages)

[7 Message Management: Creating HL7 Batch Files
27](#message-management-creating-hl7-batch-files)

[8 General Configuration Options 29](#general-configuration-options)

[9 Appendix A: Message Maker Version 1.4 Limitations
30](#appendix-a-message-maker-version-1.4-limitations)

[10 Appendix B: Trouble Shooting 30](#appendix-b-trouble-shooting)

[11 Glossary 31](#glossary)

#######  {#section-10 .unnumbered}

#######  {#section-11 .unnumbered}

####### Message Maker User's Guide {#message-maker-users-guide .unnumbered}

######## Message Maker Version 1.4 {#message-maker-version-1.4 .unnumbered}

########  {#section-12 .unnumbered}

Robert Snelick

Len Gebase

Sydney Henrard

National Institute of Standards and Technology

messagemaker@nist.gov

####### Preface {#preface .unnumbered}

The Message Maker Project is a collaborative effort between the National
Institute of Standards and Technology (NIST) and the Health Level 7
(HL7) Standards Consortium. NIST is directing its efforts towards the
development of a conformance-testing tool that automatically generates
test messages for HL7 message profile specifications. The messages can
be used to test systems for conformance to a given profile. Message
Maker is public domain software and is freely available. Message Maker
is a work-in-progress, as such, not all planned functionality is
implemented. This release is intended as a prototype; feedback on its
design, feature set, and usefulness is welcomed. This User's Guide
provides an introduction on how to install and use the tool. Send
comments and questions to messagemaker@nist.gov.

# Background

HL7 is an *application-level messaging standard* for the healthcare
industry and defines the interfaces that allow centrally located and
distributed information systems to communicate. HL7 establishes the
rules for building interfaces and provides many optional features to
accommodate the disparate needs of the health care industry. However,
for interfaces to be implemented, a precise and unambiguous
specification must be defined. Message profiles define processing rules
and, by defining exactly which of the optional elements allowed by the
standard that a message might include, provide an unambiguous XML
description of HL7 messages. Tools, such as the Messaging Workbench
(MWB), have been developed to help in the construction of message
profiles. Interfaces modeled by a message profile need to be tested to
ensure that they have been implemented correctly. Current practice
involves meticulous by hand debugging of implementations as problems
arise. Test message suites and the tools to create them are needed.
Message Maker is a tool that is designed to automatically generate test
messages.

Message Maker dynamically constructs HL7 messages while parsing a
message profile. Data values for the primitive elements (i.e., Field,
Component, and SubComponent) defined in the profile are obtained from a
number of data sources. These include the NIST developed database of HL7
primitive data items, HL7 tables, user tables, external tables, local
tables, example values from the profile, and default values.
Alternatively, data can be extracted from a site-specific database
(*this feature is not yet implemented*).

######### Figure 1. Overview of Message Maker Process {#figure-1.-overview-of-message-maker-process .unnumbered}

Message Maker creates test messages for a given HL7 profile. The
messages can be valid or invalid and contain variation from message to
message. An example of an invalid message is a missing data item for a
required field. A number of test parameters control the variation in the
construction of a message. These may include segment and field
cardinality, the usage of certain primitive fields, value sets, data
content, and more. Data content variation is achieved by randomly
selecting items from the HL7 items database.

The core engine of Message Maker generates messages in XML. These
messages can be subsequently transformed into the HL7 ER7 format. Figure
1 depicts a functional overview of Message Maker. Processing is XML
based. Profile generation tools, such as MWB, export message
specifications as XML documents. Data sources, converted into XML files,
along with the profile are used by the XSL transformation generation
engine to create the test messages. Metadata is recorded for each
message. The metadata provides information on the purpose of the test
messages. Later stages of this project will include a testing framework
that will utilize these messages to examine the behavior of HL7
implementations.

# Installation

## Download

Message Maker can be downloaded at <http://www.nist.gov/messagemaker>.

You can download either a self-installing executable jar or the entire
software bundle that includes the source code. Choose the
self-installing executable if you just plan on using the tool. The
generic file name of the installer is *maker_install_n.n.jar*, where
*n.n* represents the version number.

## System Requirements

Message Maker uses Java and XML technologies. The following software is
required:

-   Java 2 SDK (Version 1.4.2 or later)

Note that the self-installing executable is a jar file, so the Java 2
SDK needs to be installed in order to run it.

Message Maker has been tested on Windows, Linux, and MAC platforms. The
following operating systems are supported:

-   Windows XP

-   Windows 2000

-   Linux Redhat 9.0

-   MAC OS 10

Since Message Maker is Java based, it is likely that the software will
run on other system configurations, however they have not been tested.

## Installing Message Maker

Double-click on the installer's icon to run the self-installing
executable to unpack and install the Message Maker software. Then follow
the instructions the installer provides---they are self-explanatory.
Upon successful completion, you should see the MessageMaker.exe (in the
*maker bin* directory under your chosen install directory) and the
desktop short-cut icon
![](media/image2.png){width="0.16666666666666666in"
height="0.16666666666666666in"} if you requested one. Note that the file
to run on Unix based systems is MessageMaker.sh. When done with the
installation, you can delete the download file to recover disk space.

**Windows Troubleshooting:** **Installer won't execute.**

The *installer* may not execute if the jar file does not have the proper
file type association. One instance where this may occur is when you
upgrade your java SDK version. First check to see that the *installer*
is an *executable jar file* by examining its properties. If it is and
still doesn't work, ensure that the proper execution instructions are
associated with the file type. Below gives the steps for Windows 2000.
*Similar steps* apply for other versions of Windows, including Windows
XP.

In the *Window's File Explorer*, select the "**Folders Option ...**"
item from the "**Tools**" menu. Then select the "**File Types**" tab.
Check to see if there is a "*JAR*" extension with an "*Executable Jar
File*" File Type in this list.

If it is not present:

-   Select "**New**" and enter "***Jar***" for the file extension.

-   Select the "**Advanced"** button and enter "*Executable Jar File*"
    in the text field at the top of the dialog

-   Select "**New**". Enter "*Open*" under Action: and enter

> "*C:\\j2sdk1.4.2_06\\bin\\javaw.exe" -jar \"%1\" %\** (substitute the
> location of the *javaw* executable on your system) under
> "**Application used to perform action**"

-   check the "**Use DDE**" box and enter the following in the text
    fields:

> **DDE Message:**
>
> **Application:** *javaw*
>
> **DDE Application:**
>
> **Topic:** *System*

If it is present:

-   Confirm that it "Opens with" *javaw*. If not, select the **Change**
    button to launch the "**Open With**" dialog. Choose "**Other**" and
    navigate to the location of your Java installation (e.g.,
    *C:\\j2sdk1.4.2_06\\bin*) and then select "*javaw*".

-   Select "**Advanced**" and enter the string "*Executable Jar File*"
    in the text field at the top of the dialog.

-   Under the "**Actions"** box, enter "*Open*" and make sure the
    "*Confirm open after download box*" is checked.

-   Select "**Edit**" and enter the following test for these fields:

> **Action:** Open
>
> **Application used to perform action:**
> C:\\j2sdk1.4.2_06\\bin\\javaw.exe -jar \"%1\" %\*
>
> **Use DDE:** (confirm this box is checked)
>
> **DDE Message:**
>
> **Application:** javaw
>
> **DDE Application:**
>
> **Topic:** System

Note that in some cases it is easier to remove an existing Jar file type
association and start with a new one.

## Running Message Maker

To run Message Maker double-click on the
![](media/image2.png){width="0.16666666666666666in"
height="0.16666666666666666in"} desktop short-cut icon or run the
*MessageMaker.exe or MessageMaker.sh* file in the directory where
Message Maker was installed.

# Overview of Message Creation

Below the basic steps to create messages for a given profile are listed.
The user can specify the number of messages to generate and give Message
Maker complete control over the set of messages that are generated. Or,
alternatively, the user can select specific options for controlling the
types of messages that are generated.

**Overview of the Message Creation Process:**

**Initialization-** In this step the user selects the *Profile* that the
messages will be based upon. It can be used to later recall settings.
The *message path* indicates the location where messages are to be
stored. A *session name* attaches a name to the current message
generation setup. A *session* can be saved and recalled using the File
menu options.

**Options-** The user can choose from a number of options when
generating messages. By default Message Maker will create a set of valid
messages. The user can keep the default settings or customize the
process. The *volume* parameter sets the number of messages that will be
created. Additionally, various tests can be selected for specific
locations in the profile by selecting the Manual Test Selection panel.

**Data Initialization-** The user can set the values in the
configuration file and the data repository as needed. Values set in the
configuration file become the default value for a particular data
element. A typical element that might be set in the configuration file
is the Sending Application (MSH-3.1). Also, values in the data
repository can be modified. Various utilities are provided by Message
Maker to customize the data files. The MSH Segment utility can be used
to modify and saved configuration data.

**Message Generation-** After initialization is complete messages can be
generated. Message Maker provides a utility that monitors the progress
of the generation process. Messages are optionally validated against the
profile to ensure correctness (not yet implemented). Although post
validation is not done, Message Maker is designed to created valid
messages. A trace of the process is provided in a log file.

**View/Modify/Validate Messages-** After successful completion of
message generation, the test messages can be viewed and/or edited.
Message Maker provides four views: XML, ER7, Enhanced ER7, and
Validation (forthcoming). Messages in the Enhanced ER7 view are
presented in a tree structure where element values can be modified and
saved. The Validation view shows a message validation report. All of
these features can be used on current and previously created messages.

**Message Management-** Message Management provides a utility that
allows the user to create "File" (FHS) and "Batch" (BHS) message
structures.

# Initialization

## Selecting a Profile

The message generation process is driven by a message profile. The
profile provides the *template* that guides message creation. To begin
the process, select the profile you want to create messages for. The
profile can be selected from the Initialization Panel (the default panel
upon startup, Figure 2). Click on the "Browse" button to locate a
particular profile or enter the *path* and *file* name directly in the
text field. Once a profile is loaded the *message path* directory is
automatically selected. This location is provided for convenience that
can be modified. The *message path* indicates the location where the
message files are created and stored.

The *session* provides persistence that saves the settings for the
message generation process. This allows for repeating of message
generation and partial setup. A *session* name can be selected using the
utility under the File Menu.

**Test Files:** Message Maker provides an option to load an example
profile ("NIST_SampleADT_Z.xml") upon initial startup. It is a good idea
to load this profile to get familiar with Message Maker's functionality.
The profile is used in many of the examples provided in this User's
Guide. In addition to the XML profile, the native MWB profile along with
tables files are located in the maker/testing directory under the your
chosen install directory.

## Test Options

![](media/image3.png){width="5.997916666666667in"
height="3.560416666666667in"}

######## Figure 2. Initialization Panel {#figure-2.-initialization-panel .unnumbered}

Message Maker supports various message generation options. The options
include the number of messages that are created, the message validity,
constraints on usage, segment and field cardinality, and more.

### Predetermined Message Generation Sets

Message Maker by default provides testing variation. When selecting one
of the three general test options message variation is provided. You can
choose to create messages that are valid, invalid, or a mixture of both.
By choosing one of these options, you are allowing Message Maker to
control which data items and test options are varied. By default all
messages are valid. There are also options to choose a sample message.
Sample messages may be minimally populated, maximally populated, or
randomly populated. See the glossary for definitions of these terms.

### Select the Number of Messages to Create

The Volume field allows you to select the number of messages to create.
The default number is 10. Volume can be set when the predetermined
message generation sets and customize message creation options are
selected. The Volume for manual test selection is determined by the
tests that the user selects.

### Customize Message Creation

You can have finer control of the testing options by selecting
**Customize** and the **More Options** button. This will expand the
Initialization Panel (Figure 3). This group of testing options allows
you to select the type of messages you want to create.

![](media/image4.png){width="5.997916666666667in"
height="4.935416666666667in"}

######## Figure 3 Expanded Initialization Panel {#figure-3-expanded-initialization-panel .unnumbered}

The options set by the user in combination with the number of messages
to be generated, determine the types (variation) of messages that are
generated. The types of messages generated are divided roughly evenly
based on which options are selected. For example, if 10 messages are to
be generated and *Cardinality* and *Usage* are selected, then 5 messages
for testing cardinality and 5 messages for testing usage will be
generated.

A *base message* is a minimally populated message. It serves as the
reference message where deviations from it can be identified and
recorded as message variants. In selecting the customized options in
Figure 3, the user is selecting a given variant or variances, for
example, cardinality, from the base message. The "Valid (In cardinality
range)" option instructs the message generation engine to create
messages that vary the cardinality of segments and fields. The
cardinality value and location of the variation is random. Table 1 gives
a summary of options meanings.

  -------------- ------------ ------------------------------------------------
  **Category**   **Option**   **Interpretation**

  Usage          Valid        In the case of RE usage the element is populated
                              with data. The location is random.

  Usage          Invalid      An element with X usage may get populated with
                              data or an element with R usage may not get
                              populated with data.

  Cardinality    Minimally    All elements with cardinality are set to the
                              minimum.

  Cardinality    In range     All elements with cardinality will fall within
                              the cardinality range.

  Cardinality    Maximally    All elements with cardinality are set to the
                              maximum.

  Cardinality    Invalid      An Element with cardinality will be set to
                              values that fall outside the valid cardinality
                              range.

  Code Set       Valid        The value is a valid value taken from the
                              requested code set.

  Code Set       Invalid      Not Yet Implemented. When implemented it will be
                              a value not contained in the requested code set.
                              Note: You can request a specific Code Set test
                              location by using the manual test selection
                              utility (See section 4.2.4).

  Length         Valid        All elements have valid lengths.

  Length         Ignore       Disregard the length attribute during message
                              creation and validation.

  Length         Invalid      Message will contain an element with an invalid
                              length.

  **Table 1.                  
  Meaning of                  
  Customized                  
  Option                      
  Settings.**                 
  -------------- ------------ ------------------------------------------------

[]{.mark}

The variations in the data used for populating the messages is largely a
function of the size of the set of data values available for each
primitive element, Field, Component, and Subcomponent. These data values
are maintained in a set of XML files that are accessed by the message
generation software. The software uses a random number generator to
determine the location it will use as its starting point for selecting
values from the files. The frequency with which the same location will
be selected will then largely be determined by the number of possible
values. Subsequent values are selected from the files using a scheme
that will increment the starting location by a number that depends on
the hierarchical structure of the profile. This scheme should result in
relatively little repetition of data values, provided a sufficient
number of possible data values are available.

[]{.mark}

*Cardinality* and *Usage* options result in messages being generated in
an analogous manner. The length options work somewhat differently.
Length constraints can either be enforced or ignored, but the option\'s
setting doesn't otherwise impact the messages that are generated. When
length constraints are being enforced for primitive elements, repeated
attempts will be made to find suitable values satisfying the constraint;
generally if such a value is present in the XML data files, it will be
used. When the composite length option is set, its only impact is to
produce a warning in those cases where a composite element might violate
its length constraint, even though none of its component elements
violates any length constraint.

[]{.mark}

When an option for generating a length error is set, a single element in
the message will be instantiated with a value that violates the length
constraint for some numeric (NM) or string (ST) type only.

### Customized Message Creation at the Element Level

Selective element locations and test type can be identified for testing
when generating messages. Choose the "Manual Test Selection" radio
button and select the "Set" button to launch the selection panel. This
panel depicts the profile in a tree structure and shows the available
options that can be selected for generating messages for particular
elements. These options vary depending on the validity of the message.
By default the options are given for valid messages. Use the drop-down
list to change this to create invalid messages.

![](media/image5.png){width="5.997222222222222in"
height="4.875694444444444in"}

**Figure 4. Manual Test Selection Panel**

As a reference point, all modifications made to a message variant is
made with regards to the base message. The base message is a minimally
populated message. See the glossary for a precise definition of both.

Choosing a test category at a selected location indicates to Message
Maker that you want to create test messages that vary the constraints at
this element. More then one message can be created for a given
selection. A running total of message variants are given at the bottom
of the panel.

Table 2 (Valid) and Table 3 (Invalid) give the interpretation of the
options for cardinality as a function of the usage attribute. Table 4
summarizes the options for the usage constraint. Recall that message
variants are in reference to the base message, so instances that include
the base message settings are not listed here.

+-------+----------+---------------------------------------------------+
| **Us  | **Cardi  | **Message Variants**                              |
| age** | nality** |                                                   |
+-------+----------+---------------------------------------------------+
| R     | 1...1    | None                                              |
+-------+----------+---------------------------------------------------+
| R     | 1...N    | 3 message variants possible:                      |
|       |          |                                                   |
|       |          | 1.  Cardinality = 2 (minimum + 1)                 |
|       |          |                                                   |
|       |          | 2.  Cardinality = N (if N = \* then cardinality   |
|       |          |     is set to the minimum + 3, where 3 is an      |
|       |          |     arbitrary value that can be configured, see   |
|       |          |     the Options utility).                         |
|       |          |                                                   |
|       |          | 3.  Cardinality = floor (minimum + N)/2. If this  |
|       |          |     value equals one of the values in 1 or 2      |
|       |          |     above, then only 2 message variants are       |
|       |          |     created in this instance.                     |
+-------+----------+---------------------------------------------------+
| R     | M\...N   | 3 message variants possible:                      |
|       |          |                                                   |
|       |          | 1.  Cardinality = M+1 (minimum + 1)               |
|       |          |                                                   |
|       |          | 2.  Cardinality = N (if N = \* then cardinality   |
|       |          |     is set to the minimum + 3, where 3 is an      |
|       |          |     arbitrary value that can be configured).      |
|       |          |                                                   |
|       |          | 3.  Cardinality = floor (M + N)/2. If this value  |
|       |          |     equals one of the values in 1 or 2 above,     |
|       |          |     then only 2 message variants are created in   |
|       |          |     this instance.                                |
+-------+----------+---------------------------------------------------+
| RE    | 0...1    | Cardinality = 1                                   |
+-------+----------+---------------------------------------------------+
| RE    | 0...N    | 3 message variants possible:                      |
|       |          |                                                   |
|       |          | 1.  Cardinality = 1 (minimum + 1)                 |
|       |          |                                                   |
|       |          | 2.  Cardinality = N (if N = \* then cardinality   |
|       |          |     is set to the minimum + 3, where 3 is an      |
|       |          |     arbitrary value that can be configured).      |
|       |          |                                                   |
|       |          | 3.  Cardinality = floor (minimum + N)/2. If this  |
|       |          |     value equals one of the values in 1 or 2      |
|       |          |     above, then only 2 message variants are       |
|       |          |     created in this instance.                     |
+-------+----------+---------------------------------------------------+
| X     | Don't    | None                                              |
|       | care     |                                                   |
+-------+----------+---------------------------------------------------+
| **    |          |                                                   |
| Table |          |                                                   |
| 2.    |          |                                                   |
| Valid |          |                                                   |
| Me    |          |                                                   |
| ssage |          |                                                   |
| Var   |          |                                                   |
| iants |          |                                                   |
| for   |          |                                                   |
| Car   |          |                                                   |
| dinal |          |                                                   |
| ity** |          |                                                   |
+-------+----------+---------------------------------------------------+

+-------+----------+---------------------------------------------------+
| **Us  | **Cardi  | **Message Variants**                              |
| age** | nality** |                                                   |
+-------+----------+---------------------------------------------------+
| R     | 1...1    | Element not included                              |
+-------+----------+---------------------------------------------------+
| R     | 1...N    | 2 message variants possible:                      |
|       |          |                                                   |
|       |          | 1.  Element not included                          |
|       |          |                                                   |
|       |          | 2.  Cardinality = N +1 (if N = \* then there are  |
|       |          |     no variants)                                  |
+-------+----------+---------------------------------------------------+
| R     | M\...N   | 2 message variants possible:                      |
|       |          |                                                   |
|       |          | 1.  Element not included                          |
|       |          |                                                   |
|       |          | 2.  Cardinality = N +1 (if N = \* then there are  |
|       |          |     no variants)                                  |
+-------+----------+---------------------------------------------------+
| RE    | 0...1    | None                                              |
+-------+----------+---------------------------------------------------+
| RE    | 0...N    | Cardinality = N+1 (if N = \* then there are no    |
|       |          | variants)                                         |
+-------+----------+---------------------------------------------------+
| X     | Don't    | Element included                                  |
|       | care     |                                                   |
+-------+----------+---------------------------------------------------+
| **    |          |                                                   |
| Table |          |                                                   |
| 3.    |          |                                                   |
| In    |          |                                                   |
| valid |          |                                                   |
| Me    |          |                                                   |
| ssage |          |                                                   |
| Var   |          |                                                   |
| iants |          |                                                   |
| for   |          |                                                   |
| Car   |          |                                                   |
| dinal |          |                                                   |
| ity** |          |                                                   |
+-------+----------+---------------------------------------------------+

  -------------- ----------- ---------------------------------------------------
  **Validity**   **Usage**   **Message Variants**

  Valid          R           None

  Valid          RE          Element included

  Valid          X           None

  Invalid        R           Element not included

  Invalid        RE          None

  Invalid        X           Element included

  **Table 4.                 
  Message                    
  Variants for               
  Usage**                    
  -------------- ----------- ---------------------------------------------------

Note that the "Manual Selection Panel" displays only check boxes for the
tests that are possible given the validity of the message. For example,
for valid messages with elements that have R usage, no tests can be
created. If, however, Invalid message type is selected, then an element
with R usage can be selected. In this case, an element that has R usage
and is selected will instruct the message generation engine not to
populate the element with data, thus creating and invalid message.

Consider the following examples as selected in Figure 4\--these four
cases will generate five test messages:

**Case1: Invalid Value Set at PID.8 Administrative Sex**

The type of message selected is invalid and the Administrative Sex table
0001 is selected. This instructs the message generation engine to
implant an error at this location. The message generation engine will
search table 0001 and then populate this element with a value that is
not in table 0001.

**Case 2: Invalid Usage X PID.19 SSN Number -- Patient**

The type of test selected is invalid usage (X) for the SSN Number --
Patient. In this case the element is not supported (indicated by the X
usage). By selecting this test the message generation engine is
instructed to populate this element with a data value thus creating an
invalid message.

**Case 3: Invalid Cardinality PID.20 Driver's License Number - Patient**

The type of test selected is invalid cardinality for the Driver's
License Number -- Patient element. In this case the profile supports
exactly one instance of this element (indicated by the cardinality of
1..1). By selecting the test the message generation engine is instructed
to create messages where this element with have instances that fall
outside of the cardinality range; therefore two messages will be
generated:

-   The Driver's License Number -- Patient element is not present

-   The Driver's License Number -- Patient element appears twice

**Case 4: Invalid Cardinality PID.20.1 Driver's License Number**

The type of test selected is invalid usage (R) for the Driver's License
Number. In this case the element is supported (indicated by the R
usage). By selecting this test the message generation engine is
instructed not to populate this element with a data value thus creating
an invalid message

Analogous test cases can also be created for valid messages. For
example, consider an element with an RE usage. The base message does not
populate elements that have a usage of RE, so the selection at this
point indicates to the message generator to populate this element. The
selection of an element with a cardinality attribute of 1..3 indicates
that messages will be generated that contains 2 and 3 instances of that
element. The base message covers the case of 1 instance.

### Message Generation Characteristics

Each generated message is different in terms of both structure and
content. Below is a list of message characteristics that should be
considered when choosing options for message generation:

-   data content is randomly selected from a database

-   multiple variations maybe introduced for any given message

-   at most one error is introduce for a given message.

## Data File and Configuration

Message Maker provides various ways to input and modify the data that is
used in message generation. Configuration, Table, and Reference data can
be defined and modified. Configuration data are values that will always
be used in a primitive data element. Any item in the reference database
can be modified with the use of the "Data Configuration" panel
(including MSH segment and table data). MSH configuration data can be
set with the MSH Segment convenience dialog. Table data can be set or
modified with the Table Viewer dialog.

### Data Files

Message Maker maintains a number of XML data files for use in message
generation. A brief description for each is given below:

**ConfigData:** This is a special file that contains data items that are
always used for an element. Typical *configuration* data might include
the HL7 version number or the name of the sending application used in
the MSH segment. If a data item is present in this file, the message
generation software will always use the item's value when generating
messages.

![](media/image6.png){width="5.290972222222222in"
height="3.7493055555555554in"}

######## Figure 4. Saving Data Files {#figure-4.-saving-data-files .unnumbered}

**hl7tables:** This file contains the list of tables defined by HL7.
These include HL7 and HL7User table types. The file contains the table
id, name, type, and code/value pair. The initial values for the tables
are those defined or suggested by the HL7 standard. Values for the HL7
tables cannot be modified. Values for HL7User tables can be modified.

**usertables:** This file contains the list of tables defined by HL7 to
be of type "User". There are no suggested values in the standard---the
values are site specific (e.g., a hospital room number). These values
are typically unique to a particular installation and are defined
locally. NIST provides values for these tables (i.e., NIST creates
sample values). The NIST created values may be sufficient for many
testing scenarios. In cases where they are not, the tables can be
modified with the *Table Viewer* or by selecting the table from the
*Data Configuration Panel*.

**externaltables:** This file contains the list of tables defined by HL7
to be of type "User" with suggested values coming from an external
source such as ISO. For example, HL7 Table 0399 for *Country Codes* are
taken from the 3-character codes defined by ISO 3166 table.

**localtables:** This contains the list of tables that are local to a
particular site. These files are provided by the users and imported into
Message Maker. The local tables can be directly imported into Message
Maker or can be transformed into a format that Message Maker can read.

**ReferenceData:** The NIST HL7 Reference Database contains example data
values for HL7 data elements that are not found in other data sources
such as HL7 tables. The database contains items for the HL7 primitive
data elements (i.e., fields, components, and sub-components). The data
items are contained in an Microsoft Access database and are transformed
into an XML file for processing by Message Maker.

Together, these data sources are used in the message generation process.
Each of the data sources can be modified. When values from a data source
are modified, Message Maker will request the name of the file to save
(Figure 4) the new data source. By default Message Maker suggests the
"Local" prefix. Message Maker will maintain any number of *local*
versions of the file.

![](media/image7.png){width="5.993055555555555in" height="2.9625in"}

######## Figure 5. Set Data Files {#figure-5.-set-data-files .unnumbered}

The user can select which data files they want to use when generating
messages. This can be accomplished with the "**Data Files**" dialog
under the "**Configure**" menu (See Figure 5). Once set, the *Local*
data files can be used for any message generation session.

Local table data files can be added to the data lookup sequence using
the "**Data Files**" dialog. Use the "Load" button to browse the file
system to locate the file you want to add. Local tables are used when
the profile contains references to a local set of table definitions.
\[Currently, only one local table can be added. In addition the priority
feature that allows the user to set the sequence that the data files are
searched is not yet implemented.\]

![](media/image8.png){width="5.997222222222222in"
height="4.6194444444444445in"}

######## Figure 6. MSH Segment Initialization {#figure-6.-msh-segment-initialization .unnumbered}

Local table files can be imported directly into Message Maker as long as
they adhere to the format that is consistent with the data files
provided with Message Maker. Use the "Load" button. See the
*hl7tables.xml* file provided in the distribution for an example of the
table format. Also, tables produced by the MWB can be imported into
Message Maker directly. Message Maker will automatically convert the MWB
table file into its internal format. Use the "Import MWB table" button.
A third method of importing table data is via a generic mapping feature.
Click on the "Import Table" button and provide the mappings of the local
table to the format required by message maker. Again, see the
*hl7tables.xml* file for an example.

### MSH Segment Data Initialization

To set configuration data in the MSH Segment, select "MSH Segment" under
the "Configure" Menubar. This dialog displays the profile represented as
a tree structure. Data items colored in yellow can be modified. Items
that are not supported in the profile are colored in gray and contain
the text "Not supported by Profile". Items colored in green, cannot be
modified (e.g., the message type MSH.9).

![](media/image9.png){width="5.993055555555555in"
height="4.204166666666667in"}

######## Figure 7. Table Viewer {#figure-7.-table-viewer .unnumbered}

Items set on this dialog are written to the ConfigData file and as such
will be used as the default value in message creation. Change the
"Message Control ID" (MSH.10) element to set the beginning sequence
number for identifying messages.

### Table Data Initialization

Tables can be modified, created, or removed using the "**Table Viewer**"
dialog (See Figure 7). To create a new table select the "New" button and
then provide the Name, Number, Type, and code/value pairs. To remove a
table, select the table and click-on the "Remove" button.

When a table is selected, its code/value pairs are shown. Using the
utilities provided, the table code/value pairs can be modified. To
modify an entry, select the code/value pair of interest. This will copy
the entry to the text field provided below. Make the modifications and
select the edit button to make the changes permanent. New items can be
added to the table by using the "New" and "Add" buttons. Select "New",
enter the code/value pair in the text fields, and select "Add" to
include the item into the table. To remove an item, select an entry and
click-on the "Remove" button.

### Data Configuration Panel

The Data Configuration panel is a general-purpose utility that allows
the users to modify the data elements in the database, including MSH
segment and table data. The Data Configuration panel allows the user to
set various site-specific values that they want to include in messages
or allows them to provide customized variation of the data values for
particular elements. The view that is presented is a reflection of the
profile. All data elements can be modified including table values. The
user may add, edit, or delete values from the repository. Depending on
the type of data value, an appropriate data modification panel on the
right side of the Data Configuration panel will appear. To view and/or
modify a particular data element browse the tree structure and select
the desired element.

![](media/image10.png){width="5.997916666666667in"
height="4.935416666666667in"}

######## Figure 8. Data Configuration Panel (Table Data Modifications) {#figure-8.-data-configuration-panel-table-data-modifications .unnumbered}

Figure 8 shows the panel for table data (HL7 Table 0001 Administrative
Sex). To add an entry into the table select the New and Add buttons.
Select **New**. This activates the two text fields where the *Code* and
*Value* pair can be entered. Select the **Add** button to commit the
values to the table. To delete an entry from the table, select
(highlight) *Code* and *Value* pair and select the **Remove** button. To
modify an existing entry select (highlight) the *Code* and *Value* pair.
This entry will now appear in the *Code* and *Value* pair text fields.
Perform the modifications and select the **Edit** button to commit the
changes to the table.

Data values for primitive elements can also be modified. Figure 9
depicts such a panel. Again use the tree structure to navigate to the
element you want to modify. In this case we selected the *PID* segment,
the *Phone Number -- Home* field and the *\[(999)\]999-9999\[X999\]\[C
any text\]* component. The *\[(999)\]999-9999\[X999\]\[C any text\]*
component is highlighted. On the right side of the panel the values in
the database for this element are given. You can add, modify, or delete
values from this list. Also, for each value you can set the associated
attributes (e.g., Complexity). Currently, Message Maker does not yet
make use of these attributes; hence changing the attribute values will
have no affect on message construction in this release.

![](media/image11.png){width="5.997916666666667in"
height="4.935416666666667in"}

**Figure 9. Data Configuration Panel (Reference Data Modification)**

To add an entry into the element list select the **New** and **Add**
buttons. Select the **New** button; this activates the text field where
a *Value* can be entered. Select the **Add** button to commit the value
to the list. To delete an entry from the list, select (highlight) a
*Value* and click-on the **Remove** button. To modify an existing entry
select (highlight) the *Value*. This entry will now appear in the
*Value* text field. Perform the modifications and select the **Edit**
button to commit the changes to the list.

## Data for Z Segments

Because Z Segments are local extensions, they inherently present a
problem for populating message elements with data. We can provide data
values for standard HL7 elements because they are known and given in the
HL7 database. Z segments contain elements that support their local
implementations and therefore have their own nomenclature. However,
there are a number of methods to provide data values for Z segment
elements.

![](media/image12.png){width="5.997916666666667in"
height="4.935416666666667in"}

**Figure 10. Data Configuration Z-Segments Data Copy**

A link to a database can be established and the mappings to it can be
defined. This would be the optimal solution and will be provided in
future versions of Message Maker.

A second solution is to map data values provided by the repository to Z
segment elements. The repository can be search for similar element names
where by the user can review to determine if the data maps. If it does,
they can choose to copy this data to create a new element field in the
repository (Figure 10). To link data values in the repository to
elements defined in Z Segments browse through the values of the
"Suggested Data Links" and use the "Copy Values" button when appropriate
values are found.

A third method is to use the Configuration Panel to add values directory
to the repository. These values can be saved and use for subsequent use
in Message Maker. In this case follow the instructions given in the
previous section for adding new values for primitive elements.

A fourth method is to use the example data value given in the profile,
if one is provided. The downside to this is that the same data for Z
segment elements will be used for every message created.

The fifth method is to use the default values. In this case, if a data
value can't be found for a particular message element, a default data
value is assigned based on the data type of the element. Although
aesthetically unpleasing, functionally it provides the same utility as
data obtained from health care information databases.

![](media/image13.png){width="5.997916666666667in"
height="4.935416666666667in"}

**Figure 11. Identifying Elements with Missing Data Values**

## Identifying Elements with Missing Data Values

Figure 11 illustrates a utility that allows the user to determine the
elements that are missing data values. Knowing which values are not
present allows the user to populate the repository with data for these
elements. In the event that these elements are not populated, before
message generation, default values will be put into the repository based
on the data type of the element.

# Message Generation

Once initialization is complete messages can be generated. The minimum
initialization requirement is providing a valid message profile. To
start the message generator select the "*Generate..."* item under the
"*Messages"* menu. This will launch the Generate Messages Dialog, See
Figure 12. Click-on the **Start** button to begin the process.

![](media/image14.png){width="2.4270833333333335in"
height="0.9479166666666666in"}

**Figure 12. Generate Message Dialog**

Upon completion messages are saved in the "*Message Path*" directory
specified during initialization. The messages are stored as XML files.
Internally, Message Maker processes messages as XML representations.
Message can be transformed into the ER7 encoding and can be saved in XML
or ER7 format. To save messages select the Save item from the Messages
menu. If you wish to subsequently edit messages, the XML version must be
saved. Messages that are not explicitly saved will be removed when
Message Maker exits. Messages can be deleted by selecting the Delete
item from the Messages menu.

## How Message Elements are Populated with Data

Message Maker has a predefined sequence for populating primitive message
elements with data. The precedence order is given below:

1.  Values predetermine by the HL7 specification and present in the
    profile, for example, MSH.9, the Message Type.

2.  Constant Values defined in the profile (i.e, the ConstantValue
    attribute)

3.  Configuration Values set by the user either through the *MSH Segment
    Configuration Panel* or the *Data Configuration Panel*. Here the
    data that is explicitly saved as configuration data. The "namespace
    ID" for the "Sending Application, MSH.3, is a typical example. It
    may be the case where the user wants to set this value so that it
    appears in every message with the same value. Most MSH segment
    elements are considered Configuration Values.

4.  If an element indicates that a value should come from a Table, a
    data value is randomly selected from the specified table. Tables are
    search by default in the following order:

    a.  HL7 Tables

    b.  Local Tables (either imported or created in Message Maker)

    c.  User Tables

    d.  External Tables

The priority of how tables are searched can be set using the "Data
Files" dialog's "Set Priority" utility (not yet implemented). Local
Tables that are provided by the user can be imported into Message Maker.
See section 4.3.1 for details.

5.  Reference Database

6.  Example value given in the profile

7.  Default Values. These values are chosen based on the data type of
    the primitive element. Default values can be modified by using the
    Options utility. See section 8 for details.

![](media/image15.png){width="5.997916666666667in"
height="4.877777777777778in"}

**Figure 13. Message View Panel (XML View)**

Note that before message generation a data repository is created from
the configuration values, reference database, example values, and the
default values. The table data is contained in separate resources.

# Message Browsing and Editing

Select the Message View tab to review and edit the messages. The Message
Path directory selected during initialization is automatically mounted.
Open this folder and select the Test Description file associated with
the message test suite. By default the name of this file is the name of
the profile with a "TD\_" prefix. Selecting this file gives a summary of
the messages in the display panel on the right.

![](media/image16.png){width="5.997916666666667in"
height="5.429166666666666in"}

**Figure 14. Message View Panel (ER7 View)**

Expanding this folder displays the list of messages. By default the name
of the message files is the profile name with the string ".msg00000.xml"
appended. The "00000" string represents the message sequence number. By
default it starts as 0. Select a message to view its contents. Messages
can be rendered in XML, ER7, or Enhanced ER7 formats. By default
messages are displayed in XML (Figure 13). Select the ER7 tab at the
bottom to display the message in the ER7 format (Figure 14). Select
Enhanced ER7 to view and navigate messages in a tree-structure. The
Enhanced ER7 view also allows the user to edit the content of the data
values in the message. To change the value of a data element, select the
value, make the changes, and hit enter (Figure 15).

Modifications made to messages can be saved. Messages saved with the
same name will still be associated with the originating metadata file.
Messages saved under a different name will not be associated with a
metadata file.

![](media/image17.png){width="5.997916666666667in"
height="5.429166666666666in"}

**Figure 15. Message View Panel (Enhanced ER7 View-Edit)**

At the lower right hand quadrant of the Message View windows a test
description describes the purpose of the test message. When specific
test types and locations are requested, a detailed description is given.
The test type (Valid or Invalid), test category (e.g., usage,
cardinality), and the location is given. The example in Figure 14
indicates that a required element is not present in element
PID.20.DLN.1.

## Viewing Previously Generated Messages

Messages that were previously generated can be view by mounting the
directory where the messages were saved. Choose the Mount Directory
dialog from the Messages menu.

# Message Management: Creating HL7 Batch Files

The *Message Management Panel* provides functionality to create HL7
batch files. Batch files are used when there are instances when it is
convenient to transfer a batch of HL7 messages.

The following steps can be followed to create an HL7 Batch File:

1.  Enter the structure of the batch file. Enter the segment names in
    the *Structure* text field (Figure 16). The table below gives a
    summary of the allowed values and their meanings. Once the structure
    has been completed, select the compile button to build the batch
    file structure. A typical structure is FHS, BHS, MSG, BTS, FTS. This
    represents a set of messages wrapped in a batch segment wrapped in a
    file segment.

![](media/image18.png){width="5.997916666666667in"
height="4.894444444444445in"}

> **Figure 16. Message Management: Setting Field Values**
>
> The structure can be modified with the use of "Add Segment" and
> "Remove Segment" buttons. To add a segment, select a location where
> you want to add a segment and click-on the "Add Segment" button. This
> brings up a dialog requesting what segment to add and where. To remove
> a segment, select the segment and click-on the "Remove Segment"
> button.

  ------------- --------------------- --------------------------------------
  **Segment**   **Name**              **Description**

  FHS           File Header Segment   HL7 defined header segment containing
                                      File header information.

  BHS           Batch Header Segment  HL7 defined header segment containing
                                      Batch header information.

  MSG           Messages Placeholder  Message Maker defines the MSG
                                      placeholder to represent 0 or more HL7
                                      messages.

  BTS           Batch Trailer Segment HL7 defined trailer segment containing
                                      Batch trailer information.

  FTS           File Trailer Segment  HL7 defined trailer segment containing
                                      Batch trailer information.
  ------------- --------------------- --------------------------------------

2.  Once the structure is defined, each field in the FHS, BHS, BTS, and
    FTS segments can be set by selecting the item in the tree structure.
    A set of attributes for each field appears on the right hand side of
    the panel. The values set in these text fields will be copied to the
    batch file when it is generated. Figure 16 illustrates the Batch
    Sending Application field being set to "ABD Medical Application".

3.  The MSG segment is a placeholder for messages. To add messages to
    the batch file, click-on the MSG segment. This brings up a
    navigation utility to mount message directories. Select the messages
    and click-on the Add button to add them to the batch file (See
    Figure 17).

4.  After setup is complete, select the Generate button to create the
    batch file. The batch file is displayed in both XML encoding and ER7
    encoding (See Figure 17).

5.  The batch file can be saved using the "Export XML" or "Export ER7"
    buttons.

![](media/image19.png){width="5.997916666666667in"
height="5.429166666666666in"}

######## Figure 17. Message Management: Adding Messages and Generating the Batch File {#figure-17.-message-management-adding-messages-and-generating-the-batch-file .unnumbered}

# General Configuration Options

Figure 18 depicts the Options panel for setting various configuration
parameters. The HL7 version (currently 2.4 only), message and profile
validation preferences, cardinality upper bound and default value
preferences can be set.

When data is not available for a particular element, the message
generation engine will use a default value based on the data type of a
primitive element. For each primitive data type default values can be
set. However, Message Maker provides an initial set of defaults that
should be sufficient in most cases.

![](media/image20.png){width="5.993055555555555in"
height="3.3194444444444446in"}

######## Figure 18. Setting General Configuration Options {#figure-18.-setting-general-configuration-options .unnumbered}

# Appendix A: Message Maker Version 1.4 Limitations

The following list gives the current known limitations of this version
of Message Maker.

1.  The reference data is limited to version 2.4 elements.

2.  The reference database is not yet fully populated. It is partially
    populated for ADT message types. Any message type can be processed;
    however, example data from the profile and/or default data values
    will be used. User's can add their data to the reference database.

3.  Message Maker has limited support for importing site-specific data.

4.  Message Maker has limited validation and reporting functionality.

5.  There is no support for the C and CE usage types.

6.  Not all complex data types are handled (e.g., the HD data type)
    according to their semantic meaning defined in the standard. The
    elements are populated with data however the relationship of the
    data implied by the data type is not maintained. For example, in the
    case of an HD the values of the first component may not be
    identified by the second and third components. If this is critical
    to a particular message instance, the user can set these values by
    using the editing features of the enhanced ER7 view.

# Appendix B: Trouble Shooting

1.  **Profile fails to load.**

Check to see if the profile (or table file if loading a table) is a
valid XML file. In some cases the XML files created by profile
generation tools, such as the MWB, contained illegal characters. Try and
view the profile with Internet Explorer.

2.  **Non-standard HL7 profiles (e.g., field repetitions created by the
    MWB).**

Unpredictable messages may occur if the profile is a non-standard HL7
profile. For example, the MWB has an option to produce profiles with
field repetitions explicitly defined and represented with the "\_rep"
string appended to the field (e.g., Patient Address_rep).

# Glossary

***Base message.*** A base message is a minimally populated message. It
serves as the reference message where deviations from it can be
identified and recorded as message variants.

***Maximally populated message***. A maximally populated message will
follow the usage rules at each level as stated. In the case of an RE the
element will be populated. For cardinality, all maximums are selected.
In cases where the maximum is unbounded (\*), the maximum is set to the
minimum + N (N is configurable; default is 3). All lengths fall within
the specified limits at each level. If the option to ignore lengths is
chosen then the length constraint attribute is eliminated. All coded
values are taken from the specified value set.

***Minimally populated message***. A minimally populated message will
follow the usage rules at each level as stated (e.g., in the case of R
usage, the element is populated). In the case of an RE the element will
not be populated. For cardinality, all minimums are selected. All
lengths fall within the specified limits at each level. If the option to
ignore lengths is chosen then the length constraint attribute is
eliminated. All coded values are taken from the specified value set.

***Sample message.*** A sample message will follow the usage rules at
each level as stated. In the case of an RE the element is randomly
populated. For cardinality, a value within the specified limits
including the edges is randomly selected. In cases where the maximum is
unbounded (\*), the maximum is set to the minimum + N (N is
configurable; default is 3). All lengths fall within the specified
limits at each level. If the option to ignore lengths is chosen then the
length constraint attribute is eliminated. All coded values are taken
from the specified value set.