From CTMS_WIKI

Introduction

This installation guide outlines the supported configurations and instructions for installing, setting up and configuring the Patient Study Calendar (PSC).

Overview of Patient Study Calendar

The Patient Study Calendar (PSC) is an open source, standards-compliant software application that can be used by organizations that manage patients on cancer clinical trials.The PSC is a standalone, web-based application providing the ability to create and edit study calendar templates, generate and view prospective calendars of patient activities, track activities as they occur, and manage calendars as they change during a study.

There are several elements involved in a complete PSC deployment:

Minimal System Requirements

Client

• Internet connection
• Firefox 2 or higher or Internet Explorer 7

Server

The Patient Study Calendar server has been tested on the hardware and operating systems shown below.

Server Software and Technology Requirements

Software Requirements

Patient Study Calendar is a J2EE web application. This means it needs a Java runtime and a servlet container to run. PSC has been tested with JDK 5 (no earlier version will work) and Tomcat 5.5.17.

Database Requirements

PSC uses a relational database to store all its templates, schedules, etc. PSC is built with database-independence in mind and has been tested on the system in the table below.

Out of the box, PSC includes JDBC drivers for PostgreSQL and HSQLDB. If you wish to use another database not compatible with those drivers (e.g., Oracle), you will need to obtain the drivers and place them in the db/lib directory.

Installation of the web application

Preliminary Considerations

PSC has been tested with the operating systems and hardware specified earlier in this guide. Although we have made an effort to develop PSC as a platform-independent application, we cannot guarantee that it will work If you are using variations of these operating systems and/or hardware. Installing (or upgrading) PSC on a system already set-up with the proper versions of the JDK, database, and Tomcat should require about 30 minutes. Installation of all components from scratch could take several hours.

Step 1: Install and Configure Database

Note that the database was previously installed or remove this

Complete the following steps to prepare the database for Study Calendar. You can skip these steps if database for PSC is already installed

1. If not already present, install and configure your preferred database system. Consult the system's documentation
2. Configure an empty database for PSC to use.

PSC does not require that the database be called anything in particular. This guide will use study_calendar as the name in each example.

Step 2: Download and Unzip Installation Folder

Need to reference the location in the CCTS package

If you don't already have the PSC software, you'll need to download it. (You might already have it if, e.g., you downloaded the entire CCTS package.)

1. Go to the download website and get the most recent released version.
2. Unzip the installation folder. It will contain the file psc.war and a folder called conf-samples

psc.war is the actual PSC application. conf-samples folder contains sample configuration files which you will copy into place and modify to customize PSC for your environment.

You can also download PSC from CCTS bundle. It has psc.war,wsrf-psc.war, csm_jass.config and datasource.properties files. wsrf-psc.war contains PSC grid services. See Installation of Grid Services for how to install PSC grid services. csm_jass.config and datasource.properties files are sample configuration files which you will copy into place and modify to customize PSC for your environment.

     You may skip downloading wsrf-psc.war file if you don't want to install PSC grid services. PSC web application needs 
   only psc.war, csm_jass.config and datasource.properties file.

Step 3: Create Database Configuration File

1. Find datasource.properties in the conf-samples directory or in the CCTS bundle.
2. Copy datasource.properties to one of these locations.
   1. $CATALINA_HOME/conf/psc (use this one if you're not sure which to use)
   2. ~/.psc
   3. /etc/psc
3. Enter the proper JDBC connection values as described below.
4. Uncomment the driver line (delete the # symbol from the beginning) that corresponds to your database.

Step 4: Configure Security Settings

We need to specifically outline the steps necessary to merge contents of these files, etc. since we know that all the apps are being deployed

1. Copy csm_jaas.conf to $CATALINA_HOME/conf/cabig. Please note that if you are also installing other caBIG CTMS applications, you will need to merge the contents of all of the csm_jaas.conf files into one file. For example: if you have other caBIG CTMS applications installed in the same tomcat, add following configuration in csm_jass.conf file for PSC

   study_calendar {
   
      gov.nih.nci.security.authentication.loginmodules.RDBMSLoginModule required
   
      url="@datasource.url@"
   
      user= "@datasource.username@"
   
      passwd= "@datasource.password@"
   
      driver= "@datasource.driver@"
   
      encryption-enabled= "YES"
   
      query= "SELECT * FROM CSM_USER WHERE LOGIN_NAME=? and PASSWORD=?"
   
      ;
   
   };

2. Replace the placeholders for username, password, JDBC driver, and JDBC URL with the appropriate values. These will be the same values you put in datasource.properties, above.

3. Find catalina.properties in the directory $CATALINA_HOME/conf/. Add the following line to the end of that file:

    java.security.auth.login.config=${catalina.home}/conf/cabig/csm_jaas.config

Step 5: Install PSC

Need to reference specific paths based on CCTS paths

1. Copy psc.war from the unpacked zipfile to $CATALINA_HOME/webapps
2. Start Tomcat.

Step 6: Complete configuration of PSC

We should know the recommended port number based on CCTS instructions

1. Using a web browser, go to the PSC URL as determined by your Tomcat configuration. This will be something like https://hostname.domain:portnumber/psc for example:

    https://cbvapp-d1017.nci.nih.gov:28443/psc

2. Follow the on-screen instructions to create your first user and site.

You are now ready to use PSC in stand-alone mode. For more instructions regarding what to do next, please see the Administration Guide and End User Manual.

Step 7: Configuring PSC for CCTS

You need to specifically state the configuration option values based on the recommended CCTS deployment outlined in the larger document

     Before configuring PSC to caGrid SSO, make sure you have created a user in PSC with the same login name that you will 
    use in caGrid SSO for authentication.  You can create users by simply clicking on "Administration" tab of PSC ui and 
    than on "Manage users" link (make sure you are logged in as an administrative user). 

Example : See following caGrid SSO configuration option values as an example

     Service URL : https://cbvapp-d1017.nci.nih.gov:48443/cas
     Trust store : /local/home/globus/certs/websso-cacert
     PSC base URL : https://cbvapp-d1017.nci.nih.gov:28443/psc

Step 8: Configuring hotlinking to other applications for CCTS

Click on "Administration tab" and than on "Configure PSC".

1. Choose yes/no for "Application Link in another windows" . For ex : choose "yes" if you want to open links to outside applications such as caAERS in another window/tab

2. Choose yes/no for "Application links in new windows". For ex: choose "no" if you want to open each outside application in a dedicated window/tab

3.Enter value for "caAERS base url". The format of url entered must match with

    http://caaers-base-url/pages/ae/list?assignment={assignment-identifier}

For ex:

    https://cbvapp-d1017.nci.nih.gov:28443/caaers/pages/ae/list?assignment={assignment-identifier}

4. Enter value for "LabViewer base URL". The format of url entered must match with

    http://labviewer-base-url/studysubject.do?studySubjectGridId={assignment-identifier}

For ex :

    https://cbvapp-d1017.nci.nih.gov:28443/ctodslabviewer/studysubject.do?studySubjectGridId={assignment-identifier}

Install the PSC grid services

If you are using PSC as part of CCTS, you will need to install the PSC grid services. (If you are using PSC in a pure stand-alone mode, this is not necessary.)

Preliminary notes on Grid Services

There are two ways to install PSC grid services

• Download wsrf-psc.war fille from CCTS bundle, or
• build wsrf-psc.war file from source

1. Download wsrf-psc.war file

You can download wsrf-psc.war file from CCTS bundle https://gforge.nci.nih.gov/svnroot/ccts/trunk/ccts/releases/1.1rc1. Copy it to a secured tomcat and restart the tomcat server.

2. Building from source

caGrid is already installed, you shouldn't have to check out code, it should be bundled, ant is installed

Environment variables are already defined. Do you really need to define C3PR_HOME? If so, it should have a correct example from the CCTS instructions

You can also build grid services from source also..

Note: before begin, please follow following steps.

1. Install caGrid 1.1 and configure a secure tomcat. The caGrid 1.1 installer also configures a secured tomcat.
2. Checkout the PSC source code to any folder on your machine. We will refer this source code directory as PSC for ex (c:\psc-2.1)
3. Checkout caAERS code base. Please check the caAERS installation guide for source code location of caAERS.
4. Checkout ccts grid services code base from https://gforge.nci.nih.gov/svnroot/ctmscommons/ccts-grid-services .
5. Make sure you have ant installed on your machine.

     Make sure $CATALINA_HOME points to a secured tomcat. 

Installation Instruction

Please use full paths

You should include Tomcat restart

You should include smoke tests

Go to PSC/grid folder and execute following command

    ant get-grid-war

For example:

    c:/psc-2.1/grid ant get-grid-war

This should create a wsrf-psc.war file in PSC/grid/dist folder (for ex c:/psc-2.1/grid/dist)

You can now deploy this wsrf-psc.war file to any secured tomcat (i.e. copy this wsrf-psc.war file to $CATALINA_HOME/webapps). You will also need to restart the tomcat once you deploy the wsrf-psc.war file.

Contacting Technical Support

Go to the PSC Discussion Forum to post any questions. You can also contact the Project Manager of the Study Calendar Development team, Sean Whitaker.