Work item customization overview

Before you can customize work items, you need to understand key concepts. The general task flow to follow to create a work item type is also described.

To customize work items, you must be familiar with the following concepts.

Work item type

A work item type is a classification of work items that has a specific set of attributes. Each predefined process template includes the work item types that allow users to work in that process. For example, the Scrum process includes work item types such as Epic, Story, Adoption Item, Task, and Retrospective, which support an agile development model. The Formal Project Management process, which supports a more traditional development model, includes work item types such as Project Change Request, Business Need, and Risk. Some work item types, such as Defect and Task, are used by multiple processes.

Work item type category

Each work item type belongs to a work item category. Multiple work item types can belong to the same work item category. The work item types of a work item type category share workflow and custom attributes. When you create a work item type, you must associate it with a category. If you intend to define a unique workflow for the new work item type, create a new category and associate it with the work item type. Otherwise, you can associate the work item type with an existing category.


Attributes identify the information that you want to capture when users create and modify work items. Attributes are similar to fields in records. Work item types include all the built-in attributes that are listed in Table 1. However, note that not every ready-to-use work item presentation is configured to display all the built-in attributes in the IBM® Engineering Workflow Management (EWM) Eclipse and web clients.

You can customize the attributes that a work item type contains and the presentations that are used to display these attributes. For example, you can customize attributes to add behavior. Such behaviors can include validating an attribute value, or setting an attribute value that is based on other attribute values.

You can also change the name of the built-in attribute of a work item if needed. To rename a built-in attribute in a work item, take the following steps:
  1. From the Administration menu in the EWM project area dashboard, click Manage This Project Area.
  2. Click Work Items > Types and Attributes.
  3. From the Attributes section, click the attribute name such as Summary to rename it.
  4. Save the project area.
Table 1. Built-in attributes
Name Type ID Description
Archived Boolean archived Specifies whether the work item is archived.
Comments Comments
Note: This attribute type is used only for built-in attributes.
internalComments Comments about the work item.
Corrected Estimate Duration correctedEstimate Correction to the original time estimate as specified by the Estimate attribute to resolve the work item.
Created By Contributor creator The user who created the work item.
Creation Date Timestamp creationDate Date when the work item was created.
Description Large HTML description Detailed description of the work item. For example, the description for a defect might include a list of steps to reproduce the defect. You cannot save a work item if the description is longer than 32 KB.
Note: In the Eclipse client, any descriptions that are longer than 32 KB are truncated, and the entire description is added as an attachment.
Due Date Timestamp dueDate The date by which the resolution of the work item is due.
Estimate Duration duration Estimated amount of time that it takes to resolve the work item.
Filed Against Category category Category that identifies the component or functional area that the work item belongs to. For example, your project might have GUI, Build, and Documentation categories. Each category is associated with a team area; that team is responsible for responding to the work item.
Found In Deliverable foundIn Release in which the issue described in the work item was identified.
ID Integer id Identification number that is associated with the work item.
Modified By Contributor modifiedBy User who last modified the work item.
Modified Date Timestamp modified Date when the work item was last modified.
Owned By Contributor owner Owner of the work item.
Planned For Iteration target Iteration for which the work item is planned.
Priority Priority (Enumeration) internalPriority Ranked importance of a work item. For example, Low, Medium, or High.
Project Area Project Area projectArea Area in the repository where information about the project is stored.
Resolution Small String internalResolution How the work item was resolved.
Resolution Date Timestamp resolutionDate Date when the work item was resolved.
Resolved By Contributor resolver User who resolved the work item.
Restricted Access UUID
Note: This attribute type is used only for built-in attributes.
contextId Scope of access to the work item.
Severity Severity (Enumeration) internalSeverity Indication of the impact of the work item. For example, Minor, Normal, Major, or Critical.
Start Date
Important: The Start Date attribute is an internal property, which has been deprecated and is removed from the user interface. Therefore, the attribute should not be used.
Timestamp startDate Date when work began on the work item.
Status Small String internalState Status of the work item. For example, New, In Progress, or Resolved.
Subscribed By Subscriptions
Note: This attribute type is used only for built-in attributes.
internalSubscriptions Users who are subscribed to the work item.
Summary Medium HTML summary A brief headline that identifies the work item.
Tags Tag internalTags Tags that are used for organizing and querying on work items.
Time Spent Duration timeSpent Length of time that was spent to resolve the work item.
Type Type workItemType Type of work item. Commonly available types are Defect, Task, and Story.
You can also add custom attributes to a work item type. These custom attributes are available to all work item types that belong to the same work item type category. EWM supports the types of attributes that are listed in Table 2.
Table 2. Supported attribute types
Type Description
Native Simple attribute types, such as Timestamp, Integer, Long, Boolean, and Decimal.
Text-based Attribute types that support storing any text-based values. HTML-based attributes allow for formatting text and linking to artifacts. Small and medium-sized attribute types efficiently allocate database memory for attributes that are expected to be in a certain size range. The maximum attribute size applies when UTF-8 encoding is used.
Small String (250 bytes of text)
Medium String(1000 bytes of text)Note: This number is 900, if your installation uses SQL Server as the underlying DBMS and only when the field is used as a key/index. For more information, see:
Large String (32768 bytes of text)
Medium HTML (1000 bytes of XML text, including tags)
Large HTML (32768 bytes of XML text)
String List (List of text values)
Tag (Tag list for organizing and querying items)
Item-based Attribute types that are used to model EWM artifacts such as users, project areas, and work items. These attributes can be modeled as single items (for example, only one user can create a work item) and as list attributes (for example, multiple users can be set to approve a defect fix).
Contributor (Users such as Created By or Owner)
Contributor List (List of contributor values)
Process Area / Project Area / Team Area (Process Area can refer to either a project area or a team area.)
Process Area List / Project Area List (List of process area/project area values)
Work Item / Item (Item can be any item that is managed by EWM.)
Work Item List / Item List (List of work item/item values)
Enumeration-based Attributes with a fixed or extensible list of values. For example, Priority and Severity are built-in Enumeration-based attributes.Enumeration is a special attribute type that can be used to define custom attribute types.
Enumeration List (List of enumeration values)
Other Attribute types for planning and managing work items.
Iteration (Useful for iteration-based processes. For example, Planned For.)
Category (Associated with a team area. For example, Filed Against.)
Deliverable (Associated with a release)
Electronic Signature (Digital signatures)
Wiki (Wiki style content)


A workflow is a state transition model, which defines the states of a work item and the actions that users take to move the work item from one state to another. Typically, a workflow starts with an Open or Submitted state and ends with a state that reflects the final condition of the work item, such as Resolved or Closed. Each work item type is associated with a workflow. All work item types of a work item type category use the same workflow.

Editor presentation

The editor presentation defines the appearance of the work item editor. Within the editor presentation, you organize content into tabs, sections within tabs, and presentations within sections. To add an attribute to a section, you add a presentation for that attribute to the section. An editor presentation is associated with a work item type. If a work item type does not have its own editor presentation, it uses the default editor presentation that is defined for its work item type category.

You can reuse tabs and sections from other editor presentations. Changes that you make to a shared tab or section in one editor presentation appear in all instances of that shared tab or section.

In addition to the editor presentation for the default work item editor, EWM includes the following editor presentations:
  • Inline Work Item Editor: The editor for inline work item modification. For example, this editor is displayed when a user chooses to modify a work item within a query result set in the web client. It is also displayed when a user creates a work item from another integrated application, such as IBM Engineering Test Management.

    For more information, see Customizing the work item editor in the web client.

  • Lightweight Work Item Creation dialog: The editor for quickly creating work items. For example, this editor is displayed when a user creates a work item while they are delivering a change set.
  • Plan Editor Preview: The editor for viewing and modifying work items inside a plan. This editor is used for the plan editor preview pane in the Eclipse client and the inline editor in the plan in the web client.

Workflow for creating a work item type

The general workflow for creating a work item type is as follows:

  1. Define the work item type.
  2. Associate the work item type with a work item type category. Alternatively, create a new work item type category and associate it with the work item type.
  3. Associate the work item type with an editor presentation.
  4. Identify which built-in attributes to include. Add custom attributes for additional information that you want to track in work items of this type.
  5. For any enumeration type attributes that you want to add, define the corresponding enumerations.
  6. If you associate the work item type with a new work item type category, create a workflow and associate it with the work item type. If you associate the work item type with an existing work item type category, the work item type uses the same workflow as all other work item types that belong to that work item type category. You can associate the work item type with a different workflow, but be aware that all other work item types in that work item type category will then be associated with that workflow.
  7. Customize the editor presentation. At a minimum, you need to add presentations for your custom attributes to get them to display in the work item editor.