Mapping file for server rename
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:
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:
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:
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
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:
If you have applications with source URLs that are in mixed-case:
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.
you include the
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 Systems®, 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.