Introduction

Because it is also an IBM Rational product, IBM® Rational® Quality Manager keeps almost every feature of ClearQuest test manager and uses many of the same names and concepts. That makes migration much easier.

The Rational ClearQuest test manager feature

The IBM® Rational® ClearQuest® test manager feature is based on a traditional test platform that has been used for test asset management, including test case management, defects, and change-request tracking. It facilitates the development and test cycles by providing a common software platform form team members in managing software development issues.

ClearQuest test manager is highly customizable through the design of the schema, which is a collection of scripts and data stored in the schema database. The asset information is stored in the user database, which is an instance of the schema.

The Rational Quality Manager comprehensive solution

IBM Rational Quality Manager is a collaborative, web-based tool for comprehensive test management and test-driven development, based on the IBM® Rational® Jazz™ platform. Test teams can use it to define the comprehensive test plan, construct, run and reuse test cases and test scripts, exhibit test reports, and assist test analysis, and test lab management.

Rational Quality Manager is a full replacement for the IBM® Rational® Tester, Rational and Rational ClearQuest test manager.

Table 1 shows how test assets in the two product compares and lists the elements that can be migrated from the Rational ClearQuest test manager to Rational Quality Manager.

Back to top

Migration preparation

The migration plug-in, which is included in Rational Quality Manager installation, is a set of functional components for migration from ClearQuest test manager to Rational Quality Manager software.

Install the migration plug-in

The plug-in installation package is provided during Rational Quality Manager installation under $RQM_HOME\migration\ with name CQTM2RQMMigration.zip, and you need to install it to the ClearQuest test manager client.

1. Copy the plug-in package from your Rational Quality Manager installation machine (directory: <RQM_home>/migration/CQTM2RQMMigration.zip) to your ClearQuest test manager client installation machine.
2. Open the ClearQuest test manager client and launch the installation window. In the ClearQuest test manager client, select Help > Software Updates > Find and Install (Figure 1) to launch the Install/Update window.

3. Locate the migration package:
   In Install/Update panel (Figure 2), check Search for new features to install and then click Next to open the Install panel.

4. In the Install window, click New Archived site to locate the migration plug-in installation package.

This opens a file browser view to locate the plug-in installation package.

5. From the Install window (Figure 3), navigate to the file: CQTM2RQMMigration.zip file, which was copied in step 1:
   1. Select New Archived Site.
   2. In the next window, titled Select Local Site Archive, select the folder in which you have stored the zip file (such as Temp under the local directory, C:\).
   3. Then select the .zip file, and click Open to continue.

6. Click OK button and then Finish button to confirm the selection in the two windows that follow.
7. In the Updates window (Figure 4), check the box for RQM_Export Feature…, and then click Next to continue.

8. In the next window, accept the license and click Next to continue. Then click Finish to confirm the installation, and click Install All to install new features.
9. When the installation is finished, click Yes to restart ClearQuest test manager for the changes to take effect.
10. Verify the installation.
    1. Start the ClearQuest test manager client, and click the File/Export menu.
    2. Click the new menu item added to the menu, Export to RQM, to launch the CQTM to RQM Migration window.

The CQTM2RQMMigration plug-in is now installed.

Migration configuration file

Migration is a process that reads information from the source application, and then creates information in the destination application according to certain rules. To transfer and transform information between the two applications, mapping rules are mandatory. For CQTM2RQM, the mapping rules are defined in the migration.cfg file that is stored in the cqtm2rqm installation directory:

<cqtm2rqm_home>\plugins\com.ibm.rational.clearquest.testmanagement.rqmexport<version>\data\migration.cfg

The mapping rules defined in this file are good enough for basic use, so you can keep it unless you have special requirements that necessitate changing it.

There is a quick way to locate the cqtm2rqm_home path:

1. Click the Help > Software Updates >Manage Configuration in the ClearQuest test manager client to open the Product Configuration window (see Figure 6).
2. In the Product Configuration window, expand the IBM Rational ClearQuest node, and find RQM_Export Feature. The node name above that is the cqtm2rqm_home path, because the RQM_Export Feature is provided by cqtm2rqm plug-in.

3. Open Microsoft® Windows Explorer and enter the <cqtm2rqm_home> path, and then browse to \plugins\com.ibm.rational.clearquest.testmanagement.rqmexport*\data, where the migration.cfg file is stored.

In the migration.cfg file, the migration mapping relationships are defined by using field_mapping tags that contain these variables and sub-tags:

• Type: Defines the object name in ClearQuest test manager
• Target: Defines the object name in Rational Quality Manager
• Mapping sub-tag: Defines properties of the objects:
  • From: Defines the object property name in ClearQuest test manager
  • To: Defines the object property name in Rational Quality Manager.
    Note:
    For example, in the test case field mapping section, there is one line that the author highlighted in Figure 8:
    <mapping from="Headline" to = "dc:title"/>
    This means that the headline of test case in ClearQuest test manager will be migrated to title when created according to a test case in Rational Quality Manager.

The configuration file can be modified to match special migration requirements. For example, some useless lines can be deleted or commented out to avoid useless contents being migrated, mapping properties can be changed to match the actual relationship requirements, and so forth.

Back to top

Migration methods

Based on the migration plug-in, there are three methods for migrating testing assets from ClearQuest test manager to Rational Quality Manager:

End-to-end migration

This is the original, complete migration solution provided by CQTM2RQM migration plug-in. In this method, you just need to export the assets in ClearQuest test manager and then import them directly into your Rational Quality Manager project.

Export-manual import migration

Sample scenario

To describe these three migration processes, this section uses a sample scenario. This scenario contains a project with testing assets in ClearQuest test manager and an empty project in Rational Quality Manager. Every example in the migration instructions that follow is base on this scenario.

ClearQuest test manager asset sample as migration source

As the migration source, ClearQuest test manager provides a project that contains two test plans, several test cases and iterations, and so on. Figure 9 shows the structure of the project. "AssetReg" is the project name for this example. In ClearQuest test manager, it is called an Asset registry rather than a project.

The Rational Quality Manager project as the migration destination

In this sample scenario, a sample project named "MigrationPrj" is provided as the target project. Test plans and test cases will be migrated into Rational Quality Manager from ClearQuest test manager and managed under the MigrationPrj project.

Back to top

End-to-end migration

Launch the migration plug-in and choose an asset registry:

1. Log in to the ClearQuest test manager client and connect to the database where the assets that you want to migrate are stored.
2. Launch the migration plug-in as explained in the previous section (see Figure 5).
3. Asset Registries will be listed as selections in the CQTM to RQM Migration view. Click the assets that will be exported (choose AssetReg for this example), and then click the Next button to continue.

4. Configure the Rational Quality Manager server logon information.
   1. Make sure that the check box for Export to RQM Server is checked to export the assets to Rational Quality Manager directly.
   2. Enter the following required Rational Quality Manager information so that the migration plug-in can connect to Rational Quality Manager and perform the migration:
      • Rational Quality Manager Server Location: Enter the Rational Quality Manager administration console URL here:
        https://<hostname>:<port>/jazz/web/console/QM
      • Hostname: Replace <hostname> with the proper server name or IP address where your Rational Quality Manager server is installed.
      • Port: This is the port number of the Rational Quality Manager administration console (9443 is the default value). The port cannot be ignored, even though it is included in the URL.
      • Login name: This is the user name for logging into the Rational Quality Manager administration console. Proper authorization is needed for importing testing resources into Rational Quality Manager. The default is ADMIN.
      • Login password: Enter the password for the admin login name.
   3. Click Next after all required field are filled in.

The time required to connect to the Rational Quality Manager server depends on the network and computer performance. After connecting, a panel to choose the project is displayed.

4. 4. Choose the project created in Rational Quality Manager as the migration target (see Figure 12), and click Finish to start the migration.
   5. Optional: Check or uncheck computers, computer groups, configurations, and file attachments to import, or ignore those resources.

The migration progress and logs

The migration will take several minutes. It depends on how many resources there are, as well as the performance of the network and your machine. You can stop the migration at any time before it is finished by clicking Cancel.

When the migration completes, the log file will be displayed in a Notepad file. Read it to check which parts have been imported successfully and which failed.

Larger view of Figure 13.

Verify the migration result

After finishing the migration process, verify the migration result in Rational Quality Manager.

1. Use the username and password for the migration to log on to Rational Quality Manager, and make sure to choose the project used in the migration when you are asked to select a project to open (Figure 14).

