Mirth Connect is the Swiss Army knife of open source integration engines with specific Healthcare support for HL7 message integration. A Continuity of Care (CCD) Document is an XML file containing a patient summary clinical document. Mirth has support for CCD and CDA documents in their commercial offering but you can also use the open source Model Driven Health Tools library from the Open Health Tools project for free if you have some time and patience.
In this blog entry, I’m going to take you through the process to integrate the MDHT libraries into an existing Mirth Connect installation and then create a very simple channel to parse a CCD document and extract information from it. Specifically, we will:
- Download and install the MDHT Run-time JARS
- Configure and add code to a channel in Mirth to load the content of a CCD document
- Extract fields from the CCD document and populate the channel variables map
1. Download the MDHT Run-time JARS
You will need to download the latest release of the MDHT Run-time JARS from the Open Health Tools web site. At the time of writing, version 1.2.0 files are located at http://sourceforge.net/projects/oht-modeling/files/Releases/Runtime/. Download the latest zip file named “org.openhealthtools.mdht.uml.cda.hitsp.runtime” that contains the 11 core files (support for the CDA, HL7 Datatypes, HL7 Vocabulary, and RIM) and the 8 MDHT Runtime APIs for the HISTP C32 stack that includes the support for HISTP, IHE PCC, and the CCD.
2. Install the MDHT Run-time JARS into Mirth Connect
Once you have the runtime zip file downloaded you will need to open it and copy the nineteen run-time JAR files from the “1.2.0_Runtime” folder in the zip file into Mirth Connect’s custom-lib folder (in a new installation of Mirth Connect you will find this folder is empty). I’m doing this on a Microsoft Windows machine but the principle is the same for Linux and Mac too, just change the path. On Windows, the custom-lib folder is located in C:\Program Files\Mirth\Connectcustom-lib\.
Once you have copied the files to the custom-lib folder, you will need to re-start Mirth so that it can load the additional JAR files.
3. Create a new Channel to be used to parse CCD Documents
There are three steps that must be done to use the MDHT library in a channel:
- Configure the connector data types for HL7 3.0
- Initialize the MDHT classes in the deploy script
a) Create a channel and open the Data Types window by clicking the button “Set Data Types” in the “Summary” tab for the channel. Set each connector data type to “HL7 v3.0” and click the “Properties” button and UN-CHECK the “Strip Namespaces” option (if you don’t do this you most likely get errors similar to Failed to transform message before applying the filter when running the channel). It should look like the following:
b) To initialize the MDHT CCD package you should put the following code in the deploy script for the channel. Click the “Scripts” tab, make sure the Script dropdown says “Deploy” and add the openhealthtools line below so it looks like the following:
- Click the “Source” tab on the channel and under the “Channel Tasks” click on “Edit Transformer” to open the Source Transformer window.
- Click the “Add New Step” button on the left side of the screen under the “Transformer Tasks” heading.
- Place the following example code in the content area for the transformer:
The first line of the script code above will load the CCD document into the MDHT library. It does this by taking the original raw file data and extracting the bytes in UTF-8 format (change this only if you are using a different encoding for your XML). It then feeds the bytes to the Java ByteArrayInputStream which is consumed by the load() method from the CDAUtil library. The load() method takes a stream and returns our ClinicalCareDocument object.
The next section of the code reaches into the document model and extracts the sections we will be working with. The ClinicalCareDocument has many methods to allow for navigation. One thing to notice is that most of the accessor methods are PLURAL and return a collection. So, for example, the call to getRecordTargets() must be followed by a call to get(0) to return the first RecordTarget object. You should check out the User Documentation for MDHT Runtime APIs for a good introduction and the Java source code to explore the object model (unfortunately this is where time and patience are required!). There are also nuggets to be gleaned from the user forum.
The last section maps each of the fields we want to use in our channel. In this very simple example, we are simply pulling some basic patient identify fields for the Given Name, Family Name, Gender and Date of Birth.
While this blog focused on extracting data, the same API can be used in the reverse direction to allow you to create CCD documents from various data sources too while enforcing the specification business rules.