OpenClinica Developer's Manual - OpenClinica Resources - Akaza ...

assistantashamedΔιαχείριση Δεδομένων

29 Νοε 2012 (πριν από 4 χρόνια και 6 μήνες)

887 εμφανίσεις

Akaza Research

Page
1

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.


OpenClinica

1.1

Developer’s Manual


Date Created:
8/18/2006 12:18 PM

Date Updated:
3/16/2013 5:29 AM

Document Version: v0.
3

DRAFT


Document Summary


Summary here


Table of C
ontents


1

OpenClinica: Under the Hood, or a Short Introduction

................................
...........................

2

2

Installation of the OpenClinica code and developers’ toolset

................................
.................

2

2.1

Java

................................
................................
................................
................................
....

3

2.2

Eclipse

................................
................................
................................
................................

3

2.3

Postgres

................................
................................
................................
..............................

3

2.4

Tomcat

................................
................................
................................
................................

4

2.5

A (long) note on Tomcat 5.5

................................
................................
...............................

5

2.6

OpenClinica Application Setup

................................
................................
...........................

7

2.7

Verify System Environment

................................
................................
..............................

13

2.8

Online tools: bugtracker, CVS, etc.

................................
................................
..................

13

3

Java and OpenClinica

................................
................................
................................
...........

13

3.1

Model View Controller and the OpenClinica code

................................
............................

13

3.2

How code is organized in the Java layer

................................
................................
..........

15

3.3

Code conventions

................................
................................
................................
.............

15

3.4

Modifying the Java code

................................
................................
................................
...

15

3.5

An

introduction to Java troubleshooting

................................
................................
...........

15

3.6

How to use Eclipse and OpenClinica

................................
................................
...............

15

4

Postgres and OpenClinica

................................
................................
................................
....

15

4.1

The data model and its organization

................................
................................
................

15

4.2

Temporary Tables vs. Views in Extracting Data
................................
...............................

15

4.3

Auditing Triggers

................................
................................
................................
..............

15

4.4

An introduction to Postgres troubleshooting

................................
................................
.....

15

5

Tomcat and OpenClinica

................................
................................
................................
......

16

5.1

System Administration; what you or your administrator will have to know

.......................

16

5.2

Tomcat Troubleshooting

................................
................................
................................
...

16

5.3

Expanded Install FAQ

................................
................................
................................
.......

16

6

Checking changes back into CVS

................................
................................
........................

16


Revision History


Date

Version

Description of Document Up
dates

Author

8/18/06

v0.1

First
outline

Tom

8/18/06

v0.2

Revised outline

Cal & Tom

8/22/06

v0.3

Added initial draft of content

Tom


Akaza Research

Page
2

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.


1

OpenClinica: Under the Hood, or a Short Introduction

OpenClinica is a web
-
based software platform for managing multi
-
s
ite clinical research studies. It
facilitates protocol configuration, design of Case Report Forms (CRFs), electronic data capture,
retrieval, and management. OpenClinica supports HIPAA guidelines, and is designed as a
standards
-
based extensible, modular an
d open source platform.


The OpenClinica platform was developed using the Java J2EE framework, with a database
abstraction layer interoperable with PostgreSQL 8.x and Oracle 10g (porting to DB2 and SQL
Server databases planned in forthcoming releases). Ope
nClinica runs on Red Hat Enterprise
Linux v3.x, on top of any Servlet/JSP container that implements the Servlet 2.x and JavaServer
Pages 2.x specifications from the Java Community Process. It was developed to run on Apache
Jakarta Tomcat 5.x. This architec
ture provides a secure, robust and extensible system for
managing multiple clinical research studies within a centralized repository.


Software Dependencies and System Requirements


The Main Appli
cation Modules include:




Manage Study: Facilitates configuration and management of studies (protocols), sites, CRFs,
users and study event definitions by study directors and coordinators. You can define data
elements, CRFs, and protocol events without any

custom programming.



Submit Data: Provides a user
-
friendly web
-
based interface for subject enrollment, data
submission and validation. For use by clinicians and research associates involved in patient
enrollment and data capture processes.



