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.
Table 1. Mapping from ClearQuest test manager assets to Rational Quality Manager assets
|ClearQuest test manager assets||Rational Quality Manager assets||Comments|
|Test plans||Test plans||Test plan describes the scope of the overall test effort.|
|Test cases||Test cases||Test case defines the functions or aims of the test.|
|Configured cases||Test execution records||Test execution records map the test environment information to the test case|
|Test suites||Test suites||Test suite is a collection of test cases|
|Manual test scripts||Manual test scripts||Test scripts must be performed manually|
|Committed test logs and suite logs||Test execution results||the execution details for a test run|
|Links to requirements||Links to requirements within test plans and test cases||Links between test cases and test requirements|
|Links to defects||Links to defects within test execution results||Links between test executions and defects|
|Iterations||Test schedules||Test durations, periods|
|Configurations||Test environments||The platforms will be covered in the test.|
|Computers||Lab resources||The resources can be used in the test|
|Computer groups||Resource groups||To track and manage the test resource|
|Association to automated scripts||Test scripts||Scripts created by other tools|
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
Before migration, it is mandatory that you upgrade ClearQuest test manager to Version 7.0.1 or later.
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.
- 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.
- 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.
Figure 1. Launch the installation wizard
- 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.
Figure 2. Install/Update panel
- 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.
- From the Install window (Figure 3), navigate to the file:
CQTM2RQMMigration.zip file, which was copied in step 1:
- Select New Archived Site.
- 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:\).
- Then select the .zip file, and click Open to continue.
Figure 3. Locate the installation package
- Click OK button and then Finish button to confirm the selection in the two windows that follow.
- In the Updates window (Figure 4), check the box for RQM_Export Feature…, and then click Next to continue.
Figure 4. Updates window
- 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.
- When the installation is finished, click Yes to restart ClearQuest test manager for the changes to take effect.
- Verify the installation.
- Start the ClearQuest test manager client, and click the File/Export menu.
- 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.
Figure 5. Verify the installation of the migration plug-in
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:
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:
- Click the Help > Software Updates >Manage Configuration in the ClearQuest test manager client to open the Product Configuration window (see Figure 6).
- 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.
Figure 6. Finding the cqtm2rqm_home path
- 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.
Figure 7. Location of the migration.cfg file
In the migration.cfg file, the migration mapping relationships are defined
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
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.
Figure 8. migration.cfg file example
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.
Based on the migration plug-in, there are three methods for migrating testing assets from ClearQuest test manager to Rational Quality Manager:
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
In this alternative method, you export the resources in ClearQuest test manager to XML files by using the migration plug-in, and then those XML files can be imported into Rational Quality Manager manually, one by one.
Export-batch import migration
In this method, the resources in ClearQuest test manager are also exported into XML files by using migration plug-in, and then those files are imported in a batch by using the command line.
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.
Figure 9. Asset example
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.
Launch the migration plug-in and choose an asset registry:
- Log in to the ClearQuest test manager client and connect to the database where the assets that you want to migrate are stored.
- Launch the migration plug-in as explained in the previous section (see Figure 5).
- 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.
Figure 10. Choosing the asset
- Configure the Rational Quality Manager server logon information.
- Make sure that the check box for Export to RQM Server is checked to export the assets to Rational Quality Manager directly.
- 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
- 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.
- Rational Quality Manager Server Location: Enter the Rational Quality Manager administration console URL here:
- Click Next after all required field are filled in.
Figure 11. Enter the server location and login information for exporting records
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.
- Choose the project created in Rational Quality Manager as the migration target (see Figure 12), and click Finish to start the migration.
- Optional: Check or uncheck computers, computer groups, configurations, and file attachments to import, or ignore those resources.
Figure 12. Project setting
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.
Figure 13. Migration progress and logs
Verify the migration result
After finishing the migration process, verify the migration result in Rational Quality Manager.
- 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.
Figure 14. Choose which project to open
- To open the test plan, click the Planning icon in the left column (Figure 15), and then click View Plans to open test plans.
Figure 15. Open the test plan in Rational Quality Manager
- 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.
- 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.
Figure 16. Checking test plans and test cases
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.
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:
- Export the project to local files.
- 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
- Launch the export panel:
Log in ClearQuest test manager, and then select CQTM > Export > Export to RQM.
- Select the asset registry:
In the Export view, select the ClearQuest test manager asset registry, AssetReg, which was described in a previous section.
- 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.
Figure 17. Select the option to "Export to file system"
- Click Next to open the window that lists optional artifacts that you can check (see Figure 18), and check all of the options.
- Click Finish to start the exporting.
When the exporting is finished, export logs will show which records are exported in detail in Notepad.
Figure 18. Check all of the options
- Check the logs. (Figure 19 shows an example.)
Figure 19. Export logs
- 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).
Figure 20. Verify the exported files
Import into Rational Quality Manager
- Open the Import Test Plans tab:
Log in to Rational Quality Manager, and click Planning > Import Test Plans.
Figure 21. Import Test Plans tab
- 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.
Figure 22. Select the test plan
After the file is imported, you will see a "Resource Created" message (Figure 23).
- Follow the same steps to import other test plans.
Figure 23. "Resource created" notice
- 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).
Figure 24. Select the test case
After it is imported, you can choose Construction > View Test Cases to find the test case in the Rational Quality Manager project.
Figure 25. View Test Cases
- Repeat the previous steps to import the other test plans and test cases.
Besides importing test cases and test plans, the associations between test plans and test cases should be added manually.
- Click one of the imported test plans, and then click the plus sign (+) icon (Figure 26).
Figure 26. Associate the test case with a test plan
- 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.
Figure 27. Search test cases in the View Builder
- 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).
- Repeat these steps to associate other test cases with test plans.
Figure 28. Associate test cases with a test plan
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).
Figure 29. Sample files
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).
Figure 30. Rational Quality Manager import tool kits
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.
Figure 31. Exported files
Prepare a batch command file
Using a command line for importing What code Listing 1 shows is one line in a batch command file.
Listing 1. Command for import action
[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>
- 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.
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.
Table 2. Rational Quality Manager resource type list
|RQM resource type||XML files folder|
- 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.
Listing 2. Example of a command with full parameters
"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.
Figure 32. Relationship example
There are steps to do so. Take the test plan and test case, for example:
- Prepare test case XML files. For example:
- Prepare test plan XML files For example:
- Create a relationship in the test plan XML file to link the prepared test case XML files as child (subordinate).
- Add the following two lines into the test plan XML
The arrow brackets are needed here in the start and end of the line.
Listing 3. Contents of XML file ClassicII_TP.xml which defines a test plan
<?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).
- Prepare batch commands to import above three files into RQM.
Test cases (linked resources) must be imported into Rational Quality Manager before test plans (the linking resource) to avoid any dependency problems.
Listing 4. Three command lines to import test case and test plan XML files into RQM in correct sequence.
"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.
- Import the files.
- Run the import batch commands to complete the importing actions.
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.
Table 3. Benefits and limitations summary
|End-to-end migration||Export-manual import migration||Export-batch import migration|
|Advantage||Strongly supported by the Rational Quality Manager migration plug-in. Very simple to use.|
|Disadvantage||Can't support special needs such as no network access to ClearQuest test manager or only part of resources needed to migrate.|
|Best use||Use this method to migrate ClearQuest test manager assets to Rational Quality Manager if there is any special requirement. You can then use other methods as alternative or additional solutions.||Use this method when part of the resources is missed in the migration and it is not necessary to perform the whole migration.||Use this only when there are not many resources in the project or
only a few parts of it need to be migrated.|
When there is no connection access to ClearQuest test manager, you can export test assets to XML files, and then copy and import them into Rational Quality Manager.
This can be an alternative to end-to-end migration.
It is not possible to make sure that everything stated here is as the same as your local environment.
- 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®.
- 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.