Changing the context root

Rather than change the host name when you perform a server rename, you can change just the context root.

Before you begin

  • 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.
  • Before you proceed with the rename, check that the required version of the ELM software is installed and that your environment meets the criteria for a server rename. See Software version requirements and Supported scenarios for using server rename for details.

For a case study about changing the context root, see Case study: Server rename.

About this task

Although it is most common to change the host name during a server rename, it is also possible to change the context root. Doing so requires a new server installation that mirrors the old installation, but with new context roots. Make sure that you generate a mapping file against the original server, as detailed in Preparing the mapping file. Change the necessary context roots in this mapping file. For more information about changing the context root, see Case study: server rename.


  1. Use Installation Manager to install a separate, Jazz™ Team Server. When you get to the Context Root Options panel, click Select custom context root values and enter your custom context root values. Even if you are renaming only the context root for a single application, you must install all of the applications that you intend to run. For further installation instructions, see Installing the IBM Engineering Lifecycle Management by using IBM Installation Manager.
  2. Copy the following configuration files from the old installation server/conf/oldContextRoot to the new installation server/conf/newContextRoot. Copy all of these configuration files, even if you are not renaming a particular application's context root.
    Note: If you changed the context roots in the old installation, replace these default examples with your own customized versions.
    • From server/conf/jts, copy: and the indices directory.
    • From server/conf/ccm, copy and the indices directory.
    • From server/conf/dcc, copy: and the indices directory.
    • From server/conf/gc, copy: and the indices directory.
    • From server/conf/qm, copy: and the indices directory.
    • From server/conf/relm, copy: and the indices directory.
    • From server/conf/rm, copy: and the indices directory.
    • From server/conf/rs, copy:
    Note: The Lifecycle Query Engine (LQE) and Link Index Provider (LDX) do not support changing the context root.
  3. Ensure that the following database properties in the files for JTS, CCM, DCC, GC, QM, RELM, and RM are pointed at the correct database locations.
    Note: The Lifecycle Query Engine (LQE) and Link Index Provider (LDX) do not support changing the context root.

    Finally, fix the relative text indices location to use the new location. Be sure to include the new context root in the path.
  4. If you are using WebSphere® Application Server, uninstall the applications from the old installation and install them in the new installation. Also, update JAZZ_HOME to point to the new installation. For details about deploying applications to WebSphere Application Server, see Deploying applications for the IBM Engineering Lifecycle Management on WebSphere Application Server.
  5. Follow the standard rename instructions, starting at the importURLMappings step. You must run the importURLMappings command against the new installation using the generated mapping file from the old installation. Do not perform any additional steps against the old installation, which serves only as a backup until you are sure that the new installation is working correctly.
    Note: It is possible that the old application context root will appear in the server rename status UI. The UI displays the registered application name. By default, the name is the context root. Therefore, if you never changed the name from the default, the old context root is shown.
  6. Optional: Update the name of all renamed applications.
    1. Log in to the Jazz Team Server admin UI and go to the Configuration > Registered Applications.
    2. Click Edit and rename each application to its new context root or to any other name of your choosing.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki