Integrating IBM Rational Portfolio Manager and IBM Rational ClearQuest: Configuring the integration, Part 1

Task mapping

Integration between IBM® Rational® Portfolio Manager and IBM® Rational® ClearQuest® links detailed development activities in ClearQuest with project planning and tracking in Rational Portfolio Manager. This article is the first of four (4) that will explore this integration. The focus of this article will be on configuring the Task Mapping portion of a ClearQuest profile in Rational Portfolio Manager.


Debra L.K. Johnson, Software engineer, IBM

Debra JohnsonDebra Johnson has been involved in the electronics and software industries for more than 20 years. She has worked as a test floor supervisor, programmer, support engineer, instructor, technical writer, maintenance tech, education courseware developer, and marketing engineer. She has been with the Rational software brand for nine years, working in technical support as an Advisory Engineer for SoDA and ProjectConsole, as well as in marketing. Currently she is a marketing engineer for the Rational Portfolio Manager, Rational SoDA and the Team Unifying Platform tools.

09 October 2007

Also available in Chinese


The goal of the integration between IBM® Rational® Portfolio Manager and IBM® Rational® ClearQuest® is to link detailed development activities in ClearQuest with project planning and tracking in Rational Portfolio Manager to help you achieve the following goals:

  • Import and synchronize ClearQuest records into Rational Portfolio Manager as summary tasks, tasks, and scope elements
  • Provide project managers with greater visibility and insight into development activities for more effective project management and resource capacity planning. This is accomplished by automating status or state information retrieval from ClearQuest, and updating the corresponding task actuals in Rational Portfolio Manager
  • Adopt better governance practices through more detailed project tracking, without making significant changes to existing processes and practices
  • Have the appropriate roles working with the appropriate tools (for example: project managers work with Rational Portfolio Manager while developers work with ClearQuest)
  • Automate updates into Rational Portfolio Manager scope elements, including creating, modifying, and deleting from the linked ClearQuest records

This article is the first of four (4) that will explore this integration. The focus of this article will be on configuring the Task Mapping portion of a ClearQuest profile in Rational Portfolio Manager. The second article will focus on setting up the Scope Mapping component of the ClearQuest Profile, along with customizing a layout for a Project, Task, and Scope Element. The third article will cover using the integration in both the Rational Portfolio Manager and ClearQuest tools. The final article will discuss how to install and configure the middleware required to support this integration.

Your goal when configuring Rational Portfolio Manager is to create a mapping between Rational Portfolio Manager elements and ClearQuest record types. These mappings define what information will be shared between the two tools. The vast majority of the sharing is from ClearQuest to Rational Portfolio Manager, though some information from Rational Portfolio Manager can be seen in ClearQuest. There are four (4) areas in the Rational Portfolio Manager Description view that are affected by these mappings:

  • Information portlet
  • Attributes portlet
  • ClearQuest Integration portlet
  • RTF portlets

There is a tab in ClearQuest called RPM Integrations. This tab will contain the information from Rational Portfolio Manager. For previous versions of Rational Portfolio Manager, there is another tab that is called RPM Schedule. If you have already installed and used the Version 7.0.x.x integration and migrated to V7.1.x, both tabs will be visible. But before you get started, you need to know what the prerequisites are for this integration.


Listed below are the main prerequisites for establishing and using this integration:

  • In order to use the integration with ClearQuest, your version of Rational Portfolio Manager must be 7.1 or later. Version 7.1 was made generally available on June 29, 2007.
  • IBM® WebSphere® (Versions 5.x, 6.x, or later) or Apache Tomcat (Versions 5.0, 5.5, or later) must be installed as the Application Server.
  • The Rational Portfolio Manager middleware must be successfully deployed.
  • ClearQuest must be installed.
    • The supported versions of ClearQuest are:
      • 2003.06.15
      • 2003.06.16
      • 7.0.0
      • 7.0.1 or later
    • The following components of ClearQuest must be installed:
      • ClearQuest database server
      • ClearQuest client installation on Windows®
      • ClearQuest Web client
      • ClearQuest Designer
  • The supported database types for ClearQuest (for use with the integration) are:
    • IBM® DB2®
    • Oracle
  • The Rational Portfolio Manager-ClearQuest package must be applied to the local ClearQuest replica (if you are using IBM® Rational® ClearQuest MultiSite®)
  • You have made the following changes to ClearQuest (this will be discussed in detail in one of the later articles of this series)
    • You have created a RPMCQOwner record type
    • You have created a ClearQuest user specifically for the integration
  • Data must exist in ClearQuest

