# Installation and Upgrade Guide

# Installing Collaboration on UNIX or Linux

This chapter provides information on Collaboration and summarizes the procedures required to perform new product installations on a Unix or Linux machine.

This chapter is divided into the following sections:

- Pre-installation Procedures
- Running the Installer
- Post-installation Procedures

For more information on recommended configurations based on the size of your implementation, see the Deployment Guide for BEA AquaLogic User Interaction (Plumtree Application Suite).

## Pre-Installation Procedures

Before running the Collaboration installer, you must:

1. Compile the necessary configuration and installation information by completing the installation worksheet provided in Installation Worksheet.
2. Verify that your portal is installed and configured correctly.

Verify that your portal is working correctly including the Search Service, Image Service, Document Repository Service, API Service, Automation Service, and ALI Logging Utilities. For more information on installing and configuring the portal, see the Installation and Upgrade Guide for BEA Aqualogic Interaction (UNIX and Linux) (Plumtree Foundation).

3. Verify that the portal database and its components are installed and configured correctly.
4. Create the Collaboration database. Note that Collaboration for Linux only supports Oracle.

Before installing Collaboration ensure that you have a correctly installed and configured Oracle portal database. Collaboration does not use its own Oracle database. Instead, the Collaboration schema are added to the existing Oracle database that contains the portal schema.

Before proceeding with the Collaboration installation, confirm that the open_cursors parameter in the Oracle initialization file is set to greater than 1000. This parameter should have been set correctly during the portal database set up.

## Running the Installer

To install Collaboration, you must have administrator rights on the machine where you are running the installer. Additionally, you must have administrator privileges for the portal database.

To run the Collaboration installer:

1. Enter the following command lines to locate the installer:

    cd <installer_file_path>

    ./ALICollaboration_v4-1

