Shamil Nizamov

Unofficial Developer’s Guide to

FHIR on Mirth Connect*

* - Preview Edition

Introduction 2

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

3 Introduction

Contents

PART 1 GETTING STARTED

Chapter 1 Mirth Connect Basics................................................................................................ 13

Installation ............................................................................................................... 13

Mirth Connect Administrator .................................................................................... 14

Channels .................................................................................................................. 15

Connectors............................................................................................................... 16

Filters ...................................................................................................................... 17

Transformers............................................................................................................ 17

Scripts...................................................................................................................... 18

Chapter 2 What is a FHIR? ........................................................................................................ 20

FHIR Development Approach .................................................................................... 20

Templates ................................................................................................................ 22

Summary ................................................................................................................. 24

Chapter 3 What is RESTful FHIR? .............................................................................................. 26

RESTful FHIR API ....................................................................................................... 26

Transactional Integrity .............................................................................................. 29

Summary ................................................................................................................. 33

PART II BUILDING FHIR CLIENT

Chapter 4 Simple RESTful FHIR Client Overview ....................................................................... 42

Scenario Overview .................................................................................................... 42

Client Channel .......................................................................................................... 43

Summary ................................................................................................................. 49

Chapter 5 HL7v2 Enricher with multiple GETs ........................................................................... 50

Channel Overview .................................................................................................... 51

Summary Tab ........................................................................................................... 52

Source Connector ..................................................................................................... 54

Destinations Connector............................................................................................. 63

Channel Implementation Verification ........................................................................ 65

Summary ................................................................................................................. 66

Introduction 4

Chapter 6 HL7v2 Enricher with single GET ................................................................................ 68

Channel Overview .................................................................................................... 69

Destinations Connector............................................................................................. 76

Channel Implementation Verification......................................................................... 79

Summary ................................................................................................................. 80

Chapter 7 HL7v2 Enricher on HAPI-FHIR ................................................................................... 81

Global Scripts ........................................................................................................... 83

Destinations Connector ............................................................................................ 89

Channel Implementation Verification......................................................................... 90

Summary ................................................................................................................. 90

Chapter 8 Cerner FHIR Client ................................................................................................... 91

Conformance Resource ............................................................................................. 92

Conformance Resource Extensions ............................................................................ 97

Channel Implementation Verification ........................................................................ 98

Summary ................................................................................................................. 98

Chapter 9 Epic FHIR Client ..................................................................................................... 100

Channel Overview .................................................................................................. 101

Summary Tab ......................................................................................................... 106

Source Connector .................................................................................................... 89

Destinations Connector ............................................................................................ 89

Channel Implementation Verification....................................................................... 107

Summary ............................................................................................................... 107

PART III BUILDING FHIR SERVER

Chapter 10 FHIR Resource Validator ......................................................................................... 110

Scenario Overview .................................................................................................. 110

XML Client.............................................................................................................. 111

JSON Client ............................................................................................................ 113

FHIR Resource Validator.......................................................................................... 113

Channel Implementation Verification....................................................................... 113

Summary ............................................................................................................... 114

Chapter 11 FHIR Server on SMART DB ..................................................................................... 115

5 Introduction

Summary Tab ......................................................................................................... 116

Source Connector ................................................................................................... 119

Destinations Connector........................................................................................... 101

Configuration Map.................................................................................................. 106

SMART on FHIR Database ........................................................................................ 107

Channel Implementation Verification....................................................................... 107

Summary ............................................................................................................... 124

Book Resources.............................................................................................................................. 125

APPENDICES

A: Conformance ..................................................................................................... 127

B: Archive Content ................................................................................................. 130

Introduction 6

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.

7 Introduction

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

Warning and Disclaimer

Introduction 8

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.

Roadmap

This book is divided into three parts:

Part I provides an introduction to Mirth Connect and a high-level overview of the HL7

FHIR standard.

9 Introduction

Chapter 1, Mirth Connect Basics

Introduces Mirth Connect at a high level, provides an overview of the channel

architecture implemented in Mirth Connect, 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 a 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 minimizing the

number of requests that the client application sends to the FHIR server.

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

Introduction 10

Introduces readers with 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.

11 PART I – GETTING STARTED

PART I – GETTING STARTED

Getting Started CHAPTER 1 Mirth Connect Basics

CHAPTER 2 What is FHIR?

CHAPTER 3 What is RESTful FHIR?

PART I – GETTING STARTED 12

CHAPTER 1 Mirth Connect Basics

Mirth Connect Basics his chapter outlines the Mirth Connect installation procedure and basic concepts. All

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

T

13 PART I – GETTING STARTED

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

PART I – GETTING STARTED 14

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

15 PART I – GETTING STARTED

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.

PART I – GETTING STARTED 16

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 channels 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.

17 PART I – GETTING STARTED

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.

PART I – GETTING STARTED 18

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.

This is a preview edition of the book.

The full version with all related files is available to download at

http://fhironmirth.shamilpublishing.com

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

PART I – GETTING STARTED 20

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

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 Files Comment

..\Channels\ Mirth Connect channels, code

templates and global scripts

discussed in this book

..\SampleMessages\ Samples of HL7v2.6 ADT messages