When you are ready to generate a mapping file, follow the instructions in Preparing the mapping file.
The mapping file contains source-target URL pairs for the Jazz Team Server, its registered applications, and other URLs contributed by the applications. The URLs are divided into two types:
The URL pairs that are part of the rename include anything under the domain of the Jazz Team Server. These include the Jazz Team Server public URL, application public URLs, and other URLs contributed by applications.
Affected URLs include any other systems that interact with this topology but are not under the domain of this Jazz Team Server. A Rational® Engineering Lifecycle Manager application that is registered to a different Jazz Team Server but is friends with this Jazz Team Server represents an affected URL. An external integration such as Rational ClearQuest® also represents an affected URL.
# JTS
source=https://relmhost.example.org:9443/jts
target=https://relmhost2.example.org:9443/jts
#Additional Urls included in rename by relmhost.example.org:9443/jts
# ADMIN
source=https://relmhost.example.org:9443/admin
target=https://relmhost2.example.org:9443/admin
#(relm Help URL)
source=https://relmhost.example.org:9443/relmhelp
target=https://relmhost2.example.org:9443/relmhelp
# RELM
source=https://relmhost.example.org:9443/relm
target=https://relmhost2.example.org:9443/relm
# Jazz Reporting Service
source=https://relmhost.example.org:9443/sparql
target=https://relmhost2.example.org:9443/sparql
#The following list of URLs represent external servers that integrate
with this Jazz Team Server or with applications registered to it.
#Do not uncomment these lines as they are for reference purposes only.
# Friend Entry
#source=https://friend1.example.org:9443/jts/rootservices
#target=https://friend1.example.org:9443/jts/rootservices
#source=https://cqconnector.example.org:9084/cqconnector/gateway
#target=https://cqconnector.example.org:9084/cqconnector/gateway
The generated mapping file is a template that must be edited prior to running importURLMappings. It is important to understand everything in the mapping file to ensure all of the systems in your topology are renamed correctly. The upper section of the file includes the URL pairs that are part of the rename. In this example, you can see URL pairs for the public URL of the Jazz Team Server and all of its registered applications, You can also see URL pairs that are contributed by applications.
Look at each of these URLs and determine which ones are changing. Update the targets for any source URLs that will be renamed with their new values. If a given source URL is not being renamed, comment the pair out using a ' #'.
# JTS
#source=https://relmhost.example.org:9443/jts
#target=https://relmhost2.example.org:9443/jts
The bottom section of the mapping file contains a list of affected URLs that are commented out. These URLs are not part of this rename, but they are impacted by the changing URLs. Unless you need to mask out production URLs, you should leave these URLs commented out as they are meant for reference purposes only.
If you are in a staging environment, you should always mask out affected URLs to ensure there is no cross-linking between the staging and production servers. See below for details.
If you need to mask out an affected URL, you need to uncomment the source/target pair and provide a dummy target.
When setting up a staging environment, it is required that you create dummy mappings for any of the affected URLs in the mapping file. Affected URLs can include other relm applications that are friends with this deployment or external servers. For friend entries, create a dummy mapping for the friend's public URL.
For example, if your friend entry URL is https://friendhost.example.org:9443/jts/rootservices, the public URL is typically https://friendhost.example.org:9443/jts. Add a URL pair at the bottom of your mapping file to mask out this URL by setting the target to a false hostname. Verify that the dummy target hostname is unreachable before selecting it.
# Friend
source=https://friendhost.example.org:9443/jts
target=https://dummyfriendhost.example.org:9443/jts
For any affected URLs that are not friend entries, add the following URL pair at the bottom of your mapping file:
source=https://externalserver.example.org:9555/
target=https://dummyhost.example.org:9555/
It is not permitted to use the same target more than once. If you have multiple friend entries, use dummyhost2, dummyhost3, and so on. If you have a single-server deployment where the Jazz Team Server and applications all reside on the same host and port, you can use a simplified mapping, as described below.
If you have a simple topology, where the protocol, host, domain, and port are common for all URLs, the mapping file can be reduced to contain only one source-target entry. For example, if you have an all-in-one deployment at relmhost.example.org, and you want to rename everything to usenewhost.example.org, you can edit the generated mapping file to only include the following URLs:
source=https://relmhost.example.org:9443
target=https://newhost.example.org:9443
If any of the source URLs use the default port, and the default port number is not explicitly included, two sets of mappings are needed: one with the default port and one without the default port. The generateURLMappings command automatically generates the additional mappings for you. The default ports are 443 for https and 80 for http.
For example,Rational Engineering Lifecycle Manager is running at https://relmhost.example.org/relm. In this case, Rational Engineering Lifecycle Manager was deployed on a server using the default port (either by configuring the port for the application server, or by using a reverse proxy http server running on the default port). Within Rational Engineering Lifecycle Manager, links may have also been stored for URLs to resources where the port is explicitly included in the URL, for example:
https://relmhost.example.org:443/resource/...
Because of the possibility that URLs could be stored with both forms, a mapping is required for each. For example, suppose relmhost.example.org is renamed to newhost.example.org. In this case, the following mappings would be necessary to perform a rename. The pairs are generated automatically by generateURLMappings.
source=https://relmhost.example.org/relm
target=https://newhost.example.org/relm
source=https://relmhost.example.org:443/relm
target=https://newhost.example.org:443/relm
It is recommended that the URLs should be specified in all lowercase letters. URLs are case sensitive.
Due to the amount of processing involved, there is potential for errors to occur. Some errors are clearly indicated, such as if you try to generate the mapping file before starting the server, of if you use the wrong login credentials. Other errors are less obvious. For details about server rename errors, see Troubleshooting server rename.
After you generate and edit the mappings file, be sure to run the repotools-jts -verifyURLMappings command to check for missing mappings and perform several other verifications. In some cases, you can ignore the missing mappings that are found if you do not need to map that URL. For further details, see Repository tools command to verify a mapping file.