Preparing the mapping file

This topic describes how to prepare the mapping file which you will later use in the actual rename of your Jazz™ Team Server. You can prepare and review the mapping file in advance of the actual rename while your servers are still online.

Before you begin

Important: To enable server rename you must obtain a feature key file from IBM® Software Support. When contacting IBM support, please mention that you are requesting a "Server Rename Feature Key File".

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 Jazz applications, and any other applications that are impacted.

You can perform these steps in both an all-in-one deployment, where the Jazz Team Server and the Jazz applications are all installed on the same computer, or in a distributed deployment, where the Jazz 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.

Procedure

  1. After upgrading the Jazz Team Server (JTS) and all Jazz 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. If not, register them.
    5. If you registered any applications in the previous step, restart 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.
    • Windows: repotools-jts.bat -generateURLMappings toFile=mappings.txt adminUserId=<adminId> adminPassword=<adminPassword> additionalURLFile=additionalurl.txt
    • Linux: ./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 Jazz application (Rational® Engineering Lifecycle Manager, Lifecycle Query Engine, Jazz Reporting Service) that is registered with the Jazz Team Server. It also identifies source and target URLs for the 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 may need to be mapped or that reference third-party integrations that may 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 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. 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 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 Rational Engineering Lifecycle Manager on the new computers. Do not run the Jazz Setup wizard or start the Jazz Team Server.

What to do next

Proceed to renaming the server. For details, see Moving a pilot or full production deployment using server rename .

Feedback