2. Complete the installation wizard pages as described in the following table.

   Table 6-1 Collaboration Installer Screens
   Installer Screen | Description
   --- | ---
   Introduction | Provides general information on using the installer. Click Next to begin the installation.
   License Agreement | To install Collaboration, you must read and accept the license agreement. After you have read the license agreement and selected the appropriate button, click Next.
   Choose Components | You can choose the Collaboration components you want to install. Each component can be installed on a separate server depending on your configuration. For information on recommended configuration, see Recommended Configuration. The Collaboration components are: Collaboration: This is the core Collaboration application. It is required. Notification: This optional component sends e-mails from Collaboration to end-users. By subscribing to objects within Collaboration, you can receive notification when the object is updated.
   Note: | The Notification component is not required for users to employ the E-mail a Project and Groupware Integration features.
   Image Service Files: This required component installs the necessary images, styles, user interface controls, Java applets, and on-line help for Collaboration. Install Image Service Files on the same machine on which the portal's Image Service is installed. Document Repository (Portal 5.0.x only): This component is required for Collaboration 4.1 to operate with Plumtree Corporate Portal 5.0.x. It is recommended that this component be installed on the computer that is hosting the existing 5.0.x Document Repository Service. Installing this component does not overwrite the existing Document Repository Service. After you have chosen the components you want to install, click Next.
   Installation Folder | The default installation folder is /opt/plumtree Click Next to accept the default.
   AquaLogic Interaction Collaboration - Application Port | Select http or https. The default port number is 11930. Click Next to accept the default.
   Portal Settings: Collaboration URL | Collaboration URL: The URL the Portal and Notification Service use to communicate with Collaboration. You must specify a fully-qualified domain name, including the port number and path. After you have entered the required information, click Next.
   Portal Settings: AquaLogic User Interaction Database | Collaboration uses the following information to establish connections with the portal database: AquaLogic User Interaction Database Host: This is the hostname of the portal database server. You must specify a fully-qualified domain name. AquaLogic User Interaction Database Port: The port the portal database uses to handle requests. AquaLogic User Interaction Database SID: The Oracle Service ID of the portal database. AquaLogic User Interaction Database Schema User: The user_id who is granted ownership of the portal schema and its tables. After you have entered the required information, click Next.
   Portal Settings: Authentication ID | To establish secure communication between the portal and Collaboration, you must specify an authentication ID and password: Authentication ID: The portal uses the authentication ID to access resources on the machine on which Collaboration is installed. Authentication Password: This is the authentication password. This field cannot be left blank. After you have entered the required information, click Next.
   Portal Settings: Document Repository Service | The Document Repository Service is a portal component that manages storage and retrieval of documents for Collaboration and other AquaLogic Interaction products. Document Repository Service Host: The hostname of the Document Repository Service. You must specify a fully-qualified domain name. Document Repository Service Port: The port the Document Repository Service uses to handle requests. If you chose the Document Repository (Portal 5.0.x only) option in the Choose Components installer screen, the default port is 8030. If you are running Collaboration on the 6.0 version of the portal, the default port is 8020. If you chose the Document Repository (Portal 5.0.x only) option and you do not want to use the 8030 default, make sure that the port you assign is different than 8020. After you have entered the required information, click Next.
   Portal Settings: Search | Search is a component of the portal that provides search functionality to the Document Repository Service and Collaboration. You must use the same hostname and port used by the portal. Search Host: The hostname of Search uses. You must specify a fully-qualified domain name. Search Port: The port Search uses to handle requests. The default value is 15244. After you have entered the required information, click Next.
   Image Service URL | Image Service URL: (This screen only appears if you chose to install the Image Service Files component) The URL of the Image Service. You must enter the full URL, including the domain name, port number, and path. The Notification Service uses this URL to communicate with the Image Service. After you have entered the required information, click Next.
   Portal Settings: Image Service Files | Image Service Directory: This is the directory where the Image Service files are installed. For example: /opt/plumtree/ptimages
   Note: | Before clicking Next, ensure that security for the Image Service directory is appropriately configured to allow for installation of the Image Service files.
   After you have entered the required information, click Next.
   Collaboration: Database Connection | Enter the following configuration information for the Collaboration database: Collaboration Schema User: The user ID who is granted ownership of the Collaboration schema and its tables. Collaboration Schema Password: The password of the Collaboration database schema user. After you have entered the required information, click Next.
   Collaboration: Advanced Features | You can install the following optional advanced features of Collaboration: Bulk Upload: This feature allows you to simultaneously upload multiple files and folders to Collaboration. This feature uses a Java applet installed on the client's computer which requires the Java Runtime Environment. To use this feature, certain client browser security settings must be made. See Configuring Advanced Collaboration Features for more information on client changes that must be made after installing Collaboration. WebDAV Service: The Web-based Document Authoring and Versioning (WebDAV) protocol is an extension to the HTTP protocol that allows easier document management. WebDAV must be installed to use the WebEdit and Map a Web Folder. For more information on these features see Configuring Advanced Collaboration Features.
   Collaboration: Advanced Features | Microsoft Exchange Integration: Windows Only; Do Not Select. Lotus Notes Integration: This option allows users to synchronize personal Collaboration calendars with their Lotus notes calendar. If you install this feature, you must perform several configuration steps after Collaboration is installed. For more information, see Configuring Advanced Collaboration Features. No Groupware Integration: Choose this option if you do not want to allow groupware integration.
   Note: | Groupware Integration is not required for users to employ the E-mail a Project feature. For more details on the E-mail a Project feature, see Administrator Guide for BEA AquaLogic Interaction Collaboration.
   Note: | If you do not choose to install groupware integration now, you must re-run the installer to install it later.
   After you have chosen the features you want to install, click Next.
   Notification: Connection Settings | Notification Host: The hostname of the Notification Service. Notification Port: The port where the Notification Service listens for requests. The default value is 9887. After you have entered the required information, click Next.
   Notification: e-mail Server Settings | To configure the Notification Service, enter the following: Mail Server Host: The location of the mail server for your site. Notification E-mail Address: This is the e-mail address used to send Collaboration notifications. Notification E-mail Name: This is the notification e-mail name that appears in the "From" field of notification e-mails.
   Note: | The e-mail address specified here will receive a copy of every e-mail notification sent. You may want to create an e-mail account to receive these notifications.
   SMTP Server Supports E-mail Relaying: Select this check box if your SMTP server supports e-mail relaying. SMTP Domain List: If your SMTP server does not support relaying, clear the SMTP Server supports e-mail relaying check box, and list valid e-mail domains in a comma-delimited list. After you have entered the required information, click Next.
   Collaboration: e-mail a Project | Specify whether or not you want to enable e-mailing a project. If you enable this feature, you must supply an e-mail domain and port for Collaboration to use to receive e-mail messages. The default port number is 25.
   Note: | For details on the capabilities of and instructions on how to configure the E-mail a Project feature, see Administrator Guide for BEA AquaLogic Interaction Collaboration.
   Pre-Installation Summary | This screen provides a summary of the installation information you have provided in the installer. After you have reviewed this information and are satisfied with the values you have provided, click Install.
   Install Complete | This screen appears after the installer has finished. After you have made a selection, click Finish.

