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 Rational ClearQuest Web Server upgrade instructions by version 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
  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 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® introduces a 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.

The Report Launcher 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 the 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 Full Text Search upgrade instructions by version 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 IBM®Support 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.html
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.