Getting Started with Work Items in Rational Team Concert

Last modified June 24, 2009
Build basis: Rational Team Concert 1.0 and 2.0

Summary

Work Items are the fundamental mechanism to track and coordinate development tasks and workflows and they provide the hub for linkage between the various artifacts in Rational Team Concert (RTC). This article describes how to create and manage work items.

If you already know the basics and want to skip ahead or find something else, here is the list of other Work Item related documentation:


Introduction

A Work Item is a generalized notion of a development task. Typical work item types are defects and tasks. You can easily add new work item types or extend existing types via the process specification.

The purpose of this article is to help you get started using Work Items and their user interfaces like the work item editor, the query editor and the query results view.

This article is organized along typical use cases:

We strongly recommend to first read these documents:

This article also assumes that a RTC server has been setup and you have access to it. Because work items exist only in the context of a project area, you must open a connection with an existing project area before creating any work item. You can use the JUnit example project setup wizard to create a sample database. To do so follow the steps in the Setting up the Jazz JUnit Example Project.

If you are not using the JUnit Example project but have created a new project area, you'll have to do some preparatory steps before you can use it with Work Items. For this please read: Configuring Project and Team Areas for Work Items.

If you want to go one step further and configure Work Items to the needs of your company or project, learn how Work Items can be customized in Work Item Customization.

Filing Bugs - Creating Work Items

Creating a new Work Item from Scratch

To create a new work item, select the New Work Item wizard from the File > New > Work Item menu item. The wizard allows to select the desired project area and work item type. The created work item is then opened in the work item editor.

The New Work Item toolbar action allows to select the desired type directly in the drop-down menu. If connected to multiple project areas, it is furthermore possible to create a work item for any project area, without changing the default project area. The default project area can be changed with the Make Default Project Area action in the New Work Item toolbar action drop-down menu.

New work item toolbar action

Here is an example of a work item of type Defect that has been in process for a while, so it's status has been changed to Resolved and the resolution has been changed to Fixed.

Work Item editor: Initial view

The work item editor has several pages:
When filing a bug (or creating a Work Item) these attributes are important: Additional attributes that are typically not set on creation but are assigned during work item triage or when working on a bug: Useful tips for working with the Work Item editor:

Other Ways to Create Work Items

There are several other ways to create new work items in Rational Team Concert:
Some of these actions provide an optional search for duplicates based on the selected text or artifact. If successful, you can discard the newly created (but not yet saved) work item and add yourself as a subscriber to the found work item.

Managing Work Items

Jazz provides rich functionality for managing work items. Here are descriptions and screen images of the primary components that can be used to manage work items.

Finding Work Items

Find Work Items by ID

Enter the work item's ID into the text entry field in the lower left corner of the workbench window and press [ENTER]. Alternatively, you can press Ctrl+Alt+W and enter the ID into the pop-up dialog. The history in the pop-up dialog allows you to quickly reopen a recently used work item.

Find Work Items by Textual Content

The same text entry field in the window trim allows to search the repository for work items that contain certain words.

Quick Search Trim

The fields where the word can appear are not limited to summary, description and comments, but include attachments, tags or the names of users that are related to a work item.

Some search hints:

The drop-down menu next to the entry field allows to limit the search scope to a specific project area and/or to unresolved work items. If the entry field contains some text, pressing the action icon will re-execute the query.

Alternatively, you can also press Ctrl+Alt+W, type some words into the pop-up dialog and select the work item from the results.

More full text options are available in the Artifacts Search page (Search > Jazz Text Search).

Find Potential Duplicates

You can try to find duplicates for a work item using the action (Find Duplicates Action Icon) in the Work Item Editor header or in the Description field header. In the Work Items View, you can use the context menu action Find Potential Duplicates.

Other ways to find existing work items that are similar to some content include:

Find Work Items by Filter Constraints

If you need more control over the query results, or if you want to save a query for future use, you can create a query in the Query Editor. New queries can be created by selecting File > New > Work Item Queryor by using the New Query action in the Work Items View, or by using the context menu in the Team Artifacts view. Alternatively, you can duplicate an existing query using the Duplicate context menu action, or by using Save As directly in the Query Editor.

Eclipse UI Query Editor

Start with a predefined set of conditions or "from scratch":

New conditions can be added using the Add Conditions action (). Each condition follows the same rules:

