CCTS 1.1 Administration Guide

From CTMS_WIKI

Introduction

Background

The caBIG Clinical Trials Suite (CCTS) is an enterprise clinical trials system being designed primarily for use in trial sites. The suite is comprised of a collection of interoperable modules covering a broad range of key areas in cancer clinical trials management. These include patient registration via C3PR, patient scheduling via PSC, adverse events reporting via caAERS, lab analysis via LabViewer, and clinical data management via C3D. Integration between these applications is centered around five key scenarios: Study Creation, Register Subject, Load Labs in CDMS, Lab-driven AE Creation, and AE-Triggered Schedule Change. The implementation is based upon the caGrid infrastructure with caXchange as the Enterprise Service Bus for reliable message routing and GAARDS providing robust security.

Scope

Once the suite is installed and smoke tests completed successfully, there are a number of steps that should be completed in order to use the applications in the suite in their entirety. This document describes those steps.

Related Documentation

CCTS Administration

CCTS Properties

Modifying CCTS Properties in C3PR

Login to C3PR and go to Administration >Configure C3PR and enter information for the following CCTS modules:

• caAERS
  • caAERS hotlink url: This is the base URL for the caAERS deployment to which this C3PR instance can link (Default: https://cbvapp-d1017.nci.nih.gov:28443/caaers/pages/ae/list)
  • caAERS browser window name: This is the name that will be given to the browser window in which caAERS will open up. (Default: _caaers)
• PSC
  • Study Calendar hotlink URL: This is the base URL for the Study Calendar deployment to which this C3PR instance can link (Default: https://cbvapp-d1017.nci.nih.gov:28443/psc/pages/schedule)
  • PSC browser window name: The name that will be given to the browser window in which PSC will open up. (Default: _psc)

Modifying CCTS Properties in PSC

Login to PSC and go to Administration >Configure PSC and enter information for the following CCTS modules:

• caAERS base URL: This is the base URL for the caAERS deployment to which this PSC instance can link
• CTMS name: The name for the local CTMS (Default: CTMS)
• CTMS URL: The home page URL for the local CTMS
• LabViewer base URL: The base URL for the LabViewer deployment to which this PSC instance can link
• Study page URL: The URL for the study page in the CTMS

Modifying CCTS Properties in caAERS

Login to caAERS and click the Administration tab and enter information for the following CCTS modules:

• caExchange URL: This is the URL for caExchange -- the value may not be applied until the application is restarted
• LabViewer base URL: The base URL for the LabViewer deployment to which this caAERS instance can link
• Study Calendar base URL: This is the base URL for PSC (Patient Study Calendar) - the Study Calendar deployment to which this caAERS instance can link

Modifying CCTS Properties in LabViewer

Navigate to the LabViewer/cTODSDeploymentController directory. Edit the LabViewer.build.properties file and enter information for the following CCTS modules:

• caXchange URL: This is the URL for caXchange (Example: loadLabURLS = https://cbvapp-d1017.nci.nih.gov:28445/wsrf/services/cagrid/CaXchangeRequestProcessor)

• caAERS base URL: This is the base URL for caAERS deployment to which this LabViewer instance can link (Example: BaseURLcaAERS = https://cbvapp-d1017.nci.nih.gov:28443/caaers)

Restart Tomcat for the modified properties to take effect.

Modifying CCTS Properties in caXchange

All the caXchange configurations reside in {SERVICEMIX-HOME}/conf/caxchange.properties. These properties include URLs for target services, Database connection properties, JMS connection information, and paths to the host certificate and key files. The table below describes the properties included in the caxchange.properties file.

Organizations

The Organization must already exist, and the name of the Organization must match in C3PR, PSC, and caAERS. If the Organization does not already exist in all of these applications, then the create study transaction will not execute and will rollback. C3PR, PSC and caAERS are installed with a list of CTEP institutions which includes hundreds of organizations. If the organization you want to enter as a coordinating center, funding sponsor or study site is not in the list of installed CTEP organizations, you will need to manually enter the Organization in each of the applications. The following instructions explain how to manually enter Organizations.

Creating Organizations in C3PR

C3PR includes a list of hundreds of CTEP organizations as part of the basic install. In C3PR, the names of all Coordinating Centers, Funding Sponsors and Study Sites are entered as Organizations. If needed, additional organizations can be added to the list on this page. To manually enter an Organization not found in the installed list, go to the C3PR home page mouse over the Person & Organization tab and select Organization and click on Create Organization in the drop down list that appears.

To add a new Organization:

1. Enter the Name of the oganization.
2. Enter the Description of the organization.
3. Enter the NCI Institue Code of the organization.
4. Enter the Street Address of the organization.
5. Enter the City of the organization.
6. Enter the State of the organization.
7. Enter the Zip code of the organization.
8. Enter the Country that the organization located.
9. Click on the Save button.

Creating Organizations in PSC

To create a new organization in PSC:

1. Login to PSC and then go to Administration >Manage Sites.
2. Click Create New Site.
3. Enter the Site Name and click Create.

Creating Organizations in caAERS

caAERS includes a list of hundreds of CTEP organizations as part of the basic install. An Organization can be a site, a sponsor, or any institution associated with clinical trials. If needed, additional organizations can be added to the list.
Searching for an Organization Since Organizations are included in the installation, you should first search caAERS for the organization before you add it.
To search for an organization:

1. Click the Administration tab, click Organization in the task menu, click Search Organization in the steps menu to bring up the Search Organization page
2. Enter search criteria in the Name and/or the NCI Identifier field and then click Search.
   Note: You can leave the fields blank and click Search to list all Organizations.
3. The Organizations available will be listed in the bottom of the page. You can sort the search results by entering the appropriate information in the Name and/or the NCI Identifier text fields at the top of each column and then clicking the Filter button in the top right corner of the Search Results section.
4. To view and/or edit an organization listed in the search results, mouse over the Name and click on it.
   

Create an Organization

1. Click on the Administration tab and click Organization in the task menu to open the Create Organization page.
2. Enter the Name
3. If you want to provide additional details, enter the Description
4. Enter the NCI Identifier. The NCI Identifier is the primary id used by NCI and can be found at http://ctep.cancer.gov/forms/Organization_Codes.txt
5. Click Save to create the organization.

Investigators

Investigator must already be set up and must match in caAERS and C3PR. If Investigator does not already exist in either of the apps, then the create study transaction will rollback.

Creating Investigators in C3PR

From the C3PR home page mouse over the Person & Organization tab, select Investigator and click on Create Investigator in the drop down list that appears.



To add a new Investigator:

1. Select the Organization or the study site where the investigator exists. Note: This is a pre-populated field. Enter the first few letters of the name of the Organization and select it from the drop down list that appears. If the Organization is not on the list you can go to Person & Organization > Organization > Create Organization in the navigation bar. After you have entered the Organization, return to this page and it should appear in the drop down list.
2. Select the Investigator Status from the drop down list. Select Active or Inactive. This is the code value that represents the activity status of the Study site investigator that will grant that investigator activity capability within that site context.
3. Enter the First Name of the investigator.
4. Enter the Last Name of the investigator.
5. Enter the Middle Name of the investigator.
6. Enter the Maiden Name of the investigator.
7. Enter the NCI Identifier of the investigator. Note: A list of NCI Identifier Codes can be found at http://ctep.cancer.gov/forms/Organization_Codes.txt
8. Enter the Email or Username of the investigator.
9. Enter the Phone number of the investigator.
10. Enter the Fax number of the investigator.
11. Click on Save to create a new investigator.
12. Select the Organization.
13. Select a Group. If a group does not exist, and the participants want to add a group for the investigator, then click on Add Group.
14. To add an investigator group, click on Add Group.
15. Enter the Name of the group.
16. Enter the Start Date.
17. Enter the End Date.
18. Enter the Description of the group investigator.
19. To add a new Investigator to the group investigator, click on Add Investigator.
    1. Select the Investigator from the list by typing a first or few letters of the investigators first or last name.
    2. Enter the Start Date.
    3. Enter the End Date.
20. Click Save.

Creating Investigators in caAERS

To Create/Edit an Investigator:

1. Click the Administration tab and click Investigator in the task menu.
2. Enter the First Name.
3. Enter the Middle Name if desired.
4. Enter the Last Name.
5. Enter the Investigator number if desired.
6. Enter the Email address.
7. Enter the Phone number.
8. Enter the Fax number if desired.
9. Enter the Organization. This is a pre-populated field. Enter the first few letters of the name of the Organization the Investigator is associated with and select it from the drop down menu that appears.
10. Select Inactive or Active from the Status drop down box.
11. If the Investigator works with another Organization, click Add Organization and repeat the steps above.
12. Click Save. If you entered information correctly into all the required fields you will see a

confirmation message stating that the system has Successfully saved the investigator.

Note: For an Investigator to be able to log into caAERS, you will need to also add the Investigator to caAERS as a Research Staff/User. To do this, please see the Research Staff section of this guide.

Studies

The Create Study feature does not work with C3D. The create study message is not broadcasted to C3D. Study must be set up directly in C3D.

In addition, newly created studies that are broadcasted to caAERS need to have study periods set up.

In addition, newly created studies that are broadcasted to PSC need to have their template "released".

Creating a study in C3D

Creating a study in C3D involves the creation of the electronic case report forms for the collection of data, defining study intervals and events, creating study sites and investigator, and create patient positions. The guide "Creating a Study", release 4.5 provides all of the necessary information for create a study in C3D, and can be found at Creating a Study.

Special Considerations for C3D Studies

• A Site in C3D is an Organization in C3PR, so when setting of Sites in C3D, use the NCI Institution Code of the Organization as the Site Code in C3D. This will ensure that a patient will be registered to the correct Site in C3D.

Disabling C3D Integration

If it is not desired to integrate with C3D, you could choose to disable broadcasting to it through caXchange.

Remove Routing to a Target Grid Service

This requires changing the recipients list of the message type for which the target no longer wants to receive messages. Each recipient list is configured in a separate file. Appendix D describes the contents of each xml file for the EIP service unit, it can be used to determine which file contains the configuration for a particular message type. These files are located in the {caXchange-installation-dir}/conf/caXchangeConf/eip/ folder. For example the configuration for REGISTER_SUBJECT message type is in the registerSubjectRecipients.xml. This configuration is as follows:

<beans xmlns:eip="http://servicemix.apache.org/eip/1.0"
       xmlns:caxchange="http://nci.nih.gov/caXchange">
    <eip:caxchange-static-recipient-list service="caxchange:registerSubjectRecipients" endpoint="registerSubjectRecipientsEndpoint">
      <eip:recipients>
	<eip:exchange-target service="caxchange:pscRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:caaersRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:ctomRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:c3DRegisterSubjectRouter" />
      </eip:recipients>
      <eip:targetServiceIdentifiers>
               <value>psc</value>
               <value>caAERS</value>
               <value>LabViewer</value>
               <value>C3D</value>
      </eip:targetServiceIdentifiers>
  </eip:caxchange-static-recipient-list>
</beans>

To remove C3D as a recipient for the REGISTER_SUBJECT message, the administrator needs to comment out the C3D as a recipient in this file. The edited xml will be as follows:

<beans xmlns:eip="http://servicemix.apache.org/eip/1.0" 
      xmlns:caxchange="http://nci.nih.gov/caXchange">
   <eip:caxchange-static-recipient-list service="caxchange:registerSubjectRecipients"   endpoint="registerSubjectRecipientsEndpoint">
     <eip:recipients>
       <eip:exchange-target service="caxchange:pscRegisterSubjectRouter" />
       <eip:exchange-target service="caxchange:caaersRegisterSubjectRouter" />
       <eip:exchange-target service="caxchange:ctomRegisterSubjectRouter" />
       <!--<eip:exchange-target service="caxchange:c3DRegisterSubjectRouter" /> -->
     </eip:recipients>
     <eip:targetServiceIdentifiers>
              <value>psc</value>
              <value>caAERS</value>
              <value>LabViewer</value>
           <!--   <value>C3D</value> -->
     </eip:targetServiceIdentifiers>
 </eip:caxchange-static-recipient-list>
</beans>

Once these changes have been done, they are needed to be pushed to servicemix. This is done using the following steps:

ant update-routing-configuration

Configuring Evaluation Period Types & Solicited AEs in caAERS

An Evaluation Period Type is a portion of the study containing one or more study segments with a consistent objective such as screening subjects or treating disease.

Examples of Evaluation Period Types:

• Baseline
• Treatment
• Follow up

Solicited adverse events are adverse events for which clinical evaluations are requested for all participants on the study. Solicited adverse events may be assigned to one or more evaluation period types in the study. When adverse event observations are recorded in caAERS for a particular evaluation period type, the user will be prompted to enter any clinical observations for each solicited AE.

To assign solicited adverse events to a Study Evaluation Period Type in caAERS, first login and search for the study you want to update and then go to the Evaluation Period Types section of the study to update information.

1. Login and click the Studies tab.
2. Enter search criteria and click Search.
3. Click the Primary ID or Short Title of a study listed in the search results to view and edit it.
4. Click Evaluation Period Types in the steps menu at the top of the page.
5. Add solicited adverse events by entering the first few letters of the name of the AE in the Find & Add AEs field and select it from the drop down list that appears
   OR
   Click Add Multiple, select the appropriate CTC category(s) and CTC terms(s) and click Add Terms.
6. To add an evaluation period type, click Add, type in a name for the evaluation period type, and click ok. You can also click on the name of an evaluation period to change the name and click ok to save the new name.
7. Select the appropriate checkboxes in this section to associate a solicited AE to an evaluation period type and click Save & Continue.

Approving a Study Template in PSC

Templates in PSC have to be managed and released before being approved. A template must be approved before a subject can be registered to it. The following instructions explain how to manage and release a template in study.

PSC Templates

In PSC, a template is a representation of all the activities of the study protocol for subjects. Templates consist of epochs, study segments, periods, and activities.

The template creation process is flexible and allows you to create a wide variety of study designs. The template displays the study divided into large sections called “epochs.” An epoch is a section of the trial during which activities for subjects have the same goal. Some commonly-used epochs are “Screening,” “Treatment,” and “Follow-up.”

Each “epoch” contains one or more “study segments” and time within a study segment is defined by “periods”. A study segment is a portion of the trial that has a defined beginning and ending and which include specified activities. A study segment can be a set of cycles, a run-in to a transplant, or even a set of follow-up phone calls. Another way of describing study segments can be to say that they last from one decision point to the next. When it is decided what set of activities should happen next for a subject, one study segment will end and the next will begin. The study segments can be listed in any order within an epoch. This order does not determine the sequence order for a given subject. Periods have a duration (in days or weeks), a start day (relative to the beginning of the segment), and a number of repetitions. Activities are planned to occur on days within a period.

To edit a template you must be assigned the Study Coordinator role in PSC. Editing a template in PSC involves defining and entering information regarding the following primary areas (you can also edit other areas of template in addition to the primary areas):

• Periods
• Activities

Once you are logged in to PSC as a user with the Study Coordinator role:

1. Within the Calendars tab, select the template that you want to edit
2. Add a period for each study segment

Study segments

Epochs contain one or more study segments, portions of the trial that have a definable beginning and ending and within which activities can be defined. As with epochs, you may add, delete, rename, or reorder the study segments at any time during template creation, as shown below. Deleting a segment will remove any periods and activities that you have created within it.

By default, time within the study segment will be in consecutive days. However, if the template describes time in cycles, define the cycle length in the study segment details box. As shown below, study segment ‘C’ has been given a cycle length of 21 days.

Periods

Time within a study segment is defined by periods. Periods have a duration (in days or weeks), a start day (relative to the beginning of the segment), and a number of repetitions. When a study segment in the template is selected, the box below it will show the periods and activities that have been setup. To add a period to the study segment, click the “Add period” button. The following screen will appear:

You now have the choice of either adding a new period or adding a period that is a duplicate of an existing one. Create new period To create a new period, enter the information into the “Create new period” box as shown in this example.

In the example above, the period is named “Cycle A,” begins on day one of the study segment, is twenty-one days long, and will occur four times. The “Summary” section helps to confirm that you have entered the information correctly. Press “Submit” to add the period.

Copy existing period
If the period that you want to add is identical or very similar to a period that you have already created in this or any other template, use the “Copy existing period” box. The existing periods from the template that you are currently modifying will be listed by default. If you wish to copy a period from a different template, use the search box to find that template. This will list all of the periods from that template, as shown in this example.

Select one of the periods and press “Copy.” You will be presented with the current parameters of the period. You can modify these to suit the current template. Note that reducing the duration of a period may result in deletion of activities from the period.

Once added to the study segment, the period information will appear in the study segment details box with some new controls:

You may add as many periods as needed. When you are ready to add activities to the period, simply click in the gray area of the period.

Activities

Click inside the gray area of a period to access the page for managing activities of that period. This page allows you to add or remove activities for all patients or for certain populations as shown in the example below.

Add/remove
To add an activity, locate the activity using the search box. The dropdown menus to the left will allow you to limit the search by activity source and activity type. Once you have found the desired activity, click Add to period button to move the activity to appear under the grid of days. The page will now display a row of empty boxes each of which represents the set of days from the grid above. In the above example, the first box represents the first day of the period “Cycle A”: days 1, 22, 43, and 64. To add an activity to these days, simply use the mouse to drag the ‘X’ from the “Add” box to the open square. Repeat these steps for each of the desired set of days for the activity. Next, enter any details that you want to capture about the activity.

To remove an activity, simply drag the ‘X’ from the grid to the “Delete” box above the grid. For a given activity to occur more than once per day, you will need to add it to the period multiple times. This technique will also allow you to enter differing details or conditions for the same activity occurring on different days. The example below is a simplified example of the latter:

In the example shown above, one CBC will be performed for all subjects on the first day of the period, but will be performed on the eighth day only for subjects whose previous absolute neutrophil count met the condition. Note that PSC does not have the ability to determine if the condition has been met. The user must make this determination.

Once all activities have been added, click the Return to template button.

Conditional
If an activity only occurs under a certain condition (for example, only if white blood cell counts are below a certain level), enter that condition under the appropriate column. For the most efficient use of PSC, only use conditional activities for conditions that should be evaluated for all subjects that will experience the study segment. If the activity will only be performed for certain types of subjects (e.g. males over 65, females of childbearing potential, smokers), use the Populations feature described in the next section. Generally, use a conditional activity if the decision to perform an activity is based upon something that happens to the subject. Use a population if the decision is based upon an enduring characteristic of the subject.

Populations
To add activities that will only occur for certain types of subjects, use the populations feature. The first step is to create the population as described PSC End user guide. On the page where activities are added, an “Add” box will appear for each available population. Rather than dragging an ‘X’ to the activities grid, drag the abbreviation from the appropriate populations box as shown here:

As shown in this example, the ‘M’ represents the population “Males over 65.” In this example, while a CBC will be performed for all subjects, a physical exam need only be performed for subjects who are males over sixty-five years of age. Details To add additional information or instructions about an activity, click “View/Edit” and enter information into the “Details” section. This information will show on subject schedules for subject coordinators to see.

Labels
Any number of labels can be added to an activity. A label is a single word (or any consecutive letters) that can be used to generate special reports. Labels are separated from each other by spaces. Labels can be used to designate certain activities as being research billing, requiring special kit preparation, or any other use as determined by your organization.

Release Template

Once you have determined that the template is complete, the next step is to release the template for use. Before this option becomes available, though, all periods must have at least one activity, and each study segment must have at least one period. PSC will not allow incomplete templates to be released.

Release to pending state
A template that satisfies the completeness criteria described above will present a button labeled Release this template for use in the Manipulate study box of the view for editing the template. As Study Coordinator, pressing this button and confirming your choice will release the template to the pending section of the study list, which is accessed by clicking the Calendars tab. The template may no longer be modified unless it is amended as described in the Amend Template section explained in PSC end user guide( https://cabig-kc.nci.nih.gov/CTMS/KC/index.php/PSC_End_User_Guide).

Approve a Template

This section provides an overview of approving template functionality in PSC. A Site Coordinator is responsible for approving templates and amendments to templates assigned for use at their site(s). The Site Coordinator is also responsible for granting access to templates to Subject Coordinators and reassigning subjects from one Subject Coordinator to another. Topics in the section include:

• Site Coordinator Dashboard
• Approve Templates and Amendments
• Grant Access to Subject Coordinators

Site Coordinator Dashboard

This dashboard provides a convenient interface for performing the functions of a Site Coordinator. As a Site Coordinator, you will see this dashboard by default when you login. If another dashboard is presented because you are also a Subject Coordinator or you have navigated away from this page, simply select the Dashboard tab and follow the Site Coordinator link.

Approve Templates and Amendments

The Please note section at the top of the dashboard will notify you of any waiting approvals. Simply follow the approved link, check the Approve box, verify the approval date, and then finalize the approval.

Grant Access to Subject Coordinators

To grant access to a template to a Subject Coordinator, click the manage button in the Manage Subject Coordinators box. Select the study that the template represents from the dropdown list, and then check the appropriate boxes in the grid of sites and Subject Coordinators. A check means that the Subject Coordinator in that row is authorized to assign subjects to the selected study at the site in the column.

Labs

In order to load labs into a CDMS or send labs to caAERS for a potential AE, the labs need to be loaded into LabViewer.

Loading Labs into LabViewer

Steps to load a lab into LabViewer:

• Login to the server where the CCTS applications are deployed
• Change directory to the integration_smoke_test/payloads directory
• Edit the data in CT_LAB_DATA.xml
  • View the data in the CTODS identifier table and note the value in the root column where the extension is your study ID
  • Modify the <id> tag in the <ClinicalTrial> tag and change the extension to your study ID and change the root to the root noted in the previous step
    <id assigningAuthorityName="NCI" extension="04_C_0121" root="db762d64-e213-4bf9-9f9b-bccd36be56e7" xsi:type="II"/>
  • View the data in the CTODS identifier table and note the value in the protocol_id column where the extension is your study ID
  • View the data in the CTODS healthcare_site table and note the value in the nci_institute_code column where the id is the id noted in the previous step
  • Modify the <id> tag in the <trialSite> tag and change the extension to the value noted in the previous step
    <id extension="SITE_01" root="2.16.840.1.113883.19" xsi:type="II"/>
  • View the data in the CTODS identifier table and note the value in the root column where the extension is your patient ID and the participant ID is not null
  • Modify the <id> tag in the <enrolledSubject> tag and the <id> tag in the <asSpareSubject> tag and change the extension to your patient ID and change the root to the root noted in the previous step
    <id extension="69-80-12-8" root="2.16.840.1.113883.19" xsi:type="II"/>
• Change directory to the parent directory (cd ..)
• Run the following command: ant –p
• Run the following ant target: ant testCtLabData

Use LabViewer to verify the load of the lab for the study/patient.

Adverse Events

In order to process adverse events in caAERS, rules need to be loaded.

Loading Rules in caAERS

In caAERS, reporting definitions must be configured after the initial installation before rules can be imported or entered manually. The instructions below explain the initial configuration of reporting definitions and how to create report definitions once the initial configuration is complete. Following that, instructions are listed that explain how to import and manually enter rules into caAERS.

Initial Configuration after caAERS install:

When you first install caAERS and import the XML Rules files we provide, caAERS will create skeleton Reporting Definitions for CTEP reports. If the rules state that a report is required, a skeleton Report Definition will be created. These skeleton reporting definitions do not include all the necessary information.
For example, it won't have the following:

• Information to electronically submit reports to AdEERS
• Notifications that are sent o interested parties
• Defined mandatory fields to assist the users with creating expedited reports.
  

Note: caAERS will not create skeleton Report Definitions for DCP reports. If you import the DCP rules before you create the Report Definitions, you will want to delete and re-import the rules to guarantee they function correctly.

This spreadsheet provides a matrix on how to configure the Reporting Definitions. Some note about the spreadsheet:

• The first tab of the spreadsheet includes information for the first two tabs of the setup process, including details and delivery details.
• The second tab provides information for the third step of the process, the mandatory fields.
• The third tab provides the notifications we've set up for the reports.
• The file displays the information for the AdEERS staging system. To submit an expedited report to this site, the study must already be entered in the staging system.
• Some of the information listed in the spreadsheet is suggested data while other sections are 100% define. View the page/section column to determine what can be modified (Delivery Details for example) and what must be entered as displayed (Mandatory Fields for example).

In addition, if your organization has other reporting requirements, you can use the spreadsheet as a reference sheet to help configure the report definitions.

To configure reporting definitions:

1. Log in to caAERS using an account with access to the Administration area
2. Go to Rules
3. Select List Reporting Definitions
4. Select a Report and modify the information

Create Report Definitions
Click the Rules tab and click Create Report Definition in the task menu. Report definitions are the backbone of caAERS, identifying what information is required in a report and who receives the report. The report definitions you create will be used when defining rules for your rulesets.
Creating a report definition is done in five steps:

1. Basic Details – enter the general information for the report
2. Delivery Details – enter who receives the report
3. Mandatory Fields – enter what information is mandatory
4. Notifications – enter reminders for the report
5. Review – review the settings for the report

1. Basic Details
The Basic Details page defines the general information for the report. A red asterisk next to a field means it is required information.

1. Enter the organization in the Organization field. This is a pre-populated field. Enter the first few letters of the name of the Organization you are looking for and select it from the drop-down menu that appears.
2. Enter a name in the Name field.
3. Enter a name in the Display Name field. Keep the name simple but descriptive.
4. Enter a Description if you want to add more information for the report.
5. Select Yes or No for Amendable. This field defaults to Yes, which means the report can be added.
6. Select Yes or No for Report is expedited?.
7. Make a selection from the Report Format drop down list. Format choices are: caAERS XML, AdEERS PDF, MedWatch 3500A PDF, DCP SAE PDF, CIOMS PDF and DCP Safety Report PDF.
   Note:The selection of Mandatory fields you can select from will vary in the following Mandatory Fields task page based on the Report Format you select.
8. Select Yes or No for Attribution required. This field defaults to No. If you change it to Yes, it means that any time an AE is reported on, it must be related to an attribute.
9. Select a value for Time Scale UOM (unit of measurement) from the drop down box. This value tells you the measurement of time before the report is due.
10. Enter a number for Time until report due. This number is associated with what you selected for Time Scale UOM, and determines the specific measurement for when the report is due. For example, if you chose Days for Time Scale UOM, and then entered 5, you’re setting the report to be due 5 days after you document the AE.
11. Click Continue to go to the next step.
    

Warning: If you navigate from this page to a different area of caAERS without completing the entire report definition process, all information will be lost, even if you have clicked Continue.

2. Delivery Details
The delivery details allow you to setup recipients of this report. The report can be sent to a specific email address, a role, or a URL. Reports sent to email addresses and roles are sent as PDF files while reports sent to URLs go through as XML files.
Send to email
Use this option if you want the report to always go to a specific e-mail address.
Note: This is less flexible than using Send to Role, since all studies using this report definitions will go to the e-mail address listed

1. Click the Add eMail button.
2. Enter the Name. This can be the recipient’s name or another way to identify the role.
3. Enter the email address in the Role/Email Address field.
4. If at any time you want to remove information you’ve added, click the Delete button that corresponds to the information you want to remove.
   

Send to role Use this option to always send the report to a role. This offers flexibility, since it will send it to the e-mail address listed for the role for the study using the report definition. This way, if the person(s) listed for the role changes, the report will automatically be sent to the new person in the role.

1. Click Add Role.
2. Fill in the Name field. This can be the recipient’s name or another way to identify the email address.
3. Enter the appropriate information in the Role/Email Address field.
4. If at any time you want to remove information you’ve added, click the Delete button that corresponds to the information you want to remove. To add mandatory information, click Continue.
   

Send to URL
Use this role for electronic submission of a report. The URL is typically a web service that can consume the report, such as AdEERS.

1. Click Add URL.
2. Enter the Name. This can be the recipient’s name or another way to identify the URL.
3. If the site requires a username and password to access it, enter the information in the Username and Password fields.
4. Enter the URL.
5. If at any time you want to remove information you’ve added, click the Delete button that corresponds to the information you want to remove. To add mandatory information, click Continue.
   
   

3. Mandatory Fields
The mandatory fields page allows you to select the specific information to be included in the report. The selections are based on the sections of the report, where information is entered into the appropriate fields. The selections available on this page will depend on the Report Format you selected on the previous Basic Details page.

• Select Optional, Mandatory or Not Applicable from the drop down lists under each heading. Once you have completed your selections, click Continue to add notifications.

Note: This page is very long with multiple sections.

4. Notifications
Notifications can be set up to send reminders to people about the report. Multiple reminders can be created for the same report, reminding people that the report is almost due or informing them the report is past due.
Adding a notification

1. Select the number from the Time Scale box. For example, if your report is due on Day 5 (as selected on the Basic Details page), you could select 2 to send a reminder three days before the report is due.
2. Add a recipient. Click Add eMail and enter an email address or click Add Role to select a role from the list. You can add multiple recipients to the notification.
3. To add a variable, place your cursor where you want the variable to appear, then select the variable from the Insert a substitution variable drop down box.
4. Enter a Subject Line.
5. Type the body of the message in the Message field. To add a variable, place your cursor where you want the variable to appear, then select a variable from the Insert a substitution variable drop down box.
6. Click Reset to clear the information, or Delete to completely remove the notification, or Continue to review the report.
   

Adding additional notifications for the same time period
You can have multiple notifications sent out for the same Time Period. For example, you could have two different notifications being sent three days before the report is due. To do this, click Add Notification and a second Email notification will appear in the same area.
Note: The notifications can be minimized by clicking on the minimize icon.

Adding notifications for a different time period
If you want to add a notification for a different time period, for example, the day after the report was due, select a new number from Time Scale box. The notifications you’ve previously created will be saved and the page will only show notifications setup for the new time select. From here, follow the steps described previously for Adding a notification.

5. Review
The Review page allows you to review the Report Definition you’ve created. If the information is correct, click Save. If you want to make changes, click Back to return to previous sections and made your changes.

Import Rules into caAERS

You can import existing rulesets into caAERS. This is an easier and faster way to set up rules in caAERS. At present, there is a small set of existing rules covering the baseline reporting rules for most CTEP sponsored trials. New rulesets are being developed and added to this library. Copies of these existing rulesets can be obtained from the caAERS Gforger project site, https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/docs/rules/1.5/?root=caaersappdev.
To import rulesets:

1. Click the Rules tab and click Import Rules in the task menu.
2. Click Browse to locate and select the XML file that contains the ruleset.
3. Click Import.
4. If the import was successful, you will receive the message “Rules imported successfully”. If it was not successful, you will receive a message telling you to contact the system administrator.

Note: Although it is possible to create rulesets for importing using an XML authoring tool, we recommend against it. Rulesets imported into caAERS should be obtained from the caAERS ruleset library or else they should be created in caAERS using the Ruleset XML export feature.

To manually enter rules:

1. Select Category (Rule Level)
2. Select Ruleset
3. Create Rules
4. Review
5. Enable Rule Set

1. Select Category
The first step for creating rules is to determine what category the rule falls in. Click the Rules tab in the navigation bar. As discussed in the introduction, there are four different categories to choose from:

• Sponsor
• Institution
• Sponsor defined for a study
• Institution defined for a study

1. Make a selection in the Rule Level section and the associated text field will appear on the page.
2. Enter information into the fields that appear. This may mean you’re entering a Sponsor or an Institution, with the possibility of entering a study.
   Note: These are pre-populated fields. Enter the first few letters of the name of the Sponsor or Institution you are looking for and select it from the drop down menu.
3. Click Continue.

2. Select Ruleset
The next page allows you to select the rulesets. It will display any existing rulesets associated with the rule level you selected. You have the option to select an existing ruleset or create a new ruleset.

Existing Rulesets

If you chose Sponsor defined for a study or Institution defined for a study, and you’ve already went through the process for Sponsor or Institution rules, some of the information may already exist.
Note: Remember, there are only two Rulesets to choose from, and you can only have one of each type. So, if there’s an existing Ruleset, any changes you make to the rules will override the Ruleset that already exists. Making changes to an existing Ruleset will not create a separate Ruleset.

1. Select the radio button next to an existing Ruleset in the Rule Set section.
2. Click Continue.

If no rulesets exist you will need to create a Rule Set.

3. Create Rules

1. Click the Create Rule Set button.
2. Select one of the options from the Rule Set Name field.
3. Click the Continue button.

On the Rules page you can add rules to the Ruleset by clicking the Add Rule button in the right hand side of the page.
Note: If you chose an exiting Ruleset for the Sponsor or Institution category, there may be rules already associated with it. Any changes you make will override what currently exists, not create a separate Ruleset.
Note: If you chose an existing Ruleset for the Sponsor defined for a study or Institution defined for a study category, the Rulesets for the corresponding Sponsor or Institution category are automatically included so you do not have to enter the information again. You can then add or delete rules.
Important: Changes you make by following these instructions only apply to the ruleset associated with the Sponsor defined for a study or Institution defined for a study category. Changes do not apply for the original Sponsor or Institution category.

1. Click Add Rule in the right hand side of the page and a form will appear that will allow you to define the rules that go with the Ruleset. There are four drop down boxes.
2. Select Domain Object: Select Adverse Event, Study, or Report Definition from the Domain Object drop down menu.
3. Select Field: Select an option from the Field drop-down menu. The options available are dependent on what was selected as the Domain Type.
4. Select operator: Select an option from the Operator drop-down menu. This menu will always list Equal to and Not Equal to, and depending on your previous selections, may also list Greater Than or Equal To and Less Than or Equal To.
5. Select Value: Select a value from the Value drop-down menu. The options will vary based on the Domain Object and Field selected.
6. If there are additional conditions you want to assign to this Rule, click on the Plus () icon and repeat the steps above.
   Note: All of the conditions listed must be met for the Rule to be completed and saved in the system. If you do not require all the conditions to be met, create a separate Ruleset.
   Note: You can remove conditions by clicking on the Red x icon.
   Continue to step 7 if there are no additional conditions to assign to this Rule.
7. Select an option from the Action box.
8. To continue, click the Continue button. To add another rule, click Add Rule and repeat the steps above. To delete a rule, click the icon, , in the right-hand corner of the rule.

4. Review
The Review page allows you to review and verify the information before saving the ruleset. Click the Save button to save the rule you’ve created, or click Back to go back and make changes.

5. Enable Rule Set
All new rules sets are given the status of Not Enabled. Go to the Action column and click Enable. Or you can leave the status as Not Enabled and return to the List Rules task page at a later time to enable it.

User Management

The following table describes the application-specific users/roles that should be defined for each application in order to operate all of the CCTS functionality.

The following table describes the roles/users necessary to handle the specific CCTS messaging scenarios. These users must be created across all applications and be common across the applications for the messaging functionality to work.

Note: user names must be synchronized across applications (with appropriate application roles). Be sure that both user name and email address match throughout (e.g. in PSC, which captures both).

Creating Grid Users in Dorian

The first step in creating new CCTS users is to request/create a user account in the local Dorian. The Dorian Identity Provider (DorianIdP) gives developers, smaller groups, research labs, unaffiliated users, and other groups that don’t have their own IdP, the ability to leverage Dorian. The DorianIdP provides a method for prospective users to register for an account.

To request a user account please complete the following steps:

1. Launch the GAARDS UI (by running "ant gaards" from the caGrid directory on the grid node)
2. From the top menu bar in the GAARDS UI select Account Management => Local Accounts => Registration.
3. From the Service drop down, select or enter the service URL of the Dorian you wish to register with.
4. Specify a username and password - the user name should be the email address of the user
   1. NOTE: The password must contain at least 10 and at most 20 characters, as well as contain at least one capital letter, one number, one non-alphanumeric symbol, and not contain any dictionary words.
5. Finally enter your personal information and click the Apply button.

In most cases your account will be immediately approved and you should be able to create grid credentials.

See the Dorian documentation for more details.

Creating Users in C3PR

Below are instructions that explain how to create research staff in C3PR and following that are instructions that explain how to create subjects.

The likely users of C3PR are people with the job responsibilities listed below. The role(s) granted to each user in the application will depend on the specific responsibilities of the person's job and other institutional rules under which they execute their responsibilities.

• Registrar
• Study Coordinator
• Site Coordinator
• System Administrator

The following table contains the different kinds of user groups:

To create Research Staff:
From the C3PR home page mouse over the Person And Organization tab and select Research Staff and click on Create Research Staff in the drop down list that appears.

To create new Research Staff:

1. Select the Organization where the research staff are located.
2. Enter the First Name of the research staff.
3. Enter the Last Name of the research staff.
4. Enter the Middle Name of the research staff.
5. Enter the Maiden Name of the research staff.
6. Enter the NCI Identifier of the research staff. Note: A list of NCI Identifier Codes can be found at
   http://ctep.cancer.gov/forms/Organization_Codes.txt
7. Enter the Email or Username of the research staff.
8. Enter the Phone number of the research staff.
9. Enter the Fax number of the research staff.
10. Check the user role for the research staff. Check at least one or check all the roles that apply and click the Save button.

• C3pr admin
• Study coordinator
• Registrar
• Site coordinator

Creating Users in PSC

Login to PSC and go to Administration >Manage users >Create User, enter information for the following fields and click Create.

• User Name
• Email Address
• Password
• Re-Enter Password
• Enable User
• Select User Roles

Creating Users in caAERS

Below are instructions that explain how to create research staff in caAERS and following that are instructions that explain how to create subjects.

To create research staff:
Click the Administration tab and click Research Staff in the task menu. All users of the caAERS system have accounts, although their access rights vary. The Research Staff Page allows you to create the user accounts and assign their roles. Access to the different areas of caAERS is controlled by the user roles and each user can be assigned to multiple roles.
These roles are:

• Subject Coordinator – Provides access to the Adverse Events, Studies, and Subjects tabs; the user can document AEs and create reports, studies, and subjects
• Study Coordinator – Provides access to the Studies tab; the user can review studies, AEs, and expedited reports
• Adverse Event (AE) Coordinator – Provides access to the Adverse Events tab; the user can view and report AEs for studies they are assigned to
• Site Coordinator – Provides access to the Adverse Events, Studies, Rules, and Administration tabs; the user can report AEs, create studies, set up rules, and have access to administrative features of the application.
  Note: The only tasks the site coordinator doesn’t have access to is documenting AEs.

Each role provides access to different functions in caAERS. When you log in to

caAERS, you will only see the tabs and tasks that you have role authority for. The following table shows what functionality each role has access to.

= rights/access
or blank

= no rights or access If you feel you have not been assigned to the proper user role(s), contact your

caAERS Site Coordinator or System Administrator.

AE Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
AE Module tab
document AEs evaluation periods expedited reports link from Manage report (when now AEs have been documented yet)	(for assigned studies)		(for assigned studies)
edit AEs evaluation periods expedited report Links from Manage reports (Submit, Amend, Withdraw, and report to PSC; hyperlink of expedited report and evaluation period)	(for assigned studies)		(for assigned studies)
View manage reports view details of evaluation periods, expedited reports, and routine AEs Print PDFs of expedited reports View expedited report in AdEERS	(for assigned studies)	(for assigned studies)	(for assigned studies)
Studies Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Studies Module tab
Create Study
Edit Study
View Study			(for assigned studies)
Search Studies			(for assigned studies)
Subjects Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Subjects Module tab
Create and Assign Subject			(for assigned studies)
Assign a Subject to a Study (Subject already created)		(for assigned studies)	(for assigned studies)
View Subject		(for assigned studies)	(for assigned studies)
Search Subject		(for assigned studies)	(for assigned studies)
Advanced Search Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Advanced Search module tab
Study Search			(for assigned studies)
Subject Search		(for assigned studies)	(for assigned studies)
Expedited Report Search	(for assigned studies)	(for assigned studies)	(for assigned studies)
Rules module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Rules Module tab
Create Rule
Edit Rule
Create Report Definition
Edit Report Definition
View Report Definition
Admin module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Admin Module tab
create/edit/search Organization
create/edit/search Research Staff
configure caAERS
create/edit/search Investigator
Import MedDRA
IND
Password Policy
Import Study, Subject, Research Staff, Investigator

Click the Administration tab and click Research Staff in the task menu. All users of the caAERS system have accounts, although their access rights vary. The Research Staff Page allows you to create the user accounts and assign their roles.

• Enter the Grid Identity: In the CCTS suite, the user ID is the Grid identity (as shown below).
  
  
  

Access to the different areas of caAERS is controlled by the user roles and each user can be assigned to multiple roles.
These roles are:

• Subject Coordinator – Provides access to the Adverse Events, Studies, and Subjects tabs; the user can document AEs and create reports, studies, and subjects
• Study Coordinator – Provides access to the Studies tab; the user can review studies, AEs, and expedited reports
• Adverse Event (AE) Coordinator – Provides access to the Adverse Events tab; the user can view and report AEs for studies they are assigned to
• Site Coordinator – Provides access to the Adverse Events, Studies, Rules, and Administration tabs; the user can report AEs, create studies, set up rules, and have access to administrative features of the application.
  Note: The only tasks the site coordinator doesn’t have access to is documenting AEs.

Each role provides access to different functions in caAERS. When you log in to

caAERS, you will only see the tabs and tasks that you have role authority for. The following table shows what functionality each role has access to.

= rights/access
or blank

= no rights or access If you feel you have not been assigned to the proper user role(s), contact your

caAERS Site Coordinator or System Administrator.

AE Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
AE Module tab
document AEs evaluation periods expedited reports link from Manage report (when now AEs have been documented yet)	(for assigned studies)		(for assigned studies)
edit AEs evaluation periods expedited report Links from Manage reports (Submit, Amend, Withdraw, and report to PSC; hyperlink of expedited report and evaluation period)	(for assigned studies)		(for assigned studies)
View manage reports view details of evaluation periods, expedited reports, and routine AEs Print PDFs of expedited reports View expedited report in AdEERS	(for assigned studies)	(for assigned studies)	(for assigned studies)
Studies Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Studies Module tab
Create Study
Edit Study
View Study			(for assigned studies)
Search Studies			(for assigned studies)
Subjects Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Subjects Module tab
Create and Assign Subject			(for assigned studies)
Assign a Subject to a Study (Subject already created)		(for assigned studies)	(for assigned studies)
View Subject		(for assigned studies)	(for assigned studies)
Search Subject		(for assigned studies)	(for assigned studies)
Advanced Search Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Advanced Search module tab
Study Search			(for assigned studies)
Subject Search		(for assigned studies)	(for assigned studies)
Expedited Report Search	(for assigned studies)	(for assigned studies)	(for assigned studies)
Rules module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Rules Module tab
Create Rule
Edit Rule
Create Report Definition
Edit Report Definition
View Report Definition
Admin module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Admin Module tab
create/edit/search Organization
create/edit/search Research Staff
configure caAERS
create/edit/search Investigator
Import MedDRA
IND
Password Policy
Import Study, Subject, Research Staff, Investigator

Creating Users in LabViewer

Currently, Lab Viewer has one role - authorized to use Lab Viewer or not. After a user has been authenticated via WebSSO Dorian and authorized via CSM, they are allowed to use Lab Viewer.

Steps to create a user in LabViewer:

• Modify the username (ccts@nih.gov) and password (7n9/VP+v3XYWD5UHP32oFQ==) in the first SQL statement below.

• Execute the following SQL using the CTODS database system username/password:

 insert into CSM_USER(USER_ID, LOGIN_NAME, FIRST_NAME, LAST_NAME, PASSWORD, UPDATE_DATE)
        values(nextval('CSM_USER_USER_ID_SEQ'), 'ccts@nih.gov', 'CCTS', 'Demo', '7n9/VP+v3XYWD5UHP32oFQ==', now());           
 insert into CSM_USER_PE(USER_PROTECTION_ELEMENT_ID, PROTECTION_ELEMENT_ID, USER_ID, UPDATE_DATE)
        values(nextval('CSM_USER_PE_USER_PROTECTIO_SEQ'), 2, currval('CSM_USER_USER_ID_SEQ'), now());          
 commit;

C3PR Administration

Important: C3PR Administrators must enter information for Investigators, Research Staff, Organizations, Studies and Registrations before end users can enter information into the C3PR application.

Notification

You can set notifications that will send out e-mail updates (notifications/reports) to investigators and research staff when a specific event occurs in a study. For example, you can create an e-mail notification to be sent if you want users to receive an e-mail message when a study is activated or has new registrations.
From the C3PR home page mouse over the Administration tab and click on Notification in the drop down list that appears.


To create an e-mail notification:

1. Click Add Notification.
2. Select the type of Event from the drop down list. The notification e-mail will be sent immediately after the event occurs.
   Note: You have the option in this drop down list to select New Registrations Report. This will not send an e-mail notification every time a patient is registered to a study. Select Annual, Monthly or Weekly from the Frequency drop down list to determine how often the report is sent out.
3. Enter Message Details. This is the message body of the notification that is sent out every time the chosen event occurs. Click Update after you have entered the message. You can select Substitution Variables into the message and these are replaced with the actual value when the e-mail is sent.
   Note: For example, if you select Study Short Title from the substitution variables drop down list ${STUDY_SHORT_TITLE} will be inserted into the message and will automatically enter the short title of the study into the message. The message details section does not need to be filled out for New Registrations Report.
4. To enter recipients of the notification individually, click Add Email/Name to add recipients for the e-mail notification. This is a prepopulated field. Enter the first few letters of the first/last name or e-mail address of the investigator or research staff and select it from the drop down list that appears.
   OR
5. To enter recipients based on their role in the study, click Add Role and make a selection from the drop down list.
   Note: Only investigators and research staff that are entered in C3PR for the hosted site will appear in the drop down list. To add investigators and research staff for the hosted site go to Person & Organization > Investigators> Create Investigator OR Person & Organization > Research Staff > Create Research Staff in the navigation bar. You can add multiple notifications for the hosted site. Click Add Notification to enter additional notifications.
6. Click Save.

Import Study

To import studies, go to the C3PR home page and mouse over the Administration tab and click on Import Study in the drop down list that appears.

To import a study:

1. Select XML file to import by clicking on the Browse button and locating the file. To see an example of how an XML file should be formatted before it is imported, click the Download Schema File and Download Sample XML File links.
2. Click on Import to import Study.
3. Click on the Study that has just been imported and change the status of the Study Sites before you import the registration.
   Note: For instructions on how to enter a study manually go to the Studies section.

Import Registration

From the C3PR home page mouse over the Administration tab and click on Import Registration in the drop down list that appears.

Important: The Study site must already be activated before you can import registrations.

To import a Registration:

1. Select XML file to import by clicking on the Browse button and locating the file.
2. Click the Import button.
   Note: To enter a registration manually, go to Registration.

Configure C3PR

From the C3PR home page mouse over the Administration tab and click on Configure C3PR in the drop down list that appears.



The configurations for C3PR are as follows:

Authentication Mode
This defines the strategy C3PR uses to authenticate. Possible values are 'local' and 'webSSO' (Default: local)

Authorization enable switch
Switch to turn on/off authorization. The value may not be applied until the application is restarted (Default: false)

C3D hotlink URL
The base URL for the C3D deployment to which this C3PR instance can link (Default: https://octrials-train.nci.nih.gov/opa45/rdclaunch.htm)

C3PR URL
This is the URL of this C3PR instance.

caAERS hotlink URL
The base URL for the caAERS deployment to which this C3PR instance can link (Default: https://cbvapp-d1017.nci.nih.gov:28443/caaers/pages/ae/list)

WebSSO base URL
(Default: https://cbvapp-d1017.nci.nih.gov:48443/cas)

WebSSO certificate file
websso certificate file path (Default: /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home/lib/security/cacerts)

ESB enable switch
Switch to turn on/off esb (Default: false)

ESB URL
URL for the enterprise service bus -- the value may not be applied until the application is restarted (Default: https://cbvapp-d1017.nci.nih.gov:28445/wsrf/cagrid/CaXchangeRequestProcessor)

Host certificate file (host certificate file path)
(Default: /Users/kherm/certs/manav.local-cert.pem)

Host key
Host key path (Default: /Users/kherm/certs/manav.local-key.pem)

Hosted Mode
If the value is false, C3PR will not send a registration request to Co-ordinating center for approval for Multi-Site trials (Default: true)

Local site NCI institute code
The NCI institute code of the site where this C3PR instance is running

SMTP authentication
(Default: true)

From address
The "from" address for all mail sent by C3PR. This address need not be a real e-mail address. The value may not be applied until the application is restarted (Default: admin@semanticbits.com)

SMTP password
Mail server password (only necessary if the mail server requires authentication). The value may not be applied until the application is restarted (Default: biju1234)

SMTP server
The address of the outgoing mail server (e.g.: smtp.gmail.com). The value may not be applied until the application is restarted (Default: smtp.comcast.net)

SMTP port
The port number of the outgoing mail server. The value may not be applied until the application is restarted (Default: 25)

SMTP user name
Mail server username (only necessary if the mail server requires authentication). The value may not be applied until the application is restarted (Default: biju.joseph@semanticbits.com)

Study Calendar hotlink URL
The base URL for the Study Calendar deployment to which this C3PR instance can link (Default: https://cbvapp-d1017.nci.nih.gov:28443/psc/pages/schedule)

Save Your Configuration
Once you have completed C3PR configurations, click Save.

Configure Password Policy

From the C3PR home page mouse over the Administration tab and click Configure Password Policy in the drop down list that appears.

1. Enter the appropriate criteria for the following:
   1. Login Policy
   2. Password Creation Policy
   3. Complexity Requirement
2. Click Save.

caAERS Administration

Configure caAERS

Click the Administration tab in the navigation bar. caAERS is installed with empty configuration information. You will need to enter information in the Configure caAERS task page to configure caAERS to work with a mail server and with caBIG Clinical Trials Suite (CCTS), if desired. All configuration is done on a single page.

The following table describes each field and notes whether it’s for mail server configuration or CCTS configuration.

Note: The Show debugging information is not related to either mail server or CCTS configuration. This field is for developers only.

Configuring caAERS to work with a Mail Server
The caAERS application relies on sending e-mails – for alerts, reminders, and submission of some reports. In order to successfully send e-mails, caAERS must be set up to use a working Mail Server.
To configure caAERS to work with your mail server:

1. Click the Administration tab to go to the Configure caAERS task page
2. Enter the SMTP server. This is The address of the outgoing mail server (e.g.: smtp.gmail.com).
3. Enter the SMTP password. This is only necessary if the mail server requires authentication.
4. Enter the SMTP port, if different than 25.
5. Select Yes or No for Secure SMTP?.
6. Enter the SMTP user name. This is only necessary if the mail server requires authentication.
7. Enter the From address. The "from" address for all mail sent by caAERS. This address does not have to be a real e-mail address.
8. Click Save.

Note: If you do not provide information for your SMTP mail server, you will not be using caAERS full capabilities.
Note: You may need to restart the caAERS server before all the changes are recognized.

Configuring caAERS to work with CCTS
If you plan to use caAERS as a tab in the caBIG Clinical Trials Suite, you will need to complete the steps outlined in this section. If you will be using caAERS as a standalone application, you can leave these fields blank. To configure caAERS to work with CCTS:

1. Click the Administration tab.
2. Enter ESB queue URL. This is the URL for the enterprise service bus -- the value may not be applied until the application is restarted.
3. Enter the LabViewer base URL. This is the base URL for the LabViewer deployment to which this caAERS instance can link.
4. Enter the Study Calendar base URL. This is the base URL for the Study Calendar deployment to which this caAERS instance can link.
5. Click Save .

Note: You may need to restart the caAERS server before all the changes are recognized.

Investigator

The Investigators tasks allow you to create Investigators and associate them to studies. It also allows you to search the system for Investigators to see if they are already in the system and/or associated to their studies. Investigators who are added to caAERS can receive email alerts and report submissions.

To Create/Edit an Investigator:

1. Click the Administration tab and click Investigator in the task menu.
2. Enter the First Name.
3. Enter the Middle Name if desired.
4. Enter the Last Name.
5. Enter the Investigator number if desired.
6. Enter the Email address.
7. Enter the Phone number.
8. Enter the Fax number if desired.
9. Enter the Organization. This is a pre-populated field. Enter the first few letters of the name of the Organization the Investigator is associated with and select it from the drop down menu that appears.
10. Select Inactive or Active from the Status drop down box.
11. If the Investigator works with another Organization, click Add Organization and repeat the steps above.
12. Click Save. If you entered information correctly into all the required fields you will see a

confirmation message stating that the system has Successfully saved the investigator.

Note: For an Investigator to be able to log into caAERS, you will need to also add the Investigator to caAERS as a Research Staff/User. To do this, please see the Research Staff section of this guide.

Searching for an Investigator

1. Click the Administration tab and click Investigator in the task menu and then click Search Investigator in the steps menu.
2. In the Investigator Criteria box enter in the First Name, Last Name, and/or the Investigator number field and then click Search.
   Note: You can also leave the fields blank and click Search to list all Investigators.
3. The Investigators available will be listed in the bottom of the page. You can sort the search results by entering the appropriate information in the First Name, Last Name, Middle Name or NCI Institute Code text fields top of each column and then clicking the Filter button in the top right hand of the Search Results box.
4. Click on the First Name of an investigator in the search results to view and/or edit the investigator profile.

Research Staff

Click the Administration tab and click Research Staff in the task menu. All users of the caAERS system have accounts, although their access rights vary. The Research Staff Page allows you to create the user accounts and assign their roles. Access to the different areas of caAERS is controlled by the user roles and each user can be assigned to multiple roles.
These roles are:

• Subject Coordinator – Provides access to the Adverse Events, Studies, and Subjects tabs; the user can document AEs and create reports, studies, and subjects
• Study Coordinator – Provides access to the Studies tab; the user can review studies, AEs, and expedited reports
• Adverse Event (AE) Coordinator – Provides access to the Adverse Events tab; the user can view and report AEs for studies they are assigned to
• Site Coordinator – Provides access to the Adverse Events, Studies, Rules, and Administration tabs; the user can report AEs, create studies, set up rules, and have access to administrative features of the application.
  Note: The only tasks the site coordinator doesn’t have access to is documenting AEs.

Each role provides access to different functions in caAERS. When you log in to

caAERS, you will only see the tabs and tasks that you have role authority for. The following table shows what functionality each role has access to.

= rights/access
or blank

= no rights or access If you feel you have not been assigned to the proper user role(s), contact your

caAERS Site Coordinator or System Administrator.

AE Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
AE Module tab
document AEs evaluation periods expedited reports link from Manage report (when now AEs have been documented yet)	(for assigned studies)		(for assigned studies)
edit AEs evaluation periods expedited report Links from Manage reports (Submit, Amend, Withdraw, and report to PSC; hyperlink of expedited report and evaluation period)	(for assigned studies)		(for assigned studies)
View manage reports view details of evaluation periods, expedited reports, and routine AEs Print PDFs of expedited reports View expedited report in AdEERS	(for assigned studies)	(for assigned studies)	(for assigned studies)
Studies Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Studies Module tab
Create Study
Edit Study
View Study			(for assigned studies)
Search Studies			(for assigned studies)
Subjects Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Subjects Module tab
Create and Assign Subject			(for assigned studies)
Assign a Subject to a Study (Subject already created)		(for assigned studies)	(for assigned studies)
View Subject		(for assigned studies)	(for assigned studies)
Search Subject		(for assigned studies)	(for assigned studies)
Advanced Search Module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Advanced Search module tab
Study Search			(for assigned studies)
Subject Search		(for assigned studies)	(for assigned studies)
Expedited Report Search	(for assigned studies)	(for assigned studies)	(for assigned studies)
Rules module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Rules Module tab
Create Rule
Edit Rule
Create Report Definition
Edit Report Definition
View Report Definition
Admin module	AE Coordinator	Study Coordinator	Subject Coordinator	Site Coordinator	System Admin
Admin Module tab
create/edit/search Organization
create/edit/search Research Staff
configure caAERS
create/edit/search Investigator
Import MedDRA
IND
Password Policy
Import Study, Subject, Research Staff, Investigator

Import

Studies, subjects, routine AEs, Investigators and Research staff can be imported into caAERS. If you have previously used other applications and databases to maintain this information you can import it instead of manually entering it. To import studies, subjects, Routine AEs, Investigators or Research staff create valid XML files from the information in your existing application/database. Create separate XML files for each type of data (studies, subjects, and AEs). Combining everything into a single XLM file will cause the import to fail. To review copies of the XSD files and sample XML files, go to https://gforge.nci.nih.gov/svnroot/caaersappdev/docs/import/1.5 .
To import:

1. Create an XML file containing the information you want to import.
2. Click the Administration tab and click Import in the task menu.
3. Click on Import Study/Protocol, Import Subject, Import Routine AEs, Import Investigator or Import Research Staff.
4. Click Browse to locate and select the XML file that contains the information.
5. Click Save or Save & Continue.
6. The system will validate the XML file and show a synopsis of what will be imported on the Review and Submit page; if the information looks correct, click Save; depending on the size of the file, this could take minutes to hours to complete
7. To verify the information imported correctly, use the search task in the Adverse Events, Studies, or Subjects Tab.

Import MedDRA

The caAERS installation includes the CTC v2 and CTCAE v3 vocabulary. CTC is a free open-source medical vocabulary that can be used to code clinical studies. An alternative to CTC is MedDRA terminology. If your organization uses MedDRA, the vocabulary can be imported into the application. Currently, only MedDRA versions 9.0, 9.1, and 10.0 are supported. MedDRA is stored in several ASCII (.asc) files. If the file format you try to import does not mach the allowed format, the import will fail.
To import MedDRA files:

1. Locate the folder where MedDRA is stored.
2. Click the Administration tab and click Import MedDRA in the task menu.
3. Enter the full path to the folder that is located on the server which contains the files to be imported click Import MedDRA. Note: The MedDRA files and folder must be located on the server that caAERS is installed on. You cannot import files from a folder that is located on the "client side" or desktop computer.

IND#

Investigational new drugs (IND) can be added in caAERS for use in studies. By adding the IND information, adverse events related to a particular IND can be tracked more efficiently.
Creating an IND

1. Click the Administration tab and click IND# in the task menu
2. Enter the IND #
3. Click the IND held by? drop down box to select Organization or Investigator.
4. Enter the IND Holder. This is a pre-populated field. Enter the first few letters of the name of the IND Holder and select it from the drop down menu that appears.
5. Click Save.
   

Searching for an IND

1. Click the Administration tab, click IND# in the task menu and click Search IND# in the steps menu.
2. Enter search criteria in the IND # and/or the IND holder field and then click Search.
   Note: You can leave the fields blank and click Search to list all INDs.
3. The INDs will be listed in the bottom of the page. You can sort search results by entering appropriate information for IND # and/or Sponsor Name in the text fields at the top of each column and clicking the Filter button the top right corner of the Search Results section.

Organization

An Organization can be a site, a sponsor, or any institution associated with clinical trials and is a required field to add investigators and research staff. caAERS includes a large list of organizations as part of the basic install. If needed, additional organizations can be added to the list.
Searching for an Organization Since Organizations are included in the installation, you should first search caAERS for the organization before you add it.
To search for an organization:

1. Click the Administration tab, click Organization in the task menu, click Search Organization in the steps menu to bring up the Search Organization page
2. Enter search criteria in the Name and/or the NCI Identifier field and then click Search.
   Note: You can leave the fields blank and click Search to list all Organizations.
3. The Organizations available will be listed in the bottom of the page. You can sort the search results by entering the appropriate information in the Name and/or the NCI Identifier text fields at the top of each column and then clicking the Filter button in the top right corner of the Search Results section.
4. To view and/or edit an organization listed in the search results, mouse over the Name and click on it.
   

Create an Organization

1. Click on the Administration tab and click Organization in the task menu to open the Create Organization page.
2. Enter the Name
3. If you want to provide additional details, enter the Description
4. Enter the NCI Identifier. The NCI Identifier is the primary id used by NCI and can be found at http://ctep.cancer.gov/forms/Organization_Codes.txt
5. Click Save to create the organization.

Configure Password Policy

caAERS allows you to create specific rules regarding the creation of user passwords. This creates a more secure environment and allows you to control the level of security for user passwords.
To configure the password policy:

1. Click the Administration tab and click Configure Password Policy in the task menu.
2. Enter Maximum password age – this determines how long a user can keep a password before having to reset it.
3. Enter Number of allowed failed login attempts.
4. Enter the Lockout duration – this determines how long a person is locked out of the system after entering the wrong password the number of allowed times.
5. Enter the Minimum password age – this prevents a user from recreating their password numerous times in a row to go back to the same password.
6. Enter the Password history size – this determines how many past passwords you keep in the system for a user.
7. Enter Minimum password length.
8. Select the appropriate checkboxes for the Complexity Requirement.
9. Enter largest substring of username allowed – this prevents users from having their password too similar to their user name.
10. Click Save.

PSC Administration

Login to PSC as a System Administrator and locate the tab labeled Administration. Click on this tab to view the list of available administrative options.

Manage Sites

Click Manage sites in order to see a list of existing sites and to access the option to create a new site. To create a new site, click Create new site, enter a name for the site, and click Create. Each site has its own list of days on which it does not provide services. If you wish to modify this list (it is initially empty), click the Manage holidays and weekends link next to the appropriate site.

Manage Users

Click Manage users in order to see a list of existing users, make changes to existing user accounts, and add new user accounts.

Add new user account

After clicking “Manage users,” click “Create user.” Enter the appropriate information, including the role and site information. Note that Study Coordinators, Study Administrators, and System Administrators are not site specific, but Subject Coordinators and Site Coordinators are. This means that the Subject Coordinator and Site Coordinator roles must be check for each site in which the user will work. The example below shows an account that is a Study Coordinator and a Subject Coordinator at two sites:

Modify existing user account

To modify a user account, click “Manage users” and then select the desired account from the list. Any of the user account attributes may be modified and saved.

Disable account

After selecting the account from the list, uncheck the “Enable User” box.

Configure PSC

Click the Configure PSC link on the Administration tab to set most application configuration options. These include debugging information, automatic email notifications of application errors, etc… All options are described on the configuration page.

Configure Authentication

Click Configure authentication from the Administration tab in order to choose between four authentication options. The default is local, meaning that user accounts and passwords are stored locally. The other options are CAS, caGrid WebSSO (for use with CCTS), and custom.

LabViewer Administration

Navigate to the LabViewer/cTODSDeploymentController directory. Edit the LabViewer.build.properties file and specify the following properties:

• caXchange URL: This is the URL for caXchange (Example: loadLabURLS = https://cbvapp-d1017.nci.nih.gov:28445/wsrf/services/cagrid/CaXchangeRequestProcessor)

• caAERS base URL: This is the base URL for caAERS deployment to which this LabViewer instance can link (Example: BaseURLcaAERS = https://cbvapp-d1017.nci.nih.gov:28443/caaers)

• CAS server ID and port: This is used for WebSSO authentication (Example: websso.cas.server=cbvapp-d1017.nci.nih.gov:48443)

• client application server ID and port: This is used for WebSSO authentication (Example: websso.client.server=cbvapp-d1017.nci.nih.gov:28443)

• WebSSO enabled: This is used to determine the authentication method. Leave as is for WebSSO authentication (websso.enabled=TRUE). Comment out for CSM authentication (#websso.enabled=TRUE)

• database URL: This is used to connect to the database. (Example: database.url=jdbc:postgresql://cbiodb590.nci.nih.gov:5455/ctods)

• database username: This is used to connect to the database. (Example: database.username=ctods)

• database password: This is used to connect to the database. (Example: database.password=labview1234)

• test enabled: This is used to enable/disable the display of the 'Test' tab (happy.jsp). Set to true to display the Test tab (testEnabled=true). Set to false to disable the Test tab (testEnabled=false).

• smoke test grid service URL: This is used by the Test tab (Example: SmokeTestGridURL=https://cbvapp-d1017.nci.nih.gov:28445/wsrf-smoketestservice/services/cagrid/SmokeTestService)

• certificate path: This is used by Dorian. (Example: cert.path=/local/home/globus/caGrid-1.2/certs/ccts_dev_gts_host_cert.pem)

• key path: This is used by Dorian. (Example: key.path=/local/home/globus/caGrid-1.2/certs/ccts_dev_gts_host_key.pem)

Navigate to the wsrf-folder/globus_wsrf_core directory and edit the global_security_descriptor.xml file and specify the paths to the certificate file and the key file.

If WebSSO is not enabled, security settings need to be configured in Tomcat. Navigate to the CATALINA_HOME/conf/cabig directory. Edit the csm_jaas.config file and add the following text to this file. Replace the url, user and passwd parameters with the database connection properties.

 labviewer
 {
   gov.nih.nci.security.authentication.loginmodules.RDBMSLoginModule required
   driver=org.postgresql.Driver
   url="jdbc:postgresql://cbiodb590.nci.nih.gov:5455/ctods"
   user=ctods
   passwd=labview1234
   query="SELECT * FROM CSM_USER WHERE LOGIN_NAME=? and PASSWORD=?"
   encryption-enabled=YES;
 };

Edit the ApplicationSecurityconfig.xml file. An XML editor or WordPad must be used to retain the correct XML format. Add the following application tag and replace the hibernate-config-file tag contents as appropriate.

 <application>
   <context-name>
     ctodslabviewer
   </context-name>
   <authentication>
     <lockout-time>
       10000                   
     </lockout-time>
     <allowed-login-time>
       30000             
     </allowed-login-time>
     <allowed-attempts>
       2                 
     </allowed-attempts>
     <authentication-provider-class>
     </authentication-provider-class>
   </authentication>
   <authorization>
     <authorization-provider-class>
     </authorization-provider-class>
     <hibernate-config-file>
       /usr/local/jakarta-tomcat-5.0.28-8080/conf/cabig/cTODSlabviewer.hibernate.cfg.xml
     </hibernate-config-file>
   </authorization>
 </application>

C3D Connector Administration

Introduction

This administration guide provides a basic set of instructions for managing the C3D Connector. Topics include basic setup configuration for DCAPI processing related to the Enroll Patient service; configuration options of the AutoLoader in support of the Load Lab service; configuration options in support and the E-mail alert system.

Installation of the C3D Connector is covered in the C3D Connector Installation Guide.

Component Overview

Enroll Patient Service

This service accepts a request to enroll a patient into an existing study in C3D. The service will acquire a C3D patient position for the requested Study and Site, assign values to the C3D Questions related to Patient ID and NCI Institution Code, if available, and return the C3D Patient Position through received message.

These functions are made possible by leveraging the DCAPI services provided as part of the Oracle Clinical installation. To successfully interact with these services, some configuration is required, and will be covered in this document.

Load Lab Service

This service accepts requests to load patient laboratory results and loads them into C3D. This service will accepts groups of records in a single request, validates the data for completeness, prepares the data for processing, and submits the data to the C3D Lab Loader for final processing and loading. This service runs asynchronous to the Load Lab request and therefore provides a mechanism for alerting user of issues.

Due to the complexities surrounding Lab Test Result processing and the need to leverage the C3D Lab Loader to perform the actual loading of data to C3D, this service does require configuration. All of the options of the configuration are covered in this document.

E-Mail Alerts

This service is not accessible from the C3D Connector, but instead is a utility used by the Connector to alert users and/or support staff of issues during the processing of service requests. Currently, only the Load Lab service takes advantage of this utility, because of the asynchronous nature of the Load Lab service. Documentation of configuration of this utility, known as the C3D Mailer, is provided below.

Configurations

Database Connectivity Configurations

There are two different database configuration files present in the C3D Connector. The C3D Grid Services Configuration file is used to house the database connection properties for the primary services, LoadLabs and EnrollPatient. It i located at:

%CATALINA_HOME\conf\c3d\c3dgridservice.properties

The contents for this property file are described below:

The Registration Consumer Configuration file is used to house the database connection properties for the internal processings of the services. It is located at:

%CATALINA_HOME\conf\c3d\registerConsumer_gridservice.properties

The contents for this property file are described below:

Enrollment Data Controls

Enrollment Data Controls are used to identify which data elements are to be forwarded from an incoming message to the patient information table of C3D. There may be instances where identifying patient data is not required,

Changes to the configuration can be performed only after the installation war has been deployed. The war file is deployed during installation, tomcat is initiated the first time.

Use the following steps to make changes to the default Enrollment Data Controls.

1. Start the tomcat
2. Open the file %CATALINA_HOME%\webapps\c3d\WEB-INF\classes\applicationContext-grid.xml in a text editor.
3. Search for the bean "enrollPatientManager" (Look for <bean id="enrollPatientManager"..).
4. The following properties inside the enrollPatientManager bean can be toggled between true and false.
   1. saveBirthDate
   2. saveGender
   3. saveName
   4. saveInitials
   5. saveEnrollmentDate
5. After making the desired change to the properties, save the file.
6. Restart the tomcat.

E-Mail Alerts

Overview

The C3D Mail system, which is used to send the e-mail alerts for the C3D Connector, consists of three tables and one PL/SQL package. In general, the C3D Mail system uses the Oracle Provided SMTP_UTIL PL/SQL package to simply the sending of e-mails from the database instance server. This utility is included in the installation package provided for the C3D Connector. The following table describes the object of the C3D Mail System:

C3D Mailer Mail Server

The C3D Mailer requires that an SMTP Mail Server be identified to the system. This is accomplished by inserting a record into the C3D_MAIL_CTL table for the Alert Type “MAILSERVER” and Utility “C3D_MAILER”. The following SQL scripts can be used to create this record. The system will not be able to send alerts if a mail server is not defined. During C3D Connector installation, a dummy value is automatically inserted into this table, the following statements can be used to place the proper value for your installation:

Select Statement - To view the current value for the Mailer Server

select UTIL_CODE, ALERT_TYPE, TO_ADDRESS MAIL_SERVER 
  from C3D_MAIL_CTL
 where UTIL_CODE = 'C3D_MAILER'
   and ALERT_TYPE = 'MAILSERVER';

Delete Statement - To remove the current value for the Mailer Server

delete from C3D_MAIL_CTL
 where UTIL_CODE = 'C3D_MAILER'
   and ALERT_TYPE = 'MAILSERVER';

Insert Statement - To insert a new value for the Mailer Server

Insert into C3D_MAIL_CTL (UTIL_CODE, CALERT_TYPE, TO_ADDRESS)
select 'C3D_MAILER', 'MAILSERVER', '&Your_Mail_Server_Name' 
  from dual
 where not exists (select 'X' from C3D_MAIL_CTL
                    where UTIL_CODE = 'C3D_MAILER'
                      and ALERT_TYPE = 'MAILSERVER');

Update statement - To update the curent value fo the Mailer Server

Update C3D_MAIL_CTL 
   set TO_ADDRESS = '&Your_Mail_Server_Name'
 where UTIL_CODE = 'C3D_MAILER'
   and ALERT_TYPE = 'MAILSERVER';

C3D Mailer Alert Types

Alert types are used to associate e-mail recipients and message templates. The following alert types are available in the C3D Mailer:

Load Lab Alert Types

The Load Lab process uses the C3D Mailer to send alerts to recipients when specific events occur during the processing of lab data. The following events, corresponding Alert types and system event severity are used by the Load Lab process and create e-mail alerts accordingly:

The C3D Mail utility must have at least one recipient defined for each of the Alert Types SUCCCESS and FAILURE. The Utility Code used by the Load Lab Service is AUTO_LOADER.

Building a Message

The C3D Mailer uses three distinct template types to build a complete e-mail message. The template types “OPENING”, “BODY”, and “CLOSING” are defined for that purpose. The table C3D_MAIL_MESSAGE_CTL holds alert message definitions for each C3D Utility for specific Alert Types. E-mail messages are built for a C3D Utility Alert Type by concatenating the values of MESSAGE_TEXT for the three templates types in the order, “OPENING”, “BODY”, “CLOSING”. Additionally, utility generated text (usually containing information related to the triggering event) is concatenated to the “BODY” template as part of the message building process. Missing template types are ignored, and alert types without any template definitions will have messages created that contain only the utility generated text.

Assigning a Recipient

Recipients are assigned to Alert Types in the table C3D_MAIL_CTL. Each row in the table represents a single Alert Type for a recipient.

The following example defines the recipient for successful Load Lab processing:

caXchange Administration

Introduction

This caXchange is the enterprise service hub for exchanging clinical trial information between applications and systems. caXchange (originally Lab Information Hub) is now a more generic platform for exchanging all types of clinical trial data and messages using service invocations and data exchange and is leveraged in the CCTS project. The Java Business Integration (JBI) compliant Apache ServiceMix Enterprise Service Bus (ESB) is the platform on which various routing and transformation services and components will be deployed. Please note that SERVICEMIX-HOME is assumed to be the folder where Apace ServiceMix has been installed.

Starting Servicemix

To start ServiceMix, perform the following steps:

Stopping Servicemix

To stop ServiceMix, perform the following steps:

Configuring Logging

caXchange Logging Configuration

Logging in caXchange is configured using the SERVICEMIX-HOME/conf/log4j.xml. A sample file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!--

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">
	<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
		<param name="threshold" value="INFO"/>
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="%-5p - %-30c{1} - %m%n"/>
		</layout>
	</appender>
	<appender name="FILE" class="org.apache.log4j.FileAppender">
		<param name="threshold" value="DEBUG"/>
		<param name="File" value="data/log/servicemix.log"/>
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="%d{ABSOLUTE} | %-5p | %-10t | %-24.24c{1} | %-30.30C %4L | %m%n"/>
		</layout>
	</appender>
	<appender name="CLM_JDBC_Appender" class="gov.nih.nci.logging.api.appender.jdbc.JDBCAppender">
		<param name="application" value="caxchange"/>
		<param name="server" value="localhost"/>
		<param name="maxBufferSize" value="1"/>
		<param name="dbDriverClass" value="com.mysql.jdbc.Driver"/>
		<param name="dbUrl" value="jdbc:mysql://localhost:3307/llt"/>
		<param name="dbUser" value="caxchange"/>
		<param name="dbPwd" value="caxchange"/>
		<param name="useFilter" value="false"/>
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value=":: [%d{ISO8601}] %-5p %c{1}.%M() %x - %m%n"/>
		</layout>
	</appender>
	<logger name="org.apache">
		<level value="WARN"/>
	</logger>
	<logger name="org.springframework">
		<level value="WARN"/>
	</logger>
	<logger name="org.jencks">
		<level value="WARN"/>
	</logger>
	<logger name="org.apache.activemq">
		<level value="WARN"/>
	</logger>
	<logger name="org.apache.activemq.transport.discovery">
		<level value="ERROR"/>
	</logger>
	<logger name="org.apache.servicemix">
		<!-- To enable debug logging, replace the INFO by DEBUG -->
		<level value="INFO"/>
	</logger>
	<logger name="org.apache.servicemix.jbi.config">
		<level value="WARN"/>
	</logger>
	<logger name="org.apache.servicemix.jbi.deployment">
		<level value="WARN"/>
	</logger>
	<logger name="gov.nih.nci.caxchange.servicemix.jbi.audit">
		<level value="INFO"/>
		<appender-ref ref="CLM_JDBC_Appender"/>
	</logger>
	<root>
		<level value="INFO"/>
		<appender-ref ref="CONSOLE"/>
		<appender-ref ref="FILE"/>
	</root>
</log4j:configuration>

Changing caXchange Logging Configuration

To change caXchange logging, perform the following steps:

<appender name="FILE" class="org.apache.log4j.FileAppender">
		<param name="threshold" value="DEBUG"/>
		<param name="File" value="data/log/servicemix.log"/>
		<layout class="org.apache.log4j.PatternLayout">

caXchange Service Assemblies

For caXchange following service assemblies has been deployed on the servicemix server:

Deploying or Starting caXchange service assemblies

To deploy and start caXchange service assemblies, perform the following steps:

Un-deploying or Stopping caXchange service assemblies

To un-deploy or stop a service assembly, perform the following steps:

Configuring caXchange

caXchange.properties

All the caXchange configurations reside in {SERVICEMIX-HOME}/conf/caxchange.properties. These properties include URLs for target services, Database connection properties, JMS connection information, and paths to the host certificate and key files. The table below describes the properties included in the caxchange.properties file.

Configure a new Target Grid Service

This requires changing the externalized configuration files for the Beans service unit. caXchange-installation-dir is the directory where caXchange software has been downloaded and installed as outlined in CaXchange Installation Guide.The following steps are required for routing to a new target Grid Service from caXchange. In these steps we take an example of adding a new target grid service called PSC Study Consumer Service.

#URL for the PSC study consumer service.Message type STUDY_CREATION are routed to this service.
psc.study.url=https://cbvapp-d1017.nci.nih.gov:28445/psc-wsrf/services/cagrid/StudyConsumer

   <bean  id="<<beanId>>"                             class="gov.nih.nci.caXchange.outbound.operations.GenericInvocationStrategy">
       <property  name="serviceUrl"     value="<<serviceUrl>>" />
          <property  name="gridClientClassName"  value="<<gridClientClassName>>" />         
          <property  name="requestPayloadClassName"    value="<<requestPayloadClassName>>" />    
          <property name="operationName"  value="<< operationName>>" />             
    </bean>

   <bean  id="pscStudy"     class="gov.nih.nci.caXchange.outbound.operations.GenericInvocationStrategy">
     <property  name="serviceUrl"     value="${psc.study.url}" />
          <property  name="gridClientClassName"  value="gov.nih.nci.ccts.grid.client.StudyConsumerClient” />         
          <property  name="requestPayloadClassName"    value="gov.nih.nci.ccts.grid.Study" />    
          <property name="operationName"  value="createStudy" />             
    </bean>

<bean    id="<<beanIdSU>>"    class="gov.nih.nci.caXchange.outbound.GridSU">
    <property name="strategy">
      <ref bean="<< beanId>> " />
     </property>
    <property      name="targetId"      value="<<targetId>>" />
    <property   name="targetOperation"   value="<<targetOperation>>" />
  </bean>

  <bean
    id="pscStudyInvocationStrategy"
    class=" gov.nih.nci.caXchange.outbound.GridSU”>
    <property      name="targetId"      value="psc" />
    <property   name="targetOperation"   value="STUDY_CREATION" />
  </bean>

<bean:endpoint service=" caxchange:<<serviceName>>" endpoint="endpoint" bean="#<<beanIdSU>>" />

<bean:endpoint service="caxchange:pscStudy" endpoint="pscStudyEndpoint" bean="#pscStudy" />

ant update-routing-configuration

Add Routing to a Target Grid Service

This requires changing the configuration files for the caXchange EIP service unit. caXchange-installation-dir is the directory where caXchange software has been downloaded and installed. These files are located in the caXchange-installation-dir/conf/caXchangeConf/eip/ folder. Following steps walk through configuring routing for a target Grid Service:

<eip:content-based-router service="caxchange:pscStudyCreationRouter" 
			endpoint="pscStudyCreationRouterEndpoint">
    <eip:rules>
      <eip:routing-rule>
        <eip:predicate>
          <eip:xpath-predicate xpath="count(/caxchange:caXchangeRequestMessage/caxchange:metadata[caxchange:operation='ROLLBACK']) = 1" namespaceContext="#nsContext"/>
        </eip:predicate>
        <eip:target>
          <eip:exchange-target service="caxchange:pscStudyRollback" />
        </eip:target>
      </eip:routing-rule>
      <eip:routing-rule>
        <eip:target>
          <eip:exchange-target service="caxchange:callPSCStudyPipeline" />
        </eip:target>
      </eip:routing-rule>
    </eip:rules>
  </eip:content-based-router>

  <eip:pipeline service="caxchange:callPSCStudyPipeline" endpoint="callPSCStudyPipelineEndpoint">
    <eip:transformer>
      <eip:exchange-target service="caxchange:pscStudy" />
    </eip:transformer>
    <eip:target>
      <eip:exchange-target service="caxchange:caxchangeResponseAggregator" />
    </eip:target>
  </eip:pipeline>

<eip:caxchange-static-recipient-list service="caxchange:studyCreationRecipients" 
		endpoint="studyCreationRecipientsEndpoint">
      <eip:recipients>
<eip:exchange-target service="caxchange:pscStudyCreationRouter" />
        <eip:exchange-target service="caxchange:caaersStudyCreationRouter" />
        <eip:exchange-target service="caxchange:ctomStudyRouter" />
      </eip:recipients>
      <eip:targetServiceIdentifiers>
               <value>psc</value>
               <value>caAERS</value>
               <value>LabViewer</value>
      </eip:targetServiceIdentifiers>      
  </eip:caxchange-static-recipient-list>

ant update-routing-configuration

Remove Routing to a Target Grid Service

This requires changing the recipients list of the message type for which the target no longer wants to receive messages. Each recipient list is configured in a separate file. Appendix D describes the contents of each xml file for the EIP service unit, it can be used to determine which file contains the configuration for a particular message type. These files are located in the {caXchange-installation-dir}/conf/caXchangeConf/eip/ folder. For example the configuration for REGISTER_SUBJECT message type is in the registerSubjectRecipients.xml. This configuration is as follows:

<beans xmlns:eip="http://servicemix.apache.org/eip/1.0"
       xmlns:caxchange="http://nci.nih.gov/caXchange">
    <eip:caxchange-static-recipient-list service="caxchange:registerSubjectRecipients" endpoint="registerSubjectRecipientsEndpoint">
      <eip:recipients>
	<eip:exchange-target service="caxchange:pscRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:caaersRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:ctomRegisterSubjectRouter" />
        <eip:exchange-target service="caxchange:c3DRegisterSubjectRouter" />
      </eip:recipients>
      <eip:targetServiceIdentifiers>
               <value>psc</value>
               <value>caAERS</value>
               <value>LabViewer</value>
               <value>C3D</value>
      </eip:targetServiceIdentifiers>
  </eip:caxchange-static-recipient-list>
</beans>

To remove C3D as a recipient for the REGISTER_SUBJECT message, the administrator needs to comment out the C3D as a recipient in this file. The edited xml will be as follows:

<beans xmlns:eip="http://servicemix.apache.org/eip/1.0" 
      xmlns:caxchange="http://nci.nih.gov/caXchange">
   <eip:caxchange-static-recipient-list service="caxchange:registerSubjectRecipients"   endpoint="registerSubjectRecipientsEndpoint">
     <eip:recipients>
       <eip:exchange-target service="caxchange:pscRegisterSubjectRouter" />
       <eip:exchange-target service="caxchange:caaersRegisterSubjectRouter" />
       <eip:exchange-target service="caxchange:ctomRegisterSubjectRouter" />
       <!--<eip:exchange-target service="caxchange:c3DRegisterSubjectRouter" /> -->
     </eip:recipients>
     <eip:targetServiceIdentifiers>
              <value>psc</value>
              <value>caAERS</value>
              <value>LabViewer</value>
           <!--   <value>C3D</value> -->
     </eip:targetServiceIdentifiers>
 </eip:caxchange-static-recipient-list>
</beans>

Once these changes have been done, they are needed to be pushed to servicemix. This is done using the following steps:

ant update-routing-configuration

Configure a New Service Payload Type

caXchange can be configured to route new service payloads type. This involves modifying the caXchange routing configuration to add routing for the new service. This routing is defined in the externalized routing configuration files. caXchange-installation-dir is the directory where caXchange software has been downloaded and installed. The following steps are required for configuring a new service within caXchange.

     <eip:routing-rule>
       <eip:predicate>
         <eip:xpath-predicate xpath="count(/caxchange:caXchangeRequestMessage/caxchange:metadata[caxchange:messageType='NEW_SERVICE_TYPE']) = 1" namespaceContext="#nsContext"/>
       </eip:predicate>
       <eip:target>
         <eip:exchange-target service="caxchange:newServiceType" />
       </eip:target>
     </eip:routing-rule>

 <beans xmlns:eip="http://servicemix.apache.org/eip/1.0"
      xmlns:caxchange="http://nci.nih.gov/caXchange">
    <eip:caxchange-static-recipient-list service="caxchange:newServiceType" endpoint="newnewServiceEndpoint">
       <eip:recipients>
         <eip:exchange-target service="caxchange:callNewServicePipeline" />
       </eip:recipients>     
     </eip:caxchange-static-recipient-list>
  </beans>

Verify Routing

Verify routing is a feature provided within caXchange which verifies that any routing configuration changes are consistent across all configuration files. It verifies that all the service names used are defined in either the bean service unit or the EIP service unit. To execute verify routing script browse to the folder where caXchange is installed and run the following command:

ant verify-routing

This will copy the routing configuration files from SERVICEMIX_HOME/conf/caXchangeConf and verify the routing configuration. If no routing errors are found, the script will return without errors and spool a message saying no routing errors. If any errors are found, the script will spool the service name that is not configured and the component where it is referred.

Payload Validation

Removing a Service Payload for Validation

This requires editing the SERVICEMIX-HOME/conf/caxchange.properties file to modify the property "messageTypes.for.validation". This property should be modified to remove the service payload type not being validated.

#Message types eligible for payload validation
messageTypes.for.validation=STUDY_CREATION,REGISTER_SUBJECT,SCHEDULE_MODIFICATION,LAB_BASED_AE,LOAD_LAB_TO_CDMS

Configuring a Service Payload for Validation

Configuring a service payload to be validated in caXchange requires following steps.