Pulmonary Function Test Processing Installation Guide

Release 1.3

1. Prerequisites

Required Software

If you installed the prerequisite software from the Hive Installation Guide you may skip this section. In addition, if you have previously installed the PFT cell under another release there is no reason to reinstall or upgrade the PFT cell. Release 1.3 PFT changes only affect the client software.

a. Java JDK

JDK 5.0 (recommended)

Download JDK 5.0 Update 11 (jdk-1_5_0_11-linux-i586.bin) from http://java.sun.com/products/archive/

a)Install the SDK into a directory of your choice (/opt/java/jdk1.5.0_11, /opt/java/jdk1.6.0_02, or YOUR_JAVA_HOME_DIR)

b. Apache Tomcat 5.5 + JDK 1.4 Compatability Package

The PFT cell runs under tomcat. Download 'apache-tomcat-5.5.23-compat.zip' and 'apache-tomcat-5.5.23.zip' from http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.23/bin/

a)Unzip into a directory of your choice (/opt/apache-tomcat-5.5.23 or YOUR_TOMCAT_HOME_DIR)
________________________________________________________________________
_____________________________________________________________________
PFT Installation Guide Release 1.3 2
b) If default port 8080 is unavailable (another application is using this port), edit 'YOUR_TOMCAT_HOME_DIR/conf/server.xml' file to reconfigure the non-SSL HTTP/1.1 Connector to another port such as 7070 and the AJP 1.3 connector to another port such as 7009

<!-- Define a non-SSL HTTP/1.1 Connector on port 7070 -->
<Connector port="7070" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true" />

<!-- Define an AJP 1.3 Connector on port 7009 -->
<Connector port="7009"
enableLookups="false" redirectPort="8443"
protocol='AJP/1.3'/>

c)You may also need to update the run permission of the tomcat startup scripts.

'chmod 775 YOUR_TOMCAT_HOME_DIR/bin/*.sh'

c. Apache Ant 1.6.5

Download 'Apache Ant version 1.6.5' (apache-ant-1.6.5-bin.zip) from http://archive.apache.org/dist/ant/binaries/

a)Unzip into a directory of your choice (/opt/apache-ant-1.6.5 or YOUR_ANT_HOME_DIR)

d. Apache Axis2 1.1

Download 'Apache Axis2 version 1.1', from http://ws.apache.org/axis2/download/1_1/download.cgi and select the download type WAR (Web Archive) Distribution.(axis2.war)

a)Create folder axis2 inside 'YOUR_TOMCAT_HOME_DIR/webapps'

b)Unzip axis2.war inside 'YOUR_TOMCAT_HOME_DIR/webapps/axis2' folder.

e. Update your environment variables

Be sure to set the JAVA_HOME, ANT_HOME and CATALINA_HOME variables to the JAVA, ANT and Tomcat home directories you set up in steps a-c respectively. Examples are shown below.

# Sample environment variables
JAVA_HOME=/usr/java/jdk1.5.0_11
ANT_HOME=/opt/java/apache-ant-1.6.5
CATALINA_HOME=/opt/apache-tomcat-5.5.23
PATH=$PATH:$ANT_HOME/bin:$JAVA_HOME/bin
export JBOSS_HOME
export CATALINA_HOME
export JAVA_HOME

2. Install Server Software

Installing the Pulmonary Function Test Processing Application

If you have previously installed the PFT cell under another release there is no reason to reinstall or upgrade the PFT cell. Release 1.3 PFT changes only affect the client software.

1. Download and extract PFT server source code to a target area.

a) Set up a target source_directory.

b) Extract PFT server source code to the target source_directory

2. Ensure that Tomcat is not running

a) './$CATALINA_HOME/bin/catalina.sh stop'

3. Deploy from edu.harvard.i2b2.pft

a) 'cd source_directory/edu.harvard.i2b2.pft'

b) Edit the build.properties file and set tomcat.home property.

tomcat.home=YOUR_TOMCAT_HOME_DIR

c) ant -f master_build.xml build-all

d) ant tomcat-deploy

4. Start Tomcat

a) ./$CATALINA_HOME/bin/catalina.sh start

5. Verify webservice is running

