Jazz Library CLM 2011 Upgrade Frequently Asked Questions
Author name

clm,elm,test-management,workflow-management,rational-quality-manager,rational-requirements-composer,rational-team-concert

Wed, 16 Nov 2011
5 min read
0

CLM 2011 Upgrade Frequently Asked Questions

Rosa Naranjo, Jazz Jumpstart Team
Last updated: April 26, 2012
Build basis: CLM 2011, Rational Team Concert 3.0.1.1, Rational Quality Manager 3.0.1.1, Rational Requirements Composer 3.0.1.1

This article will present some frequently asked questions (FAQs) regarding the CLM 2011 Upgrade process as well as some known issues and workarounds, if applicable.  Some of the questions or issues will be related to the overall upgrade process and some will be related to a particular application upgrade.

Upgrading to 3.0.1.1

The products of the CLM 2011 solution have released their first fix pack, 3.0.1.1, and thus, the valid question arises of whether to upgrade to 3.0.1 or 3.0.1.1.  The 3.0.1.1 upgrade is the same as the 3.0.1 upgrade process if you are upgrading from 2.x.  However, if you have already upgraded to 3.0.1, the upgrade process is faster since you will not be running an export & import step and will not be running JTS setup wizard.

Here is some guidance on when to upgrade directly to 3.0.1.1 or upgrade from 3.0.1 to 3.0.1.1:
  • Read the release notes associated with each product for information on fixes: RTC 3.0.1.1, RQM 3.0.1.1, and RRC 3.0.1.1.
  • Requisite Pro migration with RRC is only available with RRC 3.0.1.1.  See RRC 3.0.1.1 New & Noteworthy for details.
  • Many data warehouse issues where Oracle is the DB vendor are fixed with RTC 3.0.1.1 and RQM 3.0.1.1, thus we strongly recommend that you upgrade directly to 3.0.1.1 if you are still using RTC or RQM 2.x or 3.0.1.  The issues found range from errors in BIRT reports to missing tables in the DW schema for RQM 3.0.1.
  • If using SQL Server 2005 as the DB vendor for the data warehouse, there was an issue in 3.0.1 that caused the STAR ETL job to fail.  This results in a loss of trend data for trend based reports.  This is now fixed with 3.0.1.1.
  • RRC 3.0.1.1 fixes issues during upgrade related to Saved Filters, attribute groups with same identifier, external resources and issues with certain markup constructs.
  • RTCz improvements related to promotion capability (other than component promotion for ALL components).  See 169140 and 177648 for more details.

General

RTC

RQM

RRC (New)

Reporting

What are the supported upgrade paths for CLM 2011?

Supported upgrade paths

  • RTC 2.x -> RTC 3.0.1 which is equal to CCM 3.0.1 JTS 3.0.1 (new or shared among CLM 2011 applications)
  • RTC 3.0 -> RTC 3.0.1 which is equal to CCM+JTS 3.0 to CCM+JTS 3.0.1
  • RQM 2.x -> RQM 3.0.1 which is equal to QM 3.0.1 + JTS 3.0.1 (new or shared among CLM 2011 applications)
  • RRC 2.x -> RRC 3.0.1 which is equal to RM 3.0.1 + JTS 3.0.1 (new or shared among CLM 2011 applications)
  • JTS 3.0 -> JTS 3.0.1 (to allow installation of new apps independent of RTC 3.0 upgrade)

RQM 3.0.1 consideration

You can find the necessary requirements in the RQM upgrade documentation.

If you are upgrading from RQM version 2.0.1 iFix02 or higher, upgrade to version 2.0.1.1 or higher before exporting your 2.x data. Then, run the following repotools command to prevent potential errors with the export-import process.

Windows: repotools -repairRequests
Unix/Linux: ./repotools.sh -clean -repairRequests

NOTE:  Users of versions prior to 2.0.1 iFix02 can ignore this step.

Back to top

How many new databases will I need?

You can find guidance by referring to the upgrade topology examples.

For a full / new CLM deployment, you will need 4 databases:  one each for the QM and CCM applications, one for the Jazz Team Server (JTS) and one for the data warehouse.

For an upgrade of all CLM 2.x applications, you will need new databases for the JTS and the data warehouse.  For a RQM 2.x upgrade, it is recommended but not required that a new database be created. For a RRC 2.x upgrade, the RRC 2.x database will not be used in the 3.0.1 topology.  The RRC 2.x repository will be migrated to the Jazz Team Server 3.0.1 repository database as part of the upgrade process.

For DB2 and SQL server:

You must use separate databases for each application and JTS, but they can be hosted on the same or separate database servers

For Oracle:

  • You will need to plan for 1 db user for each application (QM and CCM) and the JTS
  • You will need to plan for 1 db user for the data warehouse
  • You must use separate users for each app and JTS, but they can be hosted on the same database, separate databases, or separate db servers
  • Using latest Oracle JDBC driver (currently 11.2.0.2.0) is required

Note: All CLM applications require the databases use UTF-8 for character encoding.

Back to top

Is there a specific order I need to upgrade in?

For most upgrades the answer is No.  You can upgrade the applications in any order.  However, there are outage considerations to be considered so plan the order in a way to minimize outage time.

One exception is in the case where the existing environment is using Rational Common Reporting or Rational Insight.  Refer to this topic for more information: Reporting and the upgrade process

Refer to this topic for more information:  Understanding the deployment and upgrade process.

Back to top

Do I need to upgrade all my applications at once?

No.  In fact, we recommend a staged approach in order to manage the complexity and outages.  Integrations to other 2.x products (RTC, RQM, RRC) will continue to work after any one of the CLM applications is upgraded to v3.0.1.

Back to top

Can I use Lifecycle Project Administration (LPA) with my 2.x applications?

No.  To benefit from LPA, applications must be at v3.0.x and be connected to a shared JTS.  Once the applications are upgraded to v3.0.1, LPA is compatible with the existing projects.

Back to top

Do I need to update my current 2.x Eclipse/Visual Studio clients to the latest? 

Yes for RTC.  If attempting to connect from a 2.x client, a dialog will open with instructions.
 RQM and RRC clients are now web-based.

Back to top

Do I need to update my RTC 3.0 clients?

  • The Eclipse and Visual Studio RTC 3.0 client and the ClearQuest synchronizer are compatible with CCM 3.0.1 (shared amongst several CCM instances).
  • The build engines for z/OS need to be refreshed

Note: RTC 3.0.1 client is not compatible with RTC 3.0 server

Back to top

I have multiple RTC servers upgrading from 3.0 to 3.0.1. When do I instruct users to upgrade their RTC clients to 3.0.1?

Instruct users to upgrade after you have upgraded the last RTC server.  The RTC 3.0 client can operate either against a RTC 3.0 or 3.0.1 server.

Back to top

What Eclipse level is required for RTC 3.0.1 clients?

RTC 3.0.1 clients are compatible with either Eclipse 3.5 or Eclipse 3.6.  Please check compatibility with other co-located products.

Back to top

Can I change server locations as part of the upgrade to CLM 2011?

  • The application can be moved to different physical machines as long as they keep the same public server root URI
  • Stable server URI can be preserved by DNS or reverse proxy.

Back to top

How can I change the public URI of my RTC/RQM/RRC or JTS server?

It is not currently supported to change the public URI.  Development is exploring possible workarounds for silo installations that will result in some data loss.

Back to top

I saw the article on jazz.net about link migration.  Will that not fix everything?

This was targeted to a specific use case where a Clear Quest (CQ) server is moved to allow fixing work item artifact links in the RTC repository.  This is not a general purpose server move solution, although it will likely be a part of any solution available in the future.

Back to top

Was the public URI required in RTC 2.x?

It was, but it was not enforced.  There may be instances where a server was configured without a public URI.  

We recommend you set it, and choose a common stable URL that users have been using to access the server.  An upgrade to v3.0.1 will fail without a public URI so you must configure a public URI for your RTC 2.x server prior to upgrading to v3.0.1.

Back to top

Is a public URI required in 3.x?

Yes.  We have added better guidance in the infocenter and in the server setup.  Setup also performs more validation to discourage configuring a potentially unstable URL (e.g., using an IP address, short name, localhost, etc).

Back to top

I have changed the public URI and it seemed to work.  What’s broken?

There are numerous internal references, such as links in opaque resources (dashboards, RTC enterprise extensions), project area URLs, user URLs, facts in the data warehouse, fully qualified URLs in plans or workitems, and others.  The development team is assessing the impact and possible workarounds.

Back to top

Is there some set of SQL commands I can run in the database to fix everything?

The structure of the database is an internal implementation detail.  The table structure is optimized for reads, and thus item contents are stored in blobs.  Additionally, the format of some resource content is opaque to the framework and component specific (e.g. binary, rdf, xml, etc).  There is not a trivial solution mechanism to reliably process all the data in the database.

Back to top

Can I use repotools export and import commands to do a server move?

Repotools export and import commands are for database migration:  e.g., migrating from one db vendor to another or from one version/platform of a database to another, where native backup and restore is not supported by the database vendor.  Generally the offline backup and restore facilities provided by an enterprise db vendor will be much faster than repotools export and import.

There is currently not any processing in repotools export or import that will fix all URL references.

Back to top

Can I move my database from one db server to another?

Yes.  The database location is configured in the teamserver.properties configuration file, and it is not persisted anywhere else.  Remember though that you want to minimize latency between the app server and the database server, and it is not recommended to distribute it over a WAN.

Back to top

I need to replicate a repository to a testing and staging environment.  How can I do that if I cannot change the public URL?

You can set up an isolated network where the hostnames are resolved to the test machine(s).  See http://publib.boulder.ibm.com/infocenter/clmhelp/v3r0/topic/com.ibm.jazz.install.doc/topics/c_upgrade_staging_env.html

Back to top

I have a test DB that I use to give demos.  I thought I could use export and import to put this on different machines or share it with others.  What can I do?

Choose a test host name for your URL, e.g, rtcdemo.example.org.  Anyone executing the demo can add this entry to their local hosts file and resolve it to the loopback address.

Back to top

Can I reuse an existing Rational Insight database as the common data warehouse?

Yes, but the database must have already been upgraded to be compatible with Rational Insight v1.0.1.1.  You will need to upgrade Rational Insight first when planning a CLM 2011 upgrade.

Back to top

How is the reporting data handled when upgrading?

  • RTC data mart continues to work until the common data warehouse is configured via JTS setup and the first ETLs run. When the Java ETLs run for the first time, (that is, when they detect empty target tables), they attempt to fill them in with historical information:
    • For Work Items, the history is re-computed from scratch, and there is no need to consult the data mart.
    • For SCM and Build data, there is a one-time migration of data from data mart to the data warehouse which preserves data history.
  • RQM upgrade requires additional repotools commands to be run.  Refer to this topic for more information:   Migrating report data from version 2
  • Existing Rational Common Reporting (RCR) or Rational Insight users should upgrade first before configuring the data warehouse.
Refer to this topic for more information:  Reporting and the upgrade process

Back to top

What is the meaning of ‘Data Mart’ mode vs ‘Data Warehouse’ mode on the Reports tab of the JTS Admin UI?

The reporting framework has a service property named “Data Warehouse Provider” which can have one of two values. These values affects which data warehouse is populated (the RTC 2.x-era warehouse, called ‘data mart’, or the new CLM 3.0.1.x warehouse called “data wareouse”), which ETLs run, and where BIRT reports get their data.

The new warehouse covers the entire CLM domain, whereas the data mart covers only the RTC/CCM domain and is primarily meant for those who wish to continue using BIRT with their existing RTC 2.x reports and do not plan to adopt RRDI.  The out-of-the-box RQM BIRT reports do not work in data mart mode.

The com.ibm.teamserver.*.datawarehouse.provider teamserver property values are as follows and correspond to the mode visible from the Reports tab of the JTS Admin UI:

  • Local (Data Mart Mode). This is the RTC 2.x-style behaviour, where the old-style data mart Java ETLs run and store information in the data mart. BIRT reports get their data from the data mart.
  • Remote (Datawarehouse Mode). This is the default on a new CLM 2011 installation. The new Java ETLs run and store information in the new data warehouse. BIRT reports get their data from the data warehouse.  In order to access the CLM data, it is recommended that RRDI be used instead.  If you wish to keep the BIRT reports, it is still possible

Note that even in Remote mode, some information is still stored in the local data mart, including the repository sizing/count information (we don’t have tables for these in the data warehouse), so it doesn’t truly get rid of the data mart.

If you plan to move to RRDI (and hence CLM), use the new warehouse.  It is an integral to the out-of-the-box reporting of CLM configurations.

Back to top


When a customer migrates, do they have to configure the data warehouse in the setup wizard?

No. There is a checkbox that allows you to skip the configuration of the data warehouse during the JTS setup wizard. One reason why you might want to do so is if you have RQM 2.x with RCR (and thus a data warehouse), but you’re upgrading RTC first. In that case, skip the configuration of the data warehouse until you upgrade RQM, and then you can carry forward the migrated RCR warehouse as your JTS’s data warehouse, shared amongst the upgraded RTC and RQM applications. Note that if the ‘skip’ is used, the ETLs will be disabled.  This means that there will be no snapshots taken place.  Your existing RTC 2.x BIRT reports will not have any ‘new’ data from after the upgrade JTS setup phase.

Back to top

Can the data warehouse be moved?

The data warehouse (DW) cannot be moved from one database vendor to another. (work item 160608).  Thus, if you start with your DW in Oracle, it cannot later be moved to DB2.  It is important to contrast the supported database vendors of CLM 3.0.1.x and RRDI since there are some database vendors that are supported for CLM 3.0.1.x but not supported by RRDI 1.0.2.  For example, SQL Server 2008 R2 is not supported by RRDI.  Once you select the DW for your CLM 3.0.1 environment, it cannot be moved without some loss of data.

Back to top

Can I upgrade to RTC v3.0.1 and leave the JTS at v3.0?

No.  If you have a distributed topology where the CCM and JTS applications were not in the same app server, you must upgrade the Jazz Team Server (JTS) to v3.0.1 prior to upgrading the CCM application (version 2.x or 3.0).

Back to top

Can I upgrade the applications to all use a shared JTS?

Yes.  Applications can be upgraded to all use a shared JTS.  However, existing application instances still need to be deployed to distinct app servers to preserve URL stability and avoid collisions on the ‘/jazz’ context root.

You must decide in the beginning of an upgrade where your JTS is located.  It cannot be changed later.

Note:  There can only be one RM application per JTS.

Back to top

Are there differences between a new CLM 2011 installation and an upgrade?

Yes.  A new installation can share the same application container because of the use of distinct 3.x context roots.  An installation for the purposes of an upgrade cannot share the same application container due to collisions on the 2.x application context roots (/jazz). 

Note:  The installer provides a panel to select using either the 3.x or 2.x context roots. 

Back to top

Can I use the upgrade wizard of Installation Manager to upgrade to CLM 2011?

No.  The upgrade wizard path is NOT supported.  A side-by-side installation or installation on a different machine must be completed in order to begin the upgrade migration process.

Back to top

Why does my server.xml have different EOL characters than the original one?

This applies to Windows Tomcat users.  During the first phase of the upgrade process, there are configuration files that are migrated from a 2.x or 3.0 application instance.  The upgrade process asks the user to compare the updated/migrated configuration files with the original ones.  For one of these files, server.xml, there is an issue with the EOL characters which makes them different.

There is a bug in the xalan transformer code that causes the updated server.xml file to have incorrect EOL for comments.  If one opens the updated server.xml in notepad (vs another editor which will correctly interpret the LF characters and display it correctly) it is very unreadable.  Using a more advanced editor will allow things look correct.

Defect:  CLM upgrade script mangles windows newlines in my tomcat’s server.xml (166203) comment 10

Back to top

Is it possible to complete an upgrade if I cannot mount drives in my existing 2.x environment?

Yes, it is possible.  Please refer to this article that discusses Advanced Upgrade scenarios: Advanced Upgrade Scenarios

Back to top

Do I need new licenses for CLM 2011?

Yes. There is a new licensing model for CLM 2011 that requires new licenses be installed. However, RTC 3.0 licenses WILL continue to work with RTC 3.0.1.

Back to top

Can I upgrade to CLM 2011 from a previous v3.0.1 beta or milestone driver?

No.  This is not supported.

Back to top

Can my applications share a JTS if they use different authentication realms?

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

Back to top

Why is this upgrade so difficult?  Will it always be like this?

