# Installation and Upgrade Guide

# Installing Collaboration on Windows

This chapter guides you through the Collaboration installer on Windows. To install Collaboration, you must have administration rights on the machine where you are running the installer. Additionally, you must have administrator privileges for the portal database.

If you have previously run the installer and a properties file has been created, you may run the installer silently based on the values in the file. Refer to Installing Collaboration on Multiple Systems - Silent Installation for information on how to run a silent install.

Refer to Configuring Advanced Collaboration Features for instructions on how to make the Collaboration Office Tools Add-In installer available to end users.

## Pre-Installation Procedures

If you plan to install Collaboration software on a Linux machine, skip to Installing Collaboration on UNIX or Linux.

Before running the Collaboration installer on a Windows machine, you must:

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

Verify that your portal is working correctly including the Search Service, Image Service, and Document Repository Service. For more information on installing and configuring AquaLogic Interaction, see the Installation and Upgrade Guide for BEA AquaLogic Interaction (Windows) (Plumtree Foundation).Verify that the portal database and its components are installed and configured correctly

3. Create the Collaboration database.

We recommend that you create the Collaboration database before running the installer.

The Collaboration and portal databases must be the same vendor and version and they must reside on the same physical machine.

4. If you are going to integrate Collaboration with Microsoft Exchange, you must perform the following:

1. Ensure the IIS server is running before you run the Exchange Remote API installer. Refer to Configuring IIS for information on IIS configuration.
2. Install the Microsoft .NET 1.1 Framework.

This must be downloaded from the Microsoft Web site (http://www.microsoft.com/).

3. Install Microsoft Web Services Enhancement 2.0.

This must be downloaded from the Microsoft Web site (http://www.microsoft.com/).

The .NET Framework and the Web Services Enhancement must be installed on the same machine running the groupware integration for Collaboration.

### Creating a SQL Server Database

Before performing these steps, ensure that you have a SQL Server portal database that is working correctly. To complete these steps, you must be the database administrator for the portal database.

1. Ensure that the SQL Server Service Manager is running.
2. Open the SQL Server Enterprise Manager.
3. Create the Collaboration database:

1. Select the database server where you want to create the Collaboration database.
2. Right-click the database folder.
3. Choose New Database.
4. Enter a database name.

Note: | Note: Collaboration does not support case-sensitive database names.

1. Click OK.

1. Add a login ID and password for the Collaboration database:

1. Open the Security folder.
2. Right-click the Logins folder and choose New Login.
3. Specify a user ID for the new user. This is the same user ID you will specify during the Collaboration installation.
4. In the Authentication area of this dialog box, choose SQL Server Authentication and type a password. You must specify this password during Collaboration installation.
5. In the Defaults area, set the default database to be the Collaboration database just created.

2. Click the Database Access tab. On this page, grant the current user access to and ownership of the Collaboration database.

1. In the Specify which databases can be accessed by this login box, select the Collaboration database.
2. In the Database roles for `<Collaboration database>' box, select db_owner (public is already selected) and click OK.

3. Close the Enterprise Manager.

### Creating an Oracle Database

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.

1. To run the Collaboration installer, locate and double-click the installation file:

ALICollaboration_v4-1.exe

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

   Table 4-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. From the dropdown list you may choose All (Portal 6.0) or All (Portal 5.0.x) depending on which version of the portal you are running in conjunction with Collaboration 4.1. 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. The Notification component is not required for users to employ the E-mail a Project and Groupware Integration features. However the E-mail a Project feature is less useful if the Notification Service is not running. Image Service Files: This required component installs the necessary images, styles, and user interface controls, Java applets, and online 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 C:\Program Files\plumtree. After you have entered the required information or accepted the default, click Next.
   AquaLogic Interaction Collaboration - Application Port | Select either http or https and enter the port number. After you have entered the required information, click Next.
   Portal Settings: Collaboration URL | Collaboration URL: The URL the portal and Notification Service used 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 makes connections and retrieves information from the portal database. Select the appropriate vendor for your portal and Collaboration database, then click Next.
   Portal Settings: AquaLogic User Interaction Database (SQL Server) | Collaboration uses the following information to establish connections with the portal database: AquaLogic User Interaction Database Host Computer: 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 Name: The name of the database configured to work with your portal. AquaLogic User Interaction Database Login: The user name of the portal database owner. After you have entered the required information, click Next.
   Portal Settings: AquaLogic User Interaction Database (Oracle) | 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 Windows service name 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 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 | The Search Service is a component of the portal that provides search functionality to the portal and Collaboration. You must use the same hostname and port used by the portal. Search Host Computer: The hostname of Search Service. You must specify a fully-qualified domain name. Search Port: The port that the Search Service 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.
   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 (SQL Server) | Enter the following configuration information for the Collaboration database: Collaboration Database Name: The database name for the Collaboration database. Collaboration Database Login: The Collaboration database owner ID. Collaboration Database Password: The Collaboration database password. After you have entered the required information, click Next.
   Collaboration: Database Connection (Oracle) | Enter the following configuration information for the Collaboration database: Collaboration Schema User: The user ID who is granted ownership of the portal 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 features. For more information on these features see Configuring Advanced Collaboration Features. Microsoft Exchange Integration: This option allows users to synchronize personal Collaboration calendars with their Microsoft Exchange calendar to use Groupware Integration features. For more information, see Configuring Groupware Integration. If you choose this option, the installer checks that the following have been installed: Microsoft Internet Information Server (IIS) Microsoft .NET Framework Microsoft Web Server Enhancement (WSE) These components must be installed before running the installer. For more information, see Introduction
   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.
   | We recommend that you install the groupware remote API on the same physical machine where Collaboration is installed. Lotus Notes Integration: This option allows users to synchronize personal Collaboration calendars with their Lotus notes calendar to use Groupware Integration features. If you install this feature, you must perform several configuration steps after Collaboration is installed. For more information, see Configuring Groupware Integration. No Groupware Integration: Choose this option if you do not want to allow groupware integration.
   Note: | If you do not choose to install groupware integration now, you must re-run the installer to install it later.
   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.
   After you have chosen the features you want to install, click Next.
   Collaboration: Exchange Remote API URL | The URL that the Exchange Remote API uses to communicate with Collaboration. The default value is: http://[machine]/GroupwareService/GroupwareService.asmx After you have entered the required information or accepted the default, 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. After you have entered the required information, click Next.
   Note: | For 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. You must reboot the system before continuing to the post-installation procedures. After you have made a selection, click Finish.

You should perform the following immediately after the installer has completed:

1. Restart the computer.
2. Proceed to the next section to continue installing Collaboration

## Post-Installation Procedures

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.

#### Configuring MS SQL Server

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

Table 4-2 Scripts for Creating and Configuring a Collaboration SQL Server Database
Script Function | Name | Database / ID
--- | --- | ---
Configure Collaboration database schema | collaboration-server-create-tables.sql collaboration-server-data.sql collaboration-server-portal-role-grant.sql | Collaboration database / Collaboration database ID
Configure portal database schema | portal-collaboration-server-role-grant.sql portal-collaboration-server-role-grant-5.0.4.sql portal-collaboration-server-data.sql | portal database / portal database user ID

The scripts are located in:

    <PT_Home>\plumtree\ptcollab\4.1\sql\6.0\MSSQLServer

For Plumtree Corporate Portal 5.0.x only, the scripts are located in:

    <PT_Home>\plumtree\ptcollab\4.1\sql\5.0\MSSQLServer

These scripts create the Collaboration-specific tables and information in the Collaboration database. They also grant rights to access necessary tables in the portal database to the Collaboration database owner.

The following procedures show you how to run these scripts:

1. Run Query Analyzer.
2. Connect to SQL Server and log in using the Collaboration Server database user ID specified when the database was created.
3. Select the Collaboration Server database.
4. Open and run collaboration-server-create-tables.sql.

This script attempts to drop tables from the database before adding new ones.

5. Open and run collaboration-server-data.sql.

This script adds configuration information for the Collaboration database.

6. Open and run collaboration-server-portal-role-grant.sql.

This script grants the portal database user SELECT access to the Collaboration tables.

7. Connect to the portal database as the portal database user.
8. Open and run portal-collaboration-server-role-grant.sql.

For Plumtree Corporate Portal 5.0.x only, open and run portal-collaboration-server-role-grant-5.0.4.sql.

This script grants the Collaboration database user SELECT access to the portal database tables.

9. Open and run portal-collaboration-server-data.sql.

This script adds configuration information for the portal database.

10. Close Query Analyzer.

#### Configuring Oracle

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 4-3 Scripts for Creating and Configuring a Collaboration Oracle Database
Script Function | Name | Database / ID
--- | --- | ---
Create Collaboration database schema | collaboration-server-create-table-space.sql collaboration-server-create-user.sql | Collaboration database / Collaboration database ID
Configure Collaboration database schema | collaboration-server-create-tables.sql collaboration-server-data.sql collaboration-server-portal-role-grant.sql | Collaboration database / Collaboration database ID
Configure portal database schema | portal-collaboration-server-role-grant.sql portal-collaboration-server-role-grant-5.0.4.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 Server user, execute collaboration-server-create-tables.sql to create Collaboration tables. Substitute the correct Oracle user name and password; this is the user name and password you specified during Collaboration installation:

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

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

9. As the Collaboration user, execute collaboration-server-data.sql to populate the Collaboration tables. Substitute the correct Oracle user name and password; this is the user name and password you specified during Collaboration installation:

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

10. 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 is the user name and password you specified during Collaboration Server installation. The script prompts for other required passwords.

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

11. 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

For Plumtree Corporate Portal 5.0.x only, execute portal-collaboration-server-role-grant-5.0.4.sql.

12. 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

For Plumtree Foundation 6.0, import the Collaboration using the Migration Wizard as follows.

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: Collaboration6.pte.
6. Click Open.
7. Click Load Package.
8. If you are upgrading from an earlier version of Collaboration and have changed the port number that Collaboration runs on, check Overwrite Remote Servers.
9. Click Finish.
10. A pop up dialog displays asking if you want to import. Click Yes.
11. The Collaboration folder is viewable in the Admin Objects Directory.
12. Click the Collaboration folder to check for the following objects:

- Content Source
- Group
- Portlet
- Property
- Remote Server
- Web Service

For Plumtree Corporate Portal 5.0.x, import the Collaboration using the Migration Wizard as follows.

1. Start | Programs | Plumtree | Migration Wizard.
2. Enter the portal administrator password.
3. Select Portal Server Object Migration, then click Next.
4. Select Import, then click Next.
5. Select Overwrite existing Remote Server objects, then click Next.
6. Browse to `ptcollab\4.1\serverpackages\5.0`.
7. Select the Collaboration5.pte file.
8. Click Open.
9. Click Next and then Next again.
10. Click Migrate.

## 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 the Notification Service

To start the Notification service:

1. Start | Programs | Administrative Tools | Services
2. Locate and then right-click the Notification service and select Start.

## Starting Collaboration

To start Collaboration:

1. Reboot the computer where Collaboration is installed if you have not done so since running the installer.
2. Start the Windows service named BEA AquaLogic Interaction Collaboration.
3. 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.

## Starting Document Repository Service (5.0.x only)

To start the Document Repository service:

1. Start | Programs | Administrative Tools | Services
2. Locate and then right-click the Plumtree Collaboration Document Repository service and select Start.

## 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.