Mapping file for server rename

Edit online

This topic describes the structure of the mapping file generated by the generateURLMappings command and provides instructions on how to edit the mapping file for your deployment.

When you are ready to generate a mapping file, follow the instructions in Preparing the mapping file. For additional examples, see Server rename topology diagrams and mapping file examples.

The mapping file contains source-target URL pairs for the Jazz® Team Server, its registered IBM Engineering Lifecycle Management (ELM) applications, and other URLs contributed by the applications. The URLs are divided into two types:

URL pairs that indicate URLs that will change during the rename
Affected URLs that indicate external systems that could be affected by a rename

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. An ELM 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.

Description of a sample mapping file

# JTS
source=https://clmhost.example.org:9443/jts
target=https://clmhost2.example.org:9443/jts
#Additional Urls included in rename by clmhost.example.org:9443/jts
# ADMIN
source=https://clmhost.example.org:9443/admin
target=https://clmhost2.example.org:9443/admin
#(CLM Help URL)
source=https://clmhost.example.org:9443/clmhelp
target=https://clmhost2.example.org:9443/clmhelp
# CCM
source=https://clmhost.example.org:9443/ccm
target=https://clmhost2.example.org:9443/ccm
# RM
source=https://clmhost.example.org:9443/rm
target=https://clmhost2.example.org:9443/rm
# ADDITIONAL URLs included in rename by RM
source=https://clmhost.example.org:9443/converter/htmlgen
target=https://clmhost2.example.org:9443/converter/htmlgen
# QM
source=https://clmhost.example.org:9443/qm
target=https://clmhost2.example.org:9443/qm
# GC
source=https://clmhost.example.org:9443/gc
target=https://clmhost2.example.org:9443/gc

#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, such as the ELM help URL pair contributed by the Jazz Team Server and the converter URL pair contributed by the RM application.

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 out the pair using a ' #'.

# JTS
#source=https://clmhost.example.org:9443/jts
#target=https://clmhost2.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.

Dummy mappings to protect production data

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 ELM 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.

Using a simplified mapping file

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 elmhost.example.org, and you want to rename everything to use newhost.example.org, you can edit the generated mapping file to only include the following URLs:

Note: The simplified mapping from elmhost.example.org to newhost.example.org only renames the Jazz Team Server and the ELM applications. It does not rename any other integrations. You should always run generateURLMappings to determine whether your scenario is supported and to ensure everything in your topology is mapped correctly.

source=https://clmhost.example.org:9443
target=https://newhost.example.org:9443

Important: Do not use a simplified mapping file if you want to distribute your deployment at a later date.

URLs with default ports

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, suppose you have an existing CCM running at https://clmhost.example.org/ccm. In this case, CCM 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 ELM, links might have also been stored for URLs to resources where the port is explicitly included in the URL, for example:

https://clmhost.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 clmhost.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://clmhost.example.org/ccm
target=https://newhost.example.org/ccm

source=https://clmhost.example.org:443/ccm
target=https://newhost.example.org:443/ccm

Case sensitivity

The ELM applications require that URLs be lowercase. Therefore, targets in the URL mappings file must be specified in all lowercase letters.

Since this restriction was first introduced in version 3.0, there might be some cases where application URLs are upper or mixed-case if it has been upgraded from version 2.0. If this is the case, the source URL must be in the original case, and the target must be specified in all lowercase. For example:

source=https://CLMHOST:443/jts
target=https://clmhost:443/jts

If you have applications with source URLs that are in mixed-case:

https://clmhost:443/jts
https://CLMHOST:443/ccm

then you cannot use simplified mappings because you cannot map two different source URLs to the same target:

source=https://clmhost:443
target=https://clmhost:443

source=https://CLMHOST:443
target=https://clmhost:443  <- Not possible

Therefore, you must use per-application mappings, such as:

source=https://clmhost:443/jts
target=https://clmhost:443/jts

source=https://CLMHOST:443/ccm
target=https://clmhost:443/ccm

Additional URLs file

Starting in version 4.0.1, an additional file will be generated. For complex deployments, this list provides additional 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 with the repotools-jts -generateURLMappings command, you can specify a different file name for this file. For further details about this parameter, see Repository tools command to generate the server rename mappings file.

Errors during mapping file generation

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.

Verifying a mappings file

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.

Server rename on z/OS

Renaming your server is supported on z/OS®, and the process is the same on z/OS as it is on other operating systems. Run repotools -verifyURLMappings, by customizing JCL member hlq.SBLZSAMP(BLZRPOTL) as described in the comment headers, where hlq is the high-level qualifier that you specified during the SMP/E installation.

You can prepare the mapping file for z/OS using the same procedure as other operating systems, but the mapping file is UTF-8 encoded. The mapping files start with a BOM that is visible when editing through ISPF option 3.17. This BOM will appear as garbled text. Be careful not to delete the first three bytes of the file.

You can use one of the following techniques to edit UTF-8 files under z/OS UNIX:

If you have z/OS 1.10 or later or z/OS 1.9 with the PTF for APAR OA22250, use ISPF option 3.17 to edit UTF-8 files under z/OS UNIX System Services.
If you use IBM Developer for z/OS, use Remote System Explorer to connect and modify the files.
Download or use FTP to transfer the files to a Windows PC, modify them, and transfer them back to the z/OS system.
If you have other tools for editing UTF-8 files under z/OS UNIX System Services, use those tools.

After creating a mapping file, you can verify the results, that is, run repotools -verifyURLMappings, by customizing JCL member hlq.SBLZSAMP(BLZRPOTL) as described in the comment headers.