Integration overview

Rational Portfolio Manager’s integration with ClearQuest was expanded in the V7.1 release. Understanding what this integration comprised for the to (hereafter referred to as 7.0.x) versions will lay the groundwork for understanding the changes that were implemented in V7.1. In the first release of this integration:

  • The integration could be launched from Rational Portfolio Manager at the following levels:
    • Proposal
    • Project
    • Summary Task
  • Any stateful ClearQuest record that has an owner field, regardless of record type, could be imported into Rational Portfolio Manager.
  • All imported record types will become Tasks in Rational Portfolio Manager (this means that these can not be imported as a scope element type).
  • Synchronization is triggered only from Rational Portfolio Manager, and you can trigger it at will (that is, manual synchronization only).
  • For synchronization in a ClearCase MultiSite environment, the API in Rational Portfolio Manager will locate the master record (based on access to all the replicas, which have been set up in advance through the System Administrator), and update the correct record.
  • You determine precedence in the case of conflicts.
  • There are two integration scenarios based on how the Rational Portfolio Manager object (Proposal, Project, or Summary Tasks) is set up:
    • Duration-based with %Duration Complete
    • Effort-based with Actuals
  • State changes are managed in ClearQuest
  • When a ClearQuest record is instantiated in Rational Portfolio Manager, the owner will be determined by the information provided in the Owner field in ClearQuest:
    • If there is an owner in ClearQuest, that user will become the Task Responsible in Rational Portfolio Manager
    • If the Owner field is blank, the user doing the import will become the Task Responsible in Rational Portfolio Manager (until such time as a new resource is assigned task responsibility)

The changes that were introduced in Rational Portfolio Manager V7.1 include:

  • All stateful Rational ClearQuest record types can be imported as the following objects in Rational Portfolio Manager:
    • Tasks
    • Summary Tasks
    • Scope Elements
  • Tasks in Rational Portfolio Manager can be exported to Rational ClearQuest based on the mapping defined in Rational Portfolio Manager.
    • How these get exported is based on the Task Mappings in the profile associated to the project or proposal
  • You can trigger synchronization on a schedule from Rational Portfolio Manager

Validating the Rational Portfolio Manager-ClearQuest page

Before starting to use the integration, it’s a good idea to validate that the correct package has been applied to the database.

Validating with designer privileges

If you have designer privileges, you can easily check this in the ClearQuest Designer by following these steps:

  1. Start ClearQuest Designer by selecting Start > Program Files > IBM Rational > IBM Rational ClearQuest > ClearQuest Designer.
  2. Log in with a Username and Password that has designer privileges.
  3. Cancel the dialog for selecting a schema.
  4. Click View > Schema Summary.
  5. Select the schema name that you want to review. To do this, use the scroll bar located in the Schema Name section to locate the schema name.
  6. Expand the folder and select the version number. Once you’ve made this selection, the right side is updated to reflect the selected schema, as shown in Figure 1.
    Figure 1. Rational ClearQuest Designer Schema Summary
    schema summary window
  7. Using the scroll bar in the Associated Packages window, locate the RPMCQIntegration package (see Figure 1).
  8. Verify that the package Version number is 1.3 or later.
  9. Once you’ve verified the package number on the schema, click OK to exit the Schema Summary dialog.
  10. Click File > Exit to close the ClearQuest Designer.

Validating without designer privileges

If you do not have designer privileges, you cannot view the packages installed on the schema, but you can still check that the correct integration package has been installed in the Rational ClearQuest database. To do this, do the following:

  1. Start ClearQuest by selecting Start > Program Files > IBM Rational > IBM Rational ClearQuest > ClearQuest.
  2. Log in with a Username and Password that has privileges to access the database.
  3. Select and run a query for one of the record types that has been enabled for the integration (such as All Defects).
  4. Select a record from the results of this query.
    1. There should now be a tab available called RPM Integration. Click this tab.
    2. If the ClearQuest package is V1.3, the form for this tab is broken into three sections. The bottom section (which contains the Parent record id field) was added in this version, as shown in Figure 2.
      Figure 2. ClearQuest client
      ClearQuest workspace showing parent record id field
  5. Once you have validated that the correct package has been applied to the ClearQuest database, you can exit the application by clicking File > Exit.

Validating this will ensure that you can create profiles that will use all of the new features found in Rational Portfolio Manager V7.1.

