Context of this article
This is the third in the series of articles on Implementing the IBM® Rational® Portfolio Manager and IBM® Rational® ClearQuest ®integration. It continues the focus of the previous two articles, which was on the configuration of Rational Portfolio Manager.
If you haven't yet read the first two articles in this series (see More in this series in the upper-left corner or Resources), take the time to do that first, because this article builds on the information and tasks completed in those previous articles. You will need to understand that information to proceed here.
In the first two articles, you went through the process of creating the profile, which included populating two sections: Task Mapping and Scope Element Mapping. You also set up how users would authenticate between Rational Portfolio Manager and Rational ClearQuest. Now that you have created a profile, you need to be able to use this profile. In order to do this, you need to modify the layouts in the Work Management and Scope Element Description Views to include Rational ClearQuest specific fields and portlets.
Depending on how you set up your profile you may need to modify just a couple of the layouts, or you may need to modify layouts for each object type available in Rational Portfolio Manager. This article will show you how to do these two basic types (the other types are modified in the same manner):
- Project (or Proposal)
- Task (or Summary Task or Scope Element)
First, not everyone may have the rights to do this. (If you do not see the Customize button (Figure 2) on the layout next to the Name field, then your company has not granted individual users this privilege.) In this case, you will need to schedule with your administrator or your report writer to create the ClearQuest layouts. Remember you cannot start using this integration until you can associate the profile to the project. The way you do this is the same, regardless of who actually does the work. If your company has set this up so that only a few people can make these changes, then as part of this process, they will need to publish these layouts to the people who need this information, such as yourproject and portfolio managers.
Creating the ClearQuest Project Description View layout
- Log into IBM Rational Portfolio Manager (see Figure 1).
You must have Customize privileges for layouts.
Figure 1. Rational Portfolio Manager login screen
- Open the Work Management view and select a project.
- Then open the Description View (double-click the project or select Description View from the main menu bar at the top).
- After the Description View opens, click the Customize button located at the right of the layout name (see Figure 2).
Figure 2. Rational Portfolio Manager Customize button
Your layout may look very similar to Figure 2 or completely different. What matters is that the customize function be available. You will start with an existing view and modify it to contain the information that you want for this view. You may want to remove all but the ClearQuest-specific fields and portlets, or you may want to have additional information available, as well.
Adding ClearQuest integration Custom Portlet
The Custom Portlet for the ClearQuest Integration is required, because it contains the field for assigning the profile, as well as other important information.
- To add this portlet, click the Custom Portlets tab.
- Expand the ClearQuest_Integration_Category (see Figure 3).
Figure 3. Custom Portlets tab on the Customize Portlets dialog
- Drag the ClearQuest Integration title bar onto the layout:
- Highlight the ClearQuest Integration title bar in the Customize portlet dialog box.
- With the mouse hovered over this title bar, click and hold the left mouse button.
- Drag the cursor to the desired location in the layout form.
The black-bordered box in the layout indicates the location and size the portlet will take when it is placed. This can take some finesse to get the desired size. In Figure 4, the portlet will show below the existing portlet called Financials and will be the width of the pane.
- Release the left mouse button when you've got it in the desired location and size.
See Figure 4 for an example of this.
Figure 4. Customize Portlets dialog open to the Custom Portlets tab
When you have added a portlet or field to the layout, it is removed from the Customize Portlets dialog. In Figure 5, the ClearQuest Integration portlet is now in the layout and no longer shows in the Customize Portlets dialog.
Figure 5. Screen view after moving the ClearQuest Integration portlet
Add custom fields
The portlet does not contain any fields when it is first placed into the layout form. The next step is to add the project-level fields to this portlet. If this portlet is not expanded, follow these steps:
- Close the Customize Portlet dialog box by clicking the X in the upper-right corner.
- Expand the portlet in the layout: Click the Restore button in the ClearQuest Integration title bar.
- Reopen Customize Portlet dialog by clicking the Customize button:
- Click the Fields tab, and then locate and expand Custom Fields (see Figure 6).
Figure 6. Customize Portlet dialog with Fields tab showing
- Expand the ClearQuest_Integration_WBS_Project in the Customize Portlets dialog box (see Figure 7). The fields shown in this folder will be used whether the layout is for a project or a proposal.
Figure 7. Expanded ClearQuest_Integration_WBS_Project folder
- Drag the fields from the ClearQuest_Integration_WBS_Project into the ClearQuest Integration portlet that is now in the layout (see Figure 8).
Figure 8. Drag the ClearQuest Integration fields
Set the display order of the fields
- To use the latter method, drag the first field from the list (see Figure 8), and then drag the second field onto the layout. This time, position the cursor so that it will place the field above the existing field. In Figure 9, the point of the cursor is above the Last Synchronized field.
Figure 9. How to insert a field above existing fields in the ClearQuest Integration portlet
When you release the mouse, the field called Mapping Profile will be inserted above this existing field (see Figure 10).
Figure 10. Fully populated ClearQuest Integration portlet
You may want to remove existing portlets from this layout. To do this, you need to drag those portlets onto the Customize Portlets dialog box:
- In the Customize Portlets dialog box, click the Portlets tab to change the focus to the portlet level.
- In the layout, highlight the title bar for the portlet that you want to remove.
- Click the left mouse button and hold it down while dragging the cursor to the Customize Portlets dialog box (Figure 11).
Placement in the dialog box is not important.
- Release the mouse button. The portlet has now been removed from the layout form.
- Repeat these steps for all of the portlets that you want to remove.
Figure 11. Removing portlets from a layout form
You have completed all of the additions and subtractions to the layout form for a project or proposal.
- You can now click the X in the upper-right corner of the Customize Portlets dialog to close it (see Figure 12).
Figure 12. Customize portlets dialog
Modifying Custom Portlets
You will notice that the field names are not fully visible. This can be resolved by dragging the column edge and expanding it. If you do this now, it will be saved as part of the layout definitions.
- Place your cursor over the center dividing column edge, click and hold the left mouse button, and drag the cursor to the right (see Figure 13).
Figure 13. ClearQuest Integration portlet showing placement of cursor to expand the left field width
- Release the left mouse button when the column is the appropriate width (see Figure 14).
There are two fields that are preset:
- Scheduled Synchronization Task
- Synchronize Precedence
The next article in this series, which is about using this integration, explains what these are and how to set them.
Figure 14. ClearQuest Integration portlet with modified column widths
You have successfully inserted the ClearQuest Integration portlet and fields into the layout. You can minimize this portlet or leave it open. This choice depends on how your company prefers the layout presentation to the user.
Saving the layout
This completes the modifications needed for the project-level layout. The final step is to save this layout.
- Click in the layout Name field and type in an appropriate name.
- Click the check box next to the Name field. as shown in Figure 15 (you may need to click twice).
When this changes to an X , the new layout has been saved.
Figure 15. Layout form
You have successfully created a layout that will display project-level information for the ClearQuest integration.
Sharing the project layout
With Version 220.127.116.11 and later of Rational Portfolio Manager, you can share layouts with other people. You no longer have to create them individually nor have them pushed from the server. This is helpful if a group needs a specific layout that may not be necessary for others in the company.
- When you have a layout that you want to share, click the Share button located near the Name field (see Figure 16). The Share drop-down menu displays.
- To share just the layout displayed, click Share this Layout; to share all of your layouts click Share All Layouts.
Figure 16. Share button with drop-down menu
- The Save dialog displays. Using the pull-down menu for the Save in field, navigate to a location to save the layout. This location can be on your local system, on a portable drive, or on a shared drive.
- Provide a name that will make sense to other users (or to you, because you might want to import this later). Important: The extension must be RPL (see Figure 17).
- Click Save. The Save dialog will disappear when the process is finished.
Figure 17. Save dialog box for sharing layouts
This completes modifying a project layout. Depending on your process, you may need a ClearQuest layout for proposals also. The process to create the layout is the same.
The next layout that you need to create is for the task (or summary task).
Creating the ClearQuest Task Description View layout
The basic process to creating a layout for a task, summary task or scope element is the same as what you did for the project, you must add the ClearQuest Integration portlet, then add fields to this portlet. There are additional portlets needed at this level that were not required for the project/proposal layout, these will be discussed later in this article. Let's first start with the ClearQuest Integration portlet.
- Open the Work Management view.
- Open a project.
- Navigate to a task.
- Open the task Description view.
- Click the Customize button.
- Add the ClearQuest Integration portlet in the same manner as described for the project.
- Then select the Fields tab in the Customize portlets dialog. The difference is that instead of selecting fields from the [Custom Fields] > ClearQuest_Integration_WBS_Project, you select from the [Custom Fields] > ClearQuest_Integration_WBS_Task (see Figure 18).
Figure 18. Customize portlets dialog > Fields tab
The list of fields in this folder is based on what record types and fields you have selected to include in all of your profiles on the ClearQuest Integration tab in the Application Administration view. This list can be extremely long. You need to decide if you want a rather standard layout for all of the profiles or if you want to set up layouts for each profile. If you use a standard layout, add all of the fields listed in the ClearQuest_Integration_WBS_Task folder to the ClearQuest Integration portlet (see Figure 19).
Figure 19. ClearQuest fields for a task
In Version 7.1.0 and later of Rational Portfolio Manager, you must move these fields to the portlet one by one. You can organize them as you move them, or you can do that later. You must have the Customize portlet dialog open in order this organization, if you decide to do this later. Refer to the section on setting the display order of the fields in this article for instructions on how to do this organization.
If you decide to make layouts based on the profiles and Task or Scope Element mappings, you will need to know which fields have been mapped in the Task Mapping > Custom Fields and Scope Element Mapping > Custom Fields sections of the ClearQuest Integration profile.
- If you have just a few mappings and profiles, this may be a good solution, because it will keep the number of blank fields to a minimum, given that none of the record types from ClearQuest have all of these fields defined.
- If you have a large number of mappings and profiles, you may be better off using a standard layout, because the number of layouts may become unwieldy and, ultimately, difficult to maintain.
The inclusion of the ClearQuest WBS Task portlet displays all of the information that was mapped from the Rational ClearQuest short string attributes in the profile's Task Mapping or Scope Element Mapping Custom Fields column. This does not display the multi-line fields that were mapped to rich text portlets; therefore, these portlets still need to be added to the layout.
Adding the rich text format (RTF) portlets
The rich text format portlets are included in the same manner as described earlier in this article for adding the ClearQuest Integration portlet. There are ten rich text portlets (RTF). The number you need to add to the layout depends on how many you defined in the RTF column of the Task and Scope Element mappings. You will need to know which ones you used, as well as the names of the portlets, because they may be generic names.
- Refer to the Datafields > RTF tab in Application Administration and the contents of the RTF column from the mapping. Figures 20 and 21 show examples of the Task and Defect definitions.
Figure 20. Datafields > RTF with Summary Task and Task expanded
Figure 21. Datafields > RTF with Change Request and Defect expanded
These same names are used in the Customize portlet dialog box, and they have been circled in red in Figure 22.
Figure 22. Layout for the Customize portlets dialog box
- Drag each portlet into the layout in the same manner as you did the for the ClearQuest Integration portlet, ensuring that you have the desired size for each portlet (see Figure 23).
Figure 23. Adding rich text portlets to the layout
Additional Rational ClearQuest information is displayed in the Attributes portlet. This portlet should be included as part of a ClearQuest layout.
Adding the Attributes portlet
If the Attributes Portlet is not in the layout, you will need to add it through the Customize process that has been used throughout this article (see Figure 24).
Figure 24. Customize portlets dialog
If the layout you are customizing does not contain this portlet, add it in the following manner:
- Drag the Attributes title bar from the Customize Portlets dialog:
- Click and hold the left mouse button over the Attributes title bar in the Customize Portlets dialog.
- While keeping the left mouse button depressed, move to the layout pane.
- Drop it onto the layout (the black border indicates where and what size the portlet will be when you drop it).
- When you have the position with the size and placement you want, release the left mouse button (Figure 25).
There are many different variations of placement and size you could use. However, because of the data, the full width of the pane works best. However, where it resides in the list of portlets is entirely up to you.
Figure 25. Rational Portfolio Manager Description view and Customize portlets dialog
This completes the additions to the layout. The last step is to modify the Attributes portlet to add the additional fields used by the ClearQuest Integration.
Modifying the Attribute portlet
If this portlet is not restored, meaning that you can see the contents of the portlet (Figure 26), click the Restore button for this portlet .
Figure 26. Location of the Restore button on the title bar
- Hover the cursor over one of the existing headings (for example, Classification), and right-click.
- From the drop-down menu, select Customize Layout (see Figure 27).
Figure 27. Customize Attributes layout
- When the Customize dialog displays, click the Headers tab (Figure 28) to display the additional headers that you need for the ClearQuest integration.
Figure 28. Additional headers available for attributes
- Drag both of these headers onto the existing Header bar.
Figure 29 shows how the cursor indicator changes to two green arrows when the correct location has been specified. Until the correct placement is identified, the cursor contains a circle with a diagonal line that indicates incorrect placement:
Figure 29. Attributes portlet showing correct placement when dragging the additional headers
You have completed all of the changes needed for the Attributes portlet.
- Now you need to decide whether you want the presentation of this portlet to be in an open or minimized state. If you want the portlet minimized, click the Minimize button the title bar.
One final thing to remember: Until you have associated a project with a profile and have imported records from Rational ClearQuest, all of the ClearQuest-specific fields will be empty.
Saving the Task or Scope Element layout
This completes the modifications needed for the task-level layout.
- The final step is to save this layout (see Figure 30):
- Click in the Layout Name field, and type in an appropriate name.
- Click the check box next to the Name field, as shown previously in Figure 15 (you may need to click twice).
When this icon changes to an X, the new layout has been saved.
Figure 30. Task Layout form
You have successfully created a layout that will display task-level information for the ClearQuest integration.
- Use this same method to create layouts for Summary Tasks and all Scope Elements that you mapped in the ClearQuest Integration Scope Element Mapping (see Part 2, cited in Resources).
Sharing the Task, Summary Task, or Scope Element layout
Sharing the layout is the same process as shown earlier in this article for sharing a project:
- Click the Share button.
- Select either Share this Layout or Share all Layouts from the drop-down menu.
- Navigate to the appropriate directory.
- Name the shared layout. Be sure to use something that will make sense later.
- Click Save.
The Save dialog will disappear when the process is complete.
- Open the Description view for the object that you wish to import a view for (you will need to do this for each object that you have new layouts to import).
- Click the Share button.
- Select Import Layouts from the drop-down menu to display the Import dialog.
- Navigate to the directory where the layouts are located. This could be a shared directory or a portable drive, for instance.
- Highlight the file to be imported (remember. it must have an .RPL extension).
- Click Open.
The layout will be included in the list of layouts for this object.
Now that you have created, shared, and imported the layouts, you have completed all of the steps for configuring the Rational Portfolio Manager integration with Rational ClearQuest. The next step is to associate a profile with a project. This is the first step in actually using the integration. The next article in this series will show how to establish this association and how you might use this integration.
- Read the previous articles in this series, also by Debra Johnson, the author of this article:
- 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.
- Go to the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- 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 trial versions of IBM Rational software.
- Participate in the Rational Portfolio Manager forum on developerWorks to post your questions and comments and to share your thoughts, ideas, and solutions with others who use this software.
- Check out the ClearQuest discussion forum on developerWorks Rational.