Chapter 1. Work Items

This chapter is an overview of work items; it is meant to set the right context for work items within the project development process. We shall go into the details of the work item elements in Chapter 3, “The Workflow,” Chapter 4, “The Data,” and Chapter 5, “Roles.” This book is not only about work items theory but also a practical introduction to ClearQuest and the Jazz-based products’ work item management. The terms used in ClearQuest and the Jazz work items are sometimes different, so we shall provide a comparison, along with some examples.

Currently (version 3.0) the Jazz-based products that include work items are Rational Team Concert and Rational Quality Manager.

1.1. Work Item Definition

A work item is created so that people having specific roles can perform actions within the process of creating or changing (software) artifacts. This definition is taken from Jazz.net, but we can adopt a more general definition that is related to any work done in any project.

A work item is an object that controls the process of performing work during software or systems development. The work item contains the following composite elements: data, presentation forms, workflow, and possibly other elements and other objects. Each of these elements will be described in detail in the following chapters.

1.1.1. Terms Related to Work Items in ClearQuest and Jazz

Table 1.1 summarizes the basic terms that are used in ClearQuest and the Jazz products. In the book we shall use terms from both, depending on the context.

Table 1.1. Comparing ClearQuest and Jazz Work Item Terms

1.2. Work Item Classification

During software project development each role performs various activities to build or modify different artifacts. Each work effort may require different flow or data during the process, thus requiring several work item types.

There are many types of work items, and you can create additional work items both with ClearQuest and with the Jazz-based products to fulfill the business requirements of your organization.

We can classify those work items as

• Change requests

• Activities

• Test elements

• Project-related work items

In the following sections we describe each work item class. We recognize that there may be other classes, depending upon the environment and the domain in which the business operates.

1.2.1. Change Requests

Change requests are work items used to track, document, and govern the process of changing a product. Examples of changes are

• Defect: an error in the product that should be fixed, also called a bug by optimistic people

• Enhancement request: a request to improve or add functionality to an existing feature of a product

• Feature: a request to add a new feature to a product

Different change request types usually have different data fields and different workflows; in many cases the different types are realized in a single work item type. When realized in a single work item, include a field that identifies the type, as shown in Figure 1.1.

Figure 1.1. ClearQuest work item type selection

1.2.2. Activities

Activities are work items assigned to team members to perform various types of work or tasks. Activities are broken down into subclasses:

• Activities used for general project tasks, such as installation, setup, data imports, training, and so on

These work items are usually called tasks or activities. Their workflows are simple and have very few states and actions.

• Activities used to break down change requests into smaller work elements

The best way to explain this is with examples. An enhancement request is usually split into several activities when there is a need to deal with several artifacts such as a design model, code, and documentation; because different artifacts are owned by different roles, each activity is assigned to a different role. Another example is when an enhancement request is related to a few domains, such as components owned by two teams, both hardware and software; each child activity is assigned by role to the relevant solution provider.

• Administrative work such as defining new users and groups or organizing non-project activities (education, department social events, and so on)

In the ClearQuest ALM schema, activities are children of tasks, and tasks are children of requests. Figure 1.2 shows the ClearQuest Web client form of the ALMTask work item (id=0111). This record has two children of type ALMActivity. The ALMActivity (id=0114) was created for software development, and the ALMActivity (id=0115) was created for software testing.

Figure 1.2. ClearQuest work item of type ALMTask with children of type ALMActivity

1.2.3. Test Elements

Although often not considered as work items, test objects have their own lifecycle, data, and forms and thus conform to our definition of work item. We can identify several test work items; the obvious ones are test plans and test cases. In ClearQuest Test Management (CQTM), these objects are state-based record types just like defects and enhancement requests. A test case is created, assigned to a role, reviewed, implemented, and approved (for execution in a specific release) and thus has a workflow.

In Rational Quality Manager the test plan and test case objects also have a lifecycle, but they are of a different type from the other Jazz work items such as defects, enhancements, and requirements. In the Jazz foundation, test plan and test case are not considered work items and do not appear in the work item list, although they have all the elements that conform to the work item definition.

Test elements are described in detail in Chapter 10, “Test Management and Work Items.”

1.2.4. Project-Related Work Items

If you are interested in Application Lifecycle Management (ALM), you should consider additional work items that govern projects, such as risk, release, build, promotion, and other elements of the lifecycle.

• Risk work item

