Shamil Nizamov

Unofficial Developer’s Guide to
FHIR on Mirth Connect*
* - Preview Edition

Copyright Page
Copyright © 2016 by Shamil Nizamov
Cover image copyright © 2009 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®, HEALTH LEVEL SEVEN®,
FHIR® are trademarks owned by 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. 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 edition of the book. The full version is available only at http://fhironmirth.shamilpublishing.com

Introduction

2

Contents
PART 1

GETTING STARTED

Chapter 1

Mirth Connect Basics................................................................................................ 12
Installation ............................................................................................................... 12
Mirth Connect Administrator .................................................................................... 13
Channels .................................................................................................................. 14
Connectors............................................................................................................... 15
Filters ...................................................................................................................... 16
Transformers............................................................................................................ 16
Scripts...................................................................................................................... 17

Chapter 2

What is a FHIR? ........................................................................................................ 19
Resources ................................................................................................................ 20
Interoperability Paradigms ....................................................................................... 23
Profiles .................................................................................................................... 24
Summary ................................................................................................................. 25

Chapter 3

What is RESTful FHIR? .............................................................................................. 26
RESTful FHIR API ....................................................................................................... 26
Transactional Integrity .............................................................................................. 29
Summary ................................................................................................................. 30

PART II

BUILDING FHIR CLIENT

Chapter 4

Simple RESTful FHIR Client Overview ....................................................................... 33
Scenario Overview .................................................................................................... 33
Client Channel .......................................................................................................... 36
Summary ................................................................................................................. 37

Chapter 5

HL7v2 Enricher with multiple GETs ........................................................................... 38
Channel Overview .................................................................................................... 38
Summary Tab ........................................................................................................... 39
Source Connector ..................................................................................................... 39
Destinations Connector............................................................................................. 40
Channel Implementation Verification ........................................................................ 56

3

Introduction

Handling HTTP Response Codes ................................................................................ 57
Summary ................................................................................................................. 60
Chapter 6

HL7v2 Enricher with single GET ................................................................................ 62
Channel Overview .................................................................................................... 62
Destinations Connector............................................................................................. 63
Channel Implementation Verification......................................................................... 72
Summary ................................................................................................................. 73

Chapter 7

HL7v2 Enricher on HAPI-FHIR ................................................................................... 74
Global Scripts ........................................................................................................... 75
Destinations Connector ............................................................................................ 76
Channel Implementation Verification......................................................................... 82
Summary ................................................................................................................. 83

Chapter 8

Cerner FHIR Client ................................................................................................... 84
Conformance Resource ............................................................................................. 85
Conformance Resource Extensions ............................................................................ 91
Channel Implementation Verification ........................................................................ 95
Summary ................................................................................................................. 96

Chapter 9

Epic FHIR Client ....................................................................................................... 97
Channel Overview .................................................................................................... 97
Summary Tab ........................................................................................................... 98
Source Connector .................................................................................................... 99
Destinations Connector .......................................................................................... 100
Channel Implementation Verification....................................................................... 108
Summary ............................................................................................................... 109

PART III

BUILDING FHIR SERVER

Chapter 10

FHIR Resource Validator ......................................................................................... 111
Scenario Overview .................................................................................................. 112
XML Client.............................................................................................................. 113
JSON Client ............................................................................................................ 116
FHIR Resource Validator.......................................................................................... 119
Channel Implementation Verification....................................................................... 126
Introduction

4

Summary ............................................................................................................... 128
Chapter 11

FHIR Server on SMART DB ..................................................................................... 129
Summary Tab ......................................................................................................... 130
Source Connector ................................................................................................... 131
Destinations Connector........................................................................................... 133
Configuration Map.................................................................................................. 142
SMART on FHIR Database ........................................................................................ 143
Channel Implementation Verification....................................................................... 144
Summary ............................................................................................................... 148

Book Resources.............................................................................................................................. 149

APPENDICES
A: Conformance ..................................................................................................... 152
B: Archive Content ................................................................................................. 158

