# Installation and Upgrade Guide

# QuickStart Overview

This chapter provides brief, high level instructions for the installation and upgrade of Collaboration, and is intended to quickly guide experienced administrators through the installation or upgrade procedure.

This chapter is divided into two major sections:

- Installation. This section covers installing the Collaboration components, scripting the database, and starting and verifying the installation. The organization of this section maps directly to detailed instructions in Installation.
- Upgrade. This section covers upgrading Collaboration to the latest version. The organization of this section maps directly to detailed instructions in Upgrade.

## Installation

This section describes how to install Collaboration.

### Creating the Collaboration Database

Refer to the section that applies to your database vendor.

- Creating and Configuring the Collaboration Database on Microsoft SQL Server.
- Configuring an Oracle Database for Collaboration.

Note: | The Collaboration and portal databases must be the same vendor and version, and must reside on the same physical machine.

For more information on these steps, see Creating the Collaboration Database.

#### Creating and Configuring the Collaboration Database on Microsoft SQL Server

To create the Collaboration database and database user:

1. Configure the SQL Server instance to use SQL Server and Windows Authentication mode.
2. Create the Collaboration database with the Collaboration database name you designated when you completed the worksheets provided in the Installation and Configuration Worksheets for BEA AquaLogic Collaboration 4.5.
3. Create the Collaboration database user login with the login name and password you designated when you completed the worksheet provided in the Installation and Configuration Worksheets for BEA AquaLogic Collaboration 4.5.

1. Configure the Collaboration database user login to use SQL Server Authentication.
2. Set the Collaboration database user login’s default database to the Collaboration database.
3. Grant the Collaboration database user login the db_owner role for the Collaboration database.

4. Create a schema for the Collaboration database with the schema name you designated when you completed the worksheets provided in the Installation and Configuration Worksheets for BEA AquaLogic Collaboration 4.5. This name must be the same as the Collaboration database user name.
5. In the Collaboration database user’s login properties, navigate to the User Mapping page.
6. Set the default schema of the Collaboration database user login to the new schema of the same name.

#### Configuring an Oracle Database for Collaboration

The Collaboration schema is added to the existing Oracle database that contains the portal schema. 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.

### Installing the Collaboration Components

To install Collaboration, launch the Collaboration installer as a local administrator:

- On a UNIX/Linux host the installer is ALICollaboration_v4-5_mp1.
- On a Windows host the installer is ALICollaboration_v4-5.exe_mp1.

The installer prompts you for specific information about your system and configuration. For more information, see Installing the Collaboration Components.

Note: | The Notification Service that was previously included in the Collaboration installer has been replaced by the AquaLogic Notification Service. Collaboration uses the AquaLogic Notification Service to send emails from Collaboration to end users and to serve RSS feeds if that feature has been enabled. The AquaLogic Notification Service is included with the AquaLogic Interaction installer and is a required component of AquaLogic Interaction. The AquaLogic Notification Service should be installed and configured as part of your AquaLogic Interaction installation.

### Deploying Collaboration on WebLogic Server

The Collaboration installer automatically deploys Collaboration on the Embedded Servlet Engine. You can choose to deploy Collaboration on WebLogic Server instead of the Embedded Servlet Engine.

Important: If you choose to deploy Collaboration on WebLogic Server, you should disable the BEA ALI Collaboration Service that is installed by the installer on Windows machines. You will not be able to start and stop Collaboration using Configuration Manager.

To deploy Collaboration on WebLogic Server:

1. Identify a domain on which to deploy Collaboration, or create a new domain. Refer to your WebLogic Server documentation for details on creating a new domain.
2. In the portal’s config.xml file for the domain on which the portal is deployed, add the following line at the end of the <security-configuration> tag:

`<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>`

This disables basic authentication for the domain, and is necessary for WebDAV to work properly.

Note: | The <enforce-valid-basic-auth-credentials> line must be the last entry in the <security-configuration> tag for the setting to take effect.

3. Add the following text to the setDomainEnv.sh or setDomainEnv.cmd file of the domain:

- On UNIX/Linux, add the following to setDomainEnv.sh. You must add this as one line of code:

    JAVA_OPTIONS="${SAVE_JAVA_OPTIONS}

    -Dbid.application.config=PT_HOME/settings

    -Dplumtree.application.config=PT_HOME/settings

    -Dbid.application=PT_HOME/ptcollab/4.5

    -Dplumtree.application=PT_HOME

- On Windows, add the following to setDomainEnv.cmd. You must add this as one line of code:

    set JAVA_OPTIONS=%SAVE_JAVA_OPTIONS%

    -Dbid.application.config=PT_HOME\settings

    -Dplumtree.application.config=PT_HOME\settings

    -Dbid.application=PT_HOME\ptcollab\4.5

    -Dplumtree.application=PT_HOME