Creating the ClearQuest-to-Rational Portfolio Manager mapping profiles

Now that you’ve successfully validated that the correct RPMCQIntegration package has been applied to the ClearQuest schema and database, you can start configuring Rational Portfolio Manager. In order to use the integration, you must do the following in Rational Portfolio Manager:

  • Create ClearQuest Integration profile(s)
  • Create layouts for the various elements that include the ClearQuest integration information
  • Map the profile to Rational Portfolio Manager Projects

Create integration profiles

Follow these steps:

  1. Log in to Rational Portfolio Manager with a Username and Password that has application administration privileges, then click Sign in, as shown in Figure 3.
    Figure 3. Rational Portfolio Manager Login Screen
    image of log in dialog box
  2. When the application finishes loading, locate Application Administration in the navigation tree.
    Note: This tree may not be fully expanded. If it is not, then use the elevator bar above the tree to expand the tree, as shown in Figure 4. Click Application Administration once it is visible.
    Figure 4. Rational Portfolio Manager navigation tree
    image of workspace
    You can also click the Application Administration icon if you do not want to use the elevator bar (see Figure 4). This icon is located below the visible portion of the navigation tree. To determine which icon to select, hover over the icon and the name will display. Click the icon for Application Administration (this icon is usually the one farthest to the right, as shown in Figure 5).
    Figure 5. Application Administration icon with name displayed
    image of icon showing pop-up label
  3. On the General tab of the Application Administration workspace (the first one to the far left), enter the URL for the ClearQuest Web service. This is stored in the section called ClearQuest Integration located at the bottom of the tab.
    You may need to use the scrollbar located to the right to display this field. This field cannot be edited directly (even though it looks like it can). You must select the ellipsis (…) located to right of this field, as shown in Figure 6.
    Figure 6. General tab showing the ClearQuest Integration field
    image of workspace showing server URL field
  4. Once you’ve clicked the ellipsis, the ClearQuest Integration dialog displays, enter the URL for the ClearQuest Web service into the WebService Address field, then click OK, as shown in Figure 7.
    Figure 7. ClearQuest Integration URL dialog box
    image of dialog box showing Web Address field
  5. Use the right scrolling arrow (located at the upper right corner of the application) to locate the ClearQuest Integration tab, as shown in Figure 8. This tab is located at the extreme right of the list of tabs.
    Figure 8. Application Administration showing the ClearQuest Integration tab
    image of the workspace
  6. Click this tab to bring it to the foreground (see Figure 9).
    Figure 9. Application Administration ClearQuest Integration tab
    window showing ClearQuest to RPM mapping
    There are two sub-tabs within the ClearQuest Integration, Mapping Profile and Integration Settings. This article will first look at the Mapping Profile tab. There are two primary sections on this Mapping Profile sub-tab. One is for Task Mappings and the other is for Scope Element Mappings. If you want the flexibility to use either, you must populate both sections for the same profile.
  7. In order to do this, you must first create a Category, which can contain multiple profiles. Drag the Category icon into the left pane, as shown in Figure 10.
    Figure 10. Creating a new Category for the ClearQuest Integration
    image showing dragging of category icon
  8. Once you’ve created the category, type a name into the Name field, then press Enter.
  9. The next thing you must do is create a profile. To do this, drag the Profile icon onto the category that you just created, as shown in Figure 11. The tool will help you determine if you’ve got the correct placement. To check your placement:
    1. If you see the Drop icon...
      drop icon’ve aligned correctly under a category. Make sure before you drop that it is under the correct category, if more than one exists. You can now release the left mouse button.
    2. If you see the Do not Drop icon...
      do not drop icon do not have the correct placement. Move the mouse, which will drag the profile until you get the drop icon. Once you have the correct placement, release the left mouse button.
  10. The application creates a placeholder for the profile, as shown in Figure 11.
    Figure 11. Drag and drop for a profile on the ClearQuest Integration, Mapping Profile tab
    image of workspace with placeholder profile
  11. Type a name into the Name field for this profile. You will want a name that accurately reflects the type of profile being created. In the example shown in Figure 12, the name given is CQTasks and SE.
  12. Click Enter. Do NOT click the adjoining checkbox for Publish.
  13. Once you have created the profile, the Add and Remove buttons become activated in the main window (see Figure 12).
    Figure 12. The Task Mappings and Scope Element Mappings sections are now enabled
    image of workspace with enabled mapping fields

