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.
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
| 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 |
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 follow to reproduce the defect. Any descriptions that are longer than 32 KB are truncated, and the entire description is added as an attachment. |
| Due Date | Timestamp | dueDate |
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 |
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. |
| Type | Description |
|---|---|
| Native | Simple attribute types, such as Timestamp, Integer, Long, Boolean, and Decimal. |
| Text-based | Attribute types that support storing any kind of 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) | |
| 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) | |
| Process Area / Project Area / Team Area (Process Area can refer to either a project area or a team area.) | |
| Work Item / Item (Item can be any item that is managed by EWM.) | |
| 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. |
| 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) | |
| Duration | |
| Timeline | |
| Electronic Signature (Digital signatures) | |
| Wiki (Wiki style content) |
Workflow
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.
- 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:
- Define the work item type.
- 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.
- Associate the work item type with an editor presentation.
- Identify which built-in attributes to include. Add custom attributes for additional information that you want to track in work items of this type.
- For any enumeration type attributes that you want to add, define the corresponding enumerations.
- 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.
- 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.