# Installation and Upgrade Guide

# Upgrade

This chapter describes the process of upgrading versions of Plumtree Corporate Portal and Plumtree Foundation to the latest version of the portal (AquaLogic Interaction).

## Upgrade Paths

This section provides the paths that are available to upgrade your portal to AquaLogic Interaction 6.1.

Note: | When upgrading to an AquaLogic Interaction 6.1 maintenance pack, it is not necessary to upgrade to AquaLogic Interaction 6.1 first. Unless otherwise noted, follow the procedure for upgrading from your current version to AquaLogic Interaction 6.1, but use the installer for the maintenance pack instead of the installer for AquaLogic Interaction 6.1.

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
AquaLogic Interaction 6.1 to an AquaLogic Interaction 6.1 Maintenance Pack | Follow the procedures in Applying an AquaLogic Interaction 6.1 Maintenance Pack
Foundation 6.0 to AquaLogic Interaction 6.1 | Follow the procedures in Upgrading from Foundation 6.0 to AquaLogic Interaction 6.1.
Corporate Portal 5.0.4J to AquaLogic Interaction 6.1 (Unix) | Follow the procedures in Upgrading from Corporate Portal 5.0.x to AquaLogic Interaction 6.1.
Corporate Portal 5.0.2, 5.0.3, 5.0.4 to AquaLogic Interaction 6.1 (Windows) | Follow the procedures in Upgrading from Corporate Portal 5.0.x to AquaLogic Interaction 6.1.

## Applying an AquaLogic Interaction 6.1 Maintenance Pack

To apply an AquaLogic Interaction 6.1 Maintenance Pack:

1. Important: Stop the Search service on all Search nodes before starting the upgrade. Do not restart any upgraded Search services until all nodes have been upgraded.
2. Install the AquaLogic Interaction Administrative Portal and Search components. For details on launching the installer and completing its screens, see Installing the AquaLogic Interaction Components.
3. Complete the AquaLogic Interaction component installation. For details, see Completing the AquaLogic Interaction Component Upgrade.

Note: | When upgrading from AquaLogic Interaction 6.1 to AquaLogic Interaction 6.1 MP1, you must replace the license.bea file. When prompted by the installer, choose to overwrite the existing license file if only AquaLogic Interaction is installed on the machine. If other BEA products are installed on the machine, choose to merge the Evaluation license with the existing license. For more details on licensing and combining license files, see Licensing.

## Upgrading from Foundation 6.0 to AquaLogic Interaction 6.1

To upgrade from Foundation 6.0 to AquaLogic Interaction 6.1:

1. Install the Administrative Portal and Search components. For details on launching the installer and completing its screens, see Installing the AquaLogic Interaction Components.
2. Run the 6.0 to 6.1.sql database script. For details, see Running the 6.0 to 6.1 SQL Database Upgrade Script.
3. Import the Search Cluster Manager migration package. For details, see Importing the Search Cluster Manager Migration Package.
4. Rebuild the Search Index. For details, see Rebuilding the Search Index.
5. Complete the AquaLogic Interaction component installation. For details, see Completing the AquaLogic Interaction Component Upgrade

### Running the 6.0 to 6.1 SQL Database Upgrade Script

To run the 6.0 to 6.1 SQL database upgrade script:

1. Back up the portal database.
2. Locate the upgrade6.0to6.1_<your_database_type>.sql script in the installation folder of the version 6.1 Administrative Portal server. By default, the script is located in <PT_HOME>\ptportal\6.1\sql\<your_database_type>.
3. Run the database upgrade script.

## Upgrading from Corporate Portal 5.0.x to AquaLogic Interaction 6.1

To upgrade from Corporate Portal 5.0.x to AquaLogic Interaction 6.1:

1. Install the Administrative Portal and Search components. For details on launching the installer and completing its screens, see Installing the AquaLogic Interaction Components.
2. Upgrade the portal database from Corporate Portal 5.0.x to Foundation 6.0 specifications. For details, see Upgrading the Database from Corporate Portal 5.0.x to Foundation 6.0 Specifications.
3. Run the 6.0 to 6.1.sql database script. For details, see Running the 6.0 to 6.1 SQL Database Upgrade Script.
4. Start the AquaLogic Interaction 6.1 Administrative Portal and verify the installation. For details, see Starting and Verifying the Installation.
5. (Optional) Resolve missing mandatory portlets. Perform this step only if you upgraded your portal from 5.0.x to 6.1 and mandatory portlets are not appearing properly in your 6.1 portal. For details, see Resolving Missing Mandatory Portlets.
6. Import the Search Cluster Manager migration package. For details, see Importing the Search Cluster Manager Migration Package.
7. Rebuild the Search Index. For details, see Rebuilding the Search Index.
8. Complete the AquaLogic Interaction component installation. For details, see Completing the AquaLogic Interaction Component Upgrade

