Guide for migration from Rational TestManager to Rational Quality Manager

IBM® Rational® Quality Manager is new breed of quality management (QM) software. It is a web-based test management tool that provides a collaborative and customizable solution for test planning, workflow control, tracking, and metrics reporting. It offers many advantages over IBM® Rational® TestManager. However, migrating from Rational TestManager to Rational Quality Manager needs to be well-planned and tested, particularly for large projects that include integrations with IBM® Rational® RequisitePro®, IBM® Rational® ClearQuest®, IBM® Rational® Functional Tester, and IBM® Rational® SoDA®. This article will help you plan and test your migration process.


David Hanslip, Senior IT Specialist, IBM

photo of D HanslipDavid has been a software engineering specialist with Rational software since April 1995. He has participated in many consulting, training, assessment, and product support assignments covering a wide range of domains, including telecommunications, engineering, finance, warehousing, insurance, and retail sales. Previously, David spent 20 years in the defense and aerospace industry. He holds a Master of Engineering Science degree.

19 October 2010

Also available in Chinese


For their testing process, many organizations have implemented some combination of IBM® Rational® RequisitePro®, IBM® Rational® ClearQuest®, IBM® Rational® TestManager, IBM® Rational® SoDA®, and IBM® Rational® Functional Tester, typically with integrations. This article refers to those, collectively, as the Rational SDLC tools, meaning software that supports the software development life cycle (SDLC).

IBM® Rational® Quality Manager is a completely new, web-based tool that provides unprecedented productivity and efficiency enhancements. To facilitate a smooth migration to it from these SDLC tools, this article will help you select the tools that you will need in the new environment and explain how to transfer test artifacts from the old environment to the new one, organize the test artifacts, and produce reports.


  • Instructions for tool installation and configuration are addressed in various product documentation and Help files, so that information is not covered here.
  • This article is based on Rational Quality Manager Version 2.0.1, ifix3.
  • The work on which this article is based did not include migration from IBM® Rational® Manual Tester. Therefore, related issues are not addressed here.

Why migrate?

Rational Quality Manager enhancements to test management support are too numerous to discuss here, but just glancing through the table of features and benefits online will show you that moving to Rational Quality Manager makes a great deal of sense. These three features are especially relevant:

  • Each tester's dashboard can include a personal task list that shows their assigned work plus a team event list that updates automatically as tasks progress. No task needs to ever “fall through the cracks” again.
  • Work status is kept up-to-date automatically without time-consuming polling of team members.
  • The wide variety of metrics that is available, which are also updated in real time, raises confidence in decision-making.

Then there's the obvious reason to choose migration: The functionality provided by Rational TestManager and Rational SoDA must be migrated to Rational Quality Manager, because support for these tools will end in the not-too-distant future (Rational TestManager has been withdrawn from the market and an end-of-support date formally announced). Continued use precludes upgrading to new versions of Rational RequisitePro, ClearQuest, and Rational Functional Tester.


Your migration from the Rational SDLC tools to Rational Quality Manager will be successful only with extensive consultation, trials, and planning.

Consider these issues

It helps to consider these issues:

  • Advanced requirements management and advanced change management. These are not supported by Rational Quality Manager. You might need to retain Rational RequisitePro and ClearQuest and integrate them with Rational Quality Manager if you need advanced requirements and change management capabilities. (The next Rational Quality Manager release, due in late 2010, offers much stronger requirements and defect management capabilities.)
  • Legacy data. The transfer of legacy data from Rational TestManager, Rational RequisitePro, and Rational ClearQuest can be complex, because older versions of these tools do not directly support migration or integration. Therefore, you must upgrade them to more recent versions before the migration is possible, which means you must consider these factors:
    • Migration of requirements from or integration with RequisitePro requires RequisitePro v7.1.1.
    • Integrating Rational Quality Manager with Rational ClearQuest requires ClearQuest 7.1 or later.
    • Rational TestManager v7.0.2 cannot be installed on the same workstation as the 7.1 versions of RequisitePro and ClearQuest.
    • Integration with Rational Functional Tester requires an adapter that is installed only in Rational Functional Tester Version 8.0 or later.
  • Customization. Rational Quality Manager offers the ability to customize test plan and test case templates, workflows, and work -item attributes. Although some customization might be required to support existing work practices, development and testing of these customizations can take considerable time and effort. If possible, postpone customization until after Rational Quality Manager has been in use for a while to allow users to get familiar with the new tool's capabilities.
  • Test case classification. You must specify an appropriate set of Rational Quality Manager category types and categories so that test cases can be rapidly located in the flat test case structure.
  • Reporting. You must find an alternative for creating reports that have traditionally been generated by using Rational SoDA, Rational TestManager, and Rational ClearQuest. Although Rational Quality Manager includes IBM® Cognos®-based reporting, development of new reports requires Cognos reporting authoring skills, and you will still need to replace Rational SoDA with the Rational Publishing Engine automated document-generation tool, which works with Rational products selected other products.

