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

1. Log into IBM Rational Portfolio Manager (see Figure 1).

Note:
You must have Customize privileges for layouts.

2. Open the Work Management view and select a project.
3. Then open the Description View (double-click the project or select Description View from the main menu bar at the top).
4. After the Description View opens, click the Customize button located at the right of the layout name (see Figure 2).

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.

1. To add this portlet, click the Custom Portlets tab.
2. Expand the ClearQuest_Integration_Category (see Figure 3).

3. Drag the ClearQuest Integration title bar onto the layout:
   1. Highlight the ClearQuest Integration title bar in the Customize portlet dialog box.
   2. With the mouse hovered over this title bar, click and hold the left mouse button.
   3. Drag the cursor to the desired location in the layout form.

Note:
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.

4. Release the left mouse button when you've got it in the desired location and size.

See Figure 4 for an example of this.

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.

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:

1. Close the Customize Portlet dialog box by clicking the X in the upper-right corner.
2. Expand the portlet in the layout: Click the Restore button in the ClearQuest Integration title bar.
3. Reopen Customize Portlet dialog by clicking the Customize button:
4. Click the Fields tab, and then locate and expand Custom Fields (see Figure 6).

5. 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.

6. Drag the fields from the ClearQuest_Integration_WBS_Project into the ClearQuest Integration portlet that is now in the layout (see Figure 8).

Set the display order of the fields

You can set the order of the fields either by selecting the first field that you want displayed in the list, and then the next, and so on, or by setting the position as you drag and place the fields.

1. 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.

When you release the mouse, the field called Mapping Profile will be inserted above this existing field (see Figure 10).

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:

2. In the Customize Portlets dialog box, click the Portlets tab to change the focus to the portlet level.
3. In the layout, highlight the title bar for the portlet that you want to remove.
4. Click the left mouse button and hold it down while dragging the cursor to the Customize Portlets dialog box (Figure 11).

Tip:
Placement in the dialog box is not important.

5. Release the mouse button. The portlet has now been removed from the layout form.
6. Repeat these steps for all of the portlets that you want to remove.

You have completed all of the additions and subtractions to the layout form for a project or proposal.

7. You can now click the X in the upper-right corner of the Customize Portlets dialog to close it (see Figure 12).

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.

1. 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).

2. 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.

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.

1. Click in the layout Name field and type in an appropriate name.
2. 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.

You have successfully created a layout that will display project-level information for the ClearQuest integration.

Sharing the project layout

With Version 7.1.0.0 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.

1. 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.
2. To share just the layout displayed, click Share this Layout; to share all of your layouts click Share All Layouts.

3. 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.
4. 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).
5. Click Save. The Save dialog will disappear when the process is finished.

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).

Back to top

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.

1. Open the Work Management view.
2. Open a project.
3. Navigate to a task.
4. Open the task Description view.
5. Click the Customize button.
6. Add the ClearQuest Integration portlet in the same manner as described for the project.
7. 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).

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).

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.

1. 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.

These same names are used in the Customize portlet dialog box, and they have been circled in red in Figure 22.

2. 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).

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).

If the layout you are customizing does not contain this portlet, add it in the following manner:

1. Drag the Attributes title bar from the Customize Portlets dialog:
   1. Click and hold the left mouse button over the Attributes title bar in the Customize Portlets dialog.
   2. While keeping the left mouse button depressed, move to the layout pane.
2. Drop it onto the layout (the black border indicates where and what size the portlet will be when you drop it).
   1. When you have the position with the size and placement you want, release the left mouse button (Figure 25).

Tip:
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.

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 .

1. Hover the cursor over one of the existing headings (for example, Classification), and right-click.
2. From the drop-down menu, select Customize Layout (see Figure 27).

3. When the Customize dialog displays, click the Headers tab (Figure 28) to display the additional headers that you need for the ClearQuest integration.

4. 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:
.

You have completed all of the changes needed for the Attributes portlet.

5. 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.

Note:
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.

1. The final step is to save this layout (see Figure 30):
   1. Click in the Layout Name field, and type in an appropriate name.
   2. 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.

You have successfully created a layout that will display task-level information for the ClearQuest integration.

2. 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:

1. Click the Share button.
2. Select either Share this Layout or Share all Layouts from the drop-down menu.
3. Navigate to the appropriate directory.
4. Name the shared layout. Be sure to use something that will make sense later.
5. Click Save.

The Save dialog will disappear when the process is complete.

Importing layouts

1. 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).
2. Click the Share button.
3. Select Import Layouts from the drop-down menu to display the Import dialog.
4. Navigate to the directory where the layouts are located. This could be a shared directory or a portable drive, for instance.
5. Highlight the file to be imported (remember. it must have an .RPL extension).
6. Click Open.

The layout will be included in the list of layouts for this object.

Back to top

What's next?

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.

Resources

Learn

• Read the previous articles in this series, also by Debra Johnson, the author of this article:
  • Integrating IBM Rational Portfolio Manager and IBM Rational ClearQuest: Configuring the integration, Part 1, Task mapping
  • Integrating IBM Rational Portfolio Manager with IBM Rational ClearQuest: Configuring the integration, Part 2. Scope and resource mapping
  
  
• 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.
  
  

Discuss

• 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.
  
  

About the author

Debra 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.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Context of this article
• Creating the ClearQuest Project Description View layout
• Sharing the project layout
• Creating the ClearQuest Task Description View layout
• What's next?
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational ClearQuest
• Demo: Create customized queries with IBM Rational ClearQuest
• Webcast: Tips on achieving global IT efficiency through collaboration, automation, and project insight
• Briefing: Quality driven software delivery
• Buy: Rational ClearQuest

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers