Preparing the mapping file

This topic describes how to prepare the mapping file which you will later use when you rename your Rational® solution for CLM (CLM) servers. You can prepare and review the mapping file in advance of the actual rename while your servers are still online.

Before you begin

Important: Server rename operations change the public URLs of referenced artifacts in a Collaborative Lifecycle Management (CLM) deployment and might affect external links. For example, URL changes can invalidate external references such as those in email notifications, or external Open Services for Lifecycle Collaboration (OSLC) references from tools that do not support server rename. If you perform a server rename in a production environment, these changes might disrupt users. However, the server rename operation is useful for routine administrative tasks, such as refreshing data in a staging environment by using a snapshot of the production environment.

To perform a server rename, you must obtain a feature key file from IBM Software Support. When you contact IBM Support, mention that you are requesting a server rename feature key file. The key file is named ImportURLMappings.activate. Copy the file to the JazzInstallDir/server/conf directory for the applications that you will rename. The key is only needed to execute the repotools importURLMappings command.

About this task

There are several steps you need to take before you actually rename the server. In large part, this involves preparing and reviewing the mapping file that you will use to perform the rename operation. The mapping file lists the existing source URLs and the renamed target URLs in your deployment. These include the URLs for the Jazz™ Team Server, the CLM applications, the CLM help WAR file, and any other applications that are impacted. See Server rename topology diagrams and mapping file examples for sample topology diagrams and mapping files.

You can perform these steps in both an all-in-one CLM deployment, where the Jazz Team Server and the CLM applications are all installed on the same computer, or in a distributed deployment, where the CLM applications are installed on different computers. These preparatory steps can be used with various scenarios, for example where a computer is moved to a new physical location, when setting up a test sandbox on a new computer, or the case of a data center consolidation that involves a renamed environment on new computers.

For z/OS operating systemNote: Renaming a server is supported on z/OS®, but there are several differences in the process for creating a mapping file. For details, see Server rename on z/OS.


  1. After upgrading the Jazz Team Server (JTS) and all CLM applications, start the Jazz Team Server and verify that the applications have been registered correctly with the server.
    1. Log in to the Administration page of the Jazz Team Server. Point your web browser to https://hostname:port/jts/admin.
    2. Click the Server tab.
    3. In the left pane, in the Configuration section, click Registered Applications.
    4. Verify that all of your applications are registered.

    For further details, see Registering applications with the Jazz Team Server.

  2. Open a command prompt on the computer where the Jazz Team Server is installed and change to the JazzInstallDir\server directory.
    Note: Be sure to perform this step and the following steps on the original Jazz Team Server, even if you will be moving to new hardware.
  3. Use the repotools-jts -generateURLMappings command to generate an initial mapping file to use as a template for further editing, as shown below. If you have already run the command, or the file already exists, add the overwrite=true parameter.
    • For Windows operating systemrepotools-jts.bat -generateURLMappings toFile=mappings.txt adminUserId=<adminId> adminPassword=<adminPassword> additionalURLFile=additionalurl.txt
    • For Unix operating systemsFor Linux operating system./ -generateURLMappings toFile=mappings.txt adminUserId=<adminId> adminPassword=<adminPassword> additionalURLFile=additionalurl.txt

    The output of this command is a mapping file that lists the existing source Public URL and a default target URL for the Jazz Team Server and each CLM application (CCM, DCC, GC, LQE, LDX, QM, RELM, RM, and RS) that is registered with the Jazz Team Server. It also identifies source and target URLs for the CLM help WAR file and any known affected external systems.

    In addition, a second file is created that contains a list of all of the URLs that might need to be mapped or that reference third-party integrations that might need to be considered. You can add these URLs to the mappings file. For simple deployments, it is not uncommon for this file to contain no additional URLs. If you include the additionalURLFile=additionalurl.txt parameter, you can specify a different name for this file. For further details about this parameter, see Repository tools command to generate the server rename mappings file.

    Verify that there are no errors in the log file at JazzInstallDir/server/repotools-jts_generateURLMappings.log.

  4. Review and edit the generated mapping file carefully. Look for typos in the host name, port or root contexts. Some of these typos are not detectable by the server rename tools and can lead to a non-functioning product. To familiarize yourself with the structure of the mapping file, see Mapping file for server rename.
    1. Verify that a source-target pair exists for every application being renamed and for the CLM Help WAR file.
    2. Edit the target= urls for the entries that you want to rename to be the correct targets.
      Note: If you are renaming a port number of the JTS or any application, you will need to update the port information in the application server after the rename, but before the servers are restarted. For details, see Changing the port numbers for the application server. If you are renaming a context root of the JTS or any application, see Changing the context root.
    3. Using a '#', comment out the source-> target pair of any URLs that you do not want to be renamed.
    4. Review the list of affected URLs. Although the command searches for all known URLs in the deployment, it is possible that some are missed. If any of these affected URLs need to be mapped, uncomment the source/target pair for the affected URL and provide the new target URL. If you have any doubts about the environment, talk to an administrator before proceeding with the rename.
    5. Review the additionalurls file. For details, see Repository tools command to generate the server rename mappings file.
    Note: If any configuration changes are made to the CLM deployment before you proceed to the actual rename, including registering additional applications, you will need to regenerate the mapping file.
  5. Use the repotools-jts -verifyURLMappings command to verify the mapping file.
    • For Windows operating systemrepotools-jts.bat -verifyURLMappings mappingFile=mappings.txt repositoryURL=<serverURL> adminUserId=<adminId> adminPassword=<adminPassword>
    • For Unix operating systemsFor Linux operating system./ -verifyURLMappings mappingFile=mappings.txt repositoryURL=<serverURL> adminUserId=<adminId> adminPassword=<adminPassword>

    For further details about the types of verifications that this command performs, see Repository tools command to verify a mapping file.

  6. If your scenario involves new hardware, install CLM on the new computers. Do not run the Jazz Setup wizard or start the Jazz Team Server. See Supported scenarios for using server rename for details about supported software versions. See Installing Jazz Team Server and the Rational solution for Collaborative Lifecycle Management applications for details about the installation process.

video icon Watch videos

CLM playlist channel
User Education channel

learn icon Learn more

CLM learning circle
Agile learning circle
Learning circles

ask icon Ask questions forum
developerWorks forums

support icon Get support

Support Portal
Deployment wiki
Support blog