Hold a workshop with stakeholders

Hold a workshop with major stakeholders to help all involved understand the existing testing process (roles, tasks, and work products), current tool use, and the goals of migrating to Rational Quality Manager. Ensure that these goals are realistic, and manage expectations accordingly. For example, a desire to retire all SDLC tools might not be compatible with process support requirements.

In order to plan the migration and future tool use, it is most important to understand why particular use decisions have been made. If tools have been in use for many years, the reasons that decisions were made might have been lost or no longer relevant. Try to identify the rationale behind such decisions.

Requirements might also have changed, plus blind adherence to existing ways of doing things should be questioned, particularly if the use model can be simplified or if changes will mean that more functions can be migrated to Rational Quality Manager.

Before the workshop, it will be valuable to distribute questionnaires to stakeholders, asking these questions:

  • What Rational RequisitePro requirement types and attributes will be required in the future? What projects need to be migrated, and what reports are generated from RequisitePro?
  • What Rational ClearQuest user databases are in use? What record types, fields, state models, and hooks will be required in the future? What records will need to be migrated, and what reports are generated from ClearQuest?
  • What Rational TestManager test plans, test cases, test log folders and test logs, and test suites need to be migrated, and how can these be identified? What reports are generated from the TestManager tool?
  • What integrations are used among Rational RequisitePro, ClearQuest, and TestManager, linking ClearQuest records to requirements or test cases, requirements to test cases, and test logs to defects?

Review artifacts

Review process documentation and products of the existing test process and tool use. Be careful to ensure that where process documentation exists, it is actually being followed.

Review how requirements and test cases are organized to better understand the facilities that Rational Quality Manager will need to provide.

Obtain copies of all reports currently generated from the SDLC tools, and make sure that you understand how they are used in order to better understand the reports that will need to be generated by Rational Quality Manager.


You will need to make decisions about the tools that you currently use and how or whether you'll use them with Rational Quality Manager.


Rational ClearQuest is an enterprise-level change management tool. It provides extensive support for creating new record types, and customization of workflows, user interfaces, and notifications. You decision depends on your situation:

  • If ClearQuest is simply being used for internal defect tracking, and if the functionality being used is as it included in the software, responsibility for defect tracking can be moved to Rational Quality Manager.
  • If, on the other hand, defect tracking is heavily customized, or if limited access to defect tracking is being provided to external parties, ClearQuest will need to be retained for defect tracking.

You can use ClearQuest to provide limited functionality to external users without buying a license. This includes the creation of new defect records and the review of defect status.

Even if you are using ClearQuest for other change management activities, it might still be possible to move responsibility for defect tracking to Rational Quality Manager. Two options are available for integrating Rational Quality Manager with ClearQuest:

  • The ClearQuest Bridge tool, which you can use to maintain your defects in Rational ClearQuest and use Rational Quality Manager to view the defects.
  • The ClearQuest Connector tool, which you can use to maintain your defects in both repositories and synchronize information between work items in Rational Quality Manager and ClearQuest records.

In this example, we retained ClearQuest for change management and defect tracking and used the ClearQuest Bridge for integration with Rational Quality Manager.


Rational RequisitePro provides full support for requirements management, particularly the ability to link requirements of different types to establish traceability and thereby facilitate coverage and impact analysis. Rational Quality Manager provides support for only a single type of requirement. In many situations, particularly, less formal ones, this is sufficient. Therefore, if you are using RequisitePro to manage only one requirement type, you can move responsibility for requirements management to Rational Quality Manager.

Legacy data transfer

It is best to avoid transfer of legacy data if at all possible. The transfer adds complexity, only the latest artifact versions are transferred, and you might lose valuable data, relationships, and metadata. One option to consider is that of retaining the Rational SDLC tools for managing legacy data while using Rational Quality Manager for new data.

