Upgrade Rational ClearQuest Web Server features: considerations and best practices

When you upgrade, or move, to a new WebSphere® Application Server profile, Rational® ClearQuest® Web Server, Full Text Search, and Reporting features are installed in the same WebSphere Application Server profile. All of these features must be upgraded, or moved together.

Before you upgrade or apply fix packs, review important information that affects the upgrade, configuration, and administration processes for Rational ClearQuest Web Server features.

Important: , If the Rational ClearQuest environment includes the Full Text Search and Report Launcher features, you must install WebSphere Application Server 32-bit edition. These features are not supported on WebSphere Application Server 64-bit edition. For more information, see Technote 1512059.

Use these links or scroll down the page for information about upgrading Rational ClearQuest Web Server features.

Rational ClearQuest Web Server

Table 1 provides an overview of the upgrade paths for the Rational ClearQuest Web Server.

The Table 1 topic provides an overview of the upgrade process for the Rational ClearQuest Web Server by the version you are upgrading from.

Table 1. Rational ClearQuest Web Server upgrade instructions by version
Installed version	Upgrade overview
ClearQuest version 7.x	In Rational ClearQuest, the WebSphere Application Server is installed separately from the Rational ClearQuest Web Server. The separate installation enables the WebSphere Application Server and IBM® HTTP Server environments to be managed independently of the Rational ClearQuest environment. If you are upgrading from V7.x, use IBM Installation Manager to install a supported version of WebSphere Application Server and IBM HTTP Server before you upgrade ClearQuest resources. See Prepare the WebSphere Application Server environment for web servers. Restriction: Because the ClearQuest V7.x application server architecture and installation process is different than it is in V8.x, the rollback operation is not supported after you upgrade from V7.x to V8.x. To restore the previous version, remove the new version and reinstall the previous version of the product.
ClearQuest version 8.0 with WebSphere Application Server 7.0	Upgrade the WebSphere Application Server to version 8.0 or 8.5. Upgrade ClearQuest to version 8.0.1. Restriction: The rollback operation is not supported if you upgrade from a ClearQuest V8.0 deployment on WebSphere Application Server 7.0 to a ClearQuest V8.0.0.x deployment on WebSphere Application Server 8.0. To restore the previous version, remove the new version and reinstall the previous version of the product.
ClearQuest version 8.0.0.x, with WebSphere Application Server version 8.0	ClearQuest V8.0.1 is supported on WebSphere Application Server V8.0 and V8.5.0.x. When you upgrade, you have these options: Option 1: Upgrade Rational ClearQuest to version 8.0.1 without upgrading the WebSphere Application Server. Option 2: Upgrade WebSphere Application Server to version 8.5.0.x, and then upgrade Rational ClearQuest to version 8.0.1.

For more detailed upgrade instructions including a compatibility matrix for supported installation, upgrade, and rollback paths, see technote 1634465 on the IBM Support website.

Important information about upgrading the Rational ClearQuest Web Server

Before you upgrade, review the Rational ClearQuest Release Notes® to learn about any known problems or limitations that are related to installation and upgrade.
Be careful when overriding default port number assignments during the upgrade process. During upgrade or installation operations, default port numbers are assigned to ensure that each port is unique. For example, if the default port for the WebSphere Application Server version 7.x profile AppSrv01 is port 9080, when you upgrade to version 8.0.x, the default port that is assigned to AppSrv01 is 9081. If you override the default port number, you risk introducing port number conflicts.
You cannot modify profile security settings during the Rational ClearQuest upgrade process. Use the WebSphere Application Server console to manage WebSphere Application Server administrative security.
Restart IBM Installation Manager between successive operations if you are not prompted to restart the system.
After a Rational ClearQuest Web Server upgrade, notify ClearQuest Web client users to clear their browser cache and delete cookies and temporary internet files. Clearing the browser prevents Rational ClearQuest problems that result from Rational ClearQuest client/server communication that is based on cached data instead of current data from the Rational ClearQuest Web Server.

Rational ClearQuest Report Server and reporting features

If you are upgrading from Rational ClearQuest V7.1.x to Rational ClearQuest version 8.x or later, learn about changes in the installation and upgrade process for Rational ClearQuest Web environments that include reporting features.

Rational ClearQuest version introduces a new reporting strategy that might affect your upgrade process. If your upgrade plan includes updating or adding support for Rational ClearQuest reporting, see Reporting on data sources for information about these changes.

Important: If the Rational ClearQuest environment includes the Report Launcher features, you must install WebSphere Application Server 32-bit edition. These features are not supported on WebSphere Application Server 64-bit edition. For more information, see Technote 1512059.

The Report Server for Crystal Reports and Report Launcher for Web Server features are installed in the same WebSphere Application Server application server profile as the Rational ClearQuest Web server. As a result, you must upgrade reporting feature at the same time that when you upgrade the Web Server.

