Server rename

Edit online

This topic provides an overview of the server rename process and the implications of renaming the server.

Important: Server rename operations change the public URLs of referenced artifacts in an IBM® Engineering Lifecycle Management (ELM) deployment and might affect external links. For example, URL changes can invalidate external references such as those in email notifications, or external Open Services for Lifecycle Collaboration (OSLC) references from tools that do not support server rename. If you perform a server rename in a production environment, these changes might disrupt users. However, the server rename operation is useful for routine administrative tasks, such as refreshing data in a staging environment by using a snapshot of the production environment.

To perform a server rename, you must obtain a feature key file from IBM Software Support. When you contact IBM Support, mention that you are requesting a server rename feature key file. The key file is named ImportURLMappings.activate. Copy the file to the JazzInstallDir/server/conf directory for the applications that you will rename. The key is only needed to execute the repotools importURLMappings command.

A server rename is defined as changing the public URL for the Jazz® Team Server and one or more of its registered applications after those applications are deployed. The URL change can include any or all of the following components: protocol, host name, domain, port, or context root. An example of a public URL for a Jazz Team Server would be the string https://elm01.mycompany.com:9443/jts.

The Jazz Team Server and ELM applications use links to store relationships between stored artifacts that can span applications or systems, and to communicate with each other and with non-ELM applications. Server rename remaps existing URLs to new URLs to preserve the integrity of most links. Without the remapping, those links would be broken.

Note: Many links are outside the control of the Jazz Team Server and the ELM applications. The following types of links are not covered in the rename and would be broken:
  • URLs embedded in email, presentations, and documents
  • Bookmarks in browsers
  • Free text links that users paste or type into UI fields
  • Links from third-party applications

Risks and precautions

Performing a server rename is not without risk, particularly if the ELM deployment includes integrations to other non-ELM applications. Any change to a host name has the potential to break links in the data or to prevent ELM products from operating correctly.

If it is necessary to change your topology, the preferred approach is to always do so in a way that maintains a stable URL. Methods to maintain a stable URL include using DNS to route the host name to a different machine, or by using a reverse proxy or virtual hosts. For details, see Techniques for changing your topology. In cases where maintaining a stable URL is not possible, use server rename.

Review the following precautionary steps before you perform a server rename:

  • Plan your deployment carefully. See Deployment and installation planning for IBM Engineering Lifecycle Management, particularly the topic Planning your URIs.   
  • Be careful throughout the renaming process to enter URLs correctly, double-checking to avoid typographical errors in host names, ports, or context roots. Some of these typographical errors are not detectable by the rename process. To correct mistakes, you might need to perform another rename, or in extreme circumstances, you might need to restore from backups before you perform another rename.
  • Prepare and thoroughly review the mapping file in advance of the actual rename.
  • It is imperative that you fully understand your deployment before a rename, specifically the external references and links to other production systems. Review the information in Supported scenarios for using server rename to understand the scenarios that are supported. Review the information in Impact of server rename on integrated products and on the Jazz.net Deployment wiki to see whether the integrations in your deployment are supported.
  • Carefully consider clients, such as the Engineering Workflow Management Eclipse client and Engineering Workflow Management client for Microsoft Visual Studio IDE that rely on the ELM deployment to be renamed. To prevent any disruption and to preserve availability, notify users of those clients in advance that you are going to change the URLs of the ELM servers that are used by those clients. Encourage users to perform backups and to complete tasks in progress, such as code deliveries, before you start the rename procedure.
  • During the online portion of the rename, users might be able to log in to the server while the administrator is validating the renamed data. During this time, any operation that is not a read-only results in an error. Ensure that users are aware of this behavior in case they log in before the online rename is complete.
  • Ensure you have the necessary DBA permissions before you attempt to rename the server.

Software version requirements

Before you can perform a server rename, you must upgrade to the required version of the ELM software. The following table lists the software version requirements for performing a server rename:

Table 1. Required software versions
Software Required version

Jazz Team Server and the ELM applications
  • Version 4.0.1 or later is required for the pilot to production scenario and the production to production scenario.
  • Version 4.0 or later is required for the production to staging environment scenario. Version 4.0.1 or later is required to take advantage of the additional verification features that are provided in version 4.0.1 and later.

Jazz Build Engines and all clients, such as the Engineering Workflow Management Eclipse and Visual Studio clients

Version 4.0 or later is required for all scenarios.

For a complete list of system requirements for the current release, see Hardware and software requirements.

What parts of the URL can be renamed?

Renaming a Jazz Team Server and the ELM applications requires remapping the URLs that are stored in ELM resources. You can rename the entire URL prefix, which includes all parts of the URL through the context root, but does not include the context path of a resource. Specifically, you can rename the scheme (or protocol), host, domain, port, and context root.

For example, suppose that you want to rename the following old URL in a pilot deployment, which is moving to a centrally managed data center:

  • Old URL: http://bad.host.example.org:9443/ccm

    This URL uses an unsecure protocol (http), the default port configuration (9443), and a default context root (ccm).

  • New URL: https://good.host.example.org/ccm14

    This URL uses a secure protocol (https), changes the host name, uses the default port (unspecified in the URL), and a custom context root (ccm14).

Table 2. Parts of the URL that can be remapped in a server rename
Part of URI Example Comments
Scheme/Protocol http, https, FTP, Remote Connection URL

Can be changed, but using http is discouraged. If changing from https to http or vice versa, it is necessary to disable or enable security settings. See Disabling security certificate settings.

For the Remote Connection URLs that are used with the lab management features of Quality Management, be sure to include all schemes (Remote Desktop/VNC/FTP/HTTP/Telnet).

For the Software Inventory and Automation adapter connection URLs that are used with the lab management features of Quality Management, use the HTTP (http) scheme.
Host/Domain myhost.mydomain.com Use the fully qualified host name.
Port 9443 Can be changed but you need to update the port information in the application server. See Changing the port numbers for the application server. You can also use the default port by not specifying a port in the URL. See Mapping file for server rename for details about using the default port.
Note: If the public URL is set to a default port (443), you cannot change it.
Context root /jazz, /am, /ccm, /dcc, /gc, /qm, /relm, /rm, /rs To change the context root, you must complete some extra steps before the rename. For details, see Changing the context root.
Note: The Lifecycle Query Engine (LQE) and Link Index Provider (LDX) do not support changing the context root.

Server rename workflow

For an illustration of the general process flow for renaming your server, see Server rename process.