a) Check url 'http://yourHost:7070/axis2/services/listServices' in a browser.

Verify that PFTService is listed as active.

(Port will be the non-SSL HTTP/1.1 Connector configured during your Tomcat installation.)

6. Configure PFT cell information in gridsphere

This step is addressed in section 5, Global Hive Data of the Project Management (PM) Cell/gridsphere installation and set up. Please refer to this document if the PFT Cell has not yet been configured.

To verify this data, go to the site http://tomcatHost:tomcatPort/gridsphere. Once logged on, select 'Global Hive Data' from the primary navigation tab and 'Registered Cell' from the secondary navigation menu. If the PFT Cell is listed, it has already been configured. Select the PFT cell name and click on Edit Cell Info to verify the PFT cell configuration.

Changing Server log level

a) Edit $CATALINA_HOME/conf/logging.properties to indicate 'INFO' or
'DEBUG'. Logs appear in $CATALINA_HOME/logs/catalina.out

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO

3. Install Client Software

Installing the Pulmonary Function Test Processing Workbench Plugin

PFT Release 1.3 client software is compatible with versions 1.2, 1.2.1 and 1.3 of the i2b2Workbench.

3.1. Locate your i2b2Workbench software's i2b2workbench directory.

e.g. I2B2_WORKBENCH_HOME/i2b2workbench

3.2. Download PFT plugin

a) Download edu.harvard.i2b2.eclipse.plugins.pft_1.3.0.jar

b) Place into your I2B2_WORKBENCH_HOME/i2b2workbench/plugins directory

4. Verify Installation

PFT Cell Sanity Test via the i2b2Workbench

1. Configure the i2b2Workbench to communicate with your PFT cell.

This step is addressed in section 5, Global Hive Data of the PM Cell/gridsphere installation and set up. Please refer to this document if the PFT Cell has not yet been configured.

To verify this data, go to the site http://tomcatHost:tomcatPort/gridsphere. Once logged on, select 'Global Hive Data' from the primary navigation tab and 'Registered Cell' from the secondary navigation menu. If the PFT Cell has been configured you will see the following:

To verify cell data, select cell name and click on Edit Cell Info.

2. Launch the i2b2Workbench (double-click on i2b2Workbench.exe)

Login to i2b2:

a. Select your target location (YourSite)

b. Enter a valid username and password that you set up in gridsphere
(demo/demouser)

c. The URL at the bottom of the login screen should be the address of your PM cell.
If not, return to PM Cell installation procedures, section 7, Verify Installation.

3. Open the PFT view in the workbench

Window->Show View->PFT

Double-click on the PFT tab so it will consume the entire window.

Then click on the Load Sample button.

Next click on the Get Pulmonary Data button and wait for the PFT cell to process the
report.

4. Possible problems

Processing errors are reported in the Results tab.

These include:

1. No PFT results were found.

Please verify that correct report was submitted for processing.

Also verify that the PFT web service is running (see section 2, step 5).

2. No PFT response generated.

Verify that the PFT web service is running (see section 2, step 5).

Verify that the correct PFT URL was entered into gridsphere.

3. No information in Name column

Verify that the ONT web service is running.

Verify that the correct ONT URL was entered into gridsphere.

5. Importing the client source code

Importing the PFT project into the i2b2Workbench workspace

The PFT project software is contained in the Eclipse 'Archive' file called PFT-client-src-13.zip under edu.harvard.i2b2.eclipse.plugins.pft. Import this project into a workspace containing version 1.3 of the i2b2 workbench.

File->Import->General->Existing Projects into Workspace and select the archive file 'PFT-client-src-13.zip'.

Building the PFT client source code

Open the buildFiles folder in the edu.harvard.i2b2.eclipse.plugins.pft project.

Right click on the file 'master_build.xml' and select RunAs->2 Ant Build.

Select clean-all, build-all and run.

Refresh the edu.harvard.i2b2.eclipse.plugins.pft project within Package Explorer.

6. License

The i2b2 source code is licensed under the i2b2 Software License Software. This includes but is not limited to all code in the edu.harvard.mgh.i2b2.* package namespace.References

1. The original document is available at https://www.i2b2.org/software/files/PDF/current/PFT_Installation_Guide.pdf