Full-Text Search Server

Before you upgrade or apply fix packs to a Rational ClearQuest Web environment with full-text search, back up the full-text search configuration and data. Depending on how the full-text search feature was installed initially, other tasks might be required when you upgrade your environment.

You must back up Full-Text Search Server configuration and data before you upgrade WebSphere Application Server and the Rational ClearQuest Web Server.

The topic Table 2 provides an overview of the upgrade process for different upgrade paths. For more information, see Scenarios for setting up and configuring full-text search.

Important: If the Rational ClearQuest environment includes the Full Text Search, you must install WebSphere Application Server 32-bit edition. These features are not supported on WebSphere Application Server 64-bit edition. For more information, see IBM Support article #1512059.

Table 2. Full Text Search upgrade instructions by version
Rational ClearQuest version	Upgrade overview
Rational ClearQuest version 7.1.x to 8.0.x	If you downloaded and installed Rational ClearQuest 7.1.x Full Text Search Administrator tool from the DCF download website, remove or rename the full-text search script cqtsadmin.pl and the CQTsAdmin directory in the ClearQuest 7.1.x home directory before you upgrade this feature. For standard installations, you can locate these full-text search resources in the following default directory: Windows: C:\Program Files\IBM\RationalSDLC\ClearQuest\ UNIX/Linux:/opt/ibm/RationalSDLC/clearquest/ After you rename the directory, proceed with the ClearQuest upgrade process. If the Full Text Search Administrator tool was not used for the original Full-Text Search deployment, see Technote # 1515900 on the IBMSupport website for information about upgrading the Full Text Search server.
Rational ClearQuest version 8.0.0.1 or later to 8.0.x	During the Rational ClearQuest version 8.x installation process, the software for the Full Text Search Server feature is copied into the WebSphere Application Server profile for Rational ClearQuest Web Server. To preserve this information when you upgrade, remove the feature, or apply fix packs, use the Rational ClearQuest cqtsadmin.pl script to back up the full-text search configuration and data. After you upgrade, use the cqtsadmin.pl script to restore the data. For instructions, see ../../com.ibm.rational.clearquest.webadmin.doc/topics/t_fts_scn_upg_multidb_prof.htm Note: Before you run the script, run this command to verify that the CQFTS_AppServer_HOME environment variable is set to the directory where the WebSphere Application Server is installed. On Windows: `set CQFTS_AppServer_HOME=C:\Program Files\IBM\WebSphere\AppServer` On Linux: `setenv CQFTS_AppServer_HOME /opt/IBM/WebSphere/AppServer` If the value is not set, an error message like the following is displayed when you run the script: `Cannot determine WebSphere's AppServer home`.

Rational ClearQuest Web server environments with OSLC integrations

Review information about configuration tasks that might be required after you upgrade Rational ClearQuest Web server environments that support OSLC integrations.

Configuring Rational ClearQuest as a load-balanced OSLC provider

In Rational ClearQuest 8.0.1.1 and later, you can configure a load-balanced Rational ClearQuest environment as an OSLC provider. For details, see the following information:

Enabling smart card authentication

To include features to enable smart card authentication for OSLC integrations when you upgrade a Rational ClearQuest Web deployment that is configured for smart card authentication, you must update and redeploy the Rational ClearQuest Web deployment descriptor file, web.xml. Complete this task after you upgrade the Rational ClearQuest Web server. For instructions, see Configuring client certificate authentication for Web

Resolving OSLC linking errors that are caused by missing oslc:version and oslc:domain parameters

If you upgrade Rational ClearQuest Web Server from version 8.0.0.3 or earlier, you must specify values for the oslc:version and oslc:domain parameters that were added in Rational ClearQuest version 8.0.0.4. After the upgrade, the new parameters do not have valid values. As a result, you might encounter JavaScript issues when you attempt to access links in Rational ClearQuest records to external OSLC resources. To resolve this problem, update the OSLC configuration after you upgrade to a new Rational ClearQuest Web Server version. See Updating link configuration for OSLC integrations.

Update LDAP configuration to TLS 1.2 for Rational ClearQuest user authentication

Update the Rational ClearQuest version and LDAP configuration to add support for National Institute of Standards and Technology (NIST) Special Publication (SP) 800-131A guidelines.

Rational ClearQuest version 8.0.1.1 adds support for the NIST SP 800-131A guidelines that provide information about managing cryptographic keys. The guidelines cover the following areas:

Key management procedures.
How to use cryptographic algorithms.
Algorithms to use and their minimum strengths.
Key lengths for secure communications.

To comply with these guidelines, you must use LDAP with Transport Layer Security 1.2 protocol (TLS 1.2) for authenticating Rational ClearQuest users. This configuration requires updating the LDAP server and the Rational ClearQuest LDAP configuration to support TLS 1.2. For details, see technote 1646724.