Renaming your Rational solution for Collaborative Lifecycle Management server (version 4.0.1 and later)

David Chadwick, IBM Rational
Contributions from: Ritchie Schacher, Heather Sterling, Ara Masrof, Eric Solomon
Last updated: December 7, 2012
Build basis: Rational solution for Collaborative Lifecycle Management 2012 (product version 4.0.1)

Information Center link for version 4.0.1

Purpose

The purpose of this document is to provide the basic information for customers to decide when and when not to use the Jazz server rename feature introduced in version 4 of the Rational solution for Collaborative Lifecycle Management products. These products include Rational Team Concert, Rational Requirements Composer, and Rational Quality Manager. With the additional functionality added in version 4.0.1, the full set of planned user scenarios are now supported for server rename. These user scenarios have been thoroughly tested by IBM and validated in partnership with our customers. This document has been updated to include all of those user scenarios. Full support of server rename for your production installation is now available with version 4.0.1 and later.

In addition, this document provides links to other related documents on jazz.net. One such document, Impact of Server Rename and Integrated Products (Version 4.0.1), provides more detailed information on the various product integrations and which of these provide support for the CLM server rename functionality. Over time, most, if not all, of these products will accommodate CLM server rename. As each of these integrations is made fully functional and thoroughly tested, its status will be updated in that document.

Definitions

Renaming your CLM server

A CLM (or Jazz) server rename is defined as changing the public URL for the Jazz Team Server and/or one or more of its registered applications. The URL change can include any or all of the following components: protocol, hostname, domain, port, or context root. An example of a public URL for a Jazz Team Server would be the string https://clm01.mycompany.com:9443/jts.

CLM server

A CLM server is defined as a web application server hosting one or more Jazz applications that are part of the IBM Rational solution for Collaborative Lifecycle Management.

Background on Public URL

One of the most challenging aspects of using the IBM Rational Jazz products is dealing with “linked artifacts” which use absolute URL links to access the encapsulated data. From the beginning, these links were explicitly chosen to make use of the architecture of the web, which uses URLs to reference objects and expects permanent (or at least long lasting) addresses. The base part of the URL is called the “public URL”. This is the part that must stay consistent to permit access to the artifacts hosted by that Jazz application.

The advantage of this approach is that it gives you the ability to access the artifact from any context, including a browser bookmark, a hot link on a web page, or in an email message. The disadvantage is the inability to move the artifact to a new server, change DNS hostnames or domains, or freely update your IT infrastructure to support changes in project or organizational structure.

Other traditional, monolithic, database server-based SDLC products in the industry permit this freedom of movement, and users also expect that freedom from the Collaborative Lifecycle Management solution.

Because the nature of software and systems development shops is dynamic and constantly changing, there is a critical need for the CLM solution to support these changing environments by allowing administrators to rename their Jazz servers. Note, however, that changing the public URLs of existing CLM deployments can be disruptive, so it is always best if you can plan ahead and use stable URLs.

Primary user scenarios for server rename

There are a number of reasons why server rename may be desired. Listed here are a few representative user scenarios that are supported for server rename.

1. Production to Staging: This scenario involves copying a production server to a staging environment (also called a “test sandbox”) so that new or not yet used functionality can be checked before it is introduced into the production environment. Examples might include testing new project and process templates, work item customizations, integration with non-CLM tools, or trying out other CLM functions not yet used in the production environment. Note: Only a limited subset of integrations are currently supported.
2. Pilot to Production: In this scenario, the CLM server was first used as a pilot implementation and now needs to be moved to the production IT environment. There are production rules that the current public URL in the pilot system do not meet. The IT department demands adherence to their standards. This may include moving to a secure connection or a different server name/domain/port.
3. Production to Production: In this scenario, some aspect to the public URL is no longer usable and must be changed. For example, the server or domain name can not remain the same. Perhaps the customer wants to standardize on a server name based on the product’s function rather than use the name of the host machine. Also the customer may want to move to a default port so non-local access is permitted without corporate firewall exceptions.

Non-supported data reorganization scenarios

There are other user scenarios that customers are very interested in performing to modify the configuration of their production CLM installations. A few of the most common are listed below. These user scenarios are not in any way supported nor will they work. If any of these scenarios is attempted, it will result in a non-functional production environment. The development team will be reviewing these use cases for possible solutions in the future.

