Preparing the mapping file

This topic describes how to prepare the mapping file which you will later use when you rename your IBM® Engineering Lifecycle Management (ELM) servers. You can prepare and review the mapping file in advance of the actual rename while your servers are still online.

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 ELM applications, the clmhelp.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 ELM deployment, where the Jazz Team Server and the ELM applications are all installed on the same computer, or in a distributed deployment, where the ELM 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.

Note: 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 ELM 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 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.
   • repotools-jts.bat -generateURLMappings toFile=mappings.txt adminUserId=<adminId> adminPassword=<adminPassword> additionalURLFile=additionalurl.txt
   • ./repotools-jts.sh -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 ELM 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 clmhelp.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 clmhelp.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 ELM 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.
   • repotools-jts.bat -verifyURLMappings mappingFile=mappings.txt repositoryURL=<serverURL> adminUserId=<adminId> adminPassword=<adminPassword>
   • ./repotools-jts.sh -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 ELM 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 IBM Engineering Lifecycle Management applications for details about the installation process.