5

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, “The 2014 HL7 Interface Technology Survey Results” show that Mirth Connect
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 using a new set
of HL7 standards called FHIR (Fast Healthcare Interoperability Resources).
As you read this book, you will be implementing a number of fictitious FHIR related
services. Each connection point (channel and destination) is explained in a separate
chapter, which in turn provides step-by-step instructions on how to create and code data
transformation rules.
This book is written using Mirth Connect version 3.4.0.8000. Consequently, other releases
may include new features, and features used in this book may change or disappear. You
may also notice 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 lacking and needed a guidebook that
covers topics in a more detailed and organized way.
A book of this size cannot cover every feature in Mirth Connect v3.x; consequently, I
assume you already have some familiarity with its main components, functions and use.

Introduction

6

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, JSON, REST and OAuth.
Before you start reading this book, you should have a basic knowledge of Mirth Connect
development paradigm, JavaScript, Java and E4X objects; and are familiar with operating
system environment variable settings.
You should also have basic knowledge of HL7, the standard that is being used to
exchange healthcare data, both version 2 and FHIR.

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 in Mirth Connect v3.x. This book is not intended
to be a step-by-step comprehensive guide or substitute of any kind for training and
certification programs provided by Mirth Corporation.
This book is also not a tutorial on a specific messaging or middleware technology. All
examples included in this book are for illustrative purposes only. If you are interested in
learning more about a specific technology or product, please refer to one of the many
on-line resources, or trainings and certifications provided by Mirth Corporation or its
affiliates.
This book does not cover any specific installation, configuration, 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 - mirthconnect@isarp.com

7

Introduction

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 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 for 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 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 representative of Mirth Corporation and never has
been, and author’s views and opinions are not necessarily those of Mirth Corporation.
This book is not based on trainings or certifications provided by Mirth Corporation or its
affiliates.
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, 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, this book contains information on the subject only up to the publication
date.

Acknowledgements
Like most books, this guide has been a long time in the making. I would like to
acknowledge everyone who has assisted in this project. I could not have done this
without you.
My biggest thanks go to Wayne Zafft and Taylor Clark, who were incredibly gracious with
their time and effort in reviewing the final version of the book.

Introduction

8

Roadmap
This book is divided into three parts:
Part I provides an introduction to Mirth Connect and a high-level overview of the HL7
Fast Healthcare Interoperability Resources (FHIR) standard.

Chapter 1, Mirth Connect Basics
Introduces Mirth Connect at a high level, provides an overview of the channel
architecture implemented in Mirth Connect and walks the reader through the
creation and configuration of a simple channel.

Chapter 2, What is FHIR
Provides an overview of the Continuity of Care Document or CCD, the XML-based
markup standard intended to specify the encoding, structure, and semantics of a
patient summary clinical document for exchange.

Chapter 3, What is RESTful FHIR
Provides a brief overview of system design and systems integration requirements to
demonstrate the complexity of a typical HL7 based integration project.

Part II focuses on the implementation of FHIR Clients.

Chapter 4, Simple RESTful FHIR Client Overview
Introduces an imaginary scenario that mimics storyboards defined by HL7v3
Normative Edition, presents the implementation plan for this part of the book and
walks through the required components.

Chapter 5, HL7v2 Enricher with multiple GETs
Explains the implementation of a set of channels that plays the role of Client and
Enricher in this project, introduces readers with upstream and downstream channels
concept to handle HTTP errors, shows some handy techniques to retrieve and
process data from the external RESTful FHIR server.

Chapter 6, HL7v2 Enricher with single GET
Walks readers though implementation of a FHIR Client that utilizes extended FHIR
Server functionality, explores the capability of the FHIR Server to minimize the
number of requests that the client application sends to the FHIR server.

9

Introduction

Chapter 7, HL7v2 Enricher on HAPI FHIR
Expands functionality by utilizing HAPI FHIR library to parse XML and JSON based
FHIR Server responses.

Chapter 8, Cerner FHIR Client
Introduces readers to the Cerner FHIR sandbox and walks through the
implementation of a Mirth client to explore the capabilities of the external FHIR
Server.

Chapter 9, Epic FHIR Client
Continues with the implementation pattern used for other channels in this book and
walks through the implementation of a channel that extracts Patient and
DocumentReference resources as well as related CCD (HL7 Continuity of Care
Document) from the EPIC FHIR sandbox.

Part III is dedicated to building different types of FHIR Servers.

