Upgrading or reinstalling ClearQuest in a full-text search deployment with multiple WebSphere Application Server profiles

IBM Installation Manager does not recognize WebSphere Application Server profiles for the full-text search feature. Consequently, when you upgrade or reinstall ClearQuest, you might loose these profiles (but not your full-text search configuration and index files). Therefore, before you upgrade or reinstall ClearQuest, use the cqtsadmin.pl tool to back up and delete all full-text search WebSphere Application Server profiles. Subsequently, after upgrading or reinstalling ClearQuest, restore these profiles by using the version of the cqtsadmin.pl tool that is included with your version of ClearQuest.

Before you begin
This scenario includes steps to perform before and after you upgrade or reinstall ClearQuest.

The scenario assumes that you are using the SAMPL database. In a production environment, the pre-upgrade or pre-installation steps, and the post-upgrade or post-reinstallation steps can take from a few minutes to a few hours to complete, depending on the number of full-text search WebSphere Application Server profiles in your deployment. For each profile, the steps should take a few minutes to complete.

Note that you can run the cqtsadmin.pl command against any full-text search instance on the server because the command is global to all full-text search deployments on the server. After the cqtsadmin.pl command completes against one full-text search deployment, the other deployments on the server are upgraded.

Important: To run the cqtsadmin.pl command, the CQFTS_AppServer_HOME environment variable must be set to the directory where WebSphere Application Server is installed. In certain scenarios, such as when you install ClearQuest into an existing WebSphere Application profile, or when you install the full-text search feature on a separate system that remotely accesses your ClearQuest Web servers, the CQFTS_AppServer_HOME environment variable is not set and an error similar to this displays:

Cannot determine WebSphere’s AppServer home. See the ClearQuest Full-Text Search Administrator Guide on how to set it via the CQFTS_AppServer_HOME environment variable.

To resolve the issue, set CQFTS_AppServer_HOME to the directory where you installed WebSphere Application Server. For example:

On Windows:
set CQFTS_AppServer_HOME=C:\Program Files\IBM\WebSphere\AppServer

On the UNIX system and Linux:
setenv CQFTS_AppServer_HOME /opt/IBM/WebSphere/AppServer

Procedure

1. Perform the following pre-upgrade or pre-install tasks.

a. Edit the cqtsadmin-TextSearch-SAMPL.xml configuration file. Change the value of the <deleteFtsWASProfiles> tag from this:
<newValue required=”no”><newValue>
to this:
<newValue required=”no”>true<newValue>

b. Run the cqtsadmin.pl command, with the prep_upgd_was_profiles option, in a command-prompt window. This command-line option creates a backup of all your full-text search WebSphere Application Server profile data on the server and then deletes the profiles. The backed up data is saved to the FTSBackupWASProfiles directory.

c. Edit the cqtsadmin-TextSearch-SAMPL.xml file again. Change the value of the <deleteFtsWASProfiles> tag from this:

<newValue required=”no”>true<newValue>
to this:
<newValue required=”no”><newValue>

The edit prevents you from accidentally rerunning this destructive command-line option.

2. Upgrade or reinstall ClearQuest.

3. Run the cqtsadmin.pl command in a command-prompt window to restore all previously deployed and backed up full-text search WebSphere Application Server profiles. There are two use-case scenarios:

• Scenario A: Restore all previously deployed and backed up full-text search WebSphere Application Server profiles to their original locations by using the restore_was_profiles command-line option:

cqperl cqtsadmin.pl --username admin --password secret --dbset TextSearch --userdb SAMPL --ftshome D:\CQ.Search --restore_was_profiles D:\FTSBackupWASProfiles

• Scenario B: Restore all previously deployed and backed up full-text search WebSphere Application Server profiles, and consolidate these profiles in one directory, by using the restore_was_profiles and fts_was_profile_home command-line options, respectively:

cqperl cqtsadmin.pl --username admin --password secret --dbset TextSearch --userdb SAMPL --ftshome D:\CQ.Search --restore_was_profiles D:\FTSBackupWASProfiles [--fts_was_profile_home D:\FTS.wasprofiles]