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.
Before you begin
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
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.
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.
Log in to the Administration page of the Jazz Team Server.
Point your web browser to
- Click the Server tab.
- In the left pane, in the Configuration section, click Registered Applications.
- Verify that all of your applications are registered.
For further details, see Registering applications with Jazz Team Server.
- Log in to the Administration page of the Jazz Team Server. Point your web browser to
- 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.
- 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.txtparameter, 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.
- 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.
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.
- Verify that a source-target pair exists for every application being renamed and for the clmhelp.war file.
- 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.
- Using a '#', comment out the source-> target pair of any URLs that you do not want to be renamed.
- 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.
- Review the additionalurls file. For details, see Repository tools command to generate the server rename mappings file.
- 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.
- 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.