### Upgrading the Database from Corporate Portal 5.0.x to Foundation 6.0 Specifications

This section describes the procedure for upgrading the portal database to AquaLogic Interaction 6.x specifications. The basic steps described in this section are:

1. Upgrade database software, if necessary.
2. Run the duplicate names database script.
3. Run the database upgrade tool.
4. Export data from the database.
5. Create a new database schema.
6. Import data to the database.
7. Update stored procedures and system-specific parameters.

#### Upgrading Database Software

If necessary, have your DBA upgrade database software to the currently supported version. For current database version requirements, see Software Requirements.

Note: | When upgrading to Oracle 9i or 10g, ensure that the new database character set is UTF8 and the new database national character set is AL16UTF16.

#### Running the Duplicate Names Database Script

In earlier versions of the portal, document names were case sensitive; a document name in all caps would be considered a different document than one with the same name in all lower case. In AquaLogic Interaction 6.x, document names are case insensitive, which means document names considered unique in earlier versions of the portal may now be considered duplicates.

If there is a concern that your Oracle database contains duplicate document names, BEA provides two scripts that you scan run before you run the Database Upgrade Tool. It is important to note that running these scripts is optional and that they support Oracle databases only. The scripts are located in <PT_HOME>/ptportal/6.1/sql.

- find_dup_doc_names_oracle.sql – This script finds duplicate document names in the database and creates new names for the duplicates by appending the string “(dup x)”, where “x” is the number of the duplicate. The new document names are stored in a new table (PTCARDS_NEWNAMES), so the original PTCARDS table is left untouched. The script can only handle document names that are duplicated five or fewer times.
- fix_dup_doc_names_oracle.sql – This script updates the duplicate document names in the PTCARDS table with the new card names stored in PTCARDS_NEWNAMES. It then drops the PTCARDS_NEWNAMES table. You must run find_dup_doc_names_oracle.sql before running this script.

#### Running the Database Upgrade Tool

The command line Database Upgrade Tool is used to upgrade a portal database to 6.x specifications.

To successfully perform an upgrade, you must supply data needed by the upgrade process (such as the location of various files). You supply this data through a text file. This text file is the upgradedata.properties file and is created in:

    [PT_HOME]/settings/portal/upgradedata.properties

The first time you run the Database Upgrade Tool, it creates the upgradedata.properties text file that contains descriptions of the required data. You edit the upgradedata.properties file in a text editor. After entering all necessary parameters, you run the Database Upgrade Tool a second time. The Database Upgrade Tool reads the parameters from the upgradedata.properties file, and performs the upgrade.

Note: | Your system must be properly configured to run the portal in order to use this application, as it relies on your portal configuration to know how to connect to the database and complete the upgrade.

1. Run the Database Upgrade Tool from $PORTAL_HOME/bin/dbupgradetool.sh.
2. This script takes two parameters:

- Admin User Name - type the name of the Administrator user that you created when you installed your 5.0.x portal (not another user in the Administrators group). The default name is “Administrator,” but you may have changed the name for security purposes after installation.

Note: | The Admin User Name is case sensitive.

- Password - type the password for the Administrator user. If this user has an empty password, do not type anything.

3. Provide values for the parameters in the upgradedata.properties file. You may not see all of these parameters because you see only the parameters associated with the types of objects in your portal.

Note: | File paths are in the format /directory/subdir/filename.xxx and cannot have a space at the end of the path nor quotes around the path name. A correct example would be: `File_Path = /opt/plumtree/ptedir/yourfilename.pte`

- LOG_FILE_PATH - Enter the path to the log file to be created by the upgrade. The upgrade writes status information to this file.
- SQL_FILE_PATH - Enter the path to the SQL file to be created by the upgrade. The upgrade creates a SQL script in this file that corresponds to the work done by the upgrade. This parameter is optional. Leave it blank to indicate that no SQL file should be generated.

Note: | The Database Upgrade Tool modifies data regardless of whether it is also generating an SQL Script.

4. Run the Database Upgrade Tool again to begin upgrading the database. The upgrade can run for a few seconds or a few hours, depending on the size of your database. If the Database Upgrade Tool encounters errors or data inconsistencies, it does not stop. Instead it logs the errors to the file specified in Step 3.
5. When the database upgrade completes, you are notified of the status. If the upgrade completed successfully (without errors), skip to Step 7.

Note: | If PTGROUPMEMBERSHIP has a materialized view you may see an error regarding inability to drop a view. This can be ignored.

6. If there were errors, you should examine the log file, identify solutions, restore the database to its previous state, fix the problems, and re-run the Database Upgrade Tool.