Extract Data:
Enables data extraction and filtering of datasets for use by investigators,
statisticians, and study directors.



Administer Studies (Business): [Facilitates configuration and management of multiple studies
(protocols), sites, CRFs, users, and study event d
efinitions by study directors and
coordinators. Allows overall system oversight, auditing, configuration, user account
management, and reporting by business users.]



Administer System (Technical): Allows overall system oversight, auditing, configuration, u
ser
account management, and reporting by administrators.


2

Installation of the OpenClinica code and developers’ toolset

OpenClinica runs and depends on several external applications: Sun's Java Development Kit,
Apache Jakarta's Tomcat Servlet Container, an
d the Postgres Realtional Database. Although
many Linux systems already have these applications installed or can easily be installed,
OpenClinica has been tested only on the vanilla packages provided by their respective websites.
Although compatible with t
he packages supplied by your distribution, this manual does not
assume distribution
-
specific installions of the required applications.


Note: This installation guide is intended to get OpenClinica up and running as easily as possible
on a Linux server. It
does not go into details for development of OpenClinica from the source
code. This information will be available soon, and will cover setting up Apache Ant and Eclipse.


1) Install Java J2SDK 1.4.2x

2) Install OpenClinica 1.1 Source

3) Install Tomcat 5.0.x

4) Install PostgreSQL 8.0.x

5) Install OpenClinica 1.1

6) Configure OpenClinica

Akaza Research

Page
3

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

2.1

Java

This step might not required since many systems already have Java SDK installed. If there are
any issues with applications or the system only has the Java run
-
time enviro
nment (JRE), please
do the following steps. This will archive your previous installation and install the new version in its
proper location.


If you want to download the SDK from the website please go to:

http://java.sun.com/j2se/1.4.2/download.html

Click
on the link "Download J2SE SDK" and read the License. If you agree with the license, then
continue.

Under the Linux section click on the link labeled "self
-
extracting file" (not the RPM)


After you download it run the following commands:

<login with user
account>

sh j2sdk
-
1_4_2_12
-
linux
-
i586.bin;

<read license and press space until you get to bottom of screen, it will then extract>

su

<enter root password>

mv j2sdk1.4.2_12 /usr/share/

cd /usr/share/

mv java java.old

ln
-
s j2sdk1.4.2_12 java

echo "export J
AVA_HOME=/usr/share/java" >> /etc/profile;


More detailed installation instructions for the SDK can be found at
http://java.sun.com/j2se/1.4.2/install
-
linux.html.

2.2

Eclipse

2.3

Postgres

For more information about installation please check the file called INSTALL

after

extracting the tar file. This is essentially the same set of scripts, modified to

take the OpenClinica installation into account. This installion assumes that the development
libraries

are properly installed, including gcc and make.


Go to http://
www.postgresql.org/ftp/source/v8.1.4/ and select "postgresql
-
8.1.4.tar.gz". You will be
presented with mirrors. Select one in your country and it will download.


<login with user account>

tar
-
xzvf postgresql
-
8.1.4.tar.gz

cd postgresql
-
8.1.4

./configure

gm
ake

su

gmake install

/usr/sbin/adduser postgres

gpasswd
-
a postgres developers

mkdir /usr/local/pgsql/data

chown postgres /usr/local/pgsql/data

su
-

postgres

/usr/local/pgsql/bin/initdb
-
D /usr/local/pgsql/data

exit

echo "export PGDATA=/usr/local/pgsql/dat
a" >> /etc/profile;


Akaza Research

Page
4

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

Now setup postgres to run as a daemon


<login as root>

cp /var/OpenClinica
-
1.1/conf/postgresqld /etc/init.d/

cd /etc/init.d

chmod 755 postgresqld

/sbin/chkconfig
--
del postgresqld

/sbin/chkconfig
--
add postgresqld

<exit and reboot your

system>


Check if postmaster is running, you should see several postgres (postmaster) processes

