Getting Started with Mirth

Getting Started With Mirth

Contributed by VocalEZ

Creating Inbound Channel

Source = File Reader / Destination = Postgresql

The purpose of this document is to show how to configure Mirth to accept text based HL7 messages and place them into a postgresql database.

Prerequisites

1) Make sure that you have postgresql installed, running and you can log into the database (I use pgadminIII ).

2) The Mirth software is installed and running.

a. This test was performed on a Windows 2003 server.

3) Mirth version is 1.0.1.

4) You should have some test HL7 Demographic data.

Configuring and implementing a new channel

1) Start Mirth by running the mirth.bat file located in the Mirth install directory.

a. Do not close the command windows that starts

b. You can minimize if you would like to

2) Start Mirth Admin and log into the management console

a. http://localhost:8080

b. Default username and password are admin / admin

Setting up a connection 1) Creating a channel

a. Click on Channels in the left windows of the Admin console

b. Click “New Channel” in the Channel Tasks box

c. Give it a name and choose inbound. Click Next

d. Choose Broadcast for the Channel Type (this will be a one to one channel).

e. Click Finish

2) Click Summary Tab

a. Check the Enabled button. This will allow this channel to be published.

b. Click Save Changes in the Channel Tasks Window

3) Click Source Tab

a. In the Connector Type dropdown box, choose File Reader

b. Enter the directory that the HL7 text files will be located

i. Mirth will pick the files up from this location

c. Fill out any other fields that are required for your setup

i. I checked delete file after Read (Yes) because I wanted my files to be removed after used.

d. Click Save Changes in the Channel Tasks Window

4) Create Transformer a. Click on Edit Transformer in the Channel Tasks Window b. This opens an Edit Channel / Edit Transformer screen c. Click in the HL7 Message Template tab (bottom right corner) d. Open a test HL7 message (this should be from the application that will be sending you’re the live HL7 feed to make sure the message is formatted the same when you start working with live data).

i. Copy all the data from the message to the clipboard e. Paste the message into the body of the message template tab

f. Click on the HL7 Tree tab

i. This will show the outline of your message in HL7 formatting allowing you to quickly find the data you are looking for as you create the transformer statement.

g. Click Add New Step in the Transformer Tasks Window h. A line is created with 0 and New Step showing. i. Below that there is a Variable box that has newVar0

i. Change that name to something that makes sense for the field you will be creating, like MRN or firstname, etc.

1. You will be creating one NewStep for each field you want to move from the HL7 message to the postgresql database.

ii. My variable is mrn for this document

iii. In the HL7 tree open the section where the variable you are going to map to the field is located.

1. Open all the way until you see the data itself, in my case the mrn.

iv. Left click and drag the data from the HL7 tree to the Mapping window.

1. You will see something similar to: msg['PID']['PID.2'] ['CX.1'] which is the location of the data in the HL7 message that will be associated with the mrn variable.

j. Click on Add New Step and repeat the process until you have all your fields defined in the Mappings

i. You will have as many New Steps as you have fields. k. When you are finished creating transformers, click on Back to Channels in the Mirth Views window

l. Click Save Changes

5) Creating a Destination

a. Click the Destinations Tab

b. Click New Destination

i. You can use the initial Destination 1 and make changes to that if it is easier.

c. On the connector Type drop down box choose Database Writer

d. On the driver Drop down box choose ODBC Postgresql

e. In the Database URL, enter your database information in this form.

f. jdbc:postgresql://localhost:5432/Testing

i. jdbc:postgresql://%ip address of database %:%tcpip port%/ %database name%

g. Enter the username and password for accessing the database

i. This should have been setup as part of the prerequisites.

h. In the source mappings window, you will see the variables that you created in the transformer setup section.

i. In the SQL statement, enter this information

i. INSERT INTO %database name% (dbfield1, dbfield2, …) VALUES (${variable1}, ${variable2});

ii. English Translation

1. INSERT INTO Test (mrn, ssn) VALUES (${mrn}, $ {ssn});

iii. You can click the variable names from the source mappings window and drag them into the SQL statement. j. When you have your SQL statement completed, click Save Changes in the Channel Tasks window.

6) Publishing the Channel to the engine

a. Click on Channels in the Mirth window

i. You channel should be listed in the Channels window with the name you gave it.

ii. Make sure the status is Enabled.

b. Click on Deploy All in the Channel Tasks Window

c. They will disappear from the Status window (this is normal)

7) Starting and stopping a channel

a. Click on Status in the Mirth window

b. You will see the channel that you just published and it will show Stopped

c. Right click on the stopped channel and choose start channel i. The status should change to Started and become green.

Verify that everything is working.

1) Copy your HL7 message (the file) into the directory that you indicated would be the inbound (pickup) directory)

2) Mirth will pick the file up and the Received and Sent counter will increase (they should increase in lock step)

a. It might take a few moments for the counters to change.

3) Once the counters have increased, open your database and check that the data is in the appropriate fields.

Status Panel Status Panel Status Table

Status The state of the channel that is deployed. It is either in a started, stopped, or paused state.

The name of the channel that is deployed.

Received

The number of messages received by this channel.

The number of messages sent by this channel.

Errors The number of messages that caused an error on this channel.

System Events

Filter by

A user may change the data in this form to filter the system events corresponding to the it.

Event Table Event ID The ID of the event in the system.

Date The exact time that the event occurred.

Level The importance of the event.

Event The actual event that happened.

Event ID The ID of the event in the system.

Description

When selecting an event in the event table, a detailed description of that event will appear in this pane. Message Browser

Filter by

A user may change the data in this form to filter the messages corresponding to the it.

Message Table

Message ID The ID of the message in the system.

Channel ID The channel that the message went through.

Date The exact time of the message passing through the channel.

Sending Facility The facility that sent the message.

Event The message trigger and event type (ADT, ORU, etc).

Control ID The ID of the control in the system.

Status Whether the message was RECEIVED, SENT, TRANSFORMED, FILTERED, or ERRORED.

Description

When selecting a message in the message table, a detailed description of that message will appear in this pane.

ER7 The ER7 representation of the selected message.

XML The XML representation of the selected message.

HL7 A tree representation of the HL7 from the selected message.

< Prev Next > Status

Whether or not the channel is enabled or disabled. Enabled means that it will be deployed when the channels are deployed and disabled means that it won't.

Direction

If inbound, the server will listen for HL7 messages or read them from a file and transform them for use by other systems, or into different HL7 messages. If outbound, The server will read data from a database and create HL7 messages.

If broadcast, single HL7 data feed that will be filtered, transformed, and broadcast to several systems. If router, Single HL7 data feed that will be routed to several systems which require their own unique filtering and transformation. Data may also be also transformed and written to a data source such as a database or a file system. Application integration is not supported yet.

The name of the channel.

< Prev Next >

Transformer Editor Transfomer Editor Reference Panel

Variables & Functions

Variables and functions available to the user at all times.

Database Variables

Fields accessed via the SQL SELECT statement for this channel.

HL7 Tree

A draggable reference tree that is build dynamically from a given HL7 message.

HL7 Message Template A place to write or paste an HL7 message for parsing into a tree.

Step Table

The sequence number of the step.

The name of the step.

The type of step to execute.

HL7 Message Builder

A panel for building mappings based on HL7 message segments.

Mapper

A panel for binding mappings to variables.

JavaScript A panel for writing custom javascript.

< Prev Next > Filter Editor Filter Editor Reference Panel

Variables & Functions Variables and functions available to the user at all times.

Database Variables Fields accessed via the SQL SELECT statement for this channel.

HL7 Tree A draggable reference tree that is build dynamically from a given HL7 message.

HL7 Message Template A place to write or paste an HL7 message for parsing into a tree.

Step Table

# The sequence number of the rule.

Operator AND or OR - the logical way to bind the give rules.

Script The javascript to execute for that given rule; edited in the JavaScript panel.

Javascript Panel A panel for writing custom javascript.

< Prev Next > Channel Editor Channel Editor Summary

This tab presents the main information about the channel. The channel's name and description are editable, while the direction and pattern displayed are configured during new channel creation. The channel may be enabled by from this page by checking the 'Enabled' checkbox. If the channel receives messages pre-encoded in XML rather than ER7 then 'Channel will receive XML pre-encoded HL7 messages' should be checked. Source

File Reader

Directory to Read

The directory containing the file to be read.

Polling Frequency

The delay in milliseconds that will be used during two subsequent polls to the database.

Move-to Pattern

Pattern to rename files that are moved. ${DATE} : the currrent date in the format dd-MM-yy_HH-mm-ss ${DATE:yy-MM-dd} : the current date using the specified format ${SYSTIME} : The current system time milliseconds ${UUID} : A generated Universally unique id ${ORIGINALNAME} : The origial file name if the file being written was read from another location ${COUNT} : An incremental counter

Move-to Directory

The directory where the file should be moved when done processing.

Delete File After Read

Choose 'Yes' to delete the file after it is read, or 'No' to keep it.

Check File Age Check the file age before processing.

File Age

If "Check File Age" is selected, check that the file is at least this many days old.

Database Reader

Driver

The type of database driver used for this reader.

Database URL

The URL for the driver to use to connect to the database.

Username

The username used to access the database.

Password

The password to authenticate the given username.

Polling Frequency

The delay in milliseconds that will be used during two subsequent polls to the database.

SQL Statement

The SQL statement to execute.

Run On-Update SQL

Choose 'Yes' to execute an SQL statement after an update.

On-Update Statement

An SQL statement to execute after an update has occurred.

LLP Listener

Listener IP Address The address for the LLP Listener to listen on.

Listener Port

The port to listen on.

Receive Timeout

The amount of time to wait, in milleseconds, for receipt of a message.

Buffer Size

The buffer size to use for receiving messages.

Keep Connection Open

Choose 'Yes' to keep the connection open after receipt of message or 'No' to have the connection close.

Start of Message Character

The character expected at the beginning of a message. (hexadecimal)

End of Message Character

The character expected at the end of a message. (hexadecimal)

Field Seperator

The character used to delimit fields. (hexadecimal)

Record Seperator

The character used to delimit records. (hexadecimal)

Send ACK Choose 'Yes' to explicitly send an ACK after receipt, 'No' to not send an ACK, or 'Auto' to let the system decide.

Destinations

File Writer Directory

The director to where the file will be written.

File Name

The name of the file to be written.

Append to File

If a file with the given name already exists, choose 'Yes' to append the data to the end or 'No' to overwrite the file.

File Template

A template referencing transformer variables and written to the file.

Database Writer

Driver

The type of database driver used for this reader.

Database URL

The URL for the driver to use to connect to the database.

Username

The username used to access the database.

Password

The password to authenticate the given username.

SQL Statement

The SQL statement to execute.

LLP Sender

Host IP Address

The address for the LLP Sender to use. Listener Port

The port used to make the connection.

Send Timeout

The amount of time to wait, in milleseconds, for a message to be sent successfully.

Buffer Size

The buffer size to use for sending messages.

Keep Connection Open

Choose 'Yes' to keep the connection open after message sent or 'No' to have the connection close.

Start of Message Character

The character expected at the beginning of a message. (hexadecimal)

End of Message Character

The character expected at the end of a message. (hexadecimal)

Field Seperator

The character used to delimit fields. (hexadecimal)

Record Seperator

The character used to delimit records. (hexadecimal)

Next < Prev >

Administration Administration Users

This page maintains the user accounts on the server. New accounts can be created and existing accounts can be editted or deleted. It is required that at least one user accound exists on the server at all times. Client Settings

Status refresh interval (in seconds) This specifies how often the status panel refreshes automatically.

Alternate row highlighting in tables Determines whether or not alternate rows in all tables in the program are highlighted. Server Settings

Email Alert Settings The SMTP Host specifies the server that will send out the email alerts.

The SMTP Port specifies the port to use on the SMTP Host.

Require Authentication specifies whether or not the SMTP server needs a valid user account to send an email.

If Require Authentication is enabled, the Username needs to be specified in order to determine what username will be used on the SMTP Host.

If Require Authentication is enabled, the Password needs to be specified in order to determine what password will be associated with the username on the SMTP Host.

< Prev Next >

Quickstart Guide Quickstart Guide

Step 1

Download and install Java 5.0. See installation instructions here . Step 2

Run Mirth.bat if in Windows. If running Linux/Unix, first set the permission by running chmod +x Mirth.sh, the run ./Mirth. Step 3

Point your browser to http://localhost:8080 and click the button to launch the Mirth Administrator client. Allow the webstart application to run, despite certificate warnings. Step 4

Once the login screen appears, you may login to the Mirth server. The server address is https://localhost:8443. The default username is 'admin' and the default password is 'admin'. The default password should be changed in the Administrative Panel.

< Prev