TraIT OCWS Example setup & Technical usage manual
Notice to readers: It is the intention to move the TraIT-OCWS repository to the CTMM Trait repository. Once the move has been done this WIKI will be removed.
This document describes how to bulk upload data acquired in clinical trails to the OpenClinica (abbreviated from now on as OC) open-source application using the Translational Information Technology - Open Clinica Web Service (TraIT-OCWS) developed by Arjan van der Velde in 2012. Technically TraIT-OCWS can be considered as an adapter [1] which translates data from a Comma Separated Values (CSV) file to Object Data Model (ODM) format and uploads it using appropriate Webservice calls to OC while MirthConnect (MC) functions as a message-broker. The document uses an example which can be extended to usage for operational uploads.
The data structure as defined in CRF's (Clinical Report Form) of a study must be known to upload data. TraIT-OCWS can generate study-specific templates that can subsequently be populated and loaded into OpenClinica. If data has to be uploaded for an existing study into an already scheduled event for an existing study subject, then the dataImport() web service method of the OpenClinica web services can be used directly. If a subject has to be created and/or an event is to be scheduled beforehand, additional calls need to be made. The TraIT-OCWS software handles these calls transparently. The diagram below depicts the information flows within TraIT-OCWS in combination with Mirth Connect.
The next diagram shows an example of the deployment diagram of a software suite for Clinical Research. It includes 3 (virutal) machines: one for a web-facing Apache server and a second one on which the servlet container Apache Tomcat is running with the web-application OpenClinica. MirthConnect is also deployed on this machine together with the TraIT-OCWS module. A separate third machine is used as the (Postgres) DB-server for both OpenClinica and MirthConnect.
A sample input CSV-file and the corresponding CRF to setup the study can be found here in this repository.
In order to use the example a running Mirth Connect instance and an OpenClinica 3.1.x instance with web services installed are required. Installation documentation for OpenClinica can be found here. Documentation for Mirth Connect can be found here. The TraIT-OCWS library jar should be downloaded and copied into a directory called ' custom-lib ' in the Mirth Connect software tree e.g. /home/mirth/mirthconnect/custom-lib. Mirth Connect may have to be restarted after the library has been installed.
TODO: modify link to jar once the build-scripting has been finished.
Given both main components have been installed the following steps should be taken to setup the example.
- Setup a new study in OpenClinica with an event
- Setup one event and link the sample CRF Database_SAMPLE_001_TRAITOCWS.xls to that event
- Assign a data manager user account to the study and make sure that account has permissions to access the OpenClinica SOAP web services
- Import the example Mirth channels into Mirth Connect
- Change the File Reader such that it points to a valid location for file pickup
- Change the URL and user credentials in the "Setup Batch" destination of the File Read channel
- Generate Mirth ODM template from study metadata ODM using TraITOCWS utility
- Copy the generated ODM template into the OCWriter XML template
The steps above are documented in detail in the sections below.
Create a new study in OpenClinica following the OpenClinica documentation and assign one data manager user to it that has SOAP web services access. The study should look similar to the images below.
Import the two example channels into Mirth Connect and edit the source such that it points to a valid location for file pickup. The example configuration polls for new CSV files every second and processes each file line by line.
Secondly, edit the base URL and access credentials in the first destination -- Setup Batch -- of the File Reader channel. This destination sets up persistent context, identified by the originalFileName channel global variable.
The following command can be used to generate the ODM template required by Mirth Connect in order to transform comma-separated lines into a message that can be loaded into OpenClinica.
./odm.sh --extract -b http://localhost:8081/OpenClinica-ws -u arjan -p 12345678 -s "Mirth at X"
The syntax of the "extract" command is as follows.
usage: extract
-b,--base-url <URL> OpenClinica base URL (i.e.
https://www.example.org/OpenClinica-ws/)
-h,--help this help screen
-m,--meta get plain metadata (do not translate to
template)
-p,--password <password> OpenClinica password
-s,--study <study> OpenClinica study name (or site unique
identifier)
-u,--user <username> OpenClinica username
-v,--verbose be (very) verbose
#CSV-file format The CSV file to import has the following format:
The output should look like this with minor differences in some of the IDs and names in the top section. The order of the ItemData elements is critical and should match the example. The ItemData elements and their order have to be defined in a 'Source-Transformer'. To edit a source-transformer first navigate to the tab called 'Source' in the channel edit screen and then click on the entry called Edit Transformer (... in the panel called 'Channel Tasks' in the menu on the left-side of the screen. The generated template then needs to be copied as is into the destination template of the source transformation in the File Read Channel as depicted in the image below.
Now that everything is in place, the channels need to be deployed and the sample data can be fed into the system by copying it into the pickup location defined in the source of the File Reader channel. The example data contains 10 rows. Out of those 10, 9 should import without problem. The 10th row was deliberately setup to generate an OpenClinica error.
[1]. Enterprise Integration Patterns. Designing, Building and Deploying Messaging Solutions; Gregor Hohpe and Bobby Woolf; Addison-Wesley; 2003