Enter the actual value of PT_HOME in the file. PT_HOME is the same value as install_dir. By default, the value for install_dir is /opt/bea/alui on UNIX/Linux and C:\bea\alui on Windows.

4. Start the WebLogic domain.
5. Deploy collab.ear, located in the following location, as an application in the WebLogic domain:

UNIX/Linux: install_dir/ptcollab/4.5/webapp/

Windows: install_dir\ptcollab\4.5\webapp\

Refer to your WebLogic Server documentation for details on how to deploy an application.

6. Update the Collaboration application settings in Configuration Manager to reflect the correct port numbers for the Collaboration UI:

1. Launch Configuration Manager.
2. In the application list on the left, under Collaboration, click Application Settings.
3. Update the values of HTTP port and HTTPS port with the port numbers used by the Collaboration domain in WebLogic.
4. Click SAVE.

7. Update the URL of the Collaboration remote server:

1. Log in to the portal.
2. Navigate to the Collaboration remote server object in the Admin Object Directory and open it for editing.
3. On the Main Settings page, set the port number of the Base URL to the port number of the Collaboration application in WebLogic.
4. Click Finish.

8. In Collaboration’s config.xml file for the domain on which Collaboration is deployed, add the following line at the end of the <security-configuration> tag:

    <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

This disables basic authentication for the domain, and is necessary for WebDAV and Collaboration RSS Feeds to work properly.

Note: | The <enforce-valid-basic-auth-credentials> line must be the last entry in the <security-configuration> tag for the setting to take effect.

### Scripting the Collaboration and Portal Databases

Refer to the section that is appropriate to your database vendor.

#### Scripting the Databases on Microsoft SQL Server

This section describes how to create and configure the Collaboration database schema, as well as configure the portal database schema for Collaboration.

To script the databases on Microsoft SQL Server:

1. Run the following database scripts as the Collaboration database user on the Collaboration database:

- install_dir\ptcollab\4.5\sql\mssql\collaboration-server-create-tables.sql
- install_dir\
  ptcollab\4.5\sql\mssql\collaboration-server-data.sql
- install_dir\ptcollab\4.5\sql\mssql\collaboration-server-portal-role-grant.sql

2. Run the following database scripts as the `sa` user on the portal database:

- install_dir\ptcollab\4.5\sql\mssql\portal-collaboration-server-data.sql
- install_dir\ptcollab\4.5\sql\mssql\portal-collaboration-server-role-grant.sql

For more information on these steps, see Scripting the Databases on Microsoft SQL Server.

#### Scripting the Database on Oracle

This section describes how to create and configure the Collaboration database schema, as well as configure the portal database schema for Collaboration.

To script the database on Oracle:

1. Locate the versions of the database scripts appropriate to your database platform:

- install_dir/ptcollab/4.5/sql/oracle/unix/
- install_dir\ptcollab\4.5\sql\oracle\windows\

2. Run the following database scripts as the system user on the portal database:

- collaboration-server-create-table-space.sql
- collaboration-server-create-user.sql

3. Run the following database scripts as the Collaboration database user on the portal database:

- collaboration-server-create-tables.sql
- collaboration-server-data.sql
- collaboration-server-portal-role-grant.sql

4. Run the following database scripts as the portal database user on the portal database:

- portal-collaboration-server-data.sql
- portal-collaboration-server-role-grant.sql

For more information on these steps, see Scripting the Database on Oracle.

#### Scripting a DB2 Database on UNIX for Collaboration

This topic describes how to script a DB2 database for use with Collaboration.

Note: | For this release, BEA does not support scripting a DB2 database on Windows for Collaboration.

Before scripting a DB2 database for Collaboration:

- Ensure that the data for the AquaLogic Interaction and ALUI Directory applications is stored in distinct schemas on the same DB2 database.
- Create a distinct schema for the Collaboration database on the same DB2 database that contains the schemas for the AquaLogic Interaction and ALUI Directory applications.
- Have your DB2 database administrator examine and, if necessary, customize the SQL scripts before you use them. Each SQL file contains comments that describe the customizations that might be necessary.

Note: | The Collaboration SQL scripts for DB2 include hard-coded schema names for the Collaboration and portal databases. In the collaboration-server-create-tables.sql, collaboration-server-data.sql, and collaboration-server-portal-role-grant.sql scripts, the hard-coded name for the Collaboration schema is COLLAB. If you updated the Collaboration schema name to anything other than COLLAB, you must navigate to Configuration Manager, Collaboration application, Collaboration Database component, and update the Schema Name setting to match the updated Collaboration schema name.

