OC-Big is an open source software extension for the electronic data capture system OpenClinica (https://www.openclinica.com/) and has been developed at the Department of Medical Informatics, Uniklinik RWTH Aachen, Germany. OC-Big aims at enriching OpenClinica by a new module for convenient and context-related data integration of large volume files into electronic case report forms (eCRFs). OC-Big is developed using JavaScript (JQuery) and PHP, and is based on other open source projects, namely jQuery File Upload (http://blueimp.github.io/jQuery-File-Upload/) and zip.js (http://gildas-lormeau.github.io/zip.js/).
Features
- Upload of large volume date (only limited by server’s storage space) Support of multiple selection of files and queue processing
- User-friendly drag & drop support
- Data storage with unique filenames including study, event and subject context
- Chunking of data files into multiple parts to exceed browser’s upload limit of 4 GB
- Automatic compression and decompression for transfer (optional)
- Not affected by OpenClinica’s session timeout
- Easy to integrate in and configure through eCRFs
Installation Guide
System Requirements
The following system requirements represent the system configuration of our server. In general, it should also work with similar components.
- Web server (e.g. Debian GNU/Linux 7.x)
- OpenClinica 3.5. with requirements, e.g. PostreSQL, Tomcat (oldest version tested: 3.1.2)
- Apache 2
- PHP 5 (with PECL Zip 1.10.2)
- Apache Tomcat Connector (mod_jk)
- Web browser, tested with Firefox >19 and Google Chrome >26 (Last tested: Firefox 34.0.5, Chrome 44.0.2403.130 m)
Installation
Attention: Currently, OpenClinica has to be configured to be running through the Apache (Port 80) instead of Tomcat (Port 8080) to get OC-Big working. Since OC-Big is running in Apache, cross domain calls would be performed during communication with OpenClinica. These calls are usually forbidden by the browsers and cannot be executed. The following installation manual assumes that OpenClinica should be also running through Apache and explains how this can be set up (step 3).
1. Install OpenClinica
If not already done, install OpenClinica with all requirements. Installation guides for Linux/Windows can be found here. The following manual is based on a Linux (Debian) installation of OpenClinica.
2. Install Apache
Pointing the web browser to http://localhost/ takes us to the default Apache page confirming that Apache has been installed. If not, the command
aptitude install apache2
will catch apache2 from the debian packages and install it.
3. Install Apache Tomcat Connector
As explained before, we now have to configure OpenClinica to be additionally accessible via Apache. For this, we have to forward Apache calls on Port 80 to our OpenClinica location in Tomcat on Port 8080 via mod_jk.
First we install mod_jk
aptitude install libapache2-mod-jk
After this, we configure the /etc/libapache2-mod-jk/workers.properties file. It should look like this:
workers.tomcat_home=/usr/share/tomcat7
workers.java_home=/usr/lib/jvm/default-java
ps=/
worker.list=ajp13_worker
worker.ajp13_worker.port=8009
worker.ajp13_worker.host=localhost
worker.ajp13_worker.type=ajp13
worker.ajp13_worker.lbfactor=1
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=ajp13_worker
But, workers.tomcat_home
and workers.java_home
have to be adapted to your Tomcat/Java home directories.
After this, we configure Tomcat in so far, that it will allow mod_jk calls. For this, we uncomment the following lines in Tomcat’s /conf/server.xml of your Tomcat root folder:
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
In the next step, we have to load OpenClinica from Tomcat into Apache. For this, we modify the /etc/apache2/mods-available/jk.conf file and add the following lines
JkMount /openclinica/* ajp13_worker
JkMountCopy All
In the first line, our OpenClinica web app folder /openclinica/ (adapt this line here, if you changed the name) and all its sub-content is released for Apache forwarding. The second lines says that this configuration should be automatically adapted to all (virtual)-hosts defined in Apache.
Now, we just have to restart Apache and Tomcat. After this our OpenClinica installation should be available at http://hostname/OpenClinica. In addition, it should be still available at http://hostname:8080/OpenClinica, but when accessing it this way, OC-Big might not work due to cross domain calls.
4. Install PHP
PHP5 is required for OC-Big to process transferred files on server side. This can be installed along with the php apache module by
aptitude install php5 libapache2-mod-php5
After this, a server restart must be done
/etc/init.d/apache2 restart
5. Install PHP Zip Extension
Zip functionality is not usually enabled with standard php installations. To check whether the zip functionality is enabled or not, the phpinfo() function can be used. PHP's zip functionality has to be enabled by
# compiling php with the --enable-zip
option OR
# install it via PECL, e.g. install PECL, modify the php.ini file and uncomment zip.so.
6. Extract the OC-Big archive to a temporary folder
The zip file contains the directories
- bin: PHP modules
- css: Cascading Style Sheets (CSS) files for design
- images: Images used in user interface
- js: Used Javascript libraries
- lib: Original source code of used projects and libraries
- openclinica: OpenClinica files including OC-Big.xls as demo eCRF
- server: Server side PHP code to process transferred files
- templates: HTML templates for client side
7. Copy contents on server
Copy the complete content of OC-Big archive into a folder in your Apache's default document root directory (e.g /var/www/oc-big-112/).
8. Set folder permissions
In the directories /server/php/ and /server/php/files/ the transferred files are stored, so these directories need permissions (777).
9. Copy Pop-Up call script into your OpenClinica Tomcat folder
The script /openclinica/showImageUpload.js has to be copied into your OpenClinica Tomcat folder. After a backup, create a folder (e.g. /javascripts/) inside the OpenClinica webapp folder and copy the script file here. This script has to be available inside Tomcat, because it is called from OpenClinica itself.
10. Customize eCRF
Open the /openclinica/OC-Big.xls sample eCRF and modify it. Here a sample integration for image upload into the eCRF is already available. An overview of the parameters, which can be generally set in the eCRF is given below.
11. Install eCRF
Install the eCRF as usual in OpenClinica.
12. Ready!
Settings
OC-Big can be configured directly in the eCRF by modification of the upload button tag. In the sample eCRF it is as follows:
<span class="uploadButton" widthQ="240px" fileType="png" fileCount="1" imgWidth="240px" imgFloat="right" imgDefault="/openclinica/crfImages/default.png" apacheBD="oc-big-112" savePath="/var/www/oc-big-112/server/php/final/” token="test1234!"/>
You can modify the following parameters to adapt OC-Big to your needs:
- fileType: Allowed file types for upload. Multiple types can be separated by comma (e.g. jpg, png). Note: On changing this you currently also have to adapt the content-type in the download.php file to get downloads working as well.
-
fileCount: Maximum number of allowed files.
- imgDefault: Location of default image showed in the eCRF beside of the OC-Big button.
- apacheBD: Name of the OC-Big instance, which is used. If your OC-Big code is in a folder named "oc-big-112" (as described in the manual), "oc-big-112" has to be set here.
- savePath: Path where transferred files are finally stored. Note: On changing this you probably also have to adapt the extraction of the filenames in download.php.
- token: Token to avoid calls of OC-Big from outside the eCRF. The token value in the eCRF and in settings.php have to be the same. The longer this value, the lower the risk of unwanted OC-Big calls from outside. Note: Please change the token value before integration.