The upgrade from the Jazz 2.x products to 3.x introduces a change to the basic Jazz deployment architecture, but not to the logical architecture.  The big change is the addition of the JTS as a real component of the deployed architecture. The JTS provides central administration including licensing and users.  In the past, the JTS functions were dispersed in each of the Jazz products, and thus administrative duties had to be replicated in each collaborating product.  Now as the Jazz products begin to get more widely deployed and adopted by our customers (and IBM as well), an individually deployed JTS allows us to scale more easily, and allows a greatly simplified administrative experience.

We don’t anticipate doing any more radical changes to the architecture in the future, so this should be the last time that the upgrade experience is this complex.  In the future we look to have the JTS, and all of the Jazz applications, be N+1 and N-1 compatible.  This will allow our customers to upgrade their Jazz applications one at a time, for a more orderly and measured upgrade experience.

Back to top

What will happen to my local work-item based requirements in RQM 2.x after I upgrade to RQM 3.0.1?

In RQM v3.0.1, requirements are no longer managed locally. They are managed in RRC v3.0.1.  There is a process which will migrate existing local work-item based requirements to a RRC v3.0.1. It is documented via this link: Migrating work-item based requirements.
Note:  You must install and configure RRC v3.0.1 prior to running this upgrade step.

Back to top

What if some of these local RQM 2.x requirements came from RequisitePro?

If you had IBM Rational RequisitePro requirements in RQM v2.x, follow this additional process to ensure that the requirement data in testing artifacts is accurate after the migration to RQM v3.0.1: Migrating Rational RequisitePro requirements

Back to top

I upgraded to RRC 3.0.1 and notice that some data has not been migrated.  What happened?

This could be the result of an issue with the way attribute group IDs were mapped in RRC 2.x when there were multiple RRC 2.x projects with attribute groups having the same group ID.  It is common to have two or more projects with custom requirement types of the same name.  When a RRC 2.x setup has this characteristic, artifacts with those types are not visible in 3.0.1 after the upgrade.  This is fixed with 3.0.1.1, thus upgrading directly to 3.0.1.1 would be the solution here.  See 46656: RRC 2.x to 3.0.1 migration – AttributeGroups can map onto AttributeDefinitions from other projects for more details.

Back to top

I upgraded to RRC 3.0.1 and I notice that my browsing experience with IE8 is sluggish, what can I do?

There is a memory leak when IE 8 is used with RRC 3.0.1.  Use Firefox 3.6 instead or ask support for additional information and options.  See
45763: IE8 continues to leak memory for more details.

Back to top

Is there any troubleshooting information available for a RRC 3.0.1.x upgrade?

Yes, check out this page on the Jazz.net wiki:  RRC3UpgradeErrors.  For any future updates related to RRC 3.0.1.x upgrade, periodically check the parent page:  RRC3Upgrade
 
Back to top

What changes, if any, are required if I have custom report templates for RPE in use wiht RRC v2?

See this technote for details:  
Custom Rational Publishing Engine report templates must be migrated to use the Rational Requirements Composer version 3.0.1 schema​

Back to top

I have errors that mention ‘Invalid consumer key’ either in the RRC Web UI or the server logs or I noticed that the User interface controls are disabled in for the setup wizard.  Is there any assistance for this?

See this technote for details: 
Troubleshooting issues with OAuth in consumer keys in Rational Requirements Composer version 3.0.1​

Back to top

My online migration failed.  What are my recovery options? Do I need to re-run the entire upgrade?

No.  The entire upgrade does not need to be re-run.  The way to recover from a RRC online migration failure is to restore the DB backup of the Jazz Team Server 3.0.1 DB that was made prior to starting the online migration.

Back to top

For more information

Here are some links to other Jazz.net articles and workshops that are available to assist with the CLM 2011 migration process.

Another excellent resource for Upgrade information is the CLM 2011 infocenter

Support

CLM Upgrading Knowledge Collection technote
Check the IBM Support portal for other technotes related to upgrade or the 3.0.1.x applications you have deployed.

About the author

Rosa Naranjo is a member of the Jazz Jumpstart team.  The Jazz Jumpstart team is a worldwide group of development specialists who bring new and advanced Jazz-based technologies to customers. Please direct feedback and comments to rosy@us.ibm.com

Copyright © 2011 IBM Corporation

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Wed, 16 Nov 2011