This allows you (as the administrator) to add or remove a record type that has been defined in ClearQuest. Behind the scenes, Rational Portfolio Manager will dynamically query the ClearQuest schema to determine what record types are available. Some examples of record types are:

  • Defects
  • Change Requests
  • Enhancement Requests
  • Test Cases
  • Test Plans

You may see many other record types depending on how your ClearQuest Schema was designed.

Adding a new record type

Starting with the Task Mappings section, add a new record type by following these steps.

  1. Click the Add button in the Task Mappings field.
  2. Use the drop-down menu and select the desired record type, as shown in Figure 13.
    Figure 13. Inserting a new record type into a profile
    image showing record type drop-down menu
  3. Once you’ve selected the record type (in this example, Defect will be used), move to the next field and use the drop-down menu to select what is visible for the Task Name in Rational Portfolio Manager, as shown in Figure 14. In this example, the Headline task name is selected.
    Figure 14. Select the ClearQuest field that will be used for the Task Name in Rational Portfolio Manager
    image of task name drop-down menu
  4. Move to the next field to the right, called Resource Name, and use the drop-down menu to select how the resource in Rational Portfolio Manager will be assigned (see Figure 15).
    There are two options: Owner and Submitter. Owner maps to the resource that has been assigned through the evaluation process (this is entirely dependent on your change control processes) as the owner of the record. Submitter maps to the resource that created the record in ClearQuest. In this example, the Owner field was used.
    Figure 15. Mapping showing the Resource Name field drop-down menu
    image of resource name drop-down menu
    The next field you will complete is % Complete. This field defines the percent complete based on the state of the record at any given moment in time in ClearQuest. These states are created and controlled in ClearQuest. These values are used when the duration-based scenario is selected.
  5. To access this dialog, click in the % Complete field. An ellipsis displays; click the ellipsis and the RPM % Complete dialog displays, as shown in Figure 16. (By default, all States are shown as 0% complete.)
    Figure 16. Mapping showing the % Complete default values
    image of RPM % Complete dialog
    These percentage values must be determined and agreed upon by the sponsor and users prior to implementation. This example uses the values shown in Figure 17.
    Figure 17. Populated "% Complete" table
    image of RPM % Complete dialog
  6. These values are examples and as such are not to be used as recommendations for your implementation. Once values have been added for each ClearQuest state, click OK.
    The next field is used to map some of the ClearQuest fields to Rational Portfolio Manager fields. The custom fields are short text fields that can only display a maximum of 400 bytes of text. These fields are good for displaying information like the planned iteration or id. These fields are not recommended to display fields that are multi-line (like the Notes Log, Description, or CQTMTNotesLogs, to name a few examples).
  7. Click in the Custom Fields label, which makes an ellipsis display. Click the ellipsis and the RPM Custom fields dialog displays, as shown in Figure 18.
    Figure 18. Custom Fields dialog box
    image of dialog box
    The list shown in the RPM Custom fields dialog box is the list of all of the fields available in the ClearQuest schema, regardless of their type (for example, short string, integer, and so on).
    Note: These fields are also created as custom fields in Rational Portfolio Manager as well. You will see them on the Custom Field tab (located at the same level as the ClearQuest Integration tab) > Fields sub-tab (Figure 19).
  8. In the Application Adminstration dialog, Custom Fields tab, on the Fields sub-tab, expand WBS/Scope and expand ClearQuest_Integration_WBS_Task category, as shown in Figure 19.
    Figure 19: Custom Fields tab showing the ClearQuest field definitions
    image of fields list
  9. By default, none of these fields are selected in the RPM Custom fields dialog box. Use the scroll bar located to the right of the dialog box to review the entire list of available selections. When making your selections, choose those fields that are defined as short strings or numeric fields.
  10. Select the ClearQuest fields the contents of which you want visible in the Rational Portfolio Manager Description view for the Task that is created when you import this record type from ClearQuest, then click OK, as shown in Figure 20.
    Figure 20: Populated RPM Custom Fields dialog
    image of selected RPM Custom fields
    The next entry that needs to be populated is the RTF fields. RTF stands for Rich Text Format. There are ten (10) of these for each task type (i.e. Task or Summary Task). These fields can contain up to 32K bytes of text; use these fields to display the multi-line text fields such as Status Update or Description.
  11. Click in the RTF field and an ellipsis will display. Click the ellipsis, and the RPM RTF fields dialog displays, as shown in Figure 21.
    Figure 21: RPM RTF Fields dialog listing the RTF fields for Tasks and Summary Tasks
    image of dialog box

The fields described in the RTF Field Label column were defined in Rational Portfolio Manager by the administrator. They are located on the Datafields > RTF tab, as shown in Figure 22. This tab is located at the same level as the ClearQuest Integrations Tab (similar to the relationship between Custom Fields and the ClearQuest Integrations tab).

Figure 22: Tab list showing Datafields
image of Datafields tab

If this list does not meet your needs (RTF Field Label), you will need to define these RTF fields prior to creating a profile.

  1. To complete the mapping for these fields, click in the ClearQuest Fields column for the RTF Field index that you want to set up. This enables a drop-down menu.
  2. Use the scroll bar located to the right of this list to locate the ClearQuest field that you would like to use, as shown in Figure 23.
  3. Click this field name. This will then be populated in the ClearQuest Fields column.
    Figure 23: Populating the ClearQuest field for a RTF Field Index
    image of Clearquest fields drop-down menu
  4. You will need to populate all the RTF fields in this manner. If you want the ability to see these for both Tasks and Summary Tasks, you will need to enter information into both index types, as shown in Figure 24.
    Figure 24: Populated RTF Field dialog mapping the RTF fields to ClearQuest fields
    image of populated dialog box
  5. Once you’ve defined all the mappings, click OK to close the dialog box.
    This completes the Task Mapping for one record type, as shown in Figure 25.
    Figure 25: Completed mapping for a defect record type
    image of workspace showing task mapping

If you want to define more record types, you will need to repeat these instructions for each record type that you need to define (starting with Step 7 of the Create Integration Profile section).

Working with profiles

There are two things that you need to keep in mind when you design these profiles.

  1. Once you have published a profile and have used it, you cannot make any modifications to that profile (nor can you click the various fields to view what you’ve done). If you hover over the field, you can see a partial list, as shown in Figure 26.
    Figure 26: RTF Fields shown by hovering
    image of pop-up text
    Note: You can expand the width of the columns in this view (see Figure 25), which will allow you to see more of the contents. You can then use the horizontal scroll bar to view each field, as shown in Figure 27. It is recommended that you document the profile in some manner, such as screenshots or a list, before you publish and use it.
    Figure 27: Location of scroll bar when column width has been expanded
    image of expanded column
  2. With Rational Portfolio Manager V7.0.x and V7.1.x, you can assign only one profile to any project. What this means is, if you want to associate multiple record types from ClearQuest to a single project; then the profile must contain a task mapping for each record type.
    When you’ve completed all of your Task Mappings, your profile may look similar to the example shown in Figure 28.
    Figure 28. Profile containing multiple task mappings
    Image of workspace with completed Task Mapping

This completes the Task Mappings section. All of your work will be saved, even if you leave the application.
Important: No one, including you, can access this profile to assign it to a project until it gets published. You can make modifications and changes to these mappings, as well as add new Task Mappings, only before it has been published and associated to a proposal or project.


You have successfully configured the Rational Portfolio Manager - ClearQuest Integration Task Mapping section of the profile. This will allow you to import ClearQuest record types defined in the profile into tasks or summary tasks within Rational Portfolio Manager. It will also allow you to export from Rational Portfolio Manager to the defined record types in ClearQuest.

In this example, you created a Task Mapping for the defect record type. By using these instructions, you can create multiple task mappings to meet your requirements. As you saw in Figure 28, you are not limited to one record type for a profile. This will give you the versatility to attach different ClearQuest record types to any one project based on what your process requires. Nor are you limited to one profile, though do keep in mind the information in the Working with profiles section.

While the profile is not yet complete, the next article in this series will show you how to finish the profile (including the Scope Mapping and Resource Mapping sections), as well as how to publish it. Part 3 of this series is how to customize a Description View layout for a project, task and scope element.

These customizations will give you (as a project manager) the capability to see the ClearQuest data that has been made visible through the profile(s), thus giving you easy access to your development data.



Get products and technologies

  • Visit the Rational Portfolio Manager area on developerWorks for project manager content and resources.
  • ClearQuest users and administrators can find more resources in the ClearQuest section of the developerWorks Rational zone, including ClearQuest hooks, Eclipse plug-ins, product documentation, articles and whitepapers.
  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.



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

ArticleTitle=Integrating IBM Rational Portfolio Manager and IBM Rational ClearQuest: Configuring the integration, Part 1