Chapter 10, FHIR Resource Validator
Introduces a FHIR resource verification process using different methods such as XML
Schema validation, Schematron validation and conformance review. This chapter also
outlines an implementation of a FHIR resource validation server that can assist
readers in crafting their own FHIR resources both in XML and JSON formats.

Chapter 11, FHIR Server on SMART DB
Walks the reader through the implementation of the FHIR Server based Mirth FHIR
Listener connector and SMART on FHIR database. This allows readers to explore FHIR
resources and try different types of FHIR interactions to retrieve those.

Appendices include:

Conformance
The Conformance resource for FHIR Server from Chapter 11.

Archive Content
A list of supplementary materials required for parts II and III included with this book.

Introduction

10

PART I – GETTING STARTED

Getting Started

11

CHAPTER 1

Mirth Connect Basics

CHAPTER 2

What is FHIR?

CHAPTER 3

What is RESTful FHIR?

PART I – GETTING STARTED

CHAPTER 1 Mirth Connect Basics

Mirth Connect Basics
chapter outlines the Mirth Connect installation procedure and basic concepts. All
This
examples in this book are based on the Windows version of Mirth Connect v3.3,
available for downloading at http://www.mirthcorp.com/community/downloads
Make sure your computer meets minimum system requirements before you start:

Oracle JRE version 1.7 or higher;

1 GB of RAM is recommended;

A web browser.

Installation
You can install Mirth Connect in either of two ways based on which package you
downloaded or which package is available on the website. In one case, the package is an
archive of all files and classes you need to run Mirth Connect on your computer. You
simply unzip and copy the package to an appropriate folder, for example to C:\Program
Files\Mirth Connect\. In the other case, there is a GUI based wizard that you start to
go through the steps in the installation. The installation process itself is quite straight
forward.
Both methods install 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 is used by the Mirth Connect Server. The
default is 8080 for unsecure communication and 8443 for the SSL connection. You can
change the ports later using the Mirth Connect Server Manager, if necessary.
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 in Web Dashboard Sign In launch page;

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 installed Mirth Connect and are ready to continue. If not, refer to Mirth
Connect 3.1 User Guide written by “the same Mirth technical experts who developed the
software” available at - http://info.mirth.com/Connect_Documentation_Download.html
PART I – GETTING STARTED

12

Configuration
The Mirth Connect Server Manager can be used as a single point to launch Mirth
Connect Service, configure ports, allocate memories, and to establish database
connections. However, a fully-fledged configuration description is beyond the scope of
this book.
As a recommended option, add a path to the \custom-lib folder in the operating
system’s CLASSPATH environment variable. This is the folder where you put Java classes,
libraries and other required files that Mirth should be working with.
If any application on your computer or firewall uses ports 8080 or 8443 you can either
change Mirth’s ports by using Mirth Connect Server Manager or by manually modifying
the configuration file located in \conf\mirth.properties. Don’t forget to restart the
Mirth Connect Server or Service to activate your changes.

Mirth Connect Administrator
The Mirth Connect Administrator is a Java application that, by default, is not explicitly
installed on a local computer in a distributed environment. It is downloaded from the
Mirth Connect Server. This ensures the Mirth Connect Administrator matches the version
of the Mirth Connect Server being used.
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 the Mirth Connect Administrator launch
page;

Click Ok to open 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.

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 – shows the number of messages Received, Filtered,
Queued, Sent, and Errored. The left sidebar of the Dashboard has tasks panel, with
menu options related to your current activity. For example, when you are developing
a channel, menu options such as Refresh, Send Messages, and Remove All Messages

13

PART I – GETTING STARTED

are displayed. These menu items can be also accessed by right clicking on a channel
name in the Channel List.

Logs – Server Log, Connection Log and Global Maps. The Server Log is used to debug
channel development. 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; closing and opening the Mirth
Connect Administrator brings back all entries not explicitly purged. To clear the
Server Log click Clear Displayed Log under the Server Log or Connection Log area.

Familiarize yourself with other navigation items and tabs since this is the main tool used
to develop and configure channels throughout this book.

Channels
The Channel is an essential part of Mirth Connect and can be seen as one-to-many
abstract unidirectional pipes that decouple components from each other to transfer
healthcare data between two or more applications. The channel architecture
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 and/or performance. Some of the processing tasks can even
be external to Mirth Connect and developed independently.

FIGURE 1-1 Mirth Connect abstract channel architecture

