Upgrade ClearQuest Web Server features: considerations and best practices

When you upgrade, or move, to a new WebSphere® Application Server profile, 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 ClearQuest Web Server features.
Important: , If the 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 ClearQuest Web Server features.

ClearQuest Web Server

Table 1 provides an overview of the upgrade paths for the ClearQuest Web Server.
The Table 1 topic provides an overview of the upgrade process for the ClearQuest Web Server by the version you are upgrading from.
Table 1. ClearQuest Web Server upgrade instructions by version
Installed version Upgrade overview
ClearQuest version 7.x In ClearQuest V8.x, the WebSphere Application Server is installed separately from the ClearQuest Web Server, which is known as the ClearQuest CM server in ClearQuest V7.x. The separate installation enables the WebSphere Application Server and IBM® HTTP Server environments to be managed independently of the 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 ClearCase and ClearQuest 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
  1. Upgrade the WebSphere Application Server to version 8.0 or 8.5.
  2. 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 ClearQuest Web Server

  • Before you upgrade, review the 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 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 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 ClearQuest problems that result from ClearQuest client/server communication that is based on cached data instead of current data from the ClearQuest Web Server.

ClearQuest Report Server and reporting features

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

ClearQuest version 8.0 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 Rational ClearQuest data sources for information about these changes.

Important: , If the 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 ClearQuest Web Server features are installed in the same WebSphere Application Server application server profile as the ClearQuest Web server. As a result, you must upgrade reporting feature at the same time that when you upgrade the ClearQuest Web Server.

Full-Text Search Server

Before you upgrade or apply fix packs to a 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 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 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. ClearQuest Full Text Search upgrade instructions by version
ClearQuest version Upgrade overview
ClearQuest version 7.1.x to 8.0.x
  • If you downloaded and installed 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 IBM Support website for information about upgrading the Full Text Search server.
ClearQuest version 8.0.0.1 or later to 8.0.x During the ClearQuest version 8.x installation process, the software for the Full Text Search Server feature is copied into the WebSphere Application Server profile for ClearQuest Web Server. To preserve this information when you upgrade, remove the feature, or apply fix packs, use the 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 Upgrading or reinstalling ClearQuest in a full-text search deployment with multiple WebSphere profiles
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.

ClearQuest Web server environments with OSLC integrations

Review information about configuration tasks that might be required after you upgrade ClearQuest Web server environments that support OSLC integrations.
Configuring ClearQuest as a load-balanced OSLC provider
In ClearQuest 8.0.1.1 and later, you can configure a load-balanced 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 ClearQuest Web deployment that is configured for smart card authentication, you must update and redeploy the ClearQuest Web deployment descriptor file, web.xml. Complete this task after you upgrade the ClearQuest Web server. For instructions, see Configuring client certificate authentication for ClearQuest Web
Resolving OSLC linking errors that are caused by missing oslc:version and oslc:domain parameters
If you upgrade 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 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 ClearQuest records to external OSLC resources. To resolve this problem, update the OSLC configuration after you upgrade to a new ClearQuest Web Server version. See Updating link configuration for OSLC integrations.

Update LDAP configuration to TLS 1.2 for ClearQuest user authentication

Update the ClearQuest version and LDAP configuration to add support for National Institute of Standards and Technology (NIST) Special Publication (SP) 800-131A guidelines.
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 ClearQuest users. This configuration requires updating the LDAP server and the ClearQuest LDAP configuration to support TLS 1.2. For details, see technote 1646724.


Feedback