Note: | In the portal-collaboration-server-role-grant.sql and portal-collaboration-server-data.sql scripts, the hard-coded name for the portal schema is ALUI. If you updated the portal schema name to anything other than ALUI, you must update these scripts to match the updated portal schema name. Additionally, you must navigate to Configuration Manager, Collaboration application, Collaboration Settings component, and update the Linked database alias setting to match the updated portal schema name. Make sure to add .dbo. to the end of the portal schema name. For example, if the portal schema name is alidbuser, the value that you type into the Linked database alias setting should be alidbuser.dbo.

Use the DB2 command line processor to run the SQL scripts against your DB2 database. Comments in the header of each SQL file contain recommended syntax for the DB2 command line processor.

To script a DB2 database for Collaboration:

1. Copy SQL scripts from the Collaboration installation directory to your DB2 database server.

The scripts are located in: install_dir/ptcollab/4.5/sql/db2

2. As a user with administrative privileges, run the these scripts in the following order:

1. create_collab_schema.sql
2. create_collab_tablespace_unix.sql
3. grant_collab_user.sql
4. collaboration-server-create-tables.sql
5. collaboration-server-data.sql
6. collaboration-server-portal-role-grant.sql
7. portal-collaboration-server-role-grant.sql
8. portal-collaboration-server-data.sql

For more information on these steps, see Scripting a DB2 Database on UNIX for Collaboration.

### Configuring the Image Service for Notification Emails

If your Image Service is deployed on IIS, you must register two new MIME types in IIS so that email notifications will work properly.

To configure IIS for notification emails:

1. In IIS, register the extensions “.nst” and “.inc” with a MIME type of “text/plain”.
2. Restart the World Wide Web Publishing Service so that the changes take effect.

For more information on these steps, see Starting and Verifying the Installation.

### Importing the Collaboration Migration Package

Import the collaboration.pte file, which is located in the following location on the Collaboration host machine:

- UNIX/Linux: install_dir/ptcollab/4.5/serverpackages/
- Windows: install_dir\ptcollab\4.5\serverpackages\

For details, see Importing the Collaboration Migration Package.

### Starting and Verifying the Installation

This section describes how to start Collaboration and verify operation.

1. Verify that the following AquaLogic Interaction services are started:

- Search Server
- API Service
- Automation Service
- Document Repository Service
- LDAP Directory Service
- Notification Service

2. Start the Search Service used by Collaboration.
3. Start Collaboration. If Collaboration is deployed on WebLogic Server, start the domain on which Collaboration is deployed.
4. To verify that Collaboration is functioning correctly, access and analyze the Collaboration Diagnostics page:

    http://<mycollabserver>:<mycollabport>/collab/admin/diagnostic

For more information on these steps, see Starting and Verifying the Installation.

## Upgrade

This section provides brief, high level instructions for the process of upgrading previous versions of Collaboration to the latest version.

### Upgrade Paths

This section provides the paths that are available to upgrade to Collaboration 4.5 MP1.

Note: | All upgrade paths are between two systems of the same operating system brand, but not necessarily the same operating system version. Check current hardware and software requirements and make any required upgrades to operating system or database software prior to proceeding with the portal upgrade.

Upgrade Path | Upgrade References
--- | ---
Collaboration 4.2, 4.2 MP1 to Collaboration 4.5 MP1 Collaboration 4.1, 4.1 SP1, 4.1 SP2 to Collaboration 4.5 MP1 Collaboration 4.0.2 to Collaboration 4.5 MP1 | Follow the procedure described in Upgrading from Collaboration 4.x to Collaboration 4.5 MP1.
Collaboration Server 3.x to Collaboration 4.5 MP1 | Follow the procedure described in Upgrading from Collaboration Server 3.x to Collaboration 4.5 MP1.
Collaboration Server 2.x to Collaboration 4.5 MP1 | Follow the procedure described in Upgrading from Collaboration Server 2.x to Collaboration 4.5 MP1.

### Upgrading from Collaboration 4.x to Collaboration 4.5 MP1

This section describes how to upgrade from Collaboration 4.x to Collaboration 4.5 MP1.

To upgrade from Collaboration 4.x to Collaboration 4.5 MP1:

1. Stop Collaboration.
2. If you have an existing Notification Service from your previous installation of Collaboration, disable or uninstall it. The Notification Service that was previously included in the Collaboration installer has been replaced by the AquaLogic Notification Service and is included in the AquaLogic Interaction installer. The AquaLogic Notification Service is a required component of AquaLogic Interaction and should be installed and configured as part of your AquaLogic Interaction installation.
3. Stop the Search Server, Automation Service, and Document Repository Service.
4. Back up the portal database, Collaboration database, and Document Repository.
5. Clear the Embedded Servlet Engine’s work directory.
6. Install the Collaboration components. For details on launching the installer and completing its screens, see Launching the Collaboration Installer.
7. (Optional) Deploy Collaboration on WebLogic Server. By default, Collaboration is deployed on the Embedded Servlet Engine. You only need to perform this step if you want to deploy Collaboration on WebLogic Server instead of the Embedded Servlet Engine. For details, see Deploying Collaboration on WebLogic Server.
8. Upgrade the portal and Collaboration databases. For details, see Upgrading the Portal and Collaboration Databases.
9. Import the Collaboration migration package. For details, see Importing the Collaboration Migration Package.
10. (Image Service on IIS only) Configure the Image Service to work with the AquaLogic Notification Service. For details, see Configuring the Image Service for Notification Emails.
11. Start Collaboration and verify operation. For details, see Starting and Verifying the Installation.
12. Rebuild the Collaboration search collection. For details, see Rebuilding the Collaboration Search Collection.