Note: | You must restore the database to its original 5.0.x state before you re-run the Database Upgrade Tool. The Database Upgrade Tool modifies the database to determine all possible errors. Therefore, even if the upgrade did not complete successfully, the database is at least partially upgraded to 6.1 specifications.

7. If you changed the database credentials, change them back to use the AquaLogic Interaction database user.

#### Exporting Data from the Database

Export the data from the portal schemas using tools provided by your database vendor.

#### Creating the New Database Schema

To create the new database schema, follow the instructions appropriate for your database type.

##### Creating the New Database Schema on an Oracle Database

1. Drop and recreate the portal schema owner.
2. Grant connect, resource, and dba rights on the portal tablespaces to the newly created portal schema owner.
3. Run the create_tables_oracle.sql script.

On a Unix installation the script is located at:

    <PT_HOME>/ptportal/6.1/sql/oracle_unix9.2

or

    <PT_HOME>/ptportal/6.1/sql/oracle_unix10

On a Windows installation and Oracle 9i, the script is located at:

    <PT_HOME>\ptportal\6.1\sql\oracle_nt9.2

or

    <PT_HOME>\ptportal\6.1\sql\oracle_nt10

##### Creating the New Database Schema on a SQLServer Database

1. Create a new database. This database can be your new portal database, or it can serve as a temporary store for portal data.
2. Script the new database with the portal schema. To do this, run

    <PT_HOME>\ptportal\6.1\sql\mssql\create_tables_mssql.sql

#### Importing Data to the Database

Using tools provided by your database vendor, import the data you exported into the newly scripted database.

Note: | On SQLServer databases, the portal data will now be in a new database. You must either modify connection information for all servers that use the portal database, or move the portal database back to the original database by dropping the original, recreating the original using the table script in Creating the New Database Schema on a SQLServer Database, and then exporting the data from the temporary database to the original database.

#### Updating Stored Procedures and System-Specific Parameters

To update stored procedures and system-specific parameters in the new portal database, you must run two sql scripts. The scripts are located in <PT_HOME>/ptportal/6.1/sql under the directory appropriate to your operating system and database version.

On an Oracle database, run:

- stored_procs_oracle.sql
- postinst_oracle.sql

On a SQLServer database, run:

- stored_procs_mssql.sql
- postinst_mssql.sql

### Resolving Missing Mandatory Portlets

If you upgraded your portal from 5.0.x to 6.1 and find that mandatory portlets are not appearing properly in your 6.1 portal, run the following database script on your 6.1 database to resolve the issue. If you upgraded from 5.0.x to 6.0 and mandatory portlets are appearing properly in your 6.0 portal, skip this step:

    UPDATE PTPages SET TopicPos=0 WHERE TopicPos!=0 AND ObjectId IN (SELECT ObjectId FROM PTPages p, (SELECT FolderId, MIN(TopicPos) AS MinTopicPos FROM PTPages WHERE FolderId<0 GROUP BY FolderId) a WHERE p.FolderId=a.FolderId AND p.TopicPos=a.MinTopicPos)

## Rebuilding the Search Index

To rebuild the search index:

1. Log in to the portal as the administrator.
2. Navigate to Administration.
3. From the Select Utility drop-down menu, select Search Service Manager.
4. Schedule the next search repair to occur either in the past or in the very near future.
5. Click Finish.
6. Navigate to the administrative folder that contains the search update agents that are registered with the Automation Service.
7. Schedule one of the search update agents to run in the past or in the very near future
8. Click Finish.

The next search update agent that runs will rebuild the search index.

Note: | We do not recommend clicking Run Once from the administrative folder or selecting Run Once from the Job Editor. If you click Run Once from the administrative folder, the job log will be lost after the operation completes, which may inhibit troubleshooting if the rebuild fails. If you select Run Once from within the Job Editor, the Search Update Agent will not be scheduled to run again in the future.

## Completing the AquaLogic Interaction Component Upgrade

Now that you have installed version 6.1 of the Administrative Portal, scripted the database and performed other necessary upgrade steps, you can complete the AquaLogic Interaction component upgrade. You do this by installing all other AquaLogic Interaction 6.1 components on their respective hosts. On each host, first stop any existing Corporate Portal 5.0.x, Foundation 6.0 or AquaLogic 6.1 services. Run the AquaLogic Interaction 6.1 installer on each host and select Custom Install to select the AquaLogic Interaction 6.1 components that you want to install. For detailed instructions on launching the installer and completing its screens, see Installing the AquaLogic Interaction Components.

If your portal deployment includes one or more AquaLogic User Interaction products (such as Collaboration, Publisher, Analytics, and so on) upgrade those products now. Refer to each product’s associated installation and upgrade guide for instructions on upgrading those products.