1. CLM Consolidation – Merging JTS servers: In this scenario, the CLM products were implemented as multiple pilot or production installations and were originally hosted and managed separately. Now there is a desire to have the products integrated and centrally managed as a single CLM system. This would involve combining the multiple JTS instances and registering the applications with the combined JTS. (Not supported using server rename feature)
2. CLM server split: In this scenario, the user population and/or number of projects has grown to the point where customer IT wants to split the projects across two CLM instances so that they can be separately administered and managed. Through some analysis of affinities, project areas are put on server A or server B with as few cross server linkages as can be managed for performance reasons. The strategy is to clone the production server and archive projects that are to be run from the other server. (Not supported using server rename feature)
3. Project Move from one CLM server to another: In this scenario, the user wants to move project contents out of one CLM deployment and into the repositories of another. This is one of the top requests for enterprise deployments, but is also the most complex of the data reorganization scenarios. (Not supported using server rename feature)
4. CLM server cloning: This scenario involves replicating servers so that you can reuse the existing system to seed a “ready to run” fully configured new system. (Not supported using server rename feature) However, there are new command line setup capabilities that may help build newly configured systems more efficiently.

Server rename considerations

Warning: Before deciding to use the server rename feature, there are some additional factors to consider. Because artifact links are used externally to the CLM system, any existing externally-held links will no longer be valid. This would include all links that were included in email messages, web pages, and in integrated non-CLM products (unless they explicitly support CLM server rename) that may be in use in the customer’s environment.

Other integrated products storing URL references to CLM artifacts will require an implementation of a rename feature that scans for these CLM links and adjusts them based on source/target (old/new) public URL pairs. However, you may have to upgrade those products or delay the rename operation until all of the integrated products can handle the renaming of the CLM system. For example, you must have Rational ClearQuest version 8.0.0.3_2012B to apply the server rename function for the bridged integration to the CLM system. Basically all of those links must be updated so that the integrated applications can continue to work properly and make use of the functionality afforded by the linked data architecture of the CLM system and other applications using OSLC linkages.

Consult the Impact of Server Rename and Integrated Products (Version 4.0.1) document to find the required version for each of your integrated systems and verify that all are available before using server rename.

Server rename sequencing

A server rename is often accompanied by other complex operations. It is recommended that each operation be validated individually prior to the rename. This practice makes it easier to determine which operation caused any problem introduced by that operation. Detailed instructions for each of these operations can be found in the information center.

1. Upgrade – An upgrade is considered a distinct action from a rename operation. In particular when rehearsing the upgrade to a version 4.0.x product, this must be done using the production public URL (and server name) and thus must be done using an isolated network. The upgrade should be validated first before the server is renamed.
2. Changing application servers – By setting up a second application server (usually this is done to host a staging environment or to replace the old production server), careful installation and configuration steps must be followed and validated before moving forward to perform the rename operation. This is the most frequent source of problems that are attributed to the server rename operation. Validating the application server installation and configuration using a temporary Derby repository is a recommended practice before attempting a rename operation on a copy of the production repository.
3. Changing database servers – By setting up a second database server (for staging or infrastructure improvements), careful setup of the database, including granting the proper permissions to the connecting user ID, is important to validate with a database client program before connecting the Jazz applications to the restored copy of the production repository. This provides a high level of confidence that the rename operation will be able to connect and make the changes needed by the rename operation. Also, the rename process requires configuration files to be copied from the source CLM server to the target CLM server. If the database location changes, the teamserver.properties files must be updated to reflect the new location. Before proceeding with the rename, validate the target CLM server’s configuration files to ensure that they contain correct information.
4. WebSphere considerations – If you are using WebSphere Application Server, it is important that the Jazz Team Server and applications start at the appropriate times. It is a good idea to disable auto-start during the rename process since there are various offline and online steps, and the application server or applications themselves might need to be restarted. It is a best practice to start the applications before the Jazz Team Server. The Jazz Team Server polls the applications and requires them to be online for the rename to complete.

Impact of a server rename

Once you have determined what use case applies to your use of the server rename feature and that it is supported, you can proceed to the product documentation that explains how to perform a server rename operation. There are four steps in the rename process:

1. Generating and editting the mapping file that contains all of the source/target URL mappings. This must be performed while the CLM servers are still online and it does not impact product functionality. Also run the verifyURLmappings command to check for any reported errors.(preparation step)
2. Running an offline command to import the URL mappings into the JTS. All CLM servers in the topology must be shutdown prior to running this command. You will need to plan appropriately for the outage. (offline step)
3. Bringing up all CLM servers so that the applications can contact the JTS to synchronize their mappings. During this time, the JTS is in a special mode that blocks user access. All requests made to the JTS or any of its registered applications are redirected to a centralized server rename status page. (online/readonly step)
4. When the rename completes on all applications and components, the JTS and applications will enter a read-only mode of operation so that you can perform addition manual data validation steps including running the server rename validation wizard. (online/readonly step)
5. Once you are satisfied that the server rename operation has completed successfully, you can switch the servers to full production mode. (online step)

There are integrations with some subsystems within the CLM system that contain the CLM server’s public URL or at least the hostname of the server. While most of these are handled directly by the server rename operation, there are some that require manual updates. These include build engines and test adapters as well as some linkages such as live CLM data source feeds used by reporting tools. Instructions for updating these are included in the server rename instructions. Some of these steps can be manually intensive and require verification after the server rename operation.

If an error occurs during the second or third step of the server rename, or you made a mistake in the mapping input file, consult the product documentation to determine if the error is correctable. If it is not correctable, you will need to restore all of your databases and configuration files from your backups. Contact IBM Rational product support to determine how to rectify the problem.

Decision process

Once you have evaluated your server topology, integrations, and impact on your user community, you must make a decision whether to use server rename to accomplish your goal or whether to maintain the current public URL. Through the use of DNS mapping and hostname aliasing, perhaps with a reverse proxy server, you may be able to maintain the current public URL. Leaving the public URL constant is certainly a preferred solution because it preserves all of the external references as well as those that you can update through the server rename process. The linked data architecture used by the Jazz architecture (and the CLM system) expects the links to be stable and supported for a long period of time. Maintaining those links should be a high priority in setting up the CLM system.

Enabling server rename

If maintaining the public URL is simply not an option for your CLM system, and you fit into one of the supported use cases, you must contact IBM Rational product support to obtain a “Server Rename Feature Key File” to unlock the server rename feature.

During your discussion with product support, they will help you confirm that your rename usage pattern is consistent with a supported use of the server rename feature. They can also help you determine if IBM assistance is needed to help you perform the rename operation on your CLM system or if you need any additional fixes. The goal of this process is to make sure you are thoroughly informed of the process details. If you are not sure whether your user scenario is a “pilot to production” scenario or a “production to production” scenario, contact product support to engage help from IBM to help make the determination.

Server rename checklist

When you call IBM support, they will ask the following questions to ensure that you are ready to use server rename and understand it.

Server Rename Questions (All must be answered “Yes” to use this feature)

1. Is the user scenario supported — production to staging, pilot to production, or production server rename?
   • IBM only supports renaming a production server using the server rename feature with v4.0.1 or later version.
2. Are you sure that you are not attempting a different data reorganization scenario using the server rename feature?
   • In no way does this feature permit the migration of project areas associated with one JTS to another, moving project areas from one application repository to another, or provide a way of creating two production environments in any form.
3. Are all CLM applications and their JTS running the v4.0.1 product version. Is RRDI included and running v2.0 (or later)?
   • If not, all applications must be upgraded to v4.0.1 before attempting a pilot to production or a production to production rename. For a production to staging rename v4.0 is required and v4.0.1 is strongly recommended.
   • Note that you can not use server rename for staging a v3 to v4 upgrade.
   • Upgrading to version 4.0.1 is a distinct, separate activity, and still requires stable URLs and an isolated network.
   • Once you are running on version 4, you can use server rename to rename your staging environment for further testing.
4. Are all RTC client programs to be used to access the renamed system running the v4.0 GA (or later) product version?
   • If not, you must upgrade all clients to version 4 (or install separate version 4 client instances) that will be used to access the renamed system.
   • This is of primary importance for the pilot to production and production to production use cases, so your users are warned when accessing a newly renamed CLM system.
   • For the production to staging use case, the users of the staging (or test) system should use a separate client workspace and a separate v4 client to protect the production data against contamination from client interactions with the test system.
5. If used as a staging (or test) environment, is the renamed CLM system isolated from all integrated production applications? Those integrations not available as part of the renamed staging environment should be “stubbed out” (ie, set to a null system name) so that those links from the production system are not active or usable. This guarentees that the newly renamed test system is isolated from those integrated systems. See the product documentation for a complete explanation of this concept.
   • For the production to staging user scenario, as a best practice, the /etc/hosts file on the renamed test server should redirect those previously integrated production system names to a bogus IP address so no automatic communication takes place between the renamed test system and the integrated production systems.
   • The RQM Lab Management functionality now supports server rename as of version 4.0.1.
6. If you are using a Derby database in your pilot to production use case, do you understand the need to migrate the existing data repositories to a production database server?
   • All production CLM systems are expected to use production quality databases that handle the scalability, robustness, and maintainability required in a production environment. This implies that the pilot Derby database must be migrated to an enterprise database during the server rename to the new production CLM system. You will need to perform the “repotools –export” and “repotools –import” operations to migrate your data to the production database server as part of the CLM server rename procedure. See the topic “Changing the database vendor” in the Information Center for details.
7. Will only one of these systems ever be used in the production environment?
   • In the pilot to production use case, you are expected to NEVER restore to production service the original server image from before the CLM server rename. It has been replaced by the renamed CLM server.
   • In the production to staging use case, you are expected to run both the staging and production versions of the system, but the staging version will not be integrated with production applications nor be used as a production system. It should remain in an isolated staging (or test) environment.
   • Because of expected technical design limitations, the staging system and the production system can never be linked through a Jazz friend relationship or have linked data between the systems.
