From CTMS_WIKI

C3PR Administration Guide

Version 2

Duke Comprehensive Cancer Center

Document Change History

Copyright and License page

‘’’Copyright Notice.’’’ Copyright 2006 Duke Comprehensive Cancer Center (“caBIG™ Participant”). C3PR was created with NCI funding and is part of the caBIG™ initiative. The software subject to this notice and license includes both human readable source code form and machine readable, binary, object code form (the “caBIG™ Software”). This caBIG™ Software License (the “License”) is between caBIG™ Participant and You. “You (or “Your”) shall mean a person or an entity, and all other entities that control, are controlled by, or are under common control with the entity. “Control” for purposes of this definition means (i) the direct or indirect power to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. ‘’’License.’’’ Provided that You agree to the conditions described below, caBIG™ Participant grants You a non-exclusive, worldwide, perpetual, fully-paid-up, no-charge, irrevocable, transferable and royalty-free right and license in its rights in the caBIG™ Software, including any copyright or patent rights therein that may be infringed by the making, using, selling, offering for sale, or importing of caBIG™ Software, to (i) use, install, access, operate, execute, reproduce, copy, modify, translate, market, publicly display, publicly perform, and prepare derivative works of the caBIG™ Software; (ii) make, have made, use, practice, sell, and offer for sale, and/or otherwise dispose of caBIG™ Software (or portions thereof); (iii) distribute and have distributed to and by third parties the caBIG™ Software and any modifications and derivative works thereof; and (iv) sublicense the foregoing rights set out in (i), (ii) and (iii) to third parties, including the right to license such rights to further third parties. For sake of clarity, and not by way of limitation, caBIG™ Participant shall have no right of accounting or right of payment from You or Your sublicensees for the rights granted under this License. This License is granted at no charge to You. Your downloading, copying, modifying, displaying, distributing or use of caBIG™ Software constitutes acceptance of all of the terms and conditions of this Agreement. If you do not agree to such terms and conditions, you have no right to download, copy, modify, display, distribute or use the caBIG™ Software.

1. Your redistributions of the source code for the caBIG™ Software must retain the above copyright notice, this list of conditions and the disclaimer and limitation of liability of Article 6 below. Your redistributions in object code form must reproduce the above copyright notice, this list of conditions and the disclaimer of Article 6 in the documentation and/or other materials provided with the distribution, if any.
2. Your end-user documentation included with the redistribution, if any, must include the following acknowledgment: “This product includes software developed by Duke Comprehensive Cancer Center.” If You do not include such end-user documentation, You shall include this acknowledgment in the caBIG™ Software itself, wherever such third-party acknowledgments normally appear.
3. You may not use the names “Duke Comprehensive Cancer Center”, “The National Cancer Institute”, “NCI”, “Cancer Bioinformatics Grid” or “caBIG™” to endorse or promote products derived from this caBIG™ Software. This License does not authorize You to use any trademarks, service marks, trade names, logos or product names of either caBIG™ Participant, NCI or caBIG™, except as required to comply with the terms of this License.
4. For sake of clarity, and not by way of limitation, You may incorporate this caBIG™ Software into Your proprietary programs and into any third party proprietary programs. However, if You incorporate the caBIG™ Software into third party proprietary programs, You agree that You are solely responsible for obtaining any permission from such third parties required to incorporate the caBIG™ Software into such third party proprietary programs and for informing Your sublicensees, including without limitation Your end-users, of their obligation to secure any required permissions from such third parties before incorporating the caBIG™ Software into such third party proprietary software programs. In the event that You fail to obtain such permissions, You agree to indemnify caBIG™ Participant for any claims against caBIG™ Participant by such third parties, except to the extent prohibited by law, resulting from Your failure to obtain such permissions.
5. For sake of clarity, and not by way of limitation, You may add Your own copyright statement to Your modifications and to the derivative works, and You may provide additional or different license terms and conditions in Your sublicenses of modifications of the caBIG™ Software, or any derivative works of the caBIG™ Software as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
6. THIS caBIG™ SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES (INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE) ARE DISCLAIMED. IN NO EVENT SHALL THE DUKE COMPREHENSIVE CANCER CENTER OR ITS AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS caBIG™ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Resources

Introduction to the Administration Guide

About C3PRV2

Cancer Central Clinical Participant Registry version 2.0 (C3PRV2) aims to extend the existing C3PR system to enhance the capture and management of protocol/trials information, clinical trials registration, information on physicians, research sites, and organizations, and to enhance access to information.

Overview of the guide

This guide is intended for administrators of the C3PRV2 system. It will provide an overview of how to administer a pre-installed C3PRV2 system. Information of installation of C3PRV2 can be found in the Installation Guide Information on the project can also be found on our Gforge Homepage or through our mailing lists mentioned earlier in this guide.

Additional Documentation

Additional details on use cases, design, installation can be found in the following documents:

Document Text Conventions

The following table shows various typefaces to differentiate between regular text and menu commands, keyboard keys, and text that you type. This illustrates how conventions are represented in this guide.

Getting Started with this administrator’s guide

• Review Chapter 1 to learn about the manual structure

• Review Chapter 2 for a brief overview of the C3PRV2 software

• Review Chapter 3 to learn about common administration tasks of C3PRV2

Overview of the Software

Software Overview

C3PRV2 consists of a Java web application that based on the J2EE Servlets infrastructure, WSRF-compliant web services that are built on top of caGrid infrastructure, and JBI components that are hosted by Apache ServiceMix JBI container.

For details on the implementing libraries, see Chapter 4.

More information about C3PRV2 can be found at:

• The C3PR GForge site
• The C3PR Wiki
• CTMS Gforge site

System Requirements

Database Requirements

C3PRV2 requires access to a properly-configured database. The application is built with database-independence in mind and has been tested on the following:

For more details, please see the Installation Guide.

Design and Architecture

C3PRV2 is based on the J2EE n-tier architecture where business logic is partitioned in its own distinct re-usable layer. Each layer communicates with its adjacent layer only. This architecture promotes reusability, scalability and ease of implementation (See Figure 2)

Figure 2 High-level overview of the C3PR system

C3PRV2 Administration

This section describes common administrative tasks that can be executed with C3PRv2.

User Logins

By default, C3PRV2 will redirect users to a login page where users are asked to enter their username and password. C3PRv2 uses caCORE Common Security Module (CSM version 3.2) and Acegi Security for authentication and authorization. By default the c3prv2 system ships with the following logins and roles:

Depending on what User Group the User belongs to, the user has certain privileges and will not be able to access certain sections of the C3PRV2 web application. More details can be found in the C3PRv2 design document. To administer the authorization module of C3PRV2 you have to use the CSM User Provisioning tool (UPT). To download and install UPT please visit the NCICB Download Site.

Authorization is configurable at build time by setting the enableAuthorization flag. For more information refer the design document and/or the C3PRV2 installation guide.

Logging

C3PRV2 system uses Log4J for logging. By default the logging is set to a minimum so that only errors and severe problems encountered during the runtime are logged. But there might be situations where you would like to get some detailed information on system failures. To change any of the log4j settings for C3PRV2 system you will have to edit the log4j.properties file. This file for a pre-deployed C3PRV2 system will be typically in the WEB-INF folder of your web application. To make edits to the WEB-INF/log4j.properties file you will need to be familiar with the Log4j API. More information on this can be found here

‘’’Note:’’’ You will have to restart your application server (tomcat) for the new logging rules to take effect.

Database connection

As seen in Figure 2, C3PRV2 relies on a relational database for persisting information. There might be situation when a pre-deployed C3PRV2 systems database connection details need to be modified. To change the database connection details you will have to edit the build.properties (in the antfiles directory) and re-deploy C3PRV2. For more information on deploying C3PRV2 follow the Installation Guide.

This will be changed in a future iteration to enable making this change without having to re-build C3PRV2.

ESB Communication

C3PRV2 has the capability to communicate using an ESB (caAdapter) with other CTMSi applications. For more information on the design refer the Integration Design Document

C3PRV2 has two channels of communications with the ESB. It has the ability to send messages and also receive messages.

Sending Messages

The properties related to sending messages are:

• esb.brokerUrl - This property represents the URL of the ESB (caAdapter). There are situations where this can change or you would like to use a different ESB.
• broadcastEnable – This property will disable or enable sending messages to the ESB. A value of “false” will stop sending messages to the ESB.

Note: You will have to re-deploy the C3PRV2 system for these new properties to take effect.

Receiving messages

C3PRV2 also has the capability to receive messages from the ESB. This is done by deploying a special grid service that will accept messages from the ESB. To disable receiving messages, simply shut down or remove the RegistrationConsumer grid service. This will typically be deployed in $CATALINA_HOME/webapps/wsrf

Note: This grid service is not deployed by default in the present iteration of C3PRV2

Appendix B: Glossary