Verifying URLs and links after a server rename

After you rename a server, you can verify the rename at the Server Rename Status page, where you can visually inspect the key URLs for your deployment. You can validate the public URL, friend URLs, project area links, and so on. In addition, you can click on links to open the application pages in a new browser tab and look for broken links and incorrect URLs.

Before you begin

To take advantage of the verification feature, you must upgrade the Jazz® Team Server and all ELM applications to version 4.0.1 or later before the rename. Older applications do not support this feature.

Perform one of the supported server rename scenarios that are described at Performing a server rename. Then, start the Jazz Team Server as described in Step 4 in the scenario topics.

About this task

During this verification process, the Jazz Team Server and all registered applications are in read-only mode.

Be sure to inform your user community that the server will be in read-only mode during the verification process and that it is highly recommended that they not log on during that time.


  1. Log into the Jazz Team Server at https://new host:port/jts/serverRenameStatus to view the Server Rename Status screen. This starts the actual renaming process as described in Step 5 in the scenario topics.
  2. Wait for the renames to complete and the status for all of the applications to reach 100%. Any attempts to log in to the web UI for any of the ELM applications before the rename is complete will redirect you to this status page.
  3. Click Next to start the verification wizard.

    The wizard will guide you through a visual inspection of the important URLs in your deployment. During the verification process, the Jazz Team Server and all applications will be placed in read-only mode, but you will be able to browse data, and look for broken links and unmapped URLs.

    Note: Do not exit read-only mode until you have confirmed that the URLs are correct, that you can successfully browse through your application data, and that the links work. To learn more about read-only mode, including read-only mode restrictions, see Server Rename Read-only Mode Limitations.
  4. Perform additional product-specific verifications described at Completing the server rename verification process.
    Tip: Some verifications can only be completed after deactivating read-only mode, perform those steps after you later check the I have verified the server rename box and complete the verification wizard.
  5. If any of the URLs are incorrect or still need to be renamed, perform the following steps:
    1. Click the flag icon next to the URL.

      On the final step of the wizard, any flagged URLs will be included in a mapping template.

      Note: Do not check the I have verified the server rename box or click Finish at this point.
    2. Stop the Jazz Team Server and create a new mappings file using the template that is provided. The template can be used to fix URLs that were mapped incorrectly due to typos or missed mappings.
      Note: Do not append the template to the original mappings file. The new mappings file will fix the errors that were found. Do not use the original mapping file because those renames have already been performed. To fix any problems, you have to rerun repotools -importURLMappings.

      See Recovering from importURLMappings errors for a list of common mapping errors and corrective actions.

    3. Rerun the repotools -importURLMappings command to perform another rename.
    4. Restart the Jazz Team Server.
    5. Repeat the verification process starting at Step 1

    For additional information, see Server Rename Read-only Mode Limitations.

  6. If all of the URLs are correct and you are confident that the renamed data is correct, click the I have verified the server rename check box and click Finish.

    The Jazz Team Server and all registered applications will exit read-only mode and normal product use can resume.