Iteration 0 Configuration
This document outlines how to configure SCOOP components to run on a single workstation. This is the goal of Iteration0. Principles of how the components work together may then be extrapolated and applied to different deployment architectures.
All components have a web deployment platform. OSCAR runs on the Apache Tomcat web server. Mirth has the Jetty web server embedded. And the Rails based components - Mirth Rest Adaptor, Query Gateway, and Query Hub - are deployed locally on the WEBrick server (the web server bundled with rails for testing). Note - particularly for the Rails applications - this should not be considered production deployment instructions.
We deployed the OSCAR 12 Release available on sourceforge. We followed deployment instructions very close to those described in the OSCAR Setup Guide. Note that these differ from the official setup instructions due to the use of the commercial OracleJDK v6u33. The requirement is due to OSCAR's incompatibility with OpenJDK v6 for a few features.
Because Mirth accesses the OSCAR MySQL database directly, it is only essential to have the database layer of OSCAR deployed in order for this prototype to be successful.
A set of anonymized demographics for 10,000 patients was developed to test this iteration. This is available in CSV format. Place the file in the location of the OSCAR database (For MacOSX, this location is /usr/local/mysql/data/oscar12/. It can be loaded directly into the database using the MySQL command-line client and issuing the following statement LOAD DATA INFILE 'clinic1.csv' INTO TABLE demographic FIELDS TERMINATED BY ',' LINES TERMINATED BY '\r' (hin, year_of_birth, month_of_birth, date_of_birth, sex, first_name, last_name);.
[Note 1: MySQL on Ubuntu will have a "file not found error" here. An easy workaround is to copy the file to /tmp and then change the ownership of '/tmp/clinic1.csv' to belong to mysql. See http://ubuntuforums.org/showthread.php?t=822084 for details.]
[Note 2: The 'clinic1.csv' files contains many birth dates that still lie in the future. The query-composer and query-gateway silently ignore such records which means that males plus females plus unknowns do not total 10000!]
We used Mirth Connect v2.2.1.5861. At the time (June 2012) this is available from the main Mirth download page. Once downloaded and unpacked, a mirth service is started on the command-line by navigating to the Mirth Connect directory and issuing the statement ./mcservice start. Respectively the Mirth service may be shutdown by issuing the command ./mcservice stop.
In a web browser, launch the Mirth Connect admin interface from http://localhost:8080/ and log in. The default username and password are both admin.
There are two channels used. (The export file for each channel is included below.) They are run in close sequence. First all the records are removed from the query gateway mongodb by the Purge Records in hQuery Gateway channel. Immediately following - a record for each patient from OSCAR is loaded into the query-gateway mongodb by the Load hQuery Gateway Database channel.
The SCOOP version of the query-gateway includes a DELETE restful web service at /records/destroy in order to remove all records from the records collection in query-gateway's mongodb instance. This channel calls this service once.
Summary Tab
Source Tab
This is a bit of a hack. This channel uses a Database Reader connector type to retrieve a single record from the database. The contents of the record are not used. It is just needed to ensure that the destination of the channel is executed exactly once.
Query
SELECT demographic.hin AS demographic_hin
FROM demographic WHERE demographic.hin=1Destination Tab
There is a single destination defined using the HTTP Sender connector type. Settings are documented in the screenshot below. Note the URL: http://localhost:3001/records/destroy.
Scripts Tab The scripts tab is not changed from default.
This Channel retrieves every demographic record from the OSCAR MySQL database
Summary Tab
Source Tab
Database Reader connector type.
Query
SELECT demographic.demographic_no AS demographic_demographic_no, demographic.last_name AS demographic_last_name, demographic.first_name AS demographic_first_name, demographic.year_of_birth AS demographic_year_of_birth, demographic.month_of_birth AS demographic_month_of_birth, demographic.date_of_birth AS demographic_date_of_birth, demographic.hin AS demographic_hin, demographic.sex AS demographic_sex
FROM demographicSource Transformations
During the source transformation, each element from a source database record is mapped to a channel variable in Mirth. The details of each variable mapping are documented in the table below.
| Number | Variable | Mapping | Channel Type | Scope |
| 0 | firstName | msg['demographic_first_name'].toString() | Mapper | Channel Map |
| 1 | lastName | msg['demographic_last_name'].toString() | Mapper | Channel Map |
| 2 | gender | msg['demographic_sex'].toString() | Mapper | Channel Map |
| 3 | pid | msg['demographic_hin'].toString() | Mapper | Channel Map |
| 4 | birthDate2 | See code block below | JavaScript | N/A |
The 4th source transformation is different. JavaScript is used to derive an HL7 representation of birthdate from three distict elements in the OSCAR database. JavaScript is included beneath the image.
JavaScript
var year = msg['demographic_year_of_birth'].toString();
var month = msg['demographic_month_of_birth'].toString();
var day = msg['demographic_date_of_birth'].toString();
if (month.length == 1) {
month = '0' + month;
}else if (month.length != 2){
logger.error('Patient with invalid birth month');
}
if (day.length == 1) {
day = '0' + day;
}else if (month.length != 2){
logger.error('Patient with invalid birth day');
}
channelMap.put('birthDate2',year + month + day);Destination Tab
The Mirth Rest Adapter exposes a restful web service at the address http://localhost:3000/records/relay. Mirth connects to this address and sends each record as a CDA XML document. The Mirth Rest Adapter re-formats the web service call and forwards it to the query-gateway.
The connector type is HTTP Sender.
The output xml template.
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="CDA.xsl"?>
<!--
Readers should be aware of the evolving "Using SNOMED CT in HL7 Version 3" implementation guide, currently in a draft state. The guide, co-developed by HL7 and the College of American Pathologists, will be balloted by HL7 as an Informative Document. Recommendations in the final published guide should usurp patterns of SNOMED CT usage found in this sample instance.
-->
<ClinicalDocument xmlns="urn:hl7-org:v3" xmlns:voc="urn:hl7-org:v3/voc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3 CDA.xsd">
<!--
********************************************************
CDA Header
********************************************************
-->
<effectiveTime value="20000407"/>
<templateId root="scoop_basic"/>
<recordTarget>
<patientRole>
<id extension="${pid}" root="2.16.840.1.113883.19.5"/>
<patient>
<name>
<given>${firstName}</given>
<family>${lastName}</family>
</name>
<administrativeGenderCode code="${gender}" codeSystem="2.16.840.1.113883.5.1"/>
<birthTime value="${birthDate2}"/>
</patient>
</patientRole>
</recordTarget>
</ClinicalDocument>Scripts Tab This is not changed from default.
In order for a channel to be operational in Mirth Connect - it should be Enabled, then Deployed, then Started.
For reference, the export file from each channel is available for download:
We use a forked version of the query-gateway from hQuery. It can be found in the SCOOPHealth GitHub query-gateway repository. Ensure that you use the branch labeled feature-scoop-it0. Commit 405bf72.
Follow the instructions for setting up the query-gateway at the Main Github README page for hquery/query-composer.
To be consistent with the other configuration instructions, run this component on port 3001.
We used the hquery version of the query-composer found at hQuery GitHub query-composer repository. Ensure that you use the branch labeled master. Commit 83bfb3e.
Follow the instructions for setting up the query-composer at the Main Github README page for hquery/query-composer.
To be consistent with the other configuration instructions, run this component on port 3002.
Due to the way that mirth implements Restful web services, it can't connect directly to the query gateway. Each CDA document is attached as a parameter to a multipart form web service call. There is a web service call made for each patient record in OSCAR's database. The problem is that Mirth gives each CDA a randomly-generated UUID for a parameter name. The query-gateway fetches the CDA document by referencing a specific parameter name. Mirth does not support specific parameter naming for attachments to a restful web services call.
The Mirth Rest Adapter simply renames the CDA attachment on the web service call then forwards it to the query-gateway. The query-gateway is then able to retrieve the CDA document using the specific parameter name it is expecting.
It may be retrieved from the SCOOPHealth GitHub mirth-rest-adatper repository. Ensure that you use the branch labeled master. Commit 813e986.
If you have previously deployed the query-gateway or the query-composer then your rails environment should be set up correctly. However, inside the mirth-rest-adapter application the URL to forward web service called to will need to be updated. This is set in the records_controller.rb file on this line url = URI.parse('http://localhost:3001/records/create').
To be consistent with the other configuration instructions, run this component on port 3000.
These two command should be sufficient.
bundle install
bundle exec rails server -p 3000
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