## Post-Installation Procedures

The following steps should be performed immediately after the installer has completed. This section describes the procedures you must perform after running the Collaboration installer. You should perform the procedures outlined in each section in the order listed below:

1. Configuring the Portal and Collaboration Databases.
2. Restart the portal.
3. Importing the Collaboration Migration Package.
4. Starting the Notification Service.
5. Configuring Optional Collaboration Features.
6. Starting Collaboration.

### Configuring the Portal and Collaboration Databases

After you have completed the installer you must configure the portal and Collaboration databases.

This section describes how to configure the Collaboration database using Oracle. The following scripts add and configure the Collaboration schema in the portal database:

Table 6-2 Scripts for Configuring the Portal and Collaboration Databases
Script Function | Name | Database / ID
--- | --- | ---
Create Collaboration database schema | collaboration-server-create-table-space.sql collaboration-server-create-user.sql | portal database / Collaboration database ID
Configure Collaboration database schema | collaboration-server-create-tables.sql collaboration-server-data.sql collaboration-server-portal-role-grant.sql | portal database / Collaboration database ID
Configure portal database schema | portal-collaboration-server-role-grant.sql portal-collaboration-server-data.sql | portal database / portal database user ID

These SQL scripts create the Collaboration schema and add specific tables and information. They also grant SELECT access to the Collaboration schema owner.

Note: | If you are running the scripts on a local machine you do not need to include the command line @<Oracle_SID> however you do need to ensure that the environment variables are set.

The following procedures describe how to run these scripts:

1. Perform the following on the portal database server:

- Create the directory $ORACLE_HOME/ptcollabscripts.
- Copy the Collaboration database scripts from the installation location into this folder.

2. Update any required database patches.
3. If you are installing in a production environment, set up the database to archive log files. Using the default configuration, you must shut down the Oracle database to get a read-consistent backup.
4. If you want, you can change the names and locations of the COLLAB_TEMP and COLLAB_DATA tablespaces by modifying the
   collaboration-server-create-table-space.sql script. We recommend having at least two SCSI hard drives. Put each tablespace on its own hard drive.
5. By default, the Collaboration schema user name is collab, and the password is collab. You can change the schema user name and password by modifying the
   collaboration-server-create-user.sql script.
6. Use sql*plus to execute collaboration-server-create-table-space.sql. This script creates the Collaboration schema default tablespaces.

You must log in as the system user to execute this script. Substitute the correct system password in the following command:

    sqlplus system/<system_pwd>@<ORACLE_SID>
    @collaboration-server-create-table-space.sql

7. As the system user, execute collaboration-server-create-user.sql. This script creates the user and password you specified during Collaboration installation. The script prompts you to enter the password again; be sure to enter the correct password.

    sqlplus system/<system_pwd>@<ORACLE_SID>
    @collaboration-server-create-user.sql

8. As the Collaboration user, execute collaboration-server-create-tables.sql to create Collaboration tables. Substitute the correct Oracle user name and password; this should be the schema user name and password created by collaboration_server_create_user.sql

    sqlplus <collab_user_name>/<user_pwd>@<ORACLE_SID>
    @collaboration-server-create-tables.sql

