Context of this article
This article is the second of a multipart series that will explore IBM® Rational® Portfolio Manager integration with IBM® Rational® ClearQuest®. The focus of this article will be on the configuration of the Scope Mapping portion of a Rational ClearQuest profile in Rational Portfolio Manager and the resource mapping, covering both automated and manual methods. This article explains the use of the integration in both the Rational Portfolio Manager and ClearQuest tools. The next article will show how to customize a layout for a Project, Task, and a Scope Element types. The final article will discuss how to install and configure the middleware required to support this integration.
To recap from the first article, the configuration of Rational Portfolio Manager creates a mapping between Rational Portfolio Manager elements and Rational ClearQuest record types. These mappings define what information will be shared between the two tools. The first article focused on creating the task mapping, this is used to map Rational ClearQuest records (based on record type) to Rational Portfolio Manager tasks. It is also used for mapping Rational Portfolio Manager tasks to ClearQuest record types. This article will focus on the scope element mapping section, the completion of the profile and resource mapping.
If you haven't yet read the first article in this series (see Resources) , take the time to do that, because it discusses the basic concepts, history, prerequisites and how to configure the Task Mapping portion of a ClearQuest Integration profile.
Selecting a profile
- Log into Rational Portfolio Manager with a user name and password that has application administration privileges, and then click Sign in (see Figure 1).
Figure 1. Rational Portfolio Manager login screen
- Find and click Application Administration in the navigation menu (you may need to expand the menu by using the elevator bar).
Figure 2. Navigation menu
Alternatively, you can click the icon to expand the categories (see Figure 3).
Figure 3. Application Administration Icon with name displayed
- Use the right scrolling arrow at the upper-right corner of the dialog box to locate the ClearQuest Integration tab (see Figure 4). As of this writing, it is at the extreme right of the list of tabs.
Figure 4. Application Administration showing the ClearQuest Integration tab
- Click on the ClearQuest Integration tab to bring it to the forefront (see Figure 5).
Figure 5. Application Administration, ClearQuest Integration tab
There are two sub-tabs within the ClearQuest Integration: Mapping Profile and Integration Settings. By default, the Mapping Profile tab is usually displayed.
- Expand the category that you created in working through the first article. In the example, this is called Profiles2.
- Click on the profile that you started in the first article, which is called CQTask and SE (see Figure 6).
Figure 6.ClearQuest Integration tab with the Profile CQTasks and SE profile
Scope element mapping
Scope Element Mapping was introduced in the 7.1 version of Rational Portfolio Manager. It enables you to map the Rational ClearQuest record types into the Rational Portfolio Manager scope elements. Rational Portfolio Manager contains these scope elements:
- Change Request
- Service Request
Depending on your processes you may use some, all, or even none of these; you will need to map the various scope elements to ClearQuest record types. This is done through the Scope Element Mappings section in the ClearQuest Integration profile.
- Click the Add button in the Scope Element Mappings section (see Figure 7).
Figure 7. The Add button for the Scope Element Mappings section
A new row is inserted in the Scope Element Mappings section. The first field for Record Type is populated with a pull-down selection showing all of the record types available for the ClearQuest schema (see Figure 8). The default record type listed is always the first element in the drop-down menu.
Figure 8. Scope Element Mapping showing the drop-down menu
- Use the scroll bar to locate the desired record type. The example shown in Figure 9 shows Defect selected.
- Click in the next field, Scope Element Type, to enable the drop-down menu.
- From the list, select the Rational Portfolio Manager element type. This maps it to the selected record type. In the example shown in Figure 9, the arrow points to the Defect scope element type. Selection of this will then display it in the field.
Figure 9. Scope element mapping showing the Scope Element Type drop-down menu
The next field to be populated is Standard Fields. This contains a list of mandatory and optional fields. The mandatory fields are prefaced by an asterisk (*). You cannot assign the field mappings until these mandatory fields are populated.
- To access this field, click in the Standard Fields field.
- When an ellipsis (...) displays. click the ellipsis to see the Rational Portfolio Manager Standard Fields dialog (Figure 10).
Figure 10. Mapping shows the Rational Portfolio Manager Standard Fields dialog
When this dialog box opens, all of the fields are blank. Each field contains a drop-down menu with a list of all fields available for the ClearQuest record type (Figure 11).
- Using these context menus, populate the two mandatory fields and any optional fields.
Figure 11. Rational Portfolio Manager Standard Fields dialog showing the drop-down menu
Figure 12 shows an example with all of the fields populated. These are not recommendations, but merely an example that shows what type of information you might use. There is an additional check box at the bottom that will put the ClearQuest record URL into the Rational Portfolio Manager Documents portlet if it is selected. In this example, this has been enabled.
Figure 12.Completely populated Rational Portfolio Manager Standard Fields dialog
- After you have populated all mandatory and any optional fields, click OK. The field in the mapping will now contain this information.
- The next field should look familiar, because it contains the same name, Custom Fields. It also contains the same data. To access, click in the Custom Fields area. When an ellipsis displays, click the ellipsis to get the Custom fields dialog (Figure 13).
Figure 13. Rational Portfolio Manager Custom fields dialog box
- You populate this dialog in the same manner as you did for Task Mapping. Remember that these custom fields can contain only a small amount of data; therefore, check the short string or numeric fields (see Figure 14). The longer text fields can be mapped to an RTF Fields (rich text format) portlet in the next column of the mapping.
Figure 14. Populated Rational Portfolio Manager Custom Fields dialog box
- After you have selected all of the fields that you want displayed in Rational Portfolio Manager, click OK.
The last column to be populated is called RTF Fields. Again, this should look familiar, because it is similar to the RTF fields in the Task Mapping section. It contains 10 portlet names. These are defined in Rational Portfolio Manager in the Datafields tab > RTF sub-tab,
- Expand the Scope Element type (in this example, Defect was expanded) to show the list of RTF portlets (see Figure 15). If a portlet is undefined, such as 10 in the Rank column (Figure 15), you will not be able to input a mapping to that portlet in the ClearQuest profile mapping.
Figure 15: Datafields > RTF > Defect element expanded
- To access this field, click in the field labeled RTF Fields.
- Click the ellipsis when it displays to see the Rational Portfolio Manager Scope RTF Fields: Defect dialog (Figure 16).
Figure 16. Mapping shows the Rational Portfolio Manager Scope RTF Fields: Defect dialog
When this dialog box opens, all of the fields are blank. Each field contains a drop-down selection menu. Because these fields can contain a greater amount of data, map these to the multi-line fields defined in ClearQuest. Again, the selection menu contains a list of all of the fields available for the ClearQuest record type.
- Use the scroll bar to locate the appropriate field, and then select it (Figure 17).
Figure 17. Rational Portfolio Manager Scope RTF Fields: Defect dialog
- Continue to populate the RTF > ClearQuest fields.
- When you have populated all available fields, click OK.
You have now successfully mapped the scope elements. If you want to define more mappings, you will need to repeat these instructions, starting with Step 1 in this subsection, to create a new scope element mapping for each record type in Rational ClearQuest. Figure 18 shows a fully populated Mapping Profiles tab with multiple entries in both sections.
Figure 18. Populated mapping profile with multiple entries in both sections
Publishing a profile
The final step, from a configuration perspective, is to publish the profile. Remember, after you use this profile, you cannot modify it (unless you remove it from all projects that have been associated with this profile).
- To publish, select the check box in the Publish column next to the name of the profile (see Figure 19).
Figure 19. Published ClearQuest profile
Integration settings for resource mapping
- Next, in the Integration Settings tab in the Resource Mappings section, determine which resource mapping option to use (see Figure 20).
You will also find the middleware integration settings displayed in the Middleware Integration Settings section, but these are read-only fields. These settings are mastered in a properties file outside of the Rational Portfolio Manager client.
Figure 20. Integrations settings sub-tab
Automated resource mapping
Rational Portfolio Manager supports the security model defined in Rational ClearQuest. This means that if you do not have an authorized user login for ClearQuest, even if you have import rights within Rational Portfolio Manager, the import will not take place, and you will see the message in Figure 21. This is done through an integration bridge.
Figure 21. Invalid login notification
Rational Portfolio Manager gives you three ways for users to access this ClearQuest integration bridge:
- Email ID
- Login Name
Each of these is described when you select that option from the Resource Mapping area of the Integration Settings sub-tab. The Email ID is selected by default (see Figures 22 through Figure 24).
Figure 22. Resource Mapping using Email ID
For the Name field, there are two options:
- Full Name
- Nick Name (nickname)
The description field will reflect which object has been selected. The default value is Full Name (Figure 23).
Figure 23. Resource Mapping using Name, Full Name, or Nick Name
The final option is Login Name (see Figure 24). You can select only one of these methods for resource mapping, once you do select which method will be used it applies to the entire portfolio. Not all these fields used in the various methods are mandatory, so your process must reflect which option you select.
Figure 24. Resource Mapping using Login Name/Username
After you have determined which method you want to use, click the Apply Resource Mapping button (Figure 24).
A communication dialog displays indicating that the process has been started (Figure 25).
Figure 25. Communication Notification dialog
The Communication view will show if there are any Rational Portfolio Manager resources that cannot be mapped to a corresponding ClearQuest resource. This will give you the opportunity to resolve these before anyone starts to use the integration (see Figure 26). If there is no information in the Notification Comment area, this means that all resources in Rational Portfolio Manager have been successfully mapped to a corresponding ClearQuest resource.
Figure 26. Communication View showing unmapped users
If you have unmapped users, one of the possible reasons could be that objects (e-mail addresses, for example) used for the resource mapping may not have been populated in one of the applications. You can manually map them in Rational Portfolio Manager. You do not need to rerun the resource mapping function to do this, but make sure that the corresponding resource is available in Rational ClearQuest. The user must be subscribed to the Rational ClearQuest database, and the database must be upgraded to access those subscriptions. The instructions here do not cover how to create users in either application.
Manually mapping a resource
Using the list provided in the Communication view, you can manually map these users. If there are a large number of these, resolve the underlying problem (missing nicknames, e-mail addresses, and so forth), and then rerun Apply Resource Mapping from the ClearQuest Integration tab. However, if there are only a few that you need to map (as Figure 26 shows), then the manual method is an excellent alternative.
Note: To do this, you must have resource edit privileges.
- Open the Resource Management view, and then click Resource Management in the left navigation directory.
Figure 27. Resource Management view
- Expand the pool or pools, and locate the resource that needs to be mapped. Highlight and right-click this resource. The drop-down menu will display (Figure 28).
Figure 28. The Resource Management view with the resource menu displayed
- The Associate ClearQuest User dialog displays (Figure 29). Notice that the field on the left does not have a drop-down menu.
Figure 29. The Associate ClearQuest User dialog box
- Using the drop-down menu and the scroll bar, locate and highlight the ClearQuest user name that will be associated with the Rational Portfolio Manager resource name (see Figure 30), and click OK.
Figure 30. Selecting the ClearQuest user
The dialog box will close.
Validating all resource mappings
To validate that you have mapped all resources successfully, you can add a new header to the layout in the Resource Management view.
- Place your cursor on the highlighted area (any one is fine), and right-click the drop-down menu display.
- From this menu, select Customize Layout (see Figure 31).
Figure 31. Resource Management view with the drop-down menu displayed
- When the Customize dialog displays, select the Custom Fields tab (Figure 32), and then drag the CQ_UserName header onto the headers area.
Figure 32. Customize dialog box
A good place to drop this header is between the Indicators bar and the Quick Status bar. See Figure 33 for the correct placement.
Figure 33. Resource Management view showing the placement needed for adding a new header
- After you have added this header, be sure to save it (click the check box next to the layout name). When it has been successfully saved, you will see an X in that location.
You can now see all of the Rational Portfolio Manager resources and their associated ClearQuest user names (Figure 34). This is an easy way to spot any resources that are not mapped.
Figure 34. Resource Management view showing the CQ_UserName (ClearQuest) for various resources
This completes the configuration of Rational Portfolio Manager. The profile is now ready to use, and all users have been mapped and verified. The next stage is to associate the profile with projects and proposals. However, before you can add a profile to a project or proposal, you must modify some of the layouts so that you can see the information from Rational ClearQuest. The next article will describe how to modify layouts for three objects within Rational Portfolio Manager.
- Read author Debra Johnson's previous article in this series, Integrating IBM Rational Portfolio Manager and IBM Rational ClearQuest: Configuring the integration: Part 1, Task mapping .
- In Part 3 of this series, you'll learn how to customize layouts for this integration: Integrating IBM Rational Portfolio Manager and IBM Rational ClearQuest: Configuring the integration Part 3, Customizing layouts.
- To learn more about the integration of these products, sign in now for the Demo: Extending ClearQuest's Activity Management Capabilities with Rational Portfolio Manager.
- Visit the Rational Portfolio Manager area on developerWorks to find project manager content and resources.
- Visit the Rational ClearQuest area on developerWorks to find project manager content and resources.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download trial versions of IBM Rational software.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Keep up with the best and latest technical info to help you tackle your development challenges.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.