Best Practices for Server Rename and Moving to the Rational solution for Collaborative Lifecycle Managment 2012

Please be aware:The content of this article has been migrated to the Deployment wiki: Best Practices for Server Rename and Moving to the Rational solution for Collaborative Lifecycle Managment 2012 topic page. The content will be maintained and updated in the wiki going forward. Therefore, this version of the article might not contain the most up to date information.

All deployment guidance and best practice will be published in the Deployment wiki rather than as articles going forward.

The purpose of this article is to provide insight into real server rename experiences and scenarios and offer best practices and guidance as more users take advantage of this new feature in the Rational solution for Collaborative Lifecycle Management 2012. Keep checking back for updates and new information as it becomes available.

Scenario 1: Pilot-to-Production Server Rename with Upgrade, Migration, and Hardware Change

We just successfully completed a pilot-to-production rename with a customer who was running a pilot 3.x CLM server on Windows with Tomcat and DB2. Their requirement was to upgrade to 4.0, migrate to WebSphere Application Server running on Linux for System z, and cut over to their corporate LDAP for their user registry. Basically the only thing remaining the same was the DB2 database. While the actual server rename steps are few in number and rather straightforward, server rename in the context of all of these other changes becomes a daunting task. Following are the steps that were taken to accomplish the end result: 

  1. Upgrade the pilot CLM server ( to 4.0. See This includes all of the standard 3.x to 4.0 upgrade steps including:
    1. Taking down the system.
    2. Backing up the database and configuration files.
    3. Installing the 4.0 product as a side-by-side install.
    4. Copying over and updating the configuration files.
    5. Upgrading the databases using repotools –addTables.
    6. Upgrading the data warehouse.
    7. Verifying the repository data by checking the repotools logs.
    8. Starting the 4.0 applications and activating your 4.0 licenses.
    9. Validating / spot checking data in each of the applications.
    10. Pilot server is now open for business running 4.0 software. 
  2. Upgrade all Jazz Build Engines and eclipse clients to 4.0. If you are using 3.x Rational Build Agents or the ISPF client on z/OS, it is not necessary to upgrade these components prior to the rename, but you will need to upgrade them to take advantage of the new features in V4.0.
  3. Install the new production CLM V4.0 server and deploy on WebSphere Application Server on Linux for System z.
  4. Configure the new production server ( by going through setup connecting to a throwaway Derby database. Verify proper authentication from the corporate LDAP and that the WAS configuration seems to be working properly. This is a recommended step in this case because of all of the moving parts involved in moving to a new application server and new authentication server. This step may not be necessary if you are not making significant environment changes while moving your application server. Consider your own situation and make the choice that is right for you.
  5. Verify that several of the user credentials have the proper permissions based on their LDAP group membership.
  6. Shutdown the new production server.
  7. Perform the server rename procedure as outlined here:
    1. The preparation steps can be performed while the pilot system is on-line:
      1. Request a feature key from IBM support if you have not already done so.
      2. Generate a mapping file, update it with your new production URLs, and send it to IBM support for review. 
    2. The off-line steps for this scenario should be done with the pilot and production servers off-line:
      1. Back-up the pilot databases including the data warehouse.
      2. Restore the pilot databases into the production database server if you are changing (not the case in this scenario).
      3. Copy the JFS/text indices from pilot server to production server.
      4. Copy and edit the files for each application config folder from the pilot server to production server, adjusting the database entries and the LDAP entries to point to the production database server and the corporate LDAP server (as tested before).
      5. Copy the remaining properties and rdf files specified in the help from pilot to production.
      6. Copy the mapping file into the /server directory.
      7. Copy the server rename feature key file into the server directory as well.
      8. Issue the –importURLMappings fromFile=”./mappings.txt” command.
      9. Since this was an all in one install on a single server, the .mappingEvent file did not have to be copied to other application servers.
      10. Verify that the rename was successful by looking for errors in the repotools-jts_importURLMappings.log file after the repotools-jts operation completes. 
    3. The on-line steps for server rename are then done:
      1. Start the production jts server followed by the other applications.
      2. Go to the /serverRenameStatus to watch the progress of the server rename as it is propagated to each of the applications.
      3. When the rename completes, verify the project area linkages between the repositories to make sure the rename was successful.
      4. Do some of the other suggested manual validation steps in the help page such as running the data warehouse ETLs and checking dashboard widgets and reports. 
  8. Notify users that the server rename is complete and to begin using the new public URL for their access to the system. Their existing eclipse workspaces can be reused. Simply update the repository connection to point to the new production server URL. 

Scenario 2: In-Place Pilot-to-Production Server Rename

The instructions in the CLM Information Center for performing a pilot-to-production server rename are written with the expectation that you are working with two servers. However, it is possible to perform an in-place server rename on your pilot machine. When referencing the help, simply understand that your source and target servers are one and the same. For the step where you copy the indices and application configuration files from pilot to production, you should instead create a backup copy of these files from your server before performing the rename.

For more information

Changing the public URL using server rename (Information Center)

Renaming your Rational solution for Collaborative Lifecycle Management server (version 4.0)

About the authors

Robin Yehle is a member of the Jazz Jumpstart team. The Jazz Jumpstart team is a worldwide group of development specialists who bring new and advanced Jazz-based technologies to customers. Robin can be contacted at

David Chadwick is the technical lead of the Jazz Jumpstart Team for IBM Rational. He can be contacted at

Was this information helpful? Yes No 1 person rated this as helpful.