For more information on these steps, see Upgrading from Collaboration 4.x to Collaboration 4.5 MP1.

### Upgrading from Collaboration Server 3.x to Collaboration 4.5 MP1

This section describes how to upgrade from Collaboration Server 3.x to Collaboration 4.5 MP1.

If you are currently running Collaboration Server 3.x, you must first upgrade to Collaboration Server 4.0.2. Refer to the Installation Guide for Plumtree Collaboration Server 4.0.2 for information on this upgrade path.

After upgrading to Collaboration Server 4.0.2, upgrade to Collaboration 4.5 MP1 according to the instructions described in Upgrading from Collaboration 4.x to Collaboration 4.5 MP1.

### Upgrading from Collaboration Server 2.x to Collaboration 4.5 MP1

This section describes how to upgrade from Collaboration Server 2.x to Collaboration 4.5 MP1.

If you are currently running Collaboration Server version 2.x, you must first upgrade to Collaboration Server 3.0.2. Refer to the Installation Guide for Plumtree Collaboration Server 3.0 for information on this upgrade path.

After upgrading to Collaboration Server 3.0.2, you must upgrade to Collaboration Server 4.0.2. Refer to the Installation Guide for Plumtree Collaboration Server 4.0.2 for information on this upgrade path.

After upgrading to Collaboration Server 4.0.2, upgrade to Collaboration 4.5 MP1 according to the instructions described in Upgrading from Collaboration 4.x to Collaboration 4.5 MP1.

Note: | UNIX/Linux users - Collaboration 3.x was released only on Windows. The installation of 3.0.2 must take place on a Windows machine.

### Upgrading the Portal and Collaboration Databases

This section describes how to upgrade the portal and Collaboration databases.

Note: | If you are upgrading Oracle from 10.1.x to 10.2.x or SQL Server from 2000 to 2005, you should perform the Oracle or SQL Server upgrade before upgrading the databases.

Run the upgrade scripts appropriate to your database platform. The upgrade scripts are located in:

Microsoft SQL Server:

- install_dir\ptcollab\4.5\sql\mssql

Oracle:

- install_dir\ptcollab\sql\oracle\unix
- install_dir\ptcollab\4.5\sql\oracle \windows

Follow the database upgrade instructions appropriate to your previous version of Collaboration, as described in the following table:

Upgrade Path | Database Upgrade Instructions
--- | ---
4.2 MP1 to 4.5 MP1 4.2 to 4.5 MP1 | As the Collaboration database user, run the following script on the Collaboration database: collaboration-server-4.2.0-to-4.5.0-upgrade.sql As the portal database user, run the following script on the portal database: portal-collaboration-server-upgrade.sql
4.1 SP2 to 4.5 MP1 | As the Collaboration database user, run the following scripts in sequential order on the Collaboration database: collaboration-server-4.1.2-to-4.2.0-upgrade.sql collaboration-server-4.2.0-to-4.5.0-upgrade.sql As the portal database user, run the following script on the portal database: portal-collaboration-server-upgrade.sql
4.1 SP1 to 4.5 MP1 4.1 to 4.5 MP1 | As the Collaboration database user, run the following scripts in sequential order on the Collaboration database: collaboration-server-4.1.1-to-4.1.2-upgrade.sql collaboration-server-4.1.2-to-4.2.0-upgrade.sql collaboration-server-4.2.0-to-4.5.0-upgrade.sql As the portal database user, run the following script on the portal database: portal-collaboration-server-upgrade.sql
4.0.2 to 4.5 MP1 | As the Collaboration database user, run the following scripts in sequential order on the Collaboration database: collaboration-server-4.0.2-to-4.1.1-upgrade.sql collaboration-server-4.1.1-to-4.1.2-upgrade.sql collaboration-server-4.1.2-to-4.2.0-upgrade.sql collaboration-server-4.2.0-to-4.5.0-upgrade.sql As the portal database user, run the following script on the portal database: portal-collaboration-server-upgrade.sql

For more information on upgrading the portal and Collaboration databases, see Upgrading the Portal and Collaboration Databases.