Note: | This script stops immediately on a SQL server error. If this happens, resolve the problem and rerun the script.

1. As the Collaboration user, execute collaboration-server-data.sql to populate the Collaboration tables. Substitute the correct Oracle user name and password; this should be the schema user name and password created by collaboration_server_create_user.sql:

    sqlplus <collab_user_name>/<user_pwd>@<ORACLE_SID>
    @collaboration-server-data.sql

2. As the Collaboration user, execute collaboration-server-portal-role-grant.sql. This script grants the portal schema user SELECT access to required tables in the Collaboration schema. Substitute the correct Oracle user name and password; this should be the schema user name and password created by collaboration_server_create_user.sql. The script prompts for other required passwords.

    sqlplus <collab_user_name>/<user_pwd>@<ORACLE_SID>
    @collaboration-server-portal-role-grant.sql

3. As the portal user, execute portal-collaboration-server-role-grant.sql. This script grants the Collaboration schema user SELECT access to required tables in the portal schema. Substitute the correct portal database user name and password in the following command. The script prompts for other required passwords.

    sqlplus <portal_user_name>/<portal_pwd>@<ORACLE_SID>
    @portal-collaboration-server-role-grant.sql

4. As the portal user, execute portal-collaboration-server-data.sql. This script creates views in the portal schema that allow it to see Collaboration tables. Substitute the correct portal database user name and password in the command:

    sqlplus <portal_user_name>/<portal_pwd>@<ORACLE_SID>
    @portal-collaboration-server-data.sql

### Importing the Collaboration Migration Package

The following steps outline how to use the Migration Utility to import the Collaboration Migration Package into Collaboration:

1. Log on to the portal as a user who has administrative rights.
2. Click the Administration tab.
3. In the Select Utility drop-down, select Migration-Import and accept the defaults.
4. In the Migration Package area, go to File Path.
5. Click Browse to find the .pte file appropriate to your portal version:

- Collaboration5.pte
- Collaboration6.pte

6. Click Open.
7. Click Load Package.
8. Click Finish.
9. A pop up dialog displays asking if you want to import. Click Yes.
10. The Collaboration folder is viewable in the Admin Objects Directory.
11. Click the Collaboration folder to check for the following objects:

- Data Source
- Group
- Portlet
- Remote Server
- User
- Web Service

### Starting the Notification Service

To start the Notification Service you must first log in as the Portal Administrator, then access the start scripts which are located in:

plumtree/ptnotification/4.1/bin/notificationserverd.sh

To run the script use notificationserverd.sh start and to stop the script use notificationserver.sh stop

This script executes the Notification Service in the background and can be incorporated into the Linux environment startup scripts if necessary.

Check the notification.log file for errors. This file is found in the /plumtree/ptnotification/4.1/settings/logs directory.

### Configuring Optional Collaboration Features

The following optional features require additional configuration and setup after you have run the installer:

- Personal Projects
- Bulk Upload
- Groupware Integration
- Publish to Knowledge Directory

For more information on configuring these features, see Configuring Advanced Collaboration Features.

### Starting Collaboration

To start Collaboration:

1. Run the ptcollaborationserverd.sh script with the start argument. This script is found in the /plumtree/ptcollab/4.1/bin directory.
2. To verify that Collaboration is functioning correctly, access the Collaboration Diagnostics page using the following URL:

    http://<your-collab-URL>:<your-collab-port>/collab/admin/diagnostic

For more information on using the Collaboration Diagnostics page, see Troubleshooting

3. Check the collaboration.log file for any errors. This file is found in the /plumtree/ptcollab/4.1/settings/logs directory.

## Collaboration Logging

For AquaLogic Interaction 6.x, you have the option to set up Collaboration Logging. This includes setting up Logging Utilities and configuring ALI Logging Spy (formerly "Plumtree Logging Spy") to display Collaboration messages. For more information on setting up Collaboration Logging, refer to the Administrator Guide for BEA AquaLogic Interaction Collaboration.