The risk work item is part of risk management; its function is to control the process of capturing system risk, assessing the risk level, proposing solutions, and mitigating the risk. This work item is often linked to other work items such as features and enhancement requests that may introduce risks to the system.

• Release work item

The release work item controls the release process, the release content, dates, and responsibilities. Release content is derived from other work items such as defects, enhancement requests, or features. Target dates of the release work item are usually related to the project timeline or iteration plan.

• Build work item

The build work item manages the integration of change management and build management. It is common to integrate this work item with build generation tools or process automation tools such as Rational Build Forge.

• Promotion work item

The promotion work item governs the process of promoting artifacts from one environment to a higher environment. Some examples are promotion from the development environment to the test environment or promotion from the preproduction environment to the production environment. This work item is usually integrated with the software configuration management (SCM) system and the build system.

Rational Team Concert is an ALM tool, and therefore some of these elements are an integral part of the tool—the release and the build, for example.

The ClearQuest ALM schema also includes record types such as Project, Build, Phase, and Iteration. ClearQuest also provide packages for deployment tracking and for build tracking.

1.3. Work Item Elements

As explained in section 1.1, “Work Item Definition,” work item includes the following composite elements: data, presentation forms, workflow, and possibly other elements and other objects. In the following sections we provide a brief explanation of each work item element, and we shall give much more detailed information in the next chapters.

1.3.1. Data

A work item contains data that is stored in fields (or work item attributes). Although all work items have a common set of fields, such as ID, State, Subject, and Owner (built-in attributes), each work item type contains fields that are exclusive and serve the specific purpose of the work item type in the organization (custom attributes).

The following are some examples of custom fields:

• Defect contains fields such as Component, Software_Version, Phase_Detected, Severity, etc.

• Feature contains fields such as Customer_Priority, Impact, Risk, etc.

• Test Case contains fields such as Pre-Conditions, Post-Conditions, Acceptance_Criteria, etc.

• Hardware Defects contains fields such as Device, Part_Number, Machine_Type, etc.

Work items for specific domains such as finance, pharmaceutical, and telecommunications will have fields specific to their domains.

See the detailed information on work item data in Chapter 4, “The Data.”

1.3.2. Presentation Forms

The data of a work item is presented to the user in forms. A form usually has several tabs, and each tab contains graphic controls. Some graphic controls display the data fields, for example, check box, drop-down combo box, and various types of text boxes. Other controls like the pushbutton generate an action or launch an application. There are also special controls for lists, controls to deal with attachments, complex controls for parent-child relationship interactions, and many others.

Work item data is also presented outside the form, for example, in queries, charts, reports, and dashboards, but user interaction is performed in the form only.

For more detailed information on work item data presentation see Chapter 4, “The Data.”

See Figure 1.2 for the Web presentation of a work item. The same record is shown in Figure 1.3 in the ClearQuest Eclipse client and in Figure 1.4 in the ClearQuest Windows native client.

As you can see, there is not much visual difference among the three ClearQuest client environments. User interaction is slightly different because of different controls and their location.

The Jazz presentation is somewhat different. You can work with work items via the Web interface or the Eclipse interface. The Web interface is based on Web 2.0, which provides the user with a richer interface and more dynamic behavior.

Figure 1.3. ClearQuest Eclipse form work item

Figure 1.4. ClearQuest native Windows form work item

See section 4.5, “Data Representation,” in Chapter 4, “The Data,” for detailed information on this subject.

1.3.3. Workflow

The work item has a lifecycle; it is transitioned from state to state until it is closed (the end state). People with the right access control (permission) perform actions on the work item that change its state. In addition to changing the state, they are usually adding data or changing the data of the work item by typing text, selecting values from a pick list, or adding attachments. In some cases the actions are performed by automation scripts and not by people.

The workflow is designed with graphical aids like a Unified Modeling Language (UML) activity diagram and is defined in ClearQuest and Jazz with a state transition table.

An example of workflow definition in a Jazz work item is demonstrated in Figure 1.5.

The ClearQuest state transition matrix defines the workflow in a very similar way. See the more detailed information on work item workflow in Chapter 3, “The Workflow.”

Figure 1.5. Jazz default workflow definition

1.3.4. Other Work Item Elements

Work items can have additional elements such as rules, attachments, links of various types, pictures, and more. These elements are described in the following sections.

1.3.4.1. Rules

To govern the process of change, you must set rules to control the process of the work item. Some examples of rules are as follows:

• Setting the requiredness of the fields

Requires the users to provide a value after a specific event, or prevents them from changing the value of a field in specific states

• Access control

Defines whether a user is allowed to perform an action, or whether an electronic signature is required prior to performing an action

• Notifications

Notifies users by e-mail of events, for example, that the user was assigned to resolve a work item

• Perform an action

Performs an action if conditions are met or after another event

• Integration

Integrates with other applications when the work item reaches a specific state

Rules are implemented in various ways depending on the type of rule and on the tool. Customized rules can be installed in the metadata with packages like the ClearQuest Notification package or the ClearQuest Audit Trail package. Many times rules are defined by customized code, like the code examples we provide in section 8.1.2, “Implementing Patterns,” in Chapter 8, “Development,” for implementation of parent control and child control rules.

1.3.4.2. Attachments

To provide supporting information to the work item data, the user can attach a file or files to the work item. Typical attachments are screen shots, log files, or specification documents. Attachments can be divided into flow phases, such as analysis attachments, development attachments, or testing attachments.

1.3.4.3. Links to Other Work Items

The link (or reference) to other work items is important and a key feature of process management. It allows the user to see relationships such as parent-child relationships, to browse from one work item to a related work item, to derive more precise and meaningful metrics, and to automate actions based on information in related work items.

In the CQ-ALM schema the process is based on links between work items. We shall discuss this in detail in Chapter 12, “Sample Applications and Solutions.”

1.3.4.4. Pictures or Graphics

We do not refer to images that are included as attachments, which are additional data, but to presentation insertions such as a company logo, icons, or other graphics to improve the user experience. Figure 1.6 shows the picture control within the palette control of ClearQuest Windows Designer. The Rational logo was inserted in the defect submit form.

Figure 1.6. The picture control in ClearQuest Windows Designer

1.3.4.5. Applets

Applets are pieces of code that are used to perform background operations, such as integration with other products. In ClearQuest they are actually ActiveX controls. For example, the ActiveX control is used for the ClearQuest and ClearCase (base) integration.

1.3.4.6. Roles

A role is a set of activities users are allowed to perform on artifacts. Role is a key concept in any governed workflow system.

In Jazz, roles identify the functions of team members. Permissions for specific operations can be assigned to roles at the project level or within a team area.

ClearQuest does not have inherent support for roles, and because of the importance of the subject we have dedicated Chapter 5, “Roles,” to discussing how to implement roles in ClearQuest.

1.4. Customization

Work item customization means creating new work item types or changing the elements (data, workflow, presentation, and rules) of existing work item types to meet the organization’s process and policy.

The customization process, which follows the requirements analysis and design phases, includes some basic stages:

1. Create new work item types.

2. Create fields of various types in each work item type to represent the required data.

3. Create the work item workflow, which includes the definition of the states, the actions, and the allowed state transitions.

4. Create the forms, tabs, and graphical controls to present data and to interact with the user.

5. Develop the rules by setting the fields’ behavior, permission to perform actions, access to data, security, notification, integration, and other attributes.

The ClearQuest administrator or the Jazz administrator can create any type of work item that is required. But there is a need to balance business requirements, usability, and maintainability (in that order). What we are trying to say is that it is not advisable to create a work item type for each required business flow. In many cases you can unify two or more work items and achieve the functionality of two business requirements, without affecting the usability and possibly improving the maintainability.

Let’s consider some examples. A company is managing their defect tracking with ClearQuest. They would now like to start managing enhancement requests and new features as well. They can create two new work items, one for enhancement requests and one for features. They can take a completely different approach and convert the defect work item to an issue work item that will handle the three issue types (defect, enhancement request, and feature). So what is the best approach? The company must analyze the requirements of each of the three work items, for data and workflow. Considering how much each process differs from the others, does the data required in each state differ a lot from one work item to another? If the answer is that there is much similarity, the work items should be unified. In this case a field called Issue_Type should be added that will have a closed list of the three types we have mentioned (see an example in Figure 1.1).

Work item data is discussed further in Chapter 4, “The Data,” and workflow in Chapter 3, “The Workflow.”

1.4.1. Which Work Item Elements Can Be Customized?

Within each work item type you can customize the following elements:

• Data (fields, permission to view and edit)

• Presentation of data (forms, tabs, graphic controls)

• Process (workflow, actions, roles, rules)