In general, each channel consists of inbound and outbound Connectors, Filters and
Transformers. The connector that receives inbound messages from the Sending
Application is called the Source. Similarly, the connector that sends outbound messages
PART I – GETTING STARTED

14

is called the 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 Destinations connector and transforming the data
representation. Deciding each channel’s 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 and format of the inbound message;

Type and format of the outbound message(s);

Mapping table(s) between inbound and outbound messages (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 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);

FHIR;

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 Source and Destinations tabs of the channel.
Obviously, some settings are common across all connectors while others are unique to a
specific connector type.

15

PART I – GETTING STARTED

You can develop your own connector if you need one that is not shipped with the Mirth
Connect installation package, e.g., HTTPS connector. However, this is out of scope of this
book.

Filters
In a real world scenario, when numerous applications and chann els are connected, a
channel may receive messages from several sources and may process these messages
differently, based on the message type or other criteria.
There are two paradigms for addressing this requirement, a Router and a Filter:

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, this is what Mirth Connect uses, is built into a message processing mechanism
and determines whether or not the message should be processed. 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 for another pipe to filter or process.

Filters can be as simple as comparing specific elements against a hard coded value or as
complex as a scripting language routine. Filters can also be omitted allowing all
messages to pass through. Some routing capabilities have been introduced in 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 message, you can create any
number of separate pipes – Destinations - and specify none, one or more filters for each
pipe.

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.

PART I – GETTING STARTED

16

How do we communicate data using different formats then? Mirth Connect does this in a
message Transformer that translates one data format into another. As a result, a
destination application can receive messages it understands and which can be processed
and stored in the application’s internal data format.
Mirth Connect allows message transformation to occur at different levels and to chain
message transformers to achieve a required result.
Supported transformers are:
Message Builder maps segments of the inbound message to segments in the

outbound message.
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 JavaScript routines to

transform or map the data.

XSLT Step utilizes the XSL transformation.

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 enhance 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 deals with a message in a native format and allows extracting part
of the message to store as an attachment or to 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, which is XML.

Filter & Transformer scripts are the main places for handling the inbound and
outbound messages.

Response script, as the name suggests, handles the response sent by a destination.

Postprocessor script is executed after the message has been successfully sent.

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.

17

PART I – GETTING STARTED

Mirth Connect uses JavaScript as a scripting language with the ability to extend it by calls
of external Java classes. The latter may be one of those included to the Mirth installation
package or user defined.
Besides the channel level, Mirth Connect employs Global Scripts that play the same role
as channel scripts and help in separating the business logic. They have the same Deploy,
Undeploy, Preprocessor and Postprocessor scripts; the only difference is that they apply to
all channels.
This concludes Mirth Connect introduction section. To find out more, you may refer to
numerous web resources, including trainings and books provided by Mirth Corporation.
You may find it helpful to read “Unofficial Mirth Connect v3.x Developer’s Guide“ eBook
which covers Mirth Connect basics and advanced topics in greater details.
This eBook is available at - http://mirthconnect.shamilpublishing.com

This is a preview edition of the book.
The full version with all related files is available to download at

http://fhironmirth.shamilpublishing.com

PART I – GETTING STARTED

18

Book Resources

Book Resources
Other titles you may be interested in:

Unofficial Mirth Connect v3.x Developer's
Guide
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 Eligibility Query
Service, this book covers some of the topics on XML
schema and Schematron validation, XSL
Transformation, database connection pool creation,
acknowledgements implementation, Mirth Connect
extensions implementation and sending objects via
the ActiveMQ Message Broker.
The book is available to download at –
http://mirthconnect.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.
The book is available to download at –
http://hl7basics.shamilpublishing.com

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 rules for ADT and ORU messages.
The book is available to download at –
http://ccdonmirth.shamilpublishing.com

PART I – GETTING STARTED

20

APPENDICES

Appendices
A: Conformance
SMART on FHIR Conformance
A set of capabilities of a SMART on FHIR Server including list of all supported resources,
interactions and search parameters.

[snip]
B: Archive Content
These are files provided as supplementary materials required for parts II and III.
Folder
..\Channels\

..\SampleMessages\

Files

Comment
Mirth Connect channels, code
templates and global scripts
discussed in this book
Samples of HL7v2.6 ADT messages