8. There can be no linked data between the renamed system and the original system. Is this acceptable to you and for your intended use of the CLM servers?
   • In the pilot to production or production to production user scenario, the initial system with the original public URL is decommissioned.
   • In the production to staging user scenario, the staging system will never integrate with production applications but both environments will remain active.
   • By walking through the intended purposes for both the original and renamed CLM servers, it should be clear that the systems will not be linked nor used together in any way.
9. If you are performing a production rename and have multiple deployments, have you identified all affected deployments?
   • If deployment A is being renamed and any application in A is linked to any application in deployment B, B must also be renamed. This is because B contains links to A.
   • The rename for A and B MUST be performed simultaneously. Administrators must validate A and B and complete the renames at the same time. If any corrective mappings are needed, they must be applied to both A and B. Administrators must plan for outage time for all linked deployments.
   • If an administrator is not certain of all of the deployment linkages, generateURLMappings should be run against all of the Jazz Team Servers in production. Inbound friends do not show up in the generated mapping file and it is easy to miss these linkages. Scan for occurrences of any of A’s URLs in B’s generated mapping file. If deployment A is being renamed and an application in deployment B has a one-way friendship with an application in deployment A, the application in B will not show up in A’s mapping file. However, the application in A will show up in B’s mapping file. In this case, the rename must be performed against B as well, since B contains links to A.
   • Consult the additional URLs file that is generated by generateURLMappings. This file contains URLs that were not contributed to the generated mapping file. The list could contain URLs that need to be added to the generated mapping file or that represent integrations that need to be considered.
   • Many integrations do not show up in the generated mapping file. Ensure that administrators go through the list of integrations at Impact of Server Rename and Integrated Products (Version 4.0.1) to identify any integrations that they might have.
   • In some cases, backlink creation may fail during the rename read-only mode period. Consider the scenario in the first bullet where a third deployment C exists. C has linkages to B but not A. In this scenario, C does not need to be renamed but it should also be taken down because backlink creation from C to B will fail when B is in read-only mode. For some operations, the user is warned that the backlink creation failed; in other cases, it may not be obvious. There is currently no mechanism that will automatically repair missed backlinks.
10. Have you requested a server rename feature key to unlock the server rename feature from IBM product support?
    • The server rename will fail if it can not find the feature key file in the directory specified in the email from IBM support.
11. Have you reviewed the Workarounds for Server Rename problems in CLM 4.0.1 to see if there are posted solutions to any of your problems?

Server rename outage planning

It is critical to identify and plan for the amount of outage time that is needed. This is especially true for pilot-production or production renames where user productivity is impacted. Here are some best practices:

1. Do not underestimate verification time. Administrators should perform the following before completing a rename:
   • Verify that all of the URLs in the verification wizard are correct and that all of the links can be followed.
   • Verify that all links and URL data in all of the applications and project areas are correct.
   • Perform any product-specific verification, including client verification, as described in the information center.
2. By having multiple people verify things simultaneously, the overall outage time is reduced.
3. Plan outage time for recoverable mistakes. It is possible that you might miss a mapping or make a typo in a mapping. In this case, a corrective mapping must be applied and an additional serer rename must be performed.
4. Plan outage time for the worst case scenario. The rename feature is solid, however there is always a chance something could go wrong. In this case, a full backup and restore is required before normal server operation can resume.
5. In the case of multiple linked deployments, outage time must be considered for all deployments. The renames must be done simultaneously and completed at the same time.
6. If an upgrade is required beforehand, plan outage time for that as well.
7. Communicate to your users that as a best practice they should check in all of their outstanding source code before the rename occurs. For the version 4 clients, you do not have to start with a fresh workspace after the rename operation as the clients support a server rename. Include in the communication instructions for updating their connection strings for the new server location.

Summary

Renaming a server can be accomplished with proper planning and by carefully following the server rename instructions. Remember that there will be external links to CLM artifacts that will be broken after performing a server rename. You should confirm that your purpose in doing a server rename is a supported use case. Assessment of integrations with other applications is crucial to prevent a loss of integrated system functionality. There are a number of CLM subsystems that depend on the public URL that may not be obvious and must be updated to accommodate the rename operation. Communication of the server rename with the CLM user community is very important and should be planned ahead of time and done carefully to reduce lost work or productivity as a result of the rename operation.

---

For more information

• CLM Information Center — Server Rename instructions
• Impact of Server Rename and Integrated Products (Version 4.0.1) — Article about CLM server rename integration support
• Workaround: Server Rename Read-only Mode Limitations — Article explaining the limitations of the post server rename read-only mode

---

About the author

David Chadwick is the technical lead of the Jazz Jumpstart Team for IBM Rational. He can be contacted at dchadwick@us.ibm.com.

Copyright © 2012 IBM Corporation.