Tip: Rules for CLM 2011 upgrade and installation

Last Updated: June 30, 2011
Jim Ruehlin, Jazz Jumpstart Team
Build basis: CLM 2011, RTC 3.0.1, RRC 3.0.1, RQM 3.0.1


This is a set of rules for architecting new CLM 2011 installations and upgrading from 2.x products to 3.0.1 (Jazz, RTC, RQM, RRC). Most of these items are hard-and-fast rules that can’t be avoided. Some are strongly recommended because you’ll probably run into trouble at some point if you don’t follow them. You’ll significantly reduce the risk of upgrade/ migration problems if you pay attention to these rules as you plan and perform your migrations.

Use these rules as a checklist as you’re planning your installation and upgrades. They’ll help you avoid pitfalls and plan for future growth.


View the upgrade from CLM 2.x to 2011 as a migration.
CLM 2011 products use new database schemas and include other architectural changes that make an in-place upgrade impractical. Each CLM product must be upgraded by installing the new version of the product in a different location than the current version, then migrating data and configuration information from the old version of the product to the new installation. While there are circumstances in which the product data can be upgraded in-place, the experience is more like migrating than simply upgrading.

Read all applicable migration documentation in the CLM Information Center before planning or proceeding with the migration.
This includes documentation on upgrading/migrating each product that will eventually be upgraded, JTS, and CLM. Migrating products to 3.0.1 from 2.x is a complex procedure, and each product has different upgrade paths. This is especially true in an enterprise environment. Be aware of the pitfalls and issues in your environment before you begin migration.

Migrating from CLM Beta 3 to the final CLM GA is not supported.
Beta 3 can only be used as a preview or for testing. You will need to migrate from 2.x to the CLM 2011 release.

Migrate one application at a time, then stabilize.
Install a single application, migrate and verify the data, make sure it’s stable, then migrate the next application. This will prevent you from using some new CLM features until the last product is migrated, but it significantly lowers the risk and impact of the migration. This rule is not an absolute constraint – it is possible to migrate all products at one time. But this should only be done if the circumstances require it.

Public URIs used in 2.x cannot change when applications are migrated to 3.0.1.
This means, for instance, that if you have different public URIs for each application, you will need a different application server instance (for example a Tomcat installation) for each Jazz-based app. See the comparison table for 2.x and 3.x public URIs for more information.

Context roots used in 2.x cannot change when applications are migrated to 3.x.
This means that the existing 2.x content roots for RTC and RQM, which are both /jazz by default, will require different server instances (for example Tomcat installations) for each app. In other words, context roots can’t be shared between applications on the same server. See the Impact of an upgrade on your deployment section for more information.

Use virtual host names when deploying in an enterprise environment. Seriously consider virtual host names whenever you install a new server.
Virtual host names require Websphere Application Server (WAS), but allow you to move servers and applications to new machines in the future without using a reverse proxy server. See the help text.

New licenses are required when migrating to 3.x
There is a new licensing model for 3.x that requires new licenses be installed. RTC 3.0 licenses WILL work with RTC 3.0.1.

Run the 2.x version of repotools in a separate command window than the 3.x versions of repotools.
Running both versions of repotools in the same command window will cause errors when running 3.x repotools.

System clocks for the machines that host applications must be synchronized.
See the Network Time Protocol project for assistance in synchronizing system clocks across a network.

Drives will probably need to be mapped between machines in order to perform application migrations from 2.x to 3.0.1.
The migration script requires access to the JTS, the old application, and the new application in order to perform the migration. It’s likely that these will live on two or more machines. For example, see the instructions for using the RTC migration script.

Lifecycle Project Administration (LPA)

LPA can only be used when all applications are at 3.0.1.
You can’t use LPA with 2.x or 3.0 applications, even if they’re part of a hybrid 2011/2.x CLM installation.

LPA only works against a single JTS.
You cannot manage Lifecycle Projects across multiple JTSs

Shared users is only supported within a single JTS.
A JTS cannot manage users for a different JTS.


