Shamil Nizamov Unofficial Mirth Connect v3.0 Developer’s Guide* * Preview Edition
Dec 15, 2014
Shamil Nizamov
Unofficial Mirth Connect v3.0
Developer’s Guide* * Preview Edition
Introduction 2
Copyright Page
Copyright © 2013 by Shamil Nizamov
Cover image copyright © 2013 by Shamil Nizamov
All rights reserved. No part of the contents of this book may be reproduced or
transmitted in any form or by any means without the written permission of the author.
Mirth Connect is the trademark of the Mirth Corporation Company. HL7 and Health Level
Seven are registered trademarks of Health Level Seven International. All other marks are
property of their respective owners.
Any rights not expressly granted herein are reserved.
The companies, organizations, products, domain names, email addresses, logos, people,
places, and/or data mentioned herein in examples are fictitious. No association with any
real company, organization, product, domain name, email address, logo, person, place,
or data is intended or should be inferred.
This book expresses the author’s views and opinions. The information contained in this
book is provided without any express, statutory, or implied warranties. Neither the
author, Mirth Corporation, Health Level Seven International, nor resellers, or distributors
will be held liable for any damages caused or alleged to be caused either directly or
indirectly by this book.
* This is a preview edition of the book.
3 Introduction
Contents
PART 1 MIRTH CONNECT BASICS
Chapter 1 Getting Started ................................................................................................................. 11
Installation ........................................................................................................................ 11
Mirth Connect Administrator ........................................................................................... 12
Chapter 2 What is a Channel? ........................................................................................................... 14
Connectors ........................................................................................................................ 15
Filters ................................................................................................................................ 15
Transformers ..................................................................................................................... 16
Scripts................................................................................................................................ 17
Chapter 3 Creating a Channel ........................................................................................................... 19
Source Connector ............................................................................................................. 20
Destination Connectors .................................................................................................... 21
Testing the Channel .......................................................................................................... 25
Global Scripts .................................................................................................................... 28
Code Templates ................................................................................................................ 31
PART II GENERIC ELIGIBILITY SERVICE IMPLEMENTATION
Chapter 4 Generic Eligibility Service Introduction ........................................................................... 34
Eligibility Service Introduction .......................................................................................... 34
Scenario Overview ............................................................................................................ 35
Messages and Interactions Overview ............................................................................... 36
Eligibility Query Channels Overview ................................................................................. 37
Chapter 5 Sender Channel ................................................................................................................ 40
Summary Tab .................................................................................................................... 40
Source Tab ........................................................................................................................ 42
Destinations Tab ............................................................................................................... 42
Channel Implementation Verification .............................................................................. 45
Chapter 6 HL7v2 to HL7v3 Transformation Channel ........................................................................ 48
Summary Tab .................................................................................................................... 48
Introduction 4
Source Tab ........................................................................................................................ 49
Destinations Tab ............................................................................................................... 51
Code Templates ................................................................................................................ 58
Scripts................................................................................................................................ 58
Channel Implementation Verification .............................................................................. 59
Chapter 7 Logging Channel ............................................................................................................... 60
Summary Tab .................................................................................................................... 60
Source Tab ........................................................................................................................ 61
Destinations Tab ............................................................................................................... 62
Code Templates ................................................................................................................ 67
Global Scripts .................................................................................................................... 67
Channel Implementation Verification .............................................................................. 69
Chapter 8 HL7v3 Verification Channel .............................................................................................. 71
Summary Tab .................................................................................................................... 72
Source Tab ........................................................................................................................ 72
Destinations Tab ............................................................................................................... 74
Code Templates ................................................................................................................ 80
Global Scripts .................................................................................................................... 81
Scripts................................................................................................................................ 82
Channel Implementation Verification .............................................................................. 84
Chapter 9 Response Channel ............................................................................................................ 85
Summary Tab .................................................................................................................... 85
Source Tab ........................................................................................................................ 86
Destinations Tab ............................................................................................................... 88
Scripts................................................................................................................................ 91
Channel Implementation Verification .............................................................................. 91
Chapter 10 HL7v3 to HL7v2 Transformation Channel ....................................................................... 93
Summary Tab .................................................................................................................... 93
Source Tab ........................................................................................................................ 94
Destinations Tab ............................................................................................................... 94
Channel Implementation Verification .............................................................................. 97
5 Introduction
PART III ACKNOWLEDGEMENTS IMPLEMENTATION
Chapter 11 Acknowledgements Introduction .................................................................................... 99
Scenario Overview ............................................................................................................ 99
Acknowledgement Channels Overview .......................................................................... 100
Chapter 12 HL7v2 ACK Channel ........................................................................................................ 102
Summary Tab .................................................................................................................. 102
Source Tab ...................................................................................................................... 103
Destinations Tab ............................................................................................................. 103
Scripts.............................................................................................................................. 104
Chapter 13 HL7v3 ACK Channel ........................................................................................................ 106
Summary Tab .................................................................................................................. 106
Source Tab ...................................................................................................................... 106
Destinations Tab ............................................................................................................. 107
Scripts.............................................................................................................................. 108
Chapter 14 HL7v3 Verification Channel ............................................................................................ 110
Destinations Tab ............................................................................................................ 110
Code Templates .............................................................................................................. 112
Scripts.............................................................................................................................. 114
Source Tab ...................................................................................................................... 114
Chapter 15 HL7v2 to HL7v3 Transformation Channel ACK ............................................................. 116
Destinations Tab ............................................................................................................ 116
Code Templates .............................................................................................................. 119
Scripts.............................................................................................................................. 120
Source Tab ...................................................................................................................... 121
Channel Implementation Verification ............................................................................ 121
Chapter 16 Sender Channel ACK ...................................................................................................... 123
Destinations Tab ............................................................................................................ 123
Channel Implementation Verification ............................................................................ 124
Introduction 6
PART IV DEBUGGING JAVASCRIPT
Chapter 17 Debugging JavaScript in Mirth Connect ........................................................................ 126
Built in Logger function .................................................................................................. 126
Rhino JavaScript Debugger in Standalone Mode ............................................................ 127
Rhino JavaScript Debugger in Embedded Mode............................................................. 128
Eclipse JSDT Debugger in Embedded Mode ................................................................... 132
PART V APPENDICES
A: Eligibility Query Request (QUCR_IN200101) template .............................................. 138
B: Eligibility Query Results (QUCR_IN210101) template ................................................ 139
C: MS Access Log database structure ............................................................................. 140
D: PostgreSQL Eligibility database structure................................................................... 140
E: XSLT to transform from HLv3 to HL7v2 ....................................................................... 141
F: JavaScriptTask.java ...................................................................................................... 142
G: Archives content ......................................................................................................... 144
7 Introduction
Introduction
Introduction As Mirth Corporation says on their web-site, “Mirth Connect is the Swiss Army knife of
healthcare integration engines, specifically designed for HL7 message integration. It
provides the necessary tools for developing, testing, deploying, and monitoring interfaces.
And because it’s open source, you get all of the advantages of a large community of users
with commercial quality support.”
In addition to that “The 2012 HL7 Interface Technology Survey Results” show that Mirth
Connect is one of the fast growing healthcare messaging platforms due to open source
paradigm, robust functionality for HL7 messaging and X12 documents. Mirth Connect
also speeds up the development of interfaces for data exchange across different formats
and diverse healthcare systems environment.
The focus of this book is to introduce a version 3.x of the Mirth Connect to the point
when readers will gain confidence to start building their own healthcare data exchange
interfaces.
As you read this book, you will be implementing fictitious Eligibility Query Service. Each
connection point (channel) is explained in a separate chapter, which in turn provides
step-by-step instruction how to create and code data transformation rules.
This book is written using the Mirth Connect 3.0.0.6931 version of the product.
Consequently, other releases may include new features, or features used in this book
may change or disappear. Be aware that you might also notice some differences
between screen shots provided here and actual ones.
Who is this book for
I wrote this book primarily for application developers and system integrators who have
found the online Mirth Connect documentation lacking and needed a guidebook that
explained things in more detailed and organized way.
In a book of this size, I cannot cover every feature that Mirth Connect v3.x or previous
versions have; consequently I assume you have some familiarity with Mirth Connect
already.
Introduction 8
Assumption
This book assumes that you are dealing with applications using message-oriented
middleware products and expects that you have at least a minimal understanding of
Web service technologies including, but are not limited to, XML, XML Schemas, XPath,
XSL Transformation and SOAP/WSDL.
Before you start reading this book, you should have a basic knowledge of JavaScript and
Java; MS Access and PostgreSQL databases from a database administrator perspective;
and familiar with operating system environment variables settings.
You also have basic knowledge of HL7, the standard that is being used to exchange
healthcare data, both version 2 and version 3.
Who should not read this book?
As mentioned earlier, the purpose of this book is to provide the reader with a high-level
preview of the capabilities and features associated with Mirth Connect v3.0. This book is
not intended to be a step-by-step comprehensive guide or substitute of any kind to
original training and certification programs provided by the Mirth Corporation.
This book is also not a tutorial on a specific messaging or middleware technology
implementation. All examples included in this book are for illustrative purposes only. If
you are interested in learning more about any of specific technologies or products,
please refer to one of the many on-line resources.
This book does not cover any specific installation, configuration, deployment and
monitoring activities for system administrators.
Errata and Book Support
I have made every effort to ensure the accuracy of this book and its companion content.
If you find an error, please report through email - [email protected].
Warning and Disclaimer
The purpose of this book is to educate and entertain. Every effort has been made to
make this book as complete and as accurate as possible, but no warranty or fitness is
implied.
The information is provided on an “as is” basis. The author shall have neither liability nor
responsibility to any person or entity with respect to any loss or damage caused, or
9 Introduction
alleged to be caused, directly or indirectly by the information contained in this book or
from the use of software mentioned in this book. The information, methods and
techniques described by the author are based on his own experience. They may not work
for you and no recommendation is made to follow the same course of action. No
representation is made that following the advice in this book will work in your case.
The author is not an employee or a representative of the Mirth Corporation and never
has been, and author’s views and opinions are not necessarily those of the Mirth
Corporation. This book is not based on trainings or certifications provided by the Mirth
Corporation.
This book contains links to third-party Web sites that are not under the control of the
author, and the author is not responsible for the content of any linked site. If you access
a third-party website mentioned in this book, then you do so at your own risk. The
author provides these links only as a convenience, and the inclusion of the link does not
imply that the author endorses or accepts any responsibility for the content of those
third-party sites.
Furthermore, the book contains information on the subject only up to the published
date.
PART I – MIRTH CONNECT BASICS 10
PART I – MIRTH CONNECT BASICS
Mirth Connect Basics
CHAPTER 1 Getting Started
CHAPTER 2 What is a Channel?
CHAPTER 3 Creating a Channel
11 PART I – MIRTH CONNECT BASICS
CHAPTER 1 Getting Started
Getting Started his chapter outlines the Mirth Connect basic installation procedure. All examples in
this book are based on a Windows version of the Mirth Connect RC1 v3.0, which you
can download at http://www.mirthcorp.com/community/downloads.
Make sure your computer meets minimum system requirements before you start:
Sun Java JRE 1.5/5.0 or newer;
1 GB of RAM is recommended;
A web browser.
Installation
There are two possible ways to install the Mirth Connect based on what package you
have downloaded or what package is available on the website. In one case, the package
is an archive of all files and classes that you need to run Mirth Connect on your
computer. You simply unzip and copy such package to an appropriate folder, for
example C:\Program Files\Mirth Connect\. In another case, there is a GUI based
installer that you just start and go through the steps in the installation wizard. The
installation process itself is quite straight forward.
In both cases what will be installed are Mirth Connect Server, Mirth Connect Server
Manager, Mirth Connect Administrator and Mirth Connect Command Line Interface.
During the installation you have to decide which port will be used by the Mirth Connect.
By default it is 8080 for the unsecure communication and 8443 for the SSL connection.
You might change it later using the Mirth Connect Server Manager.
To verify the installation:
Launch the Mirth Connect Server either through the Mirth Connect Server Manager
or Mirth Connect Command Line;
Open the web browser and type localhost:8080 in the address bar;
Click Access Secure Site under the Web Dashboard Sign in;
Type “admin” for the user name and repeat “admin” as the password, click Sign in.
If you see the Dashboard statistics page with, most likely, no channels available, you have
successfully done the installation and ready to continue.
T
PART I – MIRTH CONNECT BASICS 12
If not, follow this link to troubleshoot -
http://www.mirthcorp.com/.../mirth/Mirth+Connect+FAQ.
Configuration
The Mirth Connect Server Manager can be used as a single point to launch Mirth
Connect Service, configure ports, allocated memories, and database connections; but
fully fledged configuration description goes beyond the scope of this book.
Here is only a recommended step to add a path to the \custom-lib folder to your
operating system’s CLASSPATH environment variable. This is the folder where you put
your Java classes, libraries and other required files.
Previous versions of Mirth Connect were using port 1099 for viewing statistics though
JMX (Java Management Extensions) and RMI (Remote Method Invocation) interfaces. It is
not confirmed if this port is still in use. Anyway, if any of your applications or firewall is
utilizing ports 8080, 8443 or 1099 you can either change that by using Mirth Connect
Server Manager or manually in the configuration files located in
\conf\mirth.properties. Restart the Mirth Connect for changes to make effect.
Mirth Connect Administrator
The Mirth Connect Administrator is a Java application that is not explicitly installed on a
local computer by default in a distributed environment, and need to be downloaded
from the Mirth Connect Server. The reason for that is to install the Mirth Connect
Administrator that matches the version of the Mirth Connect Server.
In order to download the Mirth Connect Administrator:
Start the Mirth Connect Server if it is not already running as the service;
Open the web browser;
Type localhost:8080 in the address bar;
Click Launch Mirth Connect Administrator under the Mirth Connect Administrator;
Click Ok to open the webstart.jnlp;
Type “admin” for the user name and repeat “admin” as the password in the Mirth
Connect Login pop-up window, click Login.
If everything is done correctly, every time you login, you will see the Dashboard as an
initial screen. The Dashboard displays two areas of information:
Channels status and statistics - the number of messages Received, Filtered,
Queued, Sent, and Errored. The Dashboard Tasks area on the navigation bar on the
13 PART I – MIRTH CONNECT BASICS
left side has essential for channels development menu items such as Refresh, Send
Messages, Remove All Messages. Same menu items can be accessed faster by the
right-click on a channel row.
Logs – Server Log and Connection Log. The former - Server Log - is used a lot to
debug channels development. Double-clicking on a Server Log entry brings pop-up
window to view and copy the entire log entry content. The Server Log is stored by
the Mirth Connect Server in the memory and therefore closing and opening the
Mirth Connect Administrator brings back all entries not previously explicitly purged.
To clear the Server Log click Clear Displayed Log under the Server Log or Connection
Log area.
Logging Level
Channel’s log level can be configured manually by changing \conf\log4j.properties
entries. Available options are: ERROR, WARN, INFO, DEBUG, TRACE with DEBUG selected
by default. Log levels may be configured separately for filters, transformers,
postprocessors and other scripts that will be explained later in this book.
FIGURE 1-1 Mirth Connect Administrator window when launched with no channels available
Familiarize yourself with other navigation items and tabs since this will be the main tool
to develop channels throughout this book.
PART I – MIRTH CONNECT BASICS 14
CHAPTER 2 What is a Channel?
What is a Channel? he Channel is an essential part of the Mirth Connect and can be seen as one to many
abstract unidirectional pipes to decouple components from each other to transfer
healthcare data between two or more applications. The channels architecture
implemented in the Mirth Connect allows dividing a large message processing task into
a sequence of smaller independent steps. This affords developers the flexibility for
dependency, maintenance or performance. Some of the processing tasks can even be
external to the Mirth Connect and developed independently.
FIGURE 2-1 Mirth Connect abstract channel architecture
In general, each Channel consists of connectors both inbound and outbound, filters and
transformers. The Connector that receives inbound messages from the Sending
Application is called Source. Similarly, the Connector that sends outbound messages is
called Destination. From the Source Connector the data is passed through the channel,
where filters and transformers perform operations on the data, for example routing the
message to one or another Destination Connector, and transforming the data
representation. Deciding a channel is when wearing an analyst's hat comes into play.
Before you create a new channel, you need to elicit following requirements:
Type of the Application the Channel reads data from (Source Connector type);
Type of the Application the Channel sends data to (Destination Connector type);
Type and the format of the inbound message;
Type and the format of the outbound message(s);
Mapping table(s) between inbound and outbound messages (Transformation).
T
15 PART I – MIRTH CONNECT BASICS
Connectors
In terms of Enterprise Integration, the Connector is a Message Endpoint that specifies a
particular way or, better saying, protocol the Mirth Connect should be using to
communicate with external application or another Mirth Connect channel.
The Mirth Connect supports sending and receiving messages over a variety of
Connectors listed here in no particular order:
TCP/MLLP;
Database (MySQL, PostgreSQL, Oracle, Microsoft SQL Server, ODBC);
File (local file system and network shares);
PDF and RTF documents;
JMS;
FTP/SFTP;
HTTP (note that HTTPS is not supported in the free version);
SMTP;
SOAP (over HTTP).
The Connector receiving the data is called a Reader, for example the MLLP Reader.
Consequently, the Connector that sends the data is called a Writer, the Database Writer
as an example.
Connector types are configured under Source and Destination tabs of the Channel, which
will be explained later in this chapter. It should be obvious, that whereas some settings
are common across all Connectors, some are unique to a specific Connector type.
If connectors, shipped with the Mirth Connect installation package, are not enough you
can develop your own one (thus the custom HTTPS connector implementation).
However, templates and developer’s level documentation for such development are out
of scope of this edition of the book.
Filters
In a real world scenario, when numerous applications and channels are connected, the
Channel may receive messages from several sources, and therefore these messages may
have to be processed differently based on the message type or other criteria.
There are two paradigms to solve this problem, thus by a Router or by a Filter:
PART I – MIRTH CONNECT BASICS 16
Router connects to multiple outbound channels. The key benefit of using the Router
is that the decision criteria for the destination of a message are maintained in a
single location.
Filter, this is what Mirth Connect uses, is built in into a message processing
mechanism and is responsible for determining whether the message should be
processed or not. The Filter does that by inspecting message properties (segments or
elements) without removing the message from the message queue. If the message
cannot be consumed by this particular pipe it is returned back to the queue
unchanged for another pipe to check out.
Filters can be as simple as specific field comparison against a hard coded value or as
complex as JavaScript scripts and external Java classes. Filter can even be omitted at all
allowing all messages to path through.
So if a single Channel should process more than one type of messages, you can create
any number of separate pipes (they are called Destinations) and specify none, one or
more filters for each of them.
Transformers
More often than not, messages are sent between legacy systems, custom applications,
and third-party solutions, each of which is built around a proprietary data model. Even
systems that claim to support a single standard may place specific requirements on the
data format and content. With an every new business requirement proposed, if we could
bring all legacy systems to a single format that would solve our issues. Unfortunately, for
the most legacy systems data format, content or data sequence changes are difficult and
risky, and simply not feasible.
How to communicate data using different formats then? In the Mirth Connect this is
done by a message Transformer that translates one data format into another. As a result,
a destination application expects to receive messages it understands which can be later
converted and stored in the application’s internal data format.
The Mirth Connect allows the message translation to occur at different levels, as well as
to chain message transformers to achieve a required result.
Supported Transformers are:
Message Builder is used to map segments of the inbound message to segments in
the outbound message.
17 PART I – MIRTH CONNECT BASICS
Mapper maps segments of the inbound message to internal Mirth Connect variables.
These variables may be used later.
External Script, as the name suggests, employs external JavaScripts to transform or
map the data.
XSLT Step is to utilize the XSL transformation.
JavaScript, along with the External Script, is where the flexibility comes into play.
Here any types of (Rhino) Java Scripts and Java codes can be used.
Scripts
Channels also support unique features called scripts to enhance the message processing
logic. Scripts apply to a channel itself and all messages that are passing through.
These scripts are:
Deploy script is executed each time when the Mirth Connect Server starts or a
Channel is redeployed. This is a best place to initialize variables or create class
objects.
Attachment script deals with a message in a native format and allows extracting a
part of the message to store it as an attachment or irrevocably modify a message.
Preprocessor script also allows handling each message in a native format before
Mirth Connect starts translating it into the internal format that is XML.
Postprocessor script is executed after the message has been successfully sent.
Shutdown script is launched each time when the Mirth Connect Server stops. This is
the place to release memories previously allocated by classes required for the
Channel.
Scripts are performed in a following order:
1. Deploy (once, when Mirth Connect is started or a Channel is re/deployed) ;
2. Attachment script;
3. Preprocessor script;
4. Source Connector Filters script;
5. Source Connector Transformer script or mapping;
6. Destination 1 Connector Filters script;
7. Destination 1 Connector Transformer script or mapping;
8. Destination N Connector Filters script;
9. Destination N Connector Transformer script or mapping;
10. Response 1 Transformer script or mapping;
11. Response N transformer script or mapping;
12. Postprocessor script;
PART I – MIRTH CONNECT BASICS 18
13. Shutdown (once, when a channel is undeployed).
When you create a Channel, by default, all scripts are empty and do nothing.
It is obvious that Deploy and Shutdown scripts are performed only once, when the
Channel is deployed or undeployed respectively. All others are performed every time a
message is sent through the Channel or acknowledgement is received. Further we will
explore each of these steps in detail.
19 PART I – MIRTH CONNECT BASICS
G: Archives content
There are two archives provided with this book each of which contains a complete set of
files required for Part II and Part III implementations.
Eligibility.6931.NoNACK.zip
Folder Files Comment
Channels Code Template.xml
Global Script.xml
HL7v3 Verification.xml
Logging Channel.xml
Response Channel.xml
Sender Channel.xml
v2 - v3 Transformation.xml
v3 - v2 Transformation Channel.xml
Channels, code templates and
global scripts for Part II
implementation.
custom-lib .... Custom-lib folder for Mirth Connect
Server installation.
DB PostgreSQL-Eligibility DB.sql
QBP_Log.accdb
PostgreSQL patients database
MS Access Log database
HL7v2\Samples QBP-45_Malformed.hl7
QBP-45_Request.hl7
RSP-45_Error.hl7
RSP-45_Success.hl7
HL7v2\Templates RSP-45_Template.hl7
RSP-45_XML.xml
HL7v2\XSLT QUCR-RSP.xslt
HL7v3 NE2012 .... Schemas for HL7v3 messages
HL7v3 NE2012\-
Samples_Annotated
QUCR_IN200101UV01_Request_Annotated.xml
QUCR_IN210101UV01_Error_Annoteated.xml
QUCR_IN210101UV01_Success_Annotated.xml
HL7v3 NE2012\-
Templates
MCCI_IN000002_template.xml
QUCR_IN200101_template.xml
QUCR_IN210101_template.xml
Eligibility.6931.ACK-NACK.zip
Folder Files Comment
Channels Code Template.xml
Global Script.xml
HL7v2 ACK Channel.xml
HL7v3 ACK Channel.xml
Logging Channel.xml
Sender Channel.xml
v2 - v3 Transformation Channel.xml
v3 Verification Channel.xml
Channels, code templates and
global scripts for Part III
implementation.
custom-lib .... Custom-lib folder for Mirth Connect
Server installation.
PART I – MIRTH CONNECT BASICS 20
DB PostgreSQL-Eligibility DB.sql
QBP_Log.accdb
PostgreSQL patients database
MS Access Log database
HL7v2\Samples ACK-A01_Negative.hl7
ACK-A01_Positive.hl7
QBP-45_Malformed.hl7
QBP-45_Request.hl7
RSP-45_Error.hl7
RSP-45_Success.hl7
HL7v2\Templates RSP-45_Template.hl7
RSP-45_XML.xml
HL7v2\XSLT QUCR-RSP.xslt
HL7v3 NE2012 .... Schemas for HL7v3 messages
HL7v3 NE2012\-
Samples_Annotated
MCCI_IN000002UV01.xml
QUCR_IN200101UV01_Request_Annotated.xml
QUCR_IN210101UV01_Error_Annoteated.xml
QUCR_IN210101UV01_Success_Annotated.xml
HL7v3 NE2012-
\Templates
MCCI_IN000002_template.xml
QUCR_IN200101_template.xml
QUCR_IN210101_template.xml
Other chapters, not included to this preview, cover implementation of
schema and schematron validation, XSL transformation, database
connect pool creation, acknowledgements implementation,
debugging and other related topics.
The rest of the book, including source codes and all related files,
can be downloaded from http://mirthconnect.isarp.com