OR and AND clauses can be added using the Add Conditions action menu. A third option is to add a compact set of conditions for all attributes of a specific type. The User Group for example allows to create a query for all work items created by, modified by, owned by or resolved by a certain user. The attributes of such a group are always joined using OR.

You can check the results of the query by using the Run Button (or in RTC 2.0 by pressing Ctrl+R). The results are shown in the Work Items view. Providing a name is required to save the query.

Sharing Queries: If a query is useful for others, you can share the query with your team members, with individual users or (in RTC 2.0) with all project members. Switch to the Details page of the Query Editor and select a Team Area or some users in the Sharing section.

Defining Result Columns: Depending on the query, not all columns that are shown in the Work Items view by default make sense. You can choose a custom set of columns that will be shown every time you execute the query (both in the Eclipse UI and the Web UI). Switch to the Result Layout page and choose the columns and sort order that best suit your query results.

Tips for the Query Editor: For a description of more advanced query features, please see the article Advanced User's Guide to Querying Work Items.

Query Results: Work Items view

The Work Items view shows the work items resulting from a work item query.

The result list can be filtered by typing directly into the view: a text field appears and only matching work items are shown (Ctrl+F or pressing the filter button in the view header also opens the entry field, ESC dismisses it).

Queries can directly be run from the Work Items view toolbar (Favorites Button) once you have added your most often used queries to the Favorites domain. Clicking on the toolbar button brings up the Query Selection Dialog where you can choose from all available queries.

Columns can be added and removed using the view's Columns menu.

Links between work items can optionally be shown using the view's Relationships dialog.

Work Item view showing the filter field

Tracking Work Item Changes

In this section you will learn how to track changes to work items you have a relationship to. For instance, if you are the owner of a work item, you will have a strong interest in any changes to the work item, e.g. new comments that have been added. Another example is tracking the inbox of a certain component by staying informed when new work items for the component are created.

There are four common ways of tracking work item changes:

The section concludes with showing you how the Message @Me feature can be used to directly address comments from Work Items to a user. This feature is available since RTC 2.0.

Event Log in Team Central

Team Central provides the Event Log section that is capable of showing the contents of a news feed. Out of the box, you are subscribed to two feeds that list changes to work items:

The former informs you about changes to work items where you are creator, owner, modifier or subscriber. Thus, this feed is ideal to track changes to work items that are important to you. The latter feed informs about all the changes that occur in your team. This is useful to track what's going on for all of the team members. Clicking on a news item in the event log will open a separate window next to the section containing a detailed view of the changes. Multiple changes for the same work item are aggregated so that you can easily navigate through all changes at once. The event log will automatically show recent changes when they are available from the feed.

Event Log
Event Log in Team Central with the changes for a work item showing.

Timeline

The timeline shows all news items of a feed grouped by date. Any feed can be opened in this view, e.g. by double-clicking on the desired feed from the Team Artifacts view or the feeds-dropdown in the toolbar. A timeline on top indicates the actual number of events for a given date-range and will update automatically as soon as the feed reloads and new changes are available.

Timeline
The timeline listing recent changes to work items.

Notification Popup

If you want to stay informed for changes to work items even when you are working in another application while Rational Team Concert is running you can configure notification popups to show up. Open General | Notifications in preferences to set up notification popups for the category Feeds. The popups will show up in the lower right area of your desktop and clicking on them will open the application to show the change in full detail.

Notification Popup
A notification popup informing about a change to a work item.

E-Mail

It is also possible to be notified via classic E-Mails. The tab Mail Configuration is available from the user editor. This editor can be reached from the contextual menu on your project area (Open My User Editor). The configuration provides fine grained conditions under which an E-Mail should be send to you. Similar to news items in the event log, the E-Mail will list all changes that where made to the work item.

E-Mail Configuration
E-Mail Configuration in the User Editor.

Message @Me

Knowing that collaboration is essential in a distributed team, Rational Team Concert 2.0 allows you to address one or more colleagues when editing a work item. While writing a comment or description you can simply type '@' followed by the colleague's user ID. Content assist can help you to find the right user ID. Just press Ctrl+Space and begin typing the person's first or last name.

Message @Me from a Work Item
Creating a Message for a User from a Work Item

The addressed user will receive a Notification Popup and Event to make him aware of the message.

Alert for Message @Me
Receiving a Notification Popup for a Message @Me

Event for Message @Me
Receiving an Event for a Message @Me in Team Central