Migrating RRC, RTC, and RQM from 2.x requires a minimum of 2 application server containers (Tomcat or Websphere).
One for RRC, JTS, and either RQM or RTC. One for RTC or RQM (whichever is not using the first application container). It’s likely that more application servers will be needed based on the number of machines used, performance issues, etc.
Install as few Jazz Team Servers as possible.
Many features are specific to a single JTS such as LPA, the data warehouse, licensing, etc. The fewer JTSs, the less administrative duplication. Also, a JTS cannot be merged with another JTS so starting with a single JTS eliminates potential issues with this constraint.See the rules on public URIs and context roots for more insight on why RQM and RTC require their own application servers when migrating from 2.x.

Once an application (RTC, RRC, RQM) is registered with a JTS, it cannot be moved (re-registered) to a different JTS.
If an application must be re-registered with a JTS, you must re-install that application, register it with the new JTS, and migrate the data (while maintaining the public URI and root contexts). Technically it’s possible to re-register SOME of the applications with the SAME JTS under certain conditions. Given the constraints, it’s smarter to re-install the application if necessary.

There is only one data warehouse for each JTS.

Single sign-on (SSO) in a distributed environment requires WAS.
SSO only works for Tomcat when all applications are in the same container. Note that a distributed setup is the inevitable result of migrating from CLM 2.x. So if you want to have single sign-on after migrating, you’ll need WAS.

Distribute CLM applications and the JTS to their own machines. Alternatively, place the JTS in its own Tomcat server or Websphere profile.
Installing or upgrading a CLM application in the same Tomcat server or Websphere profile is the JTS forces both to be upgraded together in the future. It is more flexible and requres less overall downtime to keep applicatioons and the JTS in separate application server instances. See this Important Note (highlighted in yellow) and this work item for more information on this limitation. To see an example of a distributed topology, see this help topic.


RTC 3.0.1, RRC 3.0.1, and RQM 3.0.1 all require JTS 3.0.1.
The latest versions of the CLM products require the latest version of the Jazz Team Server.

A full migration to CLM 2011 (all 3 products) requires at least four databases.
One database for the JTS, one database for the data warehouse, and one database each for RQM and RTC (RRC uses the JTS database).

Only one instance of the RM application can be registered with a single JTS, due to resource collisions.
Unlike other applications, RRC uses the same repository that JTS does. This implies that you can’t converge two instances of RM onto a single JTS. You can register multiple CCM and QM applications on a single JTS.

The RTC 3.0.1 Eclipse client is NOT compatible with an RTC 3.0 server.
You must use the RTC 3.0.1 server if you wish to use the 3.0.1 client.

Eclipse version 3.5 is the minimum required for the RTC 3.0.1 client.
Eclipse version 3.6 will also work.

Upgrade build engines when upgrading an RTC server.
You can run build engines that are designed to work with the most recent older version of RTC, except on Z platform. But upgrade them anyway for peace-of-mind and completeness. They’ll need to be upgraded the next time RTC is upgraded anyway.

Applications in different authentication realms can’t be merged into the same JTS.
For example, you can’t converge applications from two different LDAP realms.

All CLM applications must use a common authentication realm.
For instance, if one application needs LDAP for authentication, all applications must use LDAP. The key issue is that the user IDs must match when migrating to a common JTS.


License administration and usage is performed in the context of a single JTS.
This means that if a user connects to two different CCM applications that are registered on the same JTS, the user will consume a single license. But if a user connects to two different CCM applications that are registered to different JTSs, that user will consume two licenses (one from each JTS). This is true even if the different JTSs are connected to a shared floating license server.


You cannot perform reporting across multiple Jazz Team Servers using Rational Reporting.
You can report across multiple JTSs using IBM Rational Insight.

All reporting is based on the data warehouse associated with the JTS.
There is at most one data warehouse for a JTS.

All report customization must be done in Rational Reporting for Development Intelligence (RRDI).
This is provided with JTS 3.0.1 as a separate install.

Use Rational Insight for reporting if it’s available in your environment.
Insight is a superset of RRDI.

Related Information

The following links point to related information:

Was this information helpful? Yes No 3 people rated this as helpful.