You will see the Rational Quality Manager dashboard after you log in.

2. To open the test plan, click the Planning icon in the left column (Figure 15), and then click View Plans to open test plans.

3. Check test plans and their relationships with test cases.
   All test plans are listed in the views, such as "Migration Test" and "Environment verification" and so forth. Compare those test plans with the test plans in ClearQuest test manager Asset Registry to verify that all of the test plans are imported correctly.
4. Click one test plan to open it. Take "Environment Verification," for example, and click it to list all test cases associated with it in the left panel ("Environment setup 1" and "Environment setup 2"). Then compare these test cases with the ones listed in ClearQuest test manager to check the import result.

This method is suitable for migrating test assets from ClearQuest test manager to Rational Quality Manager directly with the migration plug-in. It is the most convenience method to perform the migration, especially when there is not much difference in testing assets management structures. Besides, it is very easy to change the mapping for special requirements before migration.

Back to top

Export-manual import migration

This section introduces the steps to migrate the example project from ClearQuest test manager to Rational Quality Manager by using XML files by following three steps:

1. Export the project to local files.
2. Import the local files into Rational Quality Manager, one by one. Add associations between the data manually (for example, the relationships between the test plan and the test cases.

Export to XML files

1. Launch the export panel:
   Log in ClearQuest test manager, and then select CQTM > Export > Export to RQM.
2. Select the asset registry:
   In the Export view, select the ClearQuest test manager asset registry, AssetReg, which was described in a previous section.
3. Specify the file location:
   In the CQTM to RQM Migration panel, check the second option, Export to file system, and then specify the location to store the XML files.

4. Click Next to open the window that lists optional artifacts that you can check (see Figure 18), and check all of the options.
5. Click Finish to start the exporting.

When the exporting is finished, export logs will show which records are exported in detail in Notepad.

6. Check the logs. (Figure 19 shows an example.)

7. Check the files:
   Open the directory where stores the files are stored. As Figure 20 shows, there are several subdirectories that include the XML files separately (for example: testplan, configuration, testcase, labresource).

Import into Rational Quality Manager

1. Open the Import Test Plans tab:
   Log in to Rational Quality Manager, and click Planning > Import Test Plans.

2. Import the test plan:
   Click Browse to open the File Upload view . In the directory that stores the XML files, select the testplan subdirectory (Figure 22). Choose one XML file and then click the Open button to import it into Rational Quality Manager.

After the file is imported, you will see a "Resource Created" message (Figure 23).

3. Follow the same steps to import other test plans.

4. Import test cases:
   Select Construction > Import Test Cases to import test cases, click Browse to open the File Upload view, and select the testcase subdirectory, so you can choose which test case to import into Rational Quality Manager (see Figure 24).

After it is imported, you can choose Construction > View Test Cases to find the test case in the Rational Quality Manager project.

5. Repeat the previous steps to import the other test plans and test cases.

Create associations

Besides importing test cases and test plans, the associations between test plans and test cases should be added manually.

1. Click one of the imported test plans, and then click the plus sign (+) icon (Figure 26).

2. In the View Builder pop-up panel (Figure 27), choose search filters and then click the Run button to search test cases. They will be listed in the Test Cases window.

3. Check the box for each test cases that belongs to the previous test plan, and then click OK to associate them with the test plan (Figure 28).
4. Repeat these steps to associate other test cases with test plans.

Back to top

Export-batch import migration

The Rational Quality Manager provides a batch import toolkit to import the data by batch. This tool kit can be integrated into the migration process as a third alternative.

In this method, you export testing assets data in ClearQuest test manager to XML files by using the migration plug-in, and then you use the import toolkits provided in Rational Quality Manager to import those XML files you're your Rational Quality Manager project.

Sample data and batch import toolkits introduction

Sample data is stored under <RQM_home>\samples\classics in XML format, such as Classics_TP.xml. (See Figure 29.) These files can be imported into Rational Quality Manager as samples for practice.

To import these files at one batch, Rational Quality Manager provides a batch command file named install_samples.bat under the same folder (install_samples.sh is for the Linux® operating system).

And then, the install_samples.bat file will call the import.bat file to import those files. The import.bat file is stored under RQM_home\tools\import (for Linuxsystems, the batch file is import.sh). You can learn from install_samples.bat to see how to use import.bat to import one test asset file into Rational Quality Manager (or see the "Prepare a batch command file" section for details).

Export assets from the ClearQuest test manager client

To export assets from the ClearQuest test manager client, see the Export-manual import migration section of this article for instructions.

Prepare a batch command file

Using a command line for importing What code Listing 1 shows is one line in a batch command file.

 [Import_Toolkit_Path\import.bat /S <Server_info> /U <RQM_User> /P <RQM_User_Password>
/A <Area_Name> /T <RQM_Resource_Type> /F <source_xml_name> /N <RQM_reource_No>

Where:

• Import_Toolkit_Path is the installation path of Rational Quality Manager import toolkits (D:\Program Files\IBM\RQM\tools\import, for example).
• Server_info is the Rational Quality Manager installation server name and port. You can use https://localhost:9443/ if you installed Rational Quality Manager on the machine that you are using for importing and the admin console port is 9443.
  Tip:
  Put the server info in quotation marks, because the URL contains special marks that have special meaning for a command line.
• RQM_User / RQM_User_Password means to use the Rational Quality Manager administrator user and password (ADMIN and ADMIN, for example).
• Area_Name is the target project for the importing. If there are spaces in the Area Name, please replace the spaces with a plus sign (+), for example: Quality+Manager, rather than Quality Manager.
• RQM_Resource_Type must be specific, because it is a very important parameter to identify which resource type in Rational Quality Manager is imported. The supported types are listed in the Table 2.

• source_xml_name is the source file name that will be imported into Rational Quality Manager. Remember these two things:
  • Every asset source file should be assigned with a correct asset type, for example /T testplan /F <testplan xml file>
  • Quote the file name by using "quotation marks" (like this) when there are spaces in the file name or path.
• RQM_reource_No is the identifier to be used in Rational Quality Manager for the asset. It is best but not mandatory for a resource to be given a number unless there are relationships between assets that need to be created when importing.

Listing 2 is an example of a command with all of the parameters that can be used to import one XML file into Rational Quality Manager.

"D:\Program Files\IBM\RQM\tools\import\import.bat" /S "https://localhost:9443/" /U ADMIN
 /P ADMIN /A MigrationPrj /T testcase /F D:/migration/testcase/CQUD00000003_testcase.xml
 /N CQUD00000003
    

Consider the relationship between resources

• What is the relationship?
  The relationship is a link between two resources. Take test cases and test plans for example: one test plan can be associated with multiple test cases. When opening a test plan, a list of test cases can open to view due to the relationship. Such relationships exist between many kinds of resources, from a test plan to test cases, from test cases to test scripts, from execution results to test cases or test scripts or execution work items, and so forth.
• Create relationships
  As an example, the relationship between test cases and test plans will be created to show how to create the relationships. As Figure 32 shows, there are two test cases, Login and Logout, which are associated with a test plan called "Classics Java II" in the example.

There are steps to do so. Take the test plan and test case, for example:

1. Prepare test case XML files. For example:
   .../testcase/Login_TC.xml
   and .../testcase/Logout_TC.xml
2. Prepare test plan XML files For example:
   .../testplan/ClassicII_TP.xml
3. Create a relationship in the test plan XML file to link the prepared test case XML files as child (subordinate).
4. Add the following two lines into the test plan XML file:
   <testcase href="../testcase/Login_TC.xml"/>
<testcase href="../testcase/Logout_TC.xml"/>>br/>
   Note:
   The arrow brackets are needed here in the start and end of the line.

<?xml version="1.0" encoding="UTF-8" ?> 
<testplan xmlns="http://jazz.net/xmlns/alm/qm/v0.1/">
 <title xmlns="http://purl.org/dc/elements/1.1/">Classics Java II</title> 
 <description xmlns="http://purl.org/dc/elements/1.1/" /> 
 <updated xmlns="http://jazz.net/xmlns/alm/v0.1/">2009-02-17T18:16:59.765Z</updated> 
 <state xmlns="http://jazz.net/xmlns/alm/v0.1/">com.ibm.rqm.planning.common.new</state> 
 <creator xmlns="http://purl.org/dc/elements/1.1/">ADMIN</creator> 
 <owner xmlns="http://jazz.net/xmlns/alm/v0.1/">unassigned</owner> 
 <testcase href="../testcase/Login_TC.xml" /> 
 <testcase href="../testcase/Logout_TC.xml" /> 
 </testplan>
    

Description of the file:

This file defines a test plan including references to two test case XML files as its child (subordinate). These references are used to associate these two test cases to the test plan when import the test plan XML file into RQM if this two test case XML file have been imported into RQM already. To note here, if these test case XML files have not been imported into RQM before importing the test plan XML file, the test plan will create in RQM without create any relationship to these two test cases and we must do association manually (to manually associate, please see the Create associations section for details).

5. Prepare batch commands to import above three files into RQM.

Note:
Test cases (linked resources) must be imported into Rational Quality Manager before test plans (the linking resource) to avoid any dependency problems.

"D:\program Files\IBM\RQM\tools\import\import.bat /S https://localhost:9443/ /U ADMIN
/P ADMIN /A MigrationPrj /T testcase /F Login_TC.xml /N "../testcase/Login_TC.xml"

"D:\program Files\IBM\RQM\tools\import\import.bat /S https://localhost:9443/ /U ADMIN
/P ADMIN /A MigrationPrj /T testcase /F Logout_TC.xml /N "../testcase/Logout_TC.xml"

"D:\program Files\IBM\RQM\tools\import\import.bat /S https://localhost:9443/ /U ADMIN
/P ADMIN /A MigrationPrj /T testplan /F ClassicII_TP.xml /N "../testplan/ClassicII_TP.xml"
    

Description of these commands:

The first two lines is used to import those two test case XML files into RQM previous to the third line which is used to import the test plan XML file into RQM. In this way to make sure the association described in Listing 3 can be created correctly.

6. Import the files.
7. Run the import batch commands to complete the importing actions.

Back to top

Benefits and limitations of these three methods

Table 3 is a summary of advantages, disadvantages, and suggestions for three methods, based on the preceding descriptions and our practice.

Disclaimer

It is not possible to make sure that everything stated here is as the same as your local environment.

Resources

Learn

• Information center: Customizing the migration of Rational ClearQuest Test Manager test assets.
  
  
• Information center: Installing Rational Quality Manager.
  
  
• Check the Rational Quality Manager page on IBM® developerWorks® for links to product documentation, articles, tutorials, courses, downloads, and other useful areas.
  
  
• For tips, read these developerWorks articles by Michael Kelly: For Managing your first project with IBM Rational Quality Manager (October 2008) and Getting started with IBM Rational Quality Manager (December 2008)
  
  
• Explore the Rational Quality Manager Information Center for technical details.
  
  
• Browse the IBM Quality Management page to learn more about what is available.
  
  
• Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
  
  
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
  

Get products and technologies

• Download the free trial version of Rational Quality Manager.
  
  
• Download these IBM product evaluation versions and get your hands on application development tools and middleware products from Rational®, DB2®, Lotus®, Tivoli®, and WebSphere®.
  
  

Discuss

• Join the Rational Quality Manager forum, which also includes discussions about Rational Test Lab Manager.
  
  
• Check the Rational Test Manager forum on developerWorks.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Lv Yang Qing is a staff software engineer who joined IBM China Development Lab in 2006 and now works there in SAAS MBPS in solution technology Level 2 support. He has more than 10 years of working experience as a software developer and tester in various fields, including banking, retail, and telecommunications. He is familiar with Rational testing products and has had one previous article by IBM developerWorks, China.

San Yun Fei, software engineer, joined IBM in 2007. She is working on solution performance testing in the SAAS department. She is interested in Rational Quality Manager and has done much investigation on Rational Quality Manager implementation.

Nie Song, software engineer, joined IBM in 2006. He has substantial experience in the design and administration of Rational ClearQuest test management and has been the administrator for that product in the MBPS department.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Migration preparation
• Migration methods
• End-to-end migration
• Export-manual import migration
• Export-batch import migration
• Benefits and limitations of these three methods
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational ClearQuest
• Demo: Create customized queries with IBM Rational ClearQuest
• Briefing: Quality driven software delivery
• Buy: Rational ClearQuest

Dig deeper into Rational on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers