Impact of server rename on the Rational solution for Collaborative Lifecycle Management

Authors: LisaFrankel
Build basis: CLM products, version 4.0.1 and later

This page describes restrictions and limitations to evaluate before proceeding with the steps of renaming a server.

Impact of server rename on the Jazz Team Server

Review the Jazz™ Team Server-specific restrictions in this section associated with server rename.

Updating the teamserver.properties file

After performing a server rename operation, you might need to change the com.ibm.team.repository.web.helpuri property in the teamserver.properties file.

This property points to the help (clmhelp/index.jsp). If you are using a single server for the Jazz Team Server and applications, the help URI is a relative path and you do not need to update it unless the context root has changed. If you have a distributed deployment, you might need to adjust the help URI after the server rename operation is complete. Go to the teamserver.properties file for each application and update the value of this property. For details, see "Configuring the location of the help in a distributed environment" in the Jazz Team Server Installing book in the IBM Knowledge Center .

Application names remain the same after a server rename operation

The server rename operation does not rename the content of the application name. If an application name contains a URL or context root which has been renamed, you must manually edit the Application name property in the Registered Applications page. For details about editing the Registered Applications page, see "Managing registered applications" in the Jazz Team Server Administering book in the IBM Knowledge Center.

Impact of server rename on the Change and Configuration Management (CCM) application

Review the following CCM-specific restrictions associated with server rename.

Restart all clients

After the server administrator renames a server, you must restart any client that connects to that server. If you leave a client open during the server rename operation, it is possible that artifacts that include the previous server URL could be stored in the repository.

Use 4.0.1 or higher clients and build engines for production scenarios

For the pilot-to-production scenario and the production-to-production scenario, all user clients and build engines must be at version 4.0 or higher prior to the rename operation

Use staging workspace for test staging environment using production data scenario

For the preparing a test staging environment using production data scenario, always use a staging workspace for connecting to the staging server. Do not re-use an existing production workspace to connect to the staging server.

Check in changes into repository workspace before renaming server

If you use Rational Team Concert™ source control, check in all of your changes into your repository workspace before you rename the server. This ensures that your changes are safely stored in the repository and no changes are lost during the rename operation.

Deactivate non-Jazz Build Engine (JBE) build engines

Before performing a server rename operation, deactivate any build engines of type Build Forge, Build Agent, and Hudson/Jenkins to prevent builds from running on these external systems until you verify the engine connection details. After the rename operation, verify the connection details for these build engines. Verification is needed especially in the preparing a test staging environment using production data scenario to prevent builds in the staging environment from running on production build servers. Verification might be needed for other scenarios, depending on whether the target build servers are moving with the renamed CCM server. If the connection details are correct after the rename operation, you can reactivate the engines if appropriate for your scenario. Other options are to leave these build engines deactivated; change their connection details to something invalid (if this was not done in the mapping); or delete them.

Because the JBE process is run with a given RTC server URL, it does not have the same issue as non-JBE build engines. Production JBE instances will continue to run against the production CCM server. However, cross-contamination from the staging environment to the production environment might be possible if JBE instances are run against the staging environment, and build scripts or build properties refer to production servers. Review for such cases before you perform the server rename operation.

Update server URLs in work item templates

The server rename operation does not update the server URL in work item templates. For any work item templates that include the server URL in a field, you must change the URL to the one used by the renamed server.

Specify full URI of renamed server in full-text searches

To search for work items that contain the URI of the renamed server, you must specify the full URI; searching for URI fragments is not supported.

Query limitations

In a work item query, you cannot search for a renamed server URI in a small or medium string/html attribute.

Plan limitations

URLs within the Notes (wiki) tab of a plan do not get renamed as a result of the server rename operation.

Impact of server rename on the Quality Management (QM) application

The Quality Management application has specific restrictions that are related a server rename.

Command-line and Selenium adapters