Work Item perspective

The Work Item perspective includes the Team Artifacts view, the Team Central view, the Work Items view, and the Tag Cloud view which are all useful when doing bug triage where you have to manage both work items and work item queries. The perspective is less important for an individual developer who only needs access to the work items that are assigned to him.

Team Artifacts view

The Team Artifacts view has a Work Item folder under every connected Project Area where you can find all work item queries stored in the repository. The "My Queries" folder contains your private queries, and the "Shared Queries" all predefined and shared queries.

Team Artifacts view showing predefined Work Item queries

The Team Artifacts view's top level Favorites node can be used to bookmark all "favorite" Jazz artifacts. This includes work items and work item queries. In addition you can create folders, which helps managing larger sets of favorites. So if you have too many private and shared queries under the Work Item node, you can keep only the frequently used ones under Favorites. To add an artifact as favorite, simply drag it on the desired folder under the favorites node. Alternatively, open the contextual menu on the artifact and select "Add to favorites". This will bring up a dialog to specify the location of the new favorite.
Some tips on how to effectively work with favorites:

The Team Artifacts view's top level Work Item History node remembers all work items that have been opened in the work item editor.

Team Central

Team Central is a view with multiple sections which gives you a quick overview of information that is relevant for your work, including builds, change set deliveries, or work item activity. A typical section shows a concise summary, and connects to another view or editor that presents the information in more detail.

Team Central view

There is no limit on how many sections you can add to team central. Here is some tips on how to manage them:

Query Sections
Query Sections can be configured with one or more queries to get a summary of each query's result count and how it varies over time. The counts can be broken down by a specific attribute (e.g. by Severity or most other built-in work item attributes).

The query sections can be configured by dropping queries onto the section or by using the configuration dialog from the section menu.

