Shamil NizamovUnofficial 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 -
[email protected] 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