After a server rename, update the Quality Management public URL in the adapter configuration file for the RQM Command-Line or Selenium adapter. Depending on the adapter version, the configuration file will be named either Config.ini or Config2.ini.

1. Stop the adapter process.
2. Open the Config.ini or Config2.ini file in a text editor.
3. Find the property named rqm.repository and modify the URL, port, and context to match the information for the renamed server.
4. Save the Config.ini or Config2.ini file and restart the adapter.

For more information, see "Setting up and starting the command line adapter" in the Rational Quality Manager Testing book in the IBM Knowledge Center.

Shared Resource Locations for automated test tools

After a server rename, update the shared resource locations used for automated test scripts at Manage Project Properties > Shared Resource Locations. For more information, see "Making shared test resources available" in the Rational Quality Manager Administering book in the IBM Knowledge Center.

Embedded links in text fields

After a server rename, embedded links in plain and rich text fields may require adjustment.

For example, test plans might feature descriptions that contain links in free-form text to another server. If a server is renamed, those links must be updated manually.

Broken links in documents pre-dating server rename

Links in emails, bookmark collections, external web pages, presentations, and documents that refer to a server will be broken when that server is renamed. Update these resources as is necessary.

Insight XML data configuration files

Insight customers use XML data configuration (.xdc) files provided with CLM as part of a Cognos Data Manager ETL solution. These files contain server names. After a server rename, these files must be downloaded again and reinstalled as documented in "Importing the XML data configuration file for live reporting" in the Rational Reporting Installing book in the IBM Knowledge Center.

Test tool adapter considerations

Reconfigure the RQM test tool adapters to use the new public URI for the Jazz Team Server. For details about the adapters, see "Rational test tools integration overview" in the Rational Quality Manager Integrating book in the IBM Knowledge Center. For specific details about configuring the adapter, see the documentation for the product providing the Rational and/or third-party test execution adapter.

For the AppScan test adapter, you will need to run the AppScan Adapter Setup and point to the new URL if the server name has changed. For details, see "Integrating with AppScan Enterprise" in the Rational Quality Manager Integrating book in the IBM Knowledge Center.

For defect submission from AppScan to Change and Configuration Management, log into AppScan Enterprise and update the Defect Tracking Configuration to point at the new URL.

Changes to advanced properties

For server rename, you can make changes to several of the advanced properties in the Quality Management (QM) application. For instructions to configure advanced properties, see “Configuring advanced properties” in the Jazz Team Server Administering book in the IBM Knowledge Center.

Remap embedded anchored links that are non-navigable

By default, embedded anchored links that are navigable in the rich text editor are remapped. However, embedded anchored links with XHTML-type or HTML 4 URI-type attributes are remapped only by configuring the MappingContentService property. This property is disabled by default for performance reasons. To find the property, on the Application Administration page, in the Advanced Property section, click RQM Process Component > com.ibm.rqm.common.service.internal.mapping.MappingContentService > Rewrite hidden links in XHTML.

Table 1 lists the embedded anchored links that can be remapped by using the MappingContentService property.

Table 1. Link types

Expand remapping beyond integration URLs

By default, only integration URLs, such as the servers for the Rational solution for Collaborative Lifecycle Management, Rational DOORS, and Rational RequisitePro, are generated in the mapping file. Other URLs are ignored to keep the generated mapping file at a manageable size.

To contribute URLs beyond integration URLs, configure the RQMServerRenameURLProviderService property. To find that property, on the Application Administration page, in the Advanced Property section, click RQM Process Component > com.ibm.rqm.oslc.service.internal.mapping.RQMServerRenameURLProviderService > Contribute navigable links to the generated mapping file. For more information about mapping files, see Preparing the mapping file.

Impact of server rename on integrated products

This topic describes the impact of a server rename on some of the products that integrate with the Rational® solution for Collaborative Lifecycle Management (CLM) applications, specifically Rational Reporting for Development Intelligence, Rational ClearQuest®, and Rational ClearCase®. Additional integrations are described in Impact of server rename on integrated products (versions 4.0.1 and later).

Server rename impacts not just the CLM applications but also any applications that integrate with the Jazz™ Team Server or CLM applications. References to CLM servers, links to CLM artifacts, and connections to Rational Team Concert repositories must all be updated. Also impacted are products that contain a Rational Team Concert plug-in or provide an optional install of the Rational Team Concert client.

Depending on the integration, specific product versions are required:

• Rational Reporting for Development Intelligence 2.0
• ClearCase Synchronizer and Importer: require ClearCase v7.1.1.x, v7.1.2.x, or v8.0.0.x
• ClearCase Bridge: requires ClearCase v7.1.1.x, ClearCase v7.1.2.x, or ClearCase v8.0.0.03 or higher
• ClearQuest Synchronizer: requires ClearQuest v7.1.1.x, v7.1.2.x, or v8.0.0.x
• ClearQuest Bridge: requires ClearQuest v7.1.2.07 or higher or ClearQuest v8.0.0.03 or higher

For these integrations, you will need to upgrade to the required version, perform the required actions, and, in most cases, plan an outage for the integrated tool. Therefore, if your deployment includes these integrations, you should undertake a server rename only after you have determined that other alternatives, such as using a reverse proxy or updating the DNS server, are not feasible.

If your deployment includes other integrations, your choices depend on which server rename scenario you are performing.

• If you are setting up a test staging environment, you must create dummy mappings in the map file to any additional integrations in your deployment. For details, see Mapping file for server rename.
• If you are renaming a pilot or full production deployment, and your deployment includes other integrations, verify that those integrations are supported. For a list of supported integrations, see Impact of server rename and integrated products (version 4.0.1 and later). If your integration is not supported, do not perform a server rename. Your integrations will break.

Rational Reporting for Development Intelligence

For information about how to configure Rational Reporting for Development Intelligence 2.0 after a server rename, see Configuring RRDI after server rename.

Rational ClearQuest

All three CLM applications can potentially integrate with the ClearQuest CLM Bridge. To maintain the integration after a server rename, you will need to run a remapping tool. For details about how to configure the Rational ClearQuest CLM Bridge after a server rename, see "Remapping URIs after renaming a CLM server" in the Rational ClearQuest Integrating book in the IBM Knowledge Center. For information about verifying the Rational ClearQuest Bridge after a server rename, see Verifying Rational ClearQuest and Rational ClearCase.

Only Rational Team Concert and Rational Quality Manager integrate with the ClearQuest Synchronizer. To maintain the integration after a server rename, you will need to update the cqconnector.properties file and perform several other steps. For details, see "Preparing the ClearQuest Synchronizer for renaming the Jazz Team Server server" in the Rational Team Concert Integrating book in the IBM Knowledge Center. For information about verifying the CLM Synchronizer after a server rename, see Verifying Rational ClearQuest and Rational ClearCase.

Rational ClearCase

Only Rational Team Concert integrates with Rational ClearCase.

For details about updating version 8.0.0.3 or higher of the Rational ClearCase Bridge after a server rename, see "Updating RTC task links after a CLM server rename" in the Administering Rational ClearCase book in the IBM Knowledge Center. This step is not required for the other versions of Rational ClearCase that support server rename; that is, versions 7.1.1.x and 7.1.2.x.

For details about updating ClearCase synchronization after a server rename, see "Updating the ClearCase Synchronizer environment after server rename: Production scenarios" in the Rational Team Concert Integrating book in the IBM Knowledge Center.

You can find additional information at Verifying Rational ClearQuest and Rational ClearCase.

For ongoing information about products that support server rename and additional supported scenarios, see Impact of server rename and integrated products (version 4.0.1 and later).

Related topics: Deployment web home, Deployment web home

External links:

• IBM

Additional contributors: None