There is one predefined query sections (additional sections can be created using Team Central's menu):

Clicking on a bar shows the corresponding work items in the work item view.

Event Log Section

The Event Log section displays the content of one or more news feeds. By default Jazz has two preconfigured feeds that deliver events from the repository server to the client:

In addition to these preconfigured feeds you can define additional feeds and show them in the existing Event Log section, or create a new event section for them. Very useful are the so called Query Feeds which contain all change events for the work items specified by a work item query. You create such a feed by executing the Subscribe to Query Feed context menu action on a work item query. The feed will appear under the Feeds node in the Team Artifacts view. In the Event Log section you'll have to enable the newly created feed in the section's Feeds submenu.

The following is a list of ways to subscribe to more feeds:

Tag Cloud View

Use the Tag Cloud view to create a tag cloud. For a given query, a tag cloud displays the number of work items by tag attribute. To create a tag cloud, drag a query from the Team Artifacts view on to the Tag Cloud view. When you click a link in the tag cloud, the work items with that tag value appear in the Work Items view.

Tag Cloud view showing the tags of a query

Using the Web UI

Overview

When you initially load the Web UI, you will be shown a list of project areas to select. Clicking on a project area will show the default page for that project area, which is usually the Dashboards page. To load the Work Items page, click on the Work Items link in the header. The selected project area determines the queries displayed, search scope, and available new work item types used in the Web UI. You can change project areas using the Project Area selector in the upper right of the web page. When you change project areas, the entire Web UI will refresh, so you will reset all recently viewed items and, after being prompted, lose any changes that have not been saved. You can also load the Web UI directly to a work item or query result view from a URL stored as a favorite, sent in a message, or linked from another page. If you need to open the Web UI manually, you can use a URL similar to the following example:

https://www.example.com:9443/jazz/web

The web address ("www.example.com") and port ("9443") will be configured for your server. Often web sites are configured to automatically route you to the appropriate port so the port number does not need to be in the URL.

The Web UI works best with the supported web browsers. The RTC 1.0 supported browsers are described in Supported Web Browsers. The RTC 2.0 supported browsers are described in the RTC 2.0 Release Plan.

When loading a work item, the work item editor appears as follows:

Apart from header and footer, the Work Item Web UI is divided into two main parts:

The left navigation part provides quick access to

The sections in the left navigation area may be collapsed using the arrows in the section titles.

The right part is larger right and shows the editors and query results. The work item editor is shown above. The default configuration of the work item editor has four tabs: 

Useful tips for working with the web Work Item editor:

Good to know: After filling in the summary and description of the work item, you can press the "Find Potential Duplicates" button in the header. This will open a query result that shows possible duplicates of the work item. You can, and should, click the Find Potential Duplicates button before saving a new work item. To get back to your work item after pressing Find Potential Duplicates, use the browser's back button or select the original work item from the Unsaved Work or Recently Viewed sections in the left navigation. If you found a duplicate of your new work item before saving it, press the Cancel button to cancel the creation of the new work item. You can then return to the duplicate you just found by looking at the query result or work item in the recently viewed. You may wish to subscribe to the duplicate by clicking on the Subscribe Me button in the header of the work item.

Creating and Editing Work Items

Use the New Work Item button in the left bar to open a new work item editor. You can select the type of work item to open using the drop-down list associated with this button. Much of the functionality described in the rich client section about Creating a Work Item is available in the Web UI, too.

Good to know: Depending on the web browser used, when the Work Item editor has focus, you may press <Ctrl>+s to save a work item instead of using the Save button. Remember that depending on how your server is configured, whenever you save, an email notification may be sent to all subscribers.
You may bookmark the "New Work Item" link.

Recently Viewed and Unsaved Changes Lists

In the left navigation, there are two special sections called Recently Viewed and Unsaved Work. The Recently Viewed list shows the last query and several recent work items opened. When work items are changed, they are moved from Recently Viewed to the Unsaved Work list. These sections are more than just a list of links!  Unlike other Jazz artifacts, the data in the items in the Recently Viewed and Unsaved Work sections are stored on your web browser and when you navigate to these items they are shown immediately without getting the information from the server. For example when you open a query and then "drill down" into a work item, then from within that work item "drill down" into a related work item, the query and two items that you had just looked at remain in the web UI cache; when you use the back button on your web browser, "drill up", or select an item from the recently viewed list, you will switch very quickly among the views of these items. 


Good to know: Although the Recently Viewed and Unsaved Work lists provides for very fast navigation among the things you are currently working on, you must manually refresh these items to see the latest changes stored on the server.

Useful tips for working with the Recently Viewed and Unsaved Work:

The work items listed in the Recently Viewed list are listed by default in the "link to work item" dialog on the Links tab (e.g., when adding a "Related" or "Duplicate" work item).  Sometimes it is easier to use the quick search field or a query to find, then open a work item to add it to the Recently Viewed list before going to the Links page to associate two work items.  

For example, if you were assigned Defect 42 and you think is a duplicate of one recently assigned to you, you could:

Resolve a work item as a duplicate
Good to know: If you change the work item's state to "Resolved" and resolution to "Duplicate", a message will appear in the header. You can click on the message to create the "duplicate of" link.

Finding Work Items

Find Work Items by ID or Textual Content

Use the quick search field in the left bar and enter the ID of a work item to open it directly in the Work Item Editor.

Alternatively, enter some words that may appear anywhere in a work item's content to see a list of work items that contain those words.

Good to know: If you want to search for work items that include a specific number in the text, put the number in quotes.

Find Work Items by Filter Constraints (Queries)

If you need more control of the query results, or if you need to run the same query frequently, use the New Query link to open the Query Editor.

New conditions can be added using the Add Conditions button (). Each condition follows the same rules:

OR and AND clauses can also be added using the Add Conditions control.

Sharing Queries: If a query is useful for others, you can share the query with your team members or with individual users. In RTC 2.0, queries can also be shared with an entire Project Area. Switch to the Details tab of the Query Editor and select a Team Area or some users in the Team Area Sharing or User Sharing sections.

Defining Result Columns: Depending on the query, not all columns that are shown in the Query Results by default make sense. You can choose a custom set of columns that will be shown every time you execute the query (both in the Eclipse UI and the Web UI). Switch to the Result Layout tab and choose the columns and sort order that best suit your query results.

Query result view

The query result view shows you the most important work item attributes at a glance.


From the query result view you can click on an item to open a full editor on the item, or in RTC 2.0 you can click on the edit action (wi-button-edit.png) on the row to open an in-line editor on the work item in the row.
wi-inline.png

Edit multiple work items from query result view

In RTC 2.0 the query result view can also be used to change the attributes of multiple work items at once. To do this, create a query result then click on the update multiple work items action (wi-button-edit-multiple.png). In edit mode, select the rows to be updated and choose the attribute and values to update using the plus actions (wi-button-select%20attribute.png), then press the Run button (wi-button-run.png).

wi-edit-multiple.png