ps
-
A | grep postmaster


If you are having issues getting postgres to run as a standalone service, check to make sure that
the daemon file (postgresd) has UNIX

style (LF only) line endings. If the file has DOS style line
endings the scripts will fail.


You can manually start postmaster with the following commands

<login as root>

su
-

postgres

/usr/local/pgsql/bin/pg_ctl start
-
D /usr/local/pgsql/data/ >logfile 2
>&1 &

exit

exit


More detailed installation instructions for Postgres can be found at
http://www.postgresql.org/docs/8.1/interactive/index.html.


<login with user account>

su
-

root

su
-

postgres

/usr/local/pgsql/bin/createdb openclinica

/usr/local/pgsql/b
in/psql
-
d openclinica
-
f /var/OpenClinica
-
1.1/database/PostgreSQL/1.1/install/OpenClinica_1.1_db_tables_only.sql

/usr/local/pgsql/bin/psql
-
d openclinica
-
f /var/OpenClinica
-
1.1/database/PostgreSQL/1.1/install/basecase_data_1.1.sql

2.4

Tomcat

We will download

the binary files of Tomcat to extract the file. We will then create a user called
tomcat. Root will put it in a system directory and set the environment variable to point to the install
directory.


<login with user account>

su
-

root

<enter password>


/us
r/sbin/adduser tomcat

/usr/sbin/groupadd developers

/usr/bin/gpasswd
-
a tomcat developers

su
-

tomcat

cd

wget http://www.apache.org/dist/jakarta/tomcat
-
5/v5.0.28/bin/jakarta
-
tomcat
-
5.0.28.tar.gz

tar
-
zxvf jakarta
-
tomcat
-
5.0.28.tar.gz

exit

mv /home/tomcat/j
akarta
-
tomcat
-
5.0.28 /usr/share/

cd /usr/share

ln
-
s jakarta
-
tomcat
-
5.0.28 tomcat

Akaza Research

Page
5

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

su
-

root

<enter password>

echo "export CATALINA_HOME=/usr/share/tomcat" >> /etc/profile

exit


To install Tomcat as a standalone service (one that stops and starts with the s
ystem) you must
install a daemon.


<login as root>

cp /var/OpenClinica
-
1.1/conf/tomcatd /etc/init.d/

cd /etc/init.d

chmod 755 tomcatd

/sbin/chkconfig
--
del tomcatd

/sbin/chkconfig
--
add tomcatd

<exit and reboot your system>


You can verify that tomcat is
running by checking

http://localhost:8080


If you are having issues getting tomcat to run as a standalone service, check to make sure that
the daemon file (tomcatd) has UNIX style line endings (LF only). If the file has DOS style line
endings the scripts
will fail.


You can manually start and stop tomcat with these scripts

/usr/share/tomcat/bin/startup.sh

/usr/share/tomcat/bin/shutdown.sh


More detailed installation instructions for Apache Tomcat can be found at
http://jakarta.apache.org/tomcat/tomcat
-
5.0
-
doc/setup.html.

2.5

A (long) note on Tomcat 5.5

The recommended environment for OpenClinica is Tomcat5.0 and Java1.4.x.


The following instructions are only for Users who already have Tomcat5.5 and Java1.5, and want
to continue using this

environment to run
OpenClinica.


NOTE that the current OpenClinica code base is not fully tested with Java1.5, but the
OpenClinica.war is runnable

under Tomcat5.5/Java1.5.x. We will upgrade OpenClinica using Java1.5 in a future release.


OpenClinica runs and depends on thre
e external applications: Sun's Java Development Kit,

Apache
-
Jakarta's Tomcat Servlet Container, and the Postgres Realtional Database.

Although many Linux systems already have these applications installed or can easily be installed,

OpenClinica has been
tested only on the vanilla packages provided by their respective websites.


Although compatible with the packages supplied by your distribution, this manual does not
assume


distribution
-
specific installions of the required applications.


1) Install Java 1
.5

2) Install Tomcat 5.5.x

3) Install PostgreSQL 8.0.x

