r8 - 2013-05-15 - 19:45:51 - StephanieBagotYou are here: TWiki >  Deployment Web > DeploymentTroubleshooting > UpgradeTroubleshooting > MigratingRequirementsManagementApplication

new.png Migrating the requirements management application

Authors: UpgradeTroubleshootingTeam
Build basis: CLM 3.x and later

This page will discuss the IBM Rational Requirements Requirement Composer (RRC) migration step during the upgrade

Migration types for the RRC 3.0.1.x to 4.0.x

Rational Requirements Composer requires a two stage upgrade process. The offline upgrade, using the upgrade scripts, and the online migration.

RRC Offline migration

The RRC offline migration consists of the rm_upgrade and jts_upgrade scripts. For the 3.0.1.x to 4.0.1, 4.0.2, the offline migration copies the fulltext search and JFS indices and merges configuration/properties files (Tomcat files, server.xml and web.xml files with the new version and copies the old version tomcat-users.xml file, teamserver.proprties files based on the information from the previous version, merges the old version friendsconfig.rdf file). The offline migration is a much simpler process when upgrading from RRC 3.0.1.x to 4.0.x. Unlike the upgrade from 2.0.1.x to 3.0.1.x, the offline migration does not move data from one repository to another (an RM repository to a Jazz Team Server repository) using the repotools export/import process.

RRC Online migration

During the online migration, RRC data is transformed (if necessary) to any new format conventions required by the new release. This was fairly extensive when ugprading from RRC 2.x to 3.0.1.x and typically very time consuming. For 3.0.1.x to 4.0.x, there is a small amount of transformation which takes place, primarily in the area of:
  • Folders which need additional information to handle the new permissions support
  • Types - some changes to the type system

This most noteable difference between the upgrade process from 3.0.1.x to 4.0.x and the online migration for RRC 2.0.x to 3.0.1.x is that the Rational Requirements Composer data is not reindexed in the former case if the 3.0.1.x indices can be used by the upgrade process.

Possible Problems in the RRC 3.0.1.x to 4.0.1/4.0.2 Offline and Online Migration

This section will discuss known issues or problems which can arise during the online and offline migration steps for RRC.


Absolute vs. relative paths for indices: When doing an upgrade, the indices from 3.0.1.x must be usable by the 4.0.1 upgrade process. As a result, indices must be moved when specified at a relative location. If an absolute path is used, than the index is maintained in the previous 3.x location, which is typically why the indices are either moved, or the server is re-indexed.
Changing from relative to absolute paths during the upgrade:
Changing index paths from relative to absolute will be unsuccessful unless the indices are copied from the location indicated by the relative location to the absolute location specified in the new configuration. Changing of the index location from relative to absolute should be made in the 3.0.1.x, prior to running the offline upgrade script process.


Using an absolute path is required with WAS installations. If the fulltext indices (com.ibm.team.fulltext.index.location from the JTS teamserver.properties) are configured with a relative path, the path will be located within the WAS profile (such as C:\IBM\WebSphere\AppServer\profiles\appsrv01) instead of the JAZZ_HOME location. The JFS indices (com.ibm.jfs.index.root.directory location from the JTS teamserver.properties) use the JAZZ_HOME property if its value is left as the default relative path.


Tomcat deployments exists within the JAZZ_HOME directory, but it is still recommended to use an absolute path for the indices. NOTE: Always back up the 3.0.1.x JFS and fulltext indicies prior to any upgrade. This could save valuable time if a rollback is required.


When the RRC upgrade is started, the repository is automatically set to READ ONLY mode and will remain in that state until the online portion of the Rational Requirements Composer upgrade is complete. This will prevent any 'lost writes' from occuring during the upgrade.

1. If any application is performing an upgrade, the repository will be in read-only mode

2. If an upgrade exits abnormally or is unsuccessful, read-only mode is effectively permanently. This will force the recovery of an earlier back-up and re-try in order to affect the upgrade.

Forcing read-only mode to be unset

This is not recommended unless the ramifications of forcing it to be unset are fully understood. Contact IBM support for more information.

License requirements for online migration

Ensure the appropriate licenses are available for the Rational Requirements Composer upgrade before you being the online migration. The online migration will fail if license requirements are not met.

RRC analyst license requirement

If the RRC Analyst license (Rational Requirements Composer - Analyst or Rational Quality Manager - Quality Professional-Floating) is not available the user will encounter a failure in the online migration portion of the upgrade. When the admin logs into the web UI migration page, an error will occur indicating that the required license is not present.

If the license was not assigned, it can be assigned in read-only mode.
The following operations are permitted while Jazz Team Server 4.x is in read only mode:

  • Upgrading the existing version 3.0.x licenses to their 4.x counterparts
  • Installing new version 4.x licenses which were not utilized for 3.0.x applications
  • Updating or altering user license assignments
See Install 4.0 license to complete the IBM Rational Requirements Composer on-line migration for more information

Functional user

The functional user rm_user requires the RM Application-Internal license for RRC online migration

Ensure that the 4.0 RM Application-Internal license is assigned to the rm_user before you start the RM online migration. For more information, see Work item 68474: RRC online migration fails with licensing errors for rm_user for more information. This license assignment is especially important if you are upgrading from a version 3.0.1.x release, because this error requires restoring from a backup and restarting.

Related topics: None

External links:

  • None

Additional contributors: BrettBohnn

Questions and comments:

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r12 | r10 < r9 < r8 < r7 | More topic actions...
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.