Shamil Nizamov
Unofficial Mirth Connect v3.6
Developer’s Guide* * - Preview Version
Copyright Page Copyright © 2013-2018 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 a trademark of Mirth Corporation. 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 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. The author, Mirth Corporation, Health Level Seven International, resellers and distributors will NOT be held liable for any damages caused or alleged to be caused either directly or indirectly by this book.
This is a preview version of the book.
Introduction
2
Contents PART 1
MIRTH CONNECT BASICS
Chapter 1
Getting Started ................................................................................................................. 15 Installation ........................................................................................................................ 15 Mirth Connect Administrator ........................................................................................... 16
Chapter 2
What is a Channel? ........................................................................................................... 18 Connectors ........................................................................................................................ 19 Filters ................................................................................................................................ 19 Transformers ..................................................................................................................... 20 Scripts................................................................................................................................ 21
Chapter 3
Creating a Channel ........................................................................................................... 23 Source Connector ............................................................................................................. 24 TMP, MSG and MESSAGE .................................................................................................. 25 Destination Connectors .................................................................................................... 27 Testing the Channel .......................................................................................................... 31 Global Map, Global Channel Map, Channel Map .................. ........................... .................. .................. .................. ................ ....... 34 Global Scripts .................................................................................................................... 36 Code Templates ................................................................................................................ 38
PART II
GENERIC ELIGIBILITY SERVICE IMPLEMENTATION
Chapter 4
Generic Eligibility Service Introduction ........................................................................... 42 Eligibility Service Introduction .......................................................................................... 42 Scenario Overview ............................................................................................................ 43 Messages and Interactions Overview ......................... ................................... ................... .................. .................. .................. ................. ........ 44 Eligibility Query Channels Overview ................................................................................. 45
Chapter 5
Query Sender Channel ..................................................................................................... 48 Summary Tab .................................................................................................................... 48 Source Connector ............................................................................................................. 50 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... ..................... ... 50 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. .............. ..... 54
3
Introduction
Chapter 6
HL7v2 to HL7v3 Transformer Channel ............................................................................. 57 Summary Tab .................................................................................................................... 57 Source Connector ............................................................................................................. 58 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... ..................... ... 60 Code Templates ................................................................................................................ 66 Scripts................................................................................................................................ 67 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. .............. ..... 68
Chapter 7
Data Logger Channel ........................................................................................................ 69 Summary Tab .................................................................................................................... 69 Source Connector ............................................................................................................. 70 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... ..................... ... 71 Code Templates ................................................................................................................ 76 Global Scripts .................................................................................................................... 76 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. .............. ..... 78
Chapter 8
HL7v3 Verification Verificati on Channel .............................................................................................. 80 Summary Tab .................................................................................................................... 81 Source Connector ............................................................................................................. 81 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... ..................... ... 84 Code Templates ................................................................................................................ 90 Global Scripts .................................................................................................................... 91 Scripts................................................................................................................................ 92 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. .............. ..... 93
Chapter 9
Response Sender Channel ................................................................................................ 96 Summary Tab .................................................................................................................... 96 Source Connector ............................................................................................................. 97 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... ..................... ... 99 Scripts.............................................................................................................................. 102 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. ............ ... 103
Chapter 10
HL7v3 to HL7v2 Transformer Channel .......................................................................... 105 Summary Tab .................................................................................................................. 105 Source Connector ........................................................................................................... 106 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 106 Introduction
4
Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. ............ ... 109
PART III
ACKNOWLEDGEMENTS IMPLEMENTATION
Chapter 11
Acknowledgements Acknowledgements Introduction .................................................................................. 112 Scenario Overview .......................................................................................................... 112 Acknowledgement Channels Overview .................. ........................... .................. .................. .................. .................. ................... ............ 113
Chapter 12
HL7v3 ACK Channel ........................................................................................................ 115 Summary Tab .................................................................................................................. 115 Source Connector ........................................................................................................... 116 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 116 Scripts.............................................................................................................................. 117
Chapter 13
HL7v3 Verification Verificati on ACK Channel .................................................................................... 119 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 119 Code Templates .............................................................................................................. 122 Scripts.............................................................................................................................. 123 Source Connector ........................................................................................................... 124
Chapter 14
HL7v2 to HL7v3 Transformer ACK Channel .................................................................. 125 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 125 Code Templates .............................................................................................................. 128 Scripts.............................................................................................................................. 129 Source Connector ........................................................................................................... 130 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. ............ ... 131
Chapter 15
Query Sender ACK Channel ........................................................................................... 132 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 132 Source Connector ........................................................................................................... 134 Channel Implementation Verification .................. ........................... ................... ................... .................. .................. .................. ............ ... 136
PART IV
DICOM
Chapter 16
DICOM Storage SCU ...................................................................................................... 138 Scenario Scenar io Overview Overv iew ............................................. ........................... ................................... ................................... ................................... ......................... ........ 138 Summary Tab ............................................ ........................... ................................... ................................... .................................. .................................. ................. 140 Source Connector ........................................................................................................... 141 Destinations Desti nations Connector Connec tor ..................................... ................... ................................... ................................... .................................... ......................... ....... 142
5
Introduction
Chapter 17
DICOM Storage SCP ....................................................................................................... 143 Summary Tab ............................................ ........................... ................................... ................................... .................................. .................................. ................. 144 Source Connector ........................................................................................................... 145 Destinations Desti nations Connector Connec tor ..................................... ................... ................................... ................................... .................................... ......................... ....... 151 Code Templates Templat es ........................................ ....................... ................................... ................................... ................................... .................................. ................ 158 Scripts ............................................................................................................................. 158 Channels Implementation Verification ................. .......................... ................... ................... .................. .................. .................. ............ ... 158
PART V
ADVANCING IN MIRTH CONNECT
Chapter 18
Debugging JavaScript in Mirth Connect ........................................................................ 161 Built in Logger function .................................................................................................. 161 Rhino JavaScript Debugger in Standalone Mode .......... ................... .................. .................. .................. .................. .............. ..... 162 Rhino JavaScript Debugger in Embedded Mode................. Mode.......................... .................. .................. .................. ................. ........ 163 Eclipse JSDT Debugger in Embedded Mode ................... ............................ .................. .................. .................. .................. ............ ... 168 Console Input .................................................................................................................. 172
Chapter 19
Utilizing JMS (Java Message Service) Service ) ............................................................................ 174 Scenario Overview .......................................................................................................... 175 Sending Messages ........................................................................................................... 176 Sending Objects .............................................................................................................. 183 Channels Implementation Verification ................. .......................... ................... ................... .................. .................. .................. ............ ... 189
Chapter 20
Polling Web Services ..................................................................................................... 191 Scenario Overview .......................................................................................................... 191 Summary Tab .................................................................................................................. 192 Source Connector ........................................................................................................... 192 Destinations Desti nations Connector Connect or ........................................... ......................... ................................... ................................... .................................... .................... 193 Channels Implementation Verification ................. .......................... ................... ................... .................. .................. .................. ............ ... 199
Chapter 21
Building Extensions ....................................................................................................... 201 Creating Templates ......................................................................................................... 203 Signing Extension ............................................................................................................ 208 Deploying Extension ....................................................................................................... 210 Extension Implementation Verification .................. ........................... .................. .................. .................. .................. ................... ............ 211
Introduction
6
Chapter 22
Tuning Mirth Connect ................................................................................................... 213 Performance Tuning ....................................................................................................... 214 Security Protection ......................................................................................................... 219
Book Resources ........................................................................................................................................ 223
PART V
APPENDICES A: Eligibility Query Request (QUCR_IN200101) Template .......... ................... .................. .................. .................. ......... 225 B: Eligibility Query Results (QUCR_IN210101) Template .................. ........................... ................... ................... ........... 226 C: MS Access Log Database Structure ............ ..................... .................. .................. .................. .................. ................... ................... ........... 227 D: PostgreSQL Eligibility Database Structure ................... ............................ .................. .................. .................. ................... ............ 227 E: XSLT to transform from HL7v3 to HL7v2................. ........................... ................... .................. .................. .................. ............... ...... 228 F: JavaScriptTask.java ...................................................................................................... 230 G: Rhino Script Engine script samples ............................................................................ 233 H: Archives Content ........................................................................................................ 239
7
Introduction
Introduction
Introduction You might missed that, since NextGen’s parent company QSI acquired Mirth Corporation, when the latter was saying on their web-site that “Mirth Connect is the Swiss Army knife of healthcare integration integration engines, specifically specifically designed for 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.” support.” Mirth Connect, or NextGen Connect as it is called now, was and still is one of the fastest growing healthcare messaging platforms due to its open source paradigm, and 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. This book describes version 3.x of Mirth Connect to the point that reader are confident enough to start building their own healthcare data exchange interfaces and transforming various versions of HL7 messages. As you read this book, you will be implementing implementing a fictitious Eligibility Eligibility Query Service. Each connection point (channel) is explained in a separate chapter, which in turn provides step-by-step step-by-step instructions on how to create and code data transformation rules. This book is written using Mirth Connect 3.6.0 version of the product. Consequently, other releases may include new features, or features used in this book may change or disappear. You may also notice some differences between screen shots provided in the book and those you see when using Mirth Connect.
Who is this book for? I wrote this book primarily for application developers and system integrators who have found the online Mirth Connect documentation documentation lacking and needed a guidebook that explains things in a 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 already have some familiarity with Mirth Connect.
Introduction
8
Assumption This book assumes that you are dealing with applications that use message-oriented middleware products and expects that you have at least a minimal understanding of Web service technologies including, but 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 are familiarity with operating system environment variables settings. You should also have basic knowledge of HL7, the standard that is being used to exchange healthcare data, data, both version 2 and version 3; and DICOM, the standard for handling information in medical imaging.
Who should not read this book? As mentioned earlier, the purpose of this book is to provide the reader with a high-level overview of the capabilities and features associated with Mirth Connect v3.6. This book is not intended to be a step-by-step comprehensive comprehensive guide or substitute of any kind to original training and certification programs provided by Mirth Corporation (Quality Systems, Inc.). This book is also not a tutorial on a specific messaging or middleware technology implementation. implementation. All examples included in this book are for illustrative purposes only. If you are interested in learning more about a specific technology technology or product, please refer to one of the many on-line resources. This book does not cover any specific installation, configuration, deployment deployment or 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. 9
Introduction
The information 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 alleged to be caused, directly or indirectly by the information contained in this book or from the use of software mentioned 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 recomme r ecommendation ndation is made to follow the same course of action. No representation is made that following following the advice in this book will work in your case. The author is not an employee or representative of Mirth Corporation (NextGen Healthcare, Quality Systems, Systems, Inc.) and never has been, and author’s views author’s views and opinions are not necessarily those of Mirth Corporation. This book is not based on trainings or certifications certifications provided by Mirth Corporation (NextGen Healthcare , Quality Systems, Inc.). This book contains links to third-party websites 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. Engine” now. The Mirth Connect is officially called “NextGen “ NextGen® Connect Integration Engine” However, this book continues to use Mirth Connect for for breviety and familiarity. Furthermore, this book contains information on the subject only up to the published date.
Acknowledgements Like most books, this guide has been a long time in the making. I would like to acknowledge everyone everyone who has assisted in this project. I could not have done this without you. Nathan Blakley and Elliot Freedman volunteered to review early versions of a few chapters. Your feedback helped steer me in the right direction. I’d like to thank Philip Helger in making an active contribution to the development of the open source Schematron validator. My biggest thanks go to Wayne Zafft, who was incredibly gracious with his time and effort in reviewing the final version of the book.
Introduction
10
Roadmap This book is divided into five parts: Part 1 provides an introduction to Mirth Connect and a high-level overview of channels.
Chapter 1, Getting Started Introduces Mirth Connect at a high level, and demonstrates how to download and install Mirth Connect Server and Administrator.
Chapter 2, What is a Channel Provides an overview of the channel architecture implemented in Mirth Connect. It also covers a channel’s major components such as connectors, filters, filters, transformers and scripts.
Chapter 3, Creating a Channel Walks the reader through the creation and configuration of a simple channel. It covers some of the major points of the Mirth Connect channels implementation implementation model such as tmp and tmp and msg variables, msg variables, different types of maps and their visibilities. It also covers Global Scripts, channel scripts and Code Templates.
Part 2 focuses on the implementation implementation of an imaginary but complete eligibility service.
Chapter 4, Generic Eligibility Service Introduction Introduces the Eligibility Service as defined in the HL7v3 Normative Edition, presents the implementation plan and walks through the required components.
Chapter 5, Query Sender Channel Walks the reader through the implementation of the first channel in a chain that serves as an interface to send HL7v2 Eligibility Query messages.
Chapter 6, HL7v2-HL7v3 Transformer Channel Explains the implementation implementation of a channel that plays the role of a conduit or broker. The chapter shows how to establish a MLLP connection to other channels, how to filter messages based on some criteria and transform messages from one format to another using different techniques that Mirth Connect provides.
Chapter 7, Data Logger Channel Explains the implementation implementation of a channel that uses a file and MS Access database as destinations.
11
Introduction
Chapter 8, HL7v3 Verification Channel Walks the reader through the implementation implementation of the XML Schema and Schematron validators using external Java classes.
Chapter 9, Response Sender Channel Provides insight into implementation implementation of a database-facing channel that retrieves data, forms the message and passes it along using a SOAP connector.
Chapter 10, HL7v3 to HL7v2 Transformer Channel Concludes the implementation implementation of the Eligibility service and provides a detailed explanation on configuring the SOAP connector and XSL Transformation.
Part 3 is dedicated to the implementation of acknowledgements. acknowledgements.
Chapter 11, Acknowledgements Acknowledgements Introduction Provides introduction and presents the implementation plan of a message acknowledgement acknowledgement based on the Eligibility Service implemented implemented in Part 2.
Chapter 12, HL7v3 ACK Channel Explains how to create another interim channel that receives routed HL7v3 messages and stores them in a file.
Chapter 13, HL7v3 Verification ACK Channel Explains how to expand functionalities of the already existing channel to send HL7v3 MCCI acknowledgements.
Chapter 14, HL7v2 to HL7v3 Transformer ACK Channel Explains how to expand functionalities of the already existing channel to send HL7v2 RSP^E45 acknowledgements acknowledgements back and intercept HL7v3 acknowledgements received from other channels.
Chapter 15, Query Sender ACK Channel Explains how to intercept HL7v2 acknowledgements received from one channel and route them to another channel.
Part 4 covers topics related to DICOM.
Chapter 16, DICOM SCU Introduction
12
Provides a short introduction and presents the implementation implementation plan of a simplified DICOM router. Walks the reader through the implementation implementation of the first channel in a chain that serves as an interface to send DICOM messages. messages.
Chapter 17, DICOM SCP Provides an in-depth explanation of such important topics as parsing DICOM messages, extracting extracting objects from a PDF file, creating and deleting template nodes, encoding PDF file to be submitted by HL7 messages.
Part 5 covers advanced topics.
Chapter 18, Debugging JavaScript in Mirth Connect Provides an in-depth explanation of such important topics as debugging filters and transformers JavaScript using built-in and external tools such as Rhino JavaScript Debugger and Eclipse JSDT Debugger.
Chapter 19, Utilizing JMS (Java Message Service) Introduces the JMS Sender and Listener connector configurations to pass messages and objects through a Message Broker such as Apache ActiveMQ. Provides insight into passing messages, and gives a detailed explanation explanation of serialization / deserialization techniques techniques to pass Java objects via the Message Broker.
Chapter 20, Polling Web Services Explains how to extend the functionality of the Web Server Sender connector to periodically poll data from external service providers.
Chapter 21, Building Extensions Provides an in-depth explanation of such confused topic as building the Mirth Connect extension using the example of building a JSON Writer Destination Connector.
Chapter 22, Tuning Mith Connect Walks the reader through Mirth Connect Server settings to increase the overall system’s performance. performance. The chapter also provides a brief overview of available security enhancement settings.
13
Introduction
PART I – MIRTH CONNECT BASICS
Mirth Connect Basics CHAPTER 1
Getting Started
CHAPTER 2
What is a Channel?
CHAPTER 3
Creating a Channel
PART I – MIRTH CONNECT BASICS
14
CHAPTER 1 Getting Started
Getting Started his chapter outlines the Mirth Connect basic installation procedure. All examples in this book are based on the Windows version of Mirth Connect v3.6, available to download at - http://www.mirthcorp.com/c http://www.mirthcorp.com/community/do ommunity/downloads wnloads Make sure your computer meets minimum system requirements before you start:
Oracle JRE version 1.8 or higher;
1 GB of RAM is recommended;
A web browser.
Installation There are two possible ways to install 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 the package to an appropriate folder, for example to the C:\Program Files\Mirth Connect\. In the other case, there there is a GUI based installer installer
that you just start and go through the steps in the installation wizard. The installation installation process itself is quite straight forward. In both cases what is 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 Server. By default it is 8080 for unsecure communication communication and 8443 for the SSL connection. You can 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 the Mirth Connect Command Line;
Open the web browser and type localhost:8080 in the address bar;
Click the Access Secure Site button Site button in Web Dashboard Sign In launch In launch page;
Type admin for the user name n ame and repeat admin as the password, click Sign in. in.
If you see the Dashboard statistics page with, most likely, no channels available, you have successfully successfully done the installation installation and ready to continue. If not, refer to Mirth Connect 3.5 User Guide written by “the “the same Mirth technical experts who developed the software” software”. 15
PART I – MIRTH CONNECT BASICS
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. connections. However, a fully-fledged configuration description is beyond the scope of this book. Here is only a recommended step is to add a path to the \custom-lib folder to the operating system’s CLASSPATH CLASSPATH environment variable. This is the folder where you put your Java classes, libraries and other required files. Versions 1 and 2 of Mirth Connect were using port 1099 for viewing statistics though the JMX (Java Management Extensions) and RMI (Remote Method Invocation) interfaces. This port is no longer used in version 3.x. Hence, if any of your applications or firewall is utilizing ports 8080 or 8443 you can either change Mirth’s ports using Mirth Connect Server Manager or manually modify the configuration file located in \conf\mirth.properties . Don’t forget to restart restart the Mirth Connect Server or Service for
any changes to make effect.
Mirth Connect Administrator The Mirth Connect Administrator is a Java application application that is not explicitly installed on a local computer by default in a distributed environment. It is downloaded from the Mirth Connect Server. The reason for this is to ensure the Mirth Connect Administrator matches version of the Mirth Connect Server. To download the Mirth Connect Administrator:
Start Mirth Connect Server if it is not already running as a service;
Open the web browser;
Type localhost:8080 in the address bar;
Click Launch Mirth Connect Administrator in in the Mirth Connect Administrator launch launch page;
Click Ok to 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, then click Login. Login.
If everything is done correctly, each time you login, you will see the Dashboard as the initial screen. The Dashboard displays two information panels:
Channels status and statistics statistics - the number of messages Received, Received, Filtered, Queued, Sent, and Errored. The Dashboard Tasks area on the navigation bar on the left side has menu items essential for developing channels such as Refresh, Send PART I – MIRTH CONNECT BASICS
16
Messages, and Remove All Messages. Same menu items can be accessed faster by right clicking on a channel row.
Logs – Server Log, Log, Connection Log and Log and Global Maps. Maps. The Server Log is Log is used a lot to debug channels development. Double-clicking Double-clicking on a Server Log entry brings a pop-up window where you can view and copy the entire log entry content. The Server Log is stored by Mirth Connect Server in the database and therefore closing and opening the Mirth Connect Administrator brings back all entries not previously explicitly purged. To clear the Server Log click Log click Clear Displayed Log under Log under the Server Log or Log or Connection Log area. Log area.
Logging Level Channel’s log level can be can be configured manually by changing \conf\log4j.properties entries. Available options are: ERROR, WARN, INFO, DEBUG, and TRACE with DEBUG selected by default. Log levels may be configured separately for filters, transformers, postprocessors and other scripts that are explained later in this book.
FIGURE 1-1 Mirth Connect Administrator window by default
Familiarize yourself with other navigation items and tabs since this is the main tool used to develop channels throughout this book.
17
PART I – MIRTH CONNECT BASICS
CHAPTER 2 What is a Channel?
What is a Channel? he Channel is an essential part of 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. applications. The channel architecture implemented implemented in Mirth Connect can divide a large message processing task into a sequence of smaller independent steps. This affords developers the flexibility for dependency, maintenance maintenance and/or performance. Some of the processing tasks can even be external to Mirth Connect and developed independently.
FIGURE 2-1 Mirth Connect abstract channel architecture
In general, each channel consists of inbound and outbound Connectors, Filters and Transformers. The connector that receives receives inbound messages from the Sending Sending Application Application is called the Source. Source . Similarly, the connector that sends outbound messages is called the Destination. Destination. From the Source connector data is passed through the channel, where filters and transformers perform operations on the data, for example, routing a message to one or another Destination connector and transforming the data representation. Deciding channel’s channel’s tasks tasks is when wearing an analyst's hat comes into play. Before you create a new channel, you need to elicit the following requirements:
Type of Application the channel reads data from (Source connector type);
Type of Application the channel sends data to (Destination connector type); type);
Type and format of the inbound message;
Type and format of the outbound message(s); PART I – MIRTH CONNECT BASICS
18
Mapping table(s) between inbound and outbound messages (Transformation). (Transformation).
Connectors In terms of Enterprise Integration, the connector is a Message Endpoint that specifies a particular way or, more accurately, a particular protocol Mirth Connect should use to communicate communicate with an external application or another Mirth Connect channel. 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;
HTTP (note that HTTPS is not supported in the free version);
SMTP;
SOAP (over HTTP).
The connector that receives the data is called a Reader , for example the MLLP Reader. The connector that sends the data is called a Writer , the Database Writer is an example. Connector types are configured under the Source and Source and Destinations tabs Destinations tabs of the channel, which is explained later in this chapter. As should be obvious, some settings are common across all connectors while others are unique to a specific connector type. If you need a connector that is not n ot shipped with the Mirth Connect installation package, you can develop your own one (such as a custom HTTPS connector). Some templates and developer’s developer’s level level documentation for such development are in the chapter dedicated to Mirth extensions.
Filters In a real world scenario, when numerous applications and channels are connected, a channel may receive messages from several sources and these messages may have to be processed differently, based on the message type or other criteria. There are two paradigms for solving this problem, a Router and and a Filter :
19
PART I – MIRTH CONNECT BASICS
Router connects Router connects to multiple outbound channels. The key benefit of the Router is that the decision criteria for the destination(s) of a message are maintained in a single location.
Filter, Filter, this is what Mirth Connect uses, is built into a message processing mechanism and is responsible for determining whether the message should be processed or not. The Filter inspects 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 to the queue unchanged un changed for another pipe to filter or process.
Filters can be as simple as specific elements comparison against a hard coded value or as complex as JavaScript scripts and external Java classes. Filters can also be omitted allowing all messages to pass through. Some routing capabilities capabilities have been introduced starting Mirth Connect v3.1 by using a "destinationSet ". If a destination is removed from the destination set, this destination will not receive the message. If a single channel needs to process more than one type of messages, you can create any number of separate pipes – Destinations 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 data format and content. If we could bring all legacy systems to a single format when a new business requirement is proposed, we would avoid conversion issues. Unfortunately, for most legacy systems, data format, content or data sequence changes are difficult and risky, and simply not feasible. How do we communicate communicate data using different formats then? In Mirth Connect this is done by a message Transformer Transformer that translates one data format into another. As a result, r esult, a destination application expects to receive messages it understands which can be processed and stored in the application’s internal data internal data format. Mirth Connect allows message translation to occur at different levels, and to chain message transformers transformers to achieve a required result. Supported transformers are:
PART I – MIRTH CONNECT BASICS
20
Message Builder maps Builder maps segments of the inbound message to segments in the
outbound message. Iterator works Iterator works similarly to Message Builder but allows to iterate over multiple
instances of the same segment and map segments of the inbound message to segments in the outbound message. Mapper maps Mapper maps segments of the inbound message to internal Mirth Connect variables.
These variables may be used later. External Script, Script, as the name suggests, employs external JavaScripts JavaScripts to transform or
map the data.
XSLT Step utilizes Step utilizes the XSL transformation. transformation.
JavaScript, JavaScript, along with External Script, is where flexibility comes into play. Here any type of (Rhino) Java Script and Java code can be used.
Scripts Channels also support unique features called Scripts to 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 Mirth Connect Server starts or a channel is redeployed. This is the best place to initialize variables or create class objects.
Attachment script Attachment script deals with a message in a native format and allows extracting a part of the message to store as an attachment attachment or to irrevocably modify a message.
Preprocessor script Preprocessor script also allows handling each message in a native format before Mirth Connect starts translating it into the internal format, which is XML.
Filter & Transformer scripts Transformer scripts are the main places where you handle the inbound and outbound messages.
Response script, as the name suggests, handles the response sent by a destination.
Postprocessor script Postprocessor script is executed after the message has been successfully sent.
Undeploy script Undeploy script is launched each time Mirth Connect Server stops. This is the place to, for example, release memory that was allocated for the classes used by the channel.
Scripts are performed in the following order: 1. Global Deploy Global Deploy script; 2. Deploy; 3. Attachment script; 4. Global Preprocessor Global Preprocessor script; 5. Preprocessor script; 21
PART I – MIRTH CONNECT BASICS
6. Source connector Filters script; 7. Source connector Transformer script or mapping; 8. Destination 1 connector Filters script; 9. Destination 1 connector Transformer script or mapping; 10. Destination N connector Filters script; 11. Destination N connector Transformer script or mapping; 12. Response 1 Transformer script or mapping; 13. Response N transformer script or mapping; 14. Postprocessor script; 15. Global Postprocessor Global Postprocessor script; 16. Undeploy; 17. Global Undeploy script. Deploy and Undeploy scripts are performed only once, when a channel is deployed or undeployed, respectively. respectively. It is important to note that Global Deploy and Deploy scripts are also executed every time any channel is redeployed. Same with Undeploy and Global Undeploy scripts, they are executed for every channel. All other scripts are performed every time a message is sent through a channel or an acknowledgement is received. Notice that the Global Preprocessor Preprocessor script is executed before the channel’s Preprocessor script is executed. Similarly, after the channel’s Postprocessor script completes, the Global Postprocessor script is run. If channels operate in series, the Attachment Script of the first channel is the first to perform. The Postprocessor Script of the same channel will be executed last, after all other scripts in all consequent channels. (see Figure 2-2)
FIGURE 2-2 Scripts execution sequence
Next, we will explore each of these steps in detail. PART I – MIRTH CONNECT BASICS
22
This is a preview edition of the book. The full versions of this and other related books are available to download at
http://mirthconnect.shamilpublishing.com
23
PART I – MIRTH CONNECT BASICS
Book Resources
Book Resources Other titles you may be interested in:
Unofficial Developer's Guide to CCD on Mirth Connect This book introduces readers to version 3.x of Mirth Connect to the point that they are confident enough to start building their own healthcare data exchange interfaces. By implementing an imaginary CCD Builder Server, this book covers topics on XSL Transformation, acknowledgements implementation, XML schema and Schematron validation. Each connection point (channels and destinations) is explained in a separate chapter, which in turn provides step-by-step instructions on how to create and code data transformation transformation rules for ADT and ORU messages. The book is available to download at – http://ccdonmirth.shamilpublishing.com
Unofficial Developer's Guide to FHIR on Mirth Connect This book describes version 3.x of Mirth Connect to the point that reader are confident enough to start building their own healthcare data exchange interfaces using a new HL7 standard called FHIR or Fast Healthcare Interoperability Interoperability Resources. This book may be interesting for those implementing HL7 FHIR based solutions. The book is available to download at – http://fhironmirth.shamilpublishing.com
Unofficial Developer's Guide to HL7v3 Basics This book introduces readers to HL7 version 3 to the point that they are confident enough to start building their own healthcare data exchange interfaces. The book provides clear and easy to use, step-by-step guidance for learning the standard, with numerous examples covering many topics. This book may be interesting for those implementing the Clinical Document Architecture (CDA) or HL7 Reference Information Model (aka RIM) based solutions. The book is available to download at – http://hl7basics.shamilpublishing.com
25
PART I – MIRTH CONNECT BASICS
APPENDICES APPEND ICES
Appendices A: Eligibility Query Request (QUCR_IN200101) Template
"> =""/> =""/> "/> "/> Gen"/> "/> "> "> "/> AGNT"> "> controlInformationExtension =""/> > > > "> "> "/> AGNT"> "> controlInformationExtension =""/> > > > ">
"/> > =""/> > > > >
B: Eligibility Query Results (QUCR_IN210101) Template
"> =""/> =""/> "/> "/> Gen"/> "/> "> "> "/> AGNT"> "> "/> > > > "> "> "/> AGNT"> "> "/> > > > AA"> > =""/> > > ">
27
APPENDICES
> =""/> > > =""/> > > > =""/> =""/> > > > "/> > > "/> > > > >
C: MS Access Log Database Structure Create a table called Messages and add following fields: Field id CreationDate UUID MsgType Trigger Version Errors Source
Type AutoNumber Date/Time Text Text Text Text Memo Memo
Comment Format: yyyy-mm-dd hh:nn:ss
D: PostgreSQL Eligibility Database Structure -- Table: messages -- DROP TABLE messages; CREATE TABLE messages ( id serial NOT NULL, -- autoincrementing id mid character varying(40), -- inbound message identifier, /QUCR_IN200101UV01/id/@extension cdate character varying(20), -- inbound message creation date, /QUCR_IN200101UV01/creationTime/@value sender character varying(100), -- inbound message sending organization, /QUCR_IN200101UV01/sender/device/asAgent/representedOrganization/id/@controlInformationExtension author character varying(100), -- assigned person identifier pid integer -- link to patients.id table ) WITH ( WITH ( OIDS=FALSE ); ALTER TABLE messages TABLE messages OWNER TO postgres; TO postgres; COMMENT ON TABLE messages TABLE messages IS 'Contain IS 'Contain QUCR_IN200101 (Elig Query Request) message related information. For the test purpose only.'; COMMENT ON COLUMN messages.id COLUMN messages.id IS IS ' ' autoincrementing id';
APPENDICES
28
COMMENT ON COLUMN messages.mid COLUMN messages.mid IS IS 'inbound 'inbound message identifier, /QUCR_IN200101UV01/id/@extension'; COMMENT ON COLUMN messages.cdate messages.cdate IS IS 'inbound 'inbound message creation date, /QUCR_IN200101UV01/creationTime/@value'; COMMENT ON COLUMN messages.sender COLUMN messages.sender IS IS 'inbound 'inbound message sending organization, /QUCR_IN200101UV01/sender/device/asAgent/representedOrganization/id/@controlInformationExtension'; COMMENT ON COLUMN messages.author COLUMN messages.author IS IS 'assigned 'assigned person identifier, /controlActProcess/authorOrPerformer/assignedPerson/id/@controlInformationExtension'; COMMENT ON COLUMN messages.pid COLUMN messages.pid IS IS 'link 'link to patients.id table'; -- Table: patients -- DROP TABLE patients; CREATE TABLE patients TABLE patients ( id serial NOT NULL, -- autoincrementing id fname character varying(100), -- patient first name, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.Name/value/p art[1]/@value lname character varying(100), -- patient last name, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.Name/value/part[1]/@ value pid character varying(10), -- patient person identifier, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatient.Id/value/@extension dob character varying(15), -- patient date of birth, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.BirthTime/value/@val ue processed boolean NOT NULL DEFAULT false -- QUCR_IN210101 (Elig Query Results) response sent flag ) WITH ( WITH ( OIDS=FALSE ); ALTER TABLE patients TABLE patients OWNER TO postgres; TO postgres; COMMENT ON TABLE patients TABLE patients IS 'Patient IS 'Patient personal information sent by QUCR_IN200101 (Elig Query Request) message. For the test purpose only.'; COMMENT ON COLUMN patients.id COLUMN patients.id IS IS 'autoincrementing 'autoincrementing id'; COMMENT ON COLUMN patients.fname patients.fname IS IS 'patient 'patient first name, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.Name/value/part[1]/@ value'; COMMENT ON COLUMN patients.lname patients.lname IS IS 'patient 'patient last name, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.Name/value/part[1]/@ value'; COMMENT ON COLUMN patients.pid COLUMN patients.pid IS IS 'patient 'patient person identifier, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatient.Id/value/@extension'; COMMENT ON COLUMN patients.dob COLUMN patients.dob IS IS 'patient 'patient date of birth, /controlActProcess/queryByParameter/parameterList/coveredPartyAsPatientPerson.BirthTime/value/@val ue'; COMMENT ON COLUMN COLUMN patients.processed IS IS 'QUCR_IN210101 'QUCR_IN210101 (Elig Query Results) response sent flag';
E: XSLT to transform from HL7v3 to HL7v2
"> "/> > > >| > >^~\& > > > ADM > > > >Sending Organization >
29
APPENDICES
> > ALL > > >Receiving Organization > > > ')"/> > > >RSP > >E22 > > "/> > >D > > >2.4 > /> /> > > AL > /> > > > AA > > > > > > > /> > >OK > > > >E22 > /> >CIHI0003 > > > > > >E22 > /> >CIHI0003 > > > /> > /> > > /> /> > > "/> > /> >ISO > >PHN > > /> > > "> 'FAM'"> "/> > > > "> 'GIV'"> "/>
APPENDICES
30
> /> /> >L > /> > > "/> > > > /> > > > > >
F: JavaScriptTask.java Rhino JS Debugger Embedded
Eclipse JSDT Debugger Embedded
G: Rhino Script Engine script samples Source and Destination connector scripts as they executed by the Mirth Connect Server using Rhino Script Engine. Code is manually tweaked and commented for better readability. Channel Source Connector script
Channel Destination Connector script
H: Archives Content There are five archives provided with this book each of which contains a complete set of files required for Part II - Part V implementations. implementations.
31
APPENDICES
Required but not included files or libraries are showin in blue blue..
Eligibility.NoACK Folder Channels
Files Code Template.xml Template.xml ConfigurationMap.properties Data Logger.xml Global Script.xml HL7v3 Verification.xml Query Sender.xml Response Sender.xml v2-v3 Transformater.xml v3-v2 Transformater.xml Eligibility No Ack Channels Group.xml custom-lib /coreschemas /schemas /schematron jsr305-2.0.1.jar phloc-commons-4.3.6.jar phloc-schematron-2.7.1.jar postgresql-9.4.1208.jre6.jar saxon9-dom.jar slf4j-api-1.7.5.jar DB PostgreSQL-Eligibility DB.sql HL7v2\Samples QBP_E22_Request.hl7 RSP_E22_Error.hl7 RSP_E22_Success.hl7 HL7v2\Templates RSP-45_Template.hl7 HL7v2\XSLT QUCR-RSP.xslt HL7v3 HL7v3\QUCR_IN200101UV01_Request_Annotated.xml Samples_Annotated QUCR_IN210101UV01_Error_Annoteated.xml QUCR_IN210101UV01_Success_Annotated.xml HL7v3\Templates QUCR_IN200101_Template.xml QUCR_IN210101_Template.xml
Comment Channels, code templates and global scripts for Part II implementation.
Custom-lib folder for Mirth Connect Server installation.
PostgreSQL patients database
Schemas for HL7v3 messages Annotated Eligibility query response and request messages Eligibility query response and request template messages with empty fields
Eligibility.ACK-NACK Folder Channels
custom-lib
Files Code Template ACK.xml ConfigurationMap.properties Data Logger.xml Global Script.xml HL7v3 ACK.xml HL7v3 Verification-ACK.xml Query Sender-ACK.xml v2-v3 Transformer-ACK.xml Transformer-ACK.xml Eligibility Ack Channels Group.xml /coreschemas
Comment Channels, code templates and global scripts for Part III implementation.
Custom-lib folder for Mirth Connect APPENDICES
32
DB HL7v2\Samples HL7v3 HL7v3\Samples HL7v3\Samples_Annotated HL7v3\Templates
/schemas /schematron jsr305-2.0.1.jar phloc-commons-4.3.6.jar phloc-schematron-2.7.1.jar postgresql-9.2-1003.jdbc4.jar saxon9-dom.jar slf4j-api-1.7.5.jar PostgreSQL-Eligibility DB.sql ACK-A01_Negative.hl7 ACK-A01_Positive.hl7 MCCI_IN000002UV01.xml MCCI_IN000002UV01.xml MCCI_IN000002UV01-Annotated.xml MCCI_IN000002UV01-Annotated.xml MCCI_IN000002_template.xml MCCI_IN000002_template.xml
Server installation.
PostgreSQL patients database HL7v2 acknowledgement samples Schemas for HL7v3 messages HL7v3 acknowledgement sample HL7v2 acknowledgement sample with annotations HL7v2 acknowledgement template with empty fields
DICOM Folder Channels
Files Code Template.xml Template.xml ConfigurationMap.properties DICOM SCP.xml DICOM SCU.xml DICOM Channels Group.xml Global Scripts.xml
Comment Channels, code templates and global scripts for Part IV implementation.
Eligibility.JMS Folder Channels
custom-lib
Files Data Logger JMS.xml Data Logger RAW.xml HL7v3 Verification JMS.xml HL7v3 Verification RAW.xml Query Sender JMS.xml v2-v3 Transformer JMS.xml v2-v3 Transformer RAW.xml JMS Channels Group.xml JMS RAW Channels Group.xml faultmessage.jar activemq-core-5.4.2.jar
Comment Channels, code templates and global scripts for Part V implementation.
Custom-lib folder for Mirth Connect Server installation.
Debugging
33
Folder JSDT
Files JavaScriptTask.java
Rhino Debugger
JavaScriptTask.java
APPENDICES
Comment Eclipse JSDT debugger in embedded mode. Rhino JavaScript debugger in embedded mode.
Polling Folder Channels
Files IHE Validator Service.xml Web Service Polling.xml Web Services Channels Group.xml
Comment Polling channels
Extension.JSON Folder Deploy
jarsigner Source\Client Source\Server
Source\org.json
Files json/lib/org-json.jar json/destination.xml json/json-client.jar json/json-server.jar json/json-shared.jar signjar.bat JSONWriter.java destination.xml JSONConnectorServlet.java JSONConnectorServletInterface.java JSONDispatcher.java JSONDispatcherProperties.java JSONArray.java JSONException.java JSONObject.java JSONString.java JSONStringer.java JSONTokener.java JSONWriter.java XML.java XMLTokener.java
Comment JSON Writer destination connector deployment package
Batch file with command command prompts to sign JARs Client side extension template Server side extension templates
XML to JSON library source code
APPENDICES
34