However, there are good reasons why you might want to transfer legacy data:

  • Existing requirements, defect records, test plans, and test cases might be required in the future, either for ongoing work or reuse in Rational Quality Manager.
  • Legacy data migrated to Rational Quality Manager provides an excellent basis for evaluating Rational Quality Manager, refining requirements for migration, organization, reporting, and customization, and development of future processes.

As previously discussed, older versions of the legacy tools do not directly support either migration to, or integration with, Rational Quality Manager. Therefore, consider these two options:

  • Upgrade RequisitePro, ClearQuest, and Rational Functional Tester as a separate activity prior to migration. Rational SoDA and TestManager will not be able to coexist on the same workstations as the latest versions of RequisitePro and ClearQuest. This upgrade should be planned and trials conducted, just as the migration to Rational Quality Manager will be. Testers, for example, will not be happy if their automated scripts no longer work and testing has to be stopped until the problem is resolved.
  • Copy all relevant artifacts (ClearQuest repositories, RequisitePro projects, test data stores, and Rational Functional Tester projects to a location with the latest versions of all of the tools (except Rational TestManager and SoDA). This is required anyway if work must continue on older tools while the migration strategy is developed and tested, but you can also use this technique to avoid upgrading the legacy SDLC environment altogether if the SDLC tools will no longer be required after the migration.

Make sure that this new environment is isolated from the existing production environment to avoid any chance of corrupting the existing production environment.


Whether you will use ClearQuest for tracking defects or not guides your decision here, too:

  • If defect data is to be transferred from ClearQuest to Rational Quality Manager, with ClearQuest no longer to be used for defect tracking, transfer of defect data can be achieved by using CSV files and the RQMExcelWordImporter, which available from (At the time of initial publication of this article, the RQMExcelWordImporter does not support the import of custom attributes.)
  • However, if you are going to retain ClearQuest, along with links between migrated Rational TestManager test logs and defects, you will need to migrate the ClearQuest schema and user databases.

Migration of data from, or integration with, Rational Quality Manager requires ClearQuest v7.1 or later.


This decision depends on whether you are going to maintain requirements data in Rational RequisitePro or transfer it to Rational Quality Manager:

  • If requirements are to be maintained in RequisitePro, with links to test cases retained after migration of the test cases from Rational TestManager to Rational Quality Manager, the TestManager Migration Tool will look after maintaining the links between requirements and test cases.
  • If requirements are to be transferred from RequisitePro to Rational Quality Manager, with RequisitePro no longer used for requirements management, the TestManager Migration Tool will migrate both the requirements and test cases and retain links between test cases and requirements in Rational Quality Manager. If RequisitePro is no longer required after the migration, you can simply leave it in place but create future requirements directly in Rational Quality Manager.

Migration of requirements from RequisitePro, or integration with it, requires RequisitePro v7.1.1 or later.

Rational TestManager

Rational Quality Manager provides a tool to import Rational TestManager data. You can use it to move all data of interest, and the mapping between the assets in each tool can be customized if necessary.

There are issues to consider when copying a Rational TestManager test data store for migration testing purposes. These will be addressed in more detail later in this article.


Current Rational SDLC users will typically use a combination of Rational ClearQuest reports and graphs, built-in Rational TestManager reporting, and Rational SoDA reporting.

As stated previously, Rational SoDA reports from Rational TestManager will generally need to be replaced by Rational Publishing Engine reports. The built-in Rational Quality Manager Common Reporting (RQM CR) capability is better-suited to business intelligence reporting and visualization. Where you used Rational TestManager reports that contained metrics information, RQM CR is a better option. Therefore, check whether the built-in RQM CR reports can meet reporting requirements as-is or with minor modification.

Rational Quality Manager offers business intelligence and reporting capabilities far beyond those provided by the legacy tools, with the ability to add reports to Rational Quality Manager dashboards. However, development and testing of these reports can take a significant amount of time and effort, so consider doing that only after migration, when you have a better understanding of what is available and what will be useful to you.

Develop a draft migration plan

Based on the decisions that your team has made, develop a draft migration plan that includes these elements in consultation with the users:

  • The creation of a migration test environment (covered in the next section) for migration testing and refinement of the migration process, Rational Quality Manager customization (primarily the addition of category types and categories to aid filtering, sorting, and grouping), report creation, demonstration, and user evaluation.
  • A test plan for validating the migration.
  • A schedule that allows time for contingencies:
    • Problems. Every SDLC user's environment is different, and you will inevitably have to deal with unique situations and challenges.
    • Learning your way around the tools if you are unfamiliar with them.
    • Setting up the test environment.
    • Trial migrations.
    • Customization.
    • Report development.
    • Demonstrations and evaluations.
    • The final migration. A weekend is ideal because this minimizes downtime.
    • Backup of all repositories before the final migration.
  • A risk mitigation plan.

Perform a trial migration

Performing a trial migration is essential. In complex situations, it might be necessary to perform several. You will need to set up a migration test environment for this purpose.

Create a migration test environment

Because successful data transfer can require experimentation and some migration processes can take a few hours (such as copying and migrating a large test data store), it might also be valuable to create a test environment that can be taken off-site, by using VMWare images, for example. This also allows customizations and reports to be developed off-site.

Set up servers

The migration test environment will need to be representative of the post-migration environment and will require a number of servers; two is a minimum:

  • One for Rational Quality Manager, ClearQuest, IBM® Rational® RequisitePro® (and application servers for Rational Quality Manager, Rational ClearQuest Web, Rational Functional Tester, and IBM® Rational® RequisiteWeb, the web client for RequisitePro
  • One for IBM® Rational® Reporting (and its application server) and the databases for Rational Quality Manager and Rational Reporting

You can find hardware sizing and operating system recommendations in the respective installation guides.

Set up the migration test environment

The process for setting up the migration test environment will be similar to the following steps:

  1. Install an appropriate web application server and database. If you are migrating a large test data store, the default Derby database will not be adequate.
  2. Install Rational Quality Manager, and configure the database and application server.
  3. Set up LDAP if it will be required. If LDAP is to be used in the production environment, it is essential that it be included in the migration test environment.
  4. Install the latest versions of Rational ClearQuest, ClearQuest Web, IBM® Rational® RequisitePro®, RequisiteWeb (the web client for RequisitePro), Rational TestManager, IBM® Rational® Functional Tester, IBM®Rational® Reporting (which is supplied with Rational Quality Manager), and Rational Publishing Engine. If ClearQuest and RequisitePro are to be retained, an enterprise database such as IBM® DB2® should be used; otherwise, Microsoft® Access will suffice.
  5. Install Rational TestManager on a different machine from ClearQuest and RequisitePro (see the notes that follow).
  6. Install applications to be tested, if required.
  7. Transfer existing data into the test environment. The ClearQuest schema and user databases and RequisitePro project databases and files will need to be copied. The Rational Functional Tester projects can also be copied from the existing production environment into the migration test environment.

Transfer the existing test data to the test environment

Now you're ready to transfer the Rational TestManager test data store into the migration test environment.

Copying of the test data store raises a number of issues. The test data store cannot be simply copied, because it contains internal references to its location. Therefore, follow these steps:

  1. Create a new Rational project in the migration test environment by using Rational Administrator.
  2. Create a new test data store and initialize it from the existing test data store. For a large test data store, this can take a number of hours. Initialize the users and groups from the existing project at the same time (see the notes that follow).
  3. Link to the ClearQuest database and the RequisitePro project.
  4. In Rational TestManager, delete all test plans, test log folders, and test suites that will not be required after migration. If there are large numbers to be deleted, the most efficient way to do this is to generate a Rational SoDA report that lists all of the test plans, test log folders, and suites in date order, and their last modification dates. Then delete all test plans, log folders, and suites after an appropriate date, and sort the list alphabetically to match the presentation in Rational TestManager. With the exception of suites, you can then select all of the artifacts to be deleted and delete them.
  1. Where test cases are linked to requirements or Rational Functional Tester scripts, requirement and test script locations are embedded in the test data store. Therefore, after copying the test data store, you'll need to update the locations in TestManager.
  2. After copying all legacy data to the migration test environment, ensure that all of the tools are working and that links between test cases and requirements, test cases and scripts, and test results and defects are intact.

Run the Data Store Doctor against the test data store before copying.


  • Rational TestManager cannot be run remotely. If headless servers and terminal sessions are being used, TestManager will need to be installed on a workstation.
  • If you do need to copy the test data store, test data, and users, Microsoft® Windows® has a 256-character path limit and might not be able perform the copy action if the test data store is large and has deeply nested folders. In that case, use a free tool, such as RichCopy. After copying, manually edit the project file, datastore.dat files, and project.dat files to point to the correct locations.

Perform the migration

Migration of Rational TestManager test assets is described in the Rational Quality Manager online help. The process is straightforward. Simply start the migration tool, and follow the instructions.

Tip: Capture the migration summary that is provided before migration actually starts.
If there are thousands of configured test cases, manual scripts, and test logs, migration could take several hours. A progress bar is provided, and you can also check progress details so that you can match the sequential numbers allocated to each test artifact against the pre-migration summary to ascertain exactly how far the migration has progressed.
Figure 1. Migration tool progress view shows the migration status of each artifact
Progress bar plus details view
  1. After the migration is finished, the migration tool presents another summary. Capture this and compare it with the pre-migration summary.
  2. It there are a large number of failures, you will need to investigate the causes.
  3. Review the migration log.
  4. If there were thousands of artifacts, this will be large, so search for occurrences of “failed” and “exception.” You will need to find satisfactory explanations for these. You might have orphan test logs, such as those with parent test cases that have been deleted.
  5. Finally, log in to Rational Quality Manager and ensure that the test asset totals match those in the post-migration summary.

If test input and automated test script locations were OK, you should have requirements migrated and Rational Functional Tester scripts created, linked to the actual Rational Functional Tester scripts.

Demonstrate and evaluate the new environment

It is essential to develop support from users for the migration. The best ways to do that are though user involvement. Before getting users involved though, develop a test case categorization strategy to replace the TestManager folder structure and develop some reports to replace those currently generated by Rational SoDA and Rational TestManager.

Develop a test case categorization strategy

You can use Rational TestManager to create hierarchical folder structures to organize test cases. Organization of the test cases into a rigid hierarchical structure of nested folders makes it difficult to take the test cases out of those structures and reuse them. Rational Quality Manager avoids this problem by using a flat structure, instead. Powerful categorization and filtering capabilities are provided so that you can organize and rapidly find test cases of interest.

By default, the migration tool will populate the Rational Quality Manager test case Category field with the TestManager folder structure. So, if the test case being migrated was in a Level 3 folder, the category field will contain “level 1 folder name/level 2 folder name/level 3 folder name.”

The default Category field is a useful aid to test case filtering, but where there are thousands of test cases, it will not be sufficient. Fortunately, Rational Quality Manager provides the ability to create new category types and categories. Just identify a set of category types and categories that adequately facilitates the user's ability to rapidly locate test cases of interest.

Figure 2 shows custom category types and categories. The category type was created by the Rational TestManager migration tool and shows the TestManager folder structure.

Figure 2. Test case list showing custom category types and categories created by the migration tool
Test Cases view with table

Larger view of Figure 2.

A much-needed enhancement is the ability to limit the scope of category types to individual test plans. Otherwise, new test plans will be burdened with old category types, and, over time, types will accumulate categories that are not relevant to new test plans. Filter bars on internal views, such as the test cases within a test plan, would also be useful, because a test plan could have many hundreds of test cases. The ability to present a subset of categories for selection, based on the value of another category type would be useful, too.

Develop reports

Redevelop the essential document reports in IBM Rational Publishing Engine and metrics reports, using Rational Reporting. Both are very powerful tools. But significant learning curves come with such increased power, so allow time for this.

Demonstrate the new environment

The new environment should be demonstrated to users of the existing SDLC tools.

Evaluate the new environment

Ensure that the new environment is thoroughly evaluated by users of the existing SDLC tools. If you are not a user of the existing environment, this is essential to ensure that no significant use cases have been overlooked.

Implement and review customizations

If the evaluation demonstrates the need for additional customizations, implement them and have them reassessed. This is particularly likely in the area of categorization. Postpone major customizations in areas such as test plan and test case templates, process support, and custom fields until users become more familiar with the new setup though real use.

Areas for future use and customization include manual script key words, manual step data, lab management, test case and test plan formal review, and enhanced reporting and use of dashboards Migrating test assets from Rational Manual Tester .

Finalize the migration plan and proceed

Update the migration plan with changes highlighted by the trial migration and any additional customizations that are required, and you're ready to proceed.

A smooth and successful migration from the Rational SDLC tools is easily achievable with adequate consultation with users, detailed planning, and trials. After the migration you'll be able to take advantage of the enhanced Rational Quality Manager collaboration, test planning, review, workflow, reporting, and dashboard capabilities.



Get products and technologies


  • Join the Rational Quality Manager forum, which also includes discussions about Rational Test Lab Manager.
  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups such as the Rational Café, and wikis.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Guide for migration from Rational TestManager to Rational Quality Manager