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.
- 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.
- Log in to the Administration page
of the Jazz Team Server.
Point your web browser to https://hostname:port/jts/admin.
- Click the Server tab.
- In the left pane, in the Configuration section, click Registered
Applications.
- Verify that all of your applications are registered.
If not, register them.
- If you registered any applications in the previous step,
restart the Jazz Team Server.
- 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.
- 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.
- 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.
- Verify that a source-target pair exists for every application
being renamed and for the Help 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. 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.
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.
- 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 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 .