4) Install OpenClinica Application

5) Install OpenClinica Libraries


Akaza Research

Page
6

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

Please refer to INSTALL.txt as the completed installation guide. Here only the different
requirements for Tomcat5.5

are listed.


Co
nfiguration File

----------------------------------------------------------------------------

Tomcat5.5 requires a different OpenClinica.xml.


Edit $TOMCAT_HOME/conf/Catalina/localhost/OpenClinica.xml to fit your Tomcat enviroment
variables.

A description

of why this file is important and what it does can be found at
http://jakarta.apache.org/tomcat/tomcat
-
5.5
-
doc/deployer
-
howto.html.


This file will contain the following XML:


<Context path="/usr/share/tomcat/webapps/OpenClinica" docBase="OpenClinica" de
bug="99"
reloadable="true"





crossContext="true" useNaming="true">





<Parameter name="propertiesDir"
value="/usr/share/tomcat/webapps/OpenClinica/properties/" override="false"/>





<Parameter name="datasetHomeDir" value="OpenClinica"
override="fal
se"/>


<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"





driverName="org.postgresql.Driver" digest="MD5"

connectionURL="jdbc:postgresql://127.0.0.1:5432/openclinicadev"

connectionName="clinica" connectionPassword="clinica" userTable="
user_account"

userNameCol="user_name" userCredCol="passwd"

userRoleTable="study_user_role" roleNameCol="role_name"/>






<Logger
className="org.apache.catalina.logger.FileLogger" prefix="openclinica_log_1.0."






suffix=".txt" timestamp="true"/>








<Resource name="SQLPostgres" auth="Container"


type="javax.sql.DataSource"
factory="org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory"


username="clinica"


password="clinica"


driverClassName="org.postgresql.Driver"


url="jdbc:postgresql://127.0.
0.1:5432/openclinicadev"




maxActive="100"


maxIdle="30"


maxWait="10000"/>







</Context>


You will have to change the following items:


url = the address of your postgres database.

username = the username that will log in to the database. Note tha
t this is unique to the
database system only, and is not a user on the Linux system.

password = the password that the database user 'clinica' will use to log in to the database. NOTE
that this should be something OTHER THAN 'clinica'.


Tomcat 5.5 Library
Files

-------------------------------------------------------------------------

The library files for Tomcat5.0 and Tomcat5.5 are a little different.

Akaza Research

Page
7

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

You can run 'ant install
-
libs
-
new' and 'ant install
-
new' to copy required libs into Tomcat5.5.

Please chec
k tomcat/commom/lib/ folder and see whether you have the following lib files, if not,
please copy

any missing files to it:


activation.jar

jstl.jar

mail.jar

poi
-
2.5
-
final
-
20040302.jar

standard.jar

postgresql
-
8.0
-
310.jdbc3.jar

commons
-
digester.jar

commons
-
d
bcp
-
1.2.1.jar

commons
-
collections
-
3.1.jar

commons
-
beanutils.jar

cos.jar


2.6

OpenClinica Application Setup

The next step is to copy the configuration files and the web application file (war) to the tomcat
folders. Since tomcat is running, it will hot deploy th
e application, creating the rest of the file
structure. Several dependent java libraries should also be copied from the source tree into the
tomcat lib folder. Next we will need to setup the applications configuration files.


<login as root>

su
-

tomcat

cp

/var/OpenClinica
-
1.1/lib/OpenClinica.war $CATALINA_HOME/webapps

cp /var/OpenClinica
-
1.1/conf/OpenClinica.xml $CATALINA_HOME/conf/Catalina/localhost