The details of how to perform the customization are described in the tools manuals and the online help and we shall not repeat them here. In the following chapters we shall discuss customization strategies and techniques that are not included in the tools manuals.

Table 1.2 shows the work item elements and indicates whether they can be customized in ClearQuest Designer and in Rational Team Concert.

Table 1.2. Comparing ClearQuest and Jazz Work Item Customization Elements and Terms

Some customization areas are not directly related to the work item elements but to the presentation of a data collection. These areas are

• Queries

• Charts

• Reports

• Dashboard

Table 1.3 shows these customization areas in ClearQuest and the Jazz-based products.

Table 1.3. Comparing ClearQuest and Jazz Queries, Charts, Reports, and Dashboard

1.4.2. Customizing Jazz Work Items

Jazz work item types for both Rational Team Concert and Rational Quality Manager are customized with the Rational Team Concert Eclipse client (RTC 3.0 also supports customization with the Web client). We shall discuss customization in detail in the following chapters. To learn how to perform the work item customization, see RTC Help > Managing change and releases > Tracking work items > Customizing work items.

For the test-specific work items created with Rational Quality Manager (test plan and test case), the customization is performed with the RQM Web client. See section 10.3, “Work Items in the Test Process,” in Chapter 10, “Test Management and Work Items,” for more information on test plan and test case customization.

1.4.3. Customizing ClearQuest Record Types

ClearQuest record types are customized with the ClearQuest Designer. Until version 7.0 only a Windows version of the ClearQuest Designer existed. Since version 7.0.1 an Eclipse version is also available. Although both designers are similar in functionality, the operations are done in different ways. ClearQuest schema designers who are used to working with the Windows version will have to get used to the new Eclipse version, which includes several advantages over the Windows version; the basic differences are described in Table 1.4.

Table 1.4. Comparing the Eclipse and Windows Versions of ClearQuest Designer

There are many additional differences that we have not mentioned. Most operations are done in a different way, to take advantage of the Eclipse platform.

Although you can use either version, we propose that you get habituated to the Eclipse version. Personally, we think that the Windows version is more user-friendly, but the Eclipse version has more features, and this version will probably get richer in features in the future. Most of the examples in this book are related to the Eclipse version of ClearQuest Designer.

1.5. Resources

What’s new in 2.0 work items? These are the main enhancements to work items in Jazz version 2.0:

• New custom attribute types

• Custom work item presentations

• RESTful Change Management API

• Import work items from CSV files

• Message @Me

• Inline work item editor in Web UI

For details of the work item enhancement, see

IBM Rational, “WorkItems—New Custom Attribute Types,” https://jazz.net/downloads/rational-team-concert/releases/2.0?p=news#workitems, June 25, 2009 (accessed February 24, 2011).

For more on work item tracking, see

IBM Rational, “Work Item Tracking,” http://jazz.net/projects/rational-team-concert/features/wi, November 2010 (accessed February 24, 2011).

For an overview of Jazz work items, consult the following:

IBM Rational, “Jazz Work Item Overview,” http://jazz.net/library/LearnItem.jsp?href=content/docs/platform-overview/work-item-overview.html, May 28, 2008 (accessed February 24, 2011).

For more on work items in version 3.0:

Benjamin Pasero, “What’s New in Rational Team Concert 3.0: Part V—Work Item Enhancements,” December 3, 2010, http://jazz.net/blog/index.php/2010/12/03/whats-new-in-rational-team-concert-3-0-part-v-work-item-enhancements/.

“What’s New in Rational Team Concert (last version),” http://jazz.net/projects/rational-team-concert/whatsnew/.

1.6. Summary

In this chapter we introduced work items. We defined a work item as an object that controls the process of performing a work or task during software or systems development. We discussed the elements of a work item: data, presentation forms, workflow, and other objects. We explained additional work item elements such as rules, attachments, links, graphics, and applets.

In the second part of the chapter we briefly discussed work item customization: create new work item types; create fields in each work item type to represent the required data; create the work item workflow, which includes the definition of the state, actions, and transitions; create the form and tabs to present data and interact with the user; develop the rule by setting the field’s behavior, access to actions and data, security, integration, and so on.

We compared the customization areas in the ClearQuest record types and the Jazz work item types and explained what can and cannot be customized in each product in the current release.

Because a new ClearQuest Designer based on Eclipse technology has been introduced, we compared the main features of this version with the legacy ClearQuest Designer.