cp /var/OpenClinica
-
1.1/lib/deps/*.jar $CATALINA_HOME/common/lib/


Note: Once Tomcat deploys the war file,
you should be able to see
$CATALINA_HOME/webapps/OpenClinica/ , if you cannot, try restarting Tomcat to kickstart the
deployer.


There are three configuration files that need to be changed.


Edit $CATALINA_HOME/webapps/OpenClinica/properties/datainfo.prope
rties and change the
properties to suit your server environment as needed. The initial datainfo.properties file looks
something like this:


dbURL=jdbc:postgresql://localhost:5432/openclinica

filePath=/usr/share/tomcat/openclinica.data/

dataBase=postgres

p
asswd_expiration_time=180

auth_mode=password

user_account_notification=email

smtpHost=localhost

adminEmail=admin@openclinica.org

sysURL=https://localhost/OpenClinica/MainMenu

change_passwd_required=0


dbURL: The uniform resource locator of your Postgres d
atabase. Typically, the only thing you will
have to change is 'localhost' to the address of your database server.


filePath: The path that files will be written to in the course of daily operations. Note that this is a
seperate directory because the weba
pps/OpenClinica directory can be erased and rebuilt when
Akaza Research

Page
8

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

you deploy a new version of the system. This directory will hold sensitive information such as
CRFs, datasets, etc. so it should be on a secured machine.


dataBase: Currently only 'postgres' is the
correct answer; for this release it should not change.
Upcoming releases will have options for an 'oracle' version of OpenClinica, however.


passwd_expiration_time: Number of days before you are prompted to change your password.
Lower numbers (30, 60, 90
) will encourage users to change their passwords more often.


auth_mode: Currently only 'password' will work; you will be able to add other authentication
modes in the future, including 'ldap'.


user_account_notification: Can be either 'email' or 'offline
'. If it is 'email' the system will send an
email to new users, notifying them that an account has been created for them. If it is 'offline', then
the system will not send an email and the administrator will have to contact the user personally to
let the
m know that they have an account.


smtpHost: The current email SMTP Host that you will use to send emails to the users of the
system. Usually it is on another machine and will not be 'localhost'.


adminEmail: The reply email used in the emails to users of

the system.


sysURL: The address of the web address for the system. Again, only 'localhost' should change
on your system, and it can either be an external address (demo.openclinica.org) or an internal IP
address (192.168.1.100).


change_passwd_required:

Indiates whether users are forced to change their password when it
expires. (Note: the first time a user logs into the system, the password is considered expired.)


Edit $CATALINA_HOME/conf/Catalina/localhost/OpenClinica.xml to fit your Tomcat enviroment
variables.

A description of why this file is important and what it does can be found at
http://jakarta.apache.org/tomcat/tomcat
-
5.0
-
doc/deployer
-
howto.html. The file should already
have the Linux paths but you will have to edit the docbase property. For m
ost purposes your
OpenClinica.xml file should look like this:


<Context path="/OpenClinica" docBase="/usr/share/tomcat/webapps/OpenClinica" debug="99"
reloadable="true" crossContext="true" useNaming="true">



<Parameter name="propertiesDir"
value="/
usr/share/tomcat/webapps/OpenClinica/properties/" override="true"/>


<Parameter name="datasetHomeDir" value="OpenClinica" override="false"/>


<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
driverName="org.postgresql.Driver"

digest="MD5"


connectionURL="jdbc:postgresql://localhost:5432/openclinica"
connectionName="clinica" connectionPassword="clinica" userTable="user_account"


userNameCol="user_name" userCredCol="passwd"
userRoleT
able="study_user_role" roleNameCol="role_name"/>


<Resource name="SQLPostgres" scope="Shareable" auth="Container"
type="javax.sql.DataSource"/>



<Logger className="org.apache.catalina.logger.FileLogger" prefix="openclinica_log"



suffix=".txt" timestamp="true"/>


<Resource name="SQLPostgres" scope="Shareable" auth="Container"


type="javax.sql.DataSource"/>


<ResourceParams name="SQLPostgres">


<parameter>

Akaza Research

Page
9

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.



<name>url</name>


<value>jdbc:postgresql://localhost:5432/openclinica</value>


</parameter>


<parameter>


<name>driverClassName</name>


<value>org.
postgresql.Driver</value>


</parameter>


<parameter>


<name>username</name>


<value>clinica</value>


</parameter>


<parameter>



<name>password</name>


<value>clinica</value>


</parameter>


<parameter>


<name>maxActive</name>


<value>50</value>


</parameter>



<parameter>


<name>maxWait</name>


<value>
-
1</value>


</parameter>


<parameter>


<name>maxIdle</name>


<value>10</value>



</parameter>


</ResourceParams>

</Context>


The things that will have to be changed to fit your Tomcat environment are the security realm
(indicated by the Realm tags) and the database resource (indicated by the ResourceParams
tags).


Let's
take a look at the Realm tags again:


<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
driverName="org.postgresql.Driver" digest="MD5"



connectionURL="jdbc:postgresql://localhost:5432/openclinica"
connectionName="clinica" connectionPasswo
rd="clinica" userTable="user_account"



userNameCol="user_name" userCredCol="passwd"
userRoleTable="study_user_role" roleNameCol="role_name"/>


You will have to change the following items:


connectionURL = the address of your postgres database.

connectionN
ame = the username that will log in to the database. Note that this is unique to the
database system only, and is not a user on the Linux system.

connectionPassword = the password that the database user 'clinica' will use to log in to the
database. NOTE
that this should be something OTHER THAN 'clinica'.


Again, let's review the ResourceParams which you should also change:


<ResourceParams name="SQLPostgres">



<parameter>




<name>url</name>

Akaza Research

Page
10

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.




<value>jdbc:postgresql://localhost:5432/openclinica</value>



</parameter>



<parameter>




<name>driverClassName</name>




<value>org.postgresql.Driver</value>



</parameter>



<parameter>




<name>username</name>




<value>clinica</value>



</parameter>



<parameter>




<name>password</name>




<value>clinica</va
lue>



</parameter>



<parameter>




<name>maxActive</name>




<value>50</value>



</parameter>



<parameter>




<name>maxWait</name>




<value>
-
1</value>



</parameter>



<parameter>




<name>maxIdle</name>




<value>10</value>



</parameter>


</ResourceP
arams>


Note that the names of the paramters will remain unchanged, but the values will be different.


url = again, the address of your database. Should be the same as connectionURL above.

username = the user name for your database. Should be the same as

connectionName.

password = the password used to access your database. Should be the same as
connectionPassword.


Edit $CATALINA_HOME/webapps/OpenClinica/properties/facilityinfo.properties and change the
settings there for your facility's name, address, s
tate, etc that will be treated as the 'default'
location and contact information for users and subjects.


#
-----
Facility information
--------

FacName=Default GCRC

FacCity=Boston

FacState=MA

FacZIP=02142

FacCountry=USA

FacContactName=John Smith

FacContactDe
gree=PhD, MD

FacContactPhone=617
-
123
-
1234

FacContactEmail=aaa@aaa.org

#
-----
User Role information
--------

ra=Data Entry Person

investigator=Investigator

director=Study Director

coordinator=Study Coordinator


Akaza Research

Page
11

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

Many of the fields above are self
-
explanatory;
the user role names are to switch out the names
we have in our system for names that are convention in your own study, i.e. Research Assistant
instead of Data Entry Person.


Create Directory Structure

-------------------------------------------------------
-------

In the previous step, we defined the filePath in datainfo.properties.

The default value is filePath=/usr/share/tomcat/openclinica.data/, but it can be any value you
wish. Make sure you have the path defined as the filePath on the server, and the
path must be
accessible by tomcat user.


This path is required for saving uploaded CRFs and archived dataset files.

Also, it is the home for the CRF spreadsheet template. To offer the template through your
system, create a folder "crf" under the path an
d copy /var/OpenClinica
-
1.1/conf/CRF_Design_Template.xls into it.



For example, if the filePath=/usr/share/tomcat/openclinica.data/, you can

cp /var/OpenClinica
-
1.1/conf/CRF_Design_Template.xls /usr/share/tomcat/openclinica.data/crf/


The final CRF and da
taset file structure will be like the following:

+
---
filePath

+
---
crf
-

crf blank template (CRF_Design_Template.xls )


+
---
new
-

crf verion templates reorganized by system (.xls)


+
---
ori
ginal
-

crf original templates uploaded from user's local machine (.xls)

+
---
datasets


+
---
21
-

dataset files (.txt, .dat, .sps)


+
---
22
-

dataset files (.txt, .dat, .sps)


+
---
25
-

dataset files (.txt, .dat, .sps)


+
---
(etc.)
-

dataset files (.txt, .dat, .sps)



The folders 'new', 'original', and 'datasets' will be created by OpenClinica application if they don
't
exist on the server. But you should create 'filePath','crf' manually before using the application.


Note: Make sure the tomcat user has write permissions on all of these directories.


Configure HTTPS

-----------------------------------------------------
---------

First generate an SSL Certificate. Please go to the Apache website for a more detailed
explanation:

http://jakarta.apache.org/tomcat/tomcat
-
5.0
-
doc/ssl
-
howto.html


In summary of the above HOWTO, run the following commands:


<login as root>

su
-

t
omcat

$JAVA_HOME/bin/keytool
-
genkey
-
alias tomcat
-
keyalg RSA

exit


and specify the password. The default Tomcat password is "changeit". NOTE that you should
please use another password.


In $CATALINA_HOME/conf/server.xml comment out the Connector whose p
ort is 8080. Like the
example below:


<!
--

<Connector port="8080"

Akaza Research

Page
12

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.


maxThreads="150" minSpareThreads="25" maxSpareThreads="75"


enableLookups="false" redirectPort="8443" acceptCount="100"


debug="0" connectionTimeout="20000"


disableUploadTimeout="true" />

--
>


Then enable the Connector whose port is 8443. And be sure to specify the password.

The Connector should look like this:


<Connector port="8443"


maxThreads="150" minSpareThreads="25" maxSpareThreads="75"


enableLookups="false" disableUploadTimeout=
"true"


acceptCount="100" debug="0" scheme="https" secure="true"


clientAuth="false" sslProtocol="TLS"


keystorePass="changeit"

/>





For Tomcat to run in port 443 (https), Tomcat will need to run as root or a rerouting must enabled
at the
firewall level. We discourage running Tomcat as root so the following explains how to setup
iptables to redirect traffic from port 8443 to 443. When redirecting port, the localhost will still need
to access in port 8443 and external users will see it in po
rt 443.


<login as root>

/sbin/iptables
-
t nat
-
A PREROUTING
-
p tcp
--
dport 443
-
j REDIRECT
--
to
-
port 8443


Then save the iptables configuration, so it can be loaded at system boot.

/sbin/iptables
-
save > /etc/sysconfig/iptables

<exit and reboot>


Setting U
p The Data Warehouse

--------------------------------------------------------------

In order to run queries on data, a data warehouse table needs to be created that will compile data
automatically while users are entering it on the system. The script that

does this is contained in
/var/OpenClinica
-
1.1/conf/pg_data_warehouse.sql; a cron job must be set up on the Linux server
to run the script on a regular basis. Documentation about the cron job can also be found in the
conf directory.


Future versions of O
penClinica will not require the cron job, as we are working on a scheduler to
manage these events.


You will have to add a line to the crontab for the user postgres (Note: crontab defaults to using vi
as an editor, if you are more comfortable with emacs or

some other text editor, try calling export
EDITOR=emacs before running crontab)


<login as root>

su
-

postgres

crontab
-
e


add the following row to the table

0 0 * * * /usr/local/pgsql/bin/psql
-
U clinica
-
d openclinica
-
f /var/OpenClinica
-
1.1/conf/pg_dat
a_warehouse.sql


This will setup a cron job that will update the data warehouse daily at midnight.


Akaza Research

Page
13

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

2.7

Verify System Environment


The following set of tasks must be conducted to ensure the system is correctly setup and

integrated for user testing.


1. First
ensure that Tomcat is running and properly configured in Linux:


Login as root and type "su
-

tomcat" to login as tomcat


Type ps aux | grep tomcat and see if it is running


Type env | grep CATALINA_HOME and make sure that it is set


2. Ensure that Postgre
s is running:


Login as postgres and type "su
-

postgres" to login as postgres


Type ps aux | grep postmaster and see if it is running


Type env | grep PGDATA and make sure that it is set.


3. Verify Tomcat deployed the web application.


Check $CATALINA_HO
ME/webapps for an OpenClinica directory.



4. Test in browser.


On the server, if browser is installed, type https://<hostname>:8443/OpenClinica


If it loads the OpenClinica page, then the installation is OK. Next, load the


https://<hostname>/OpenClinica

on a remote machine that can access the server.


5. Login.


Login with the username "root" and the password "12345678". Please change this
password as soon as you log in. The root user will be assigned a default project called "default".
Create a technica
l admininstrator login for youself and remove the default root user and other
"demo" accounts.


6. To Upload a Case Report Form (CRF):


After logging in as a Manager/Study Director/Administrator, go to Manage Study
-
> CRFs
-
> Create New CRF. After enteri
ng the general name and description for the CRF, you will be
prompted for information about the first version and asked to upload the CRF spreadsheet, a
version of which is provided in the conf directory. After checking all the fields, you will be
prompte
d to confirm the new CRF and version and it will appear in your study in the OpenClinica
application.

2.8

Online tools: bugtracker, CVS, etc.


3

Java and OpenClinica

3.1

Model View Controller and the OpenClinica code

The OpenClinica system is based on a classic desi
gn pattern known as Model
-
View
-
Controller, or

MVC for short. The MVC architecture originally has its roots in Smalltalk, where it was used to

map traditional input, processing and output tasks to the graphical user interaction model. It has

been used in ma
ny applications since then, because of its straightforward approach to creating

flexible multi
-
tier applications.


In OpenClinica, the code base is divided to provide a thoughtful, easy to extend strategy:




The View components
all work towards forwarding t
he user to Java Server Pages (JSP)

and HTML pages, which display the content.



The Model components
all work to interface with the database and create Java Objects

based on the data present in the database.

Akaza Research

Page
14

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.



The Controller components
regulate the traffic bet
ween the view and the model,

regulating
secure access and providing the business logic.


Additionally, the Model layer is created using a database
-
agnostic layer, which is code that

separates database
-
specific query code from the standard Java Database Con
nectivity (JDBC)

code standard for all applications using Java. This means that switching between databases is

easy to manage.


Use of the MVC together with a database abstraction layer gives OpenClinica several strengths:




Ease of modification.
Since the
application is distributed, the design lends itself

naturally to
concurrent modification and updates by multiple developers. This allows more

of the
contributions of the OSS community to be included in each release.



Easier support for unique technology nee
ds.
Every clinical research laboratory will

have
different needs and requirements; the OpenClinica code base allows different types

of labs to
use its system effectively.



Re
-
use of Model and Controller components.
Using MVC, developers are able to reuse

co
de and keep the size of the entire application down.


Akaza Research

Page
15

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

3.2

How code is organized in the Java layer


3.3

Code conventions

3.4

Modifying the Java code

3.5

An introduction to Java troubleshooting

3.6

How to use Eclipse and OpenClinica


4

Postgres and OpenClinica

4.1

The data model and

its organization

4.2

Temporary Tables vs. Views in Extracting Data

4.3

Auditing Triggers

4.4

An introduction to Postgres troubleshooting


Akaza Research

Page
16

Created:
8/23/2006 10:37 AM

www.AkazaResearch.com


Last Saved:
3/16/2013 5:29 AM

www.Op
enClinica.org


Last Saved by:

ccollins


assistantashamed_1cdd91fc
-
f233
-
44a0
-
9437
-
e7c835101420.doc





Copyright 2006 Akaza Research, LLC
.
All Rights Reserved.

5

Tomcat and OpenClinica

5.1

System Administration; what you or your administrator will have to know

5.2

Tomcat Troubleshooting

5.3

Expanded In
stall FAQ


6

Checking changes back into CVS