Defining work item types and attributes

The set of work item types that is defined for a project area depends on the process template that the project area uses. You can define more work item types for your project in the Eclipse client.

About this task

Work item types are associated with type categories. For example, in the Scrum process, the Defect work item type belongs to the category. One or more types can be associated with a type category. All types of a type category share custom attributes and follow the same workflow.
Attention: When you change the associated workflow or attributes of a type category, including the definition of a work item type, all work item types that are associated with that type category change. If any work items are based on those work item types, they also adopt the changes.
Attention: If you delete a work item type that is part of a change management type binding, you must manually update the type binding. Otherwise, the Open Services for Lifecycle Collaboration (OSLC) creation dialog for change management services contains the incorrect URI, and an error similar to the following one displays when you try to create a work item from the integrated application:

Cannot create working copy


To create a new work item type:

  1. Open the Types and Attributes page:
    1. In the Team Artifacts view of the Work Items perspective, right-click the project area and select Open.
    2. Click the Process Configuration tab.
    3. Expand Project Configuration > Configuration Data > Work Items, then click Types and Attributes.
  2. In the Work Item Types section, click Add.
    Note: The order in which types are displayed in the Work Item Types list determines the order in which they are displayed in the Create Work Item menus. The first type in the list is the default type that is used when you create a work item with a single click.
  3. In the Add type window, complete the following steps:
    1. Enter a name for the new type. By default, the ID field is populated with the same value that you enter in the Name field, but the ID value is in lowercase. You can edit the ID value.
      Note: This ID is used to distinguish one work item type from another.
      Important: The ID must not contain white spaces. Double-byte character sets are not supported.
    2. Create or select a type category to associate the work item type with. Each type category has an associated workflow and attributes. If you create a type category, you must define these associations for it. If you select an existing type category, the new work item type adopts the associations of the type category by default.
    3. Click OK to create the new work item type and open it in the Types and Attributes page.
  4. In the Icon field, click the icon button and select an icon. The process templates include a set of icons to use. Select one of the icons, or use your own graphic as the icon. To use your own graphic, click Manage Icons > Add Icons, and select the graphics file to use as the icon for the new work item type. When you are finished, click OK.
  5. Optional: Create one or more aliases. An alias is another name for a work item type. It is used to create an automatic text link in the Summary, Description, and Comments fields of a work item. Each work item type can have a set of aliases, which you can define in the Aliases field by using a comma-separated list. For example, if the Aliases field for the Task work item type is defined as work item, workitem, item, text links are automatically created when a user refers to Task 123 in the Summary, Description, and Comments fields as work item 123, workitem 123, or item 123.
    Note: In addition to customizing aliases that are associated with a work item type, built-in automatic link strings exist that are not modifiable:
    • attachment file_name, used to reference a file attachment
    • comment number, used to reference a comment within the work item
    • email links of the following format: user_id@domain, for example,
    • user links of the following format: @user_id, for example, @bob
    • URI links, for example,,, ftp://FTP_site_file_location
    • Java™ stack trace links
  6. Select an editor presentation that defines how the new work item type is displayed in each of the following editors:
    • Work Item Editor: The default editor for creating and modifying work items.
    • 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.

    You can customize the editor presentations on the Editor Presentations page.

  7. If you are creating a new type category, in the Workflow section, select a workflow to associate with that category. To edit the selected workflow or create a new workflow, click Edit to open the Workflows page.
  8. To add an attribute to the type category that the selected work item type is associated with:
    1. In the Attributes section, click Add.
    2. In the Add Custom Attribute window, enter a name and an ID for the attribute and select a type. You might be able to select a default value, calculated value, value set, condition, or validators to associate with the custom attribute. To see or modify the available default values, values sets, calculated values, and validation rules, in the Project Area, on the Process Configuration tab, click Project Configuration > Configuration Data > Work Items > Attribute Customization. To reuse an attribute that is defined for another type category, click Reuse Existing Attribute and select the attribute from the Attribute list.
      Note: This ID is used if the related information is represented as UML source in the Eclipse client.
      Important: After you create and save a custom attribute type, it cannot be modified.

      In addition to common data types such as string, enumeration, integer, decimal, and Boolean, you can use the following types that are references to items:

      • Category (for attributes similar to Filed Against)
      • Contributor and Contributor lists (for attributes similar to Owner)
      • Deliverable
      • Duration
      • Electronic Signature
      • Item and Item lists
      • Iteration (for attributes similar to Planned For)
      • Process Area and Process Area lists
      • Project Area and Project Area lists
      • Release (for attributes similar to Found In)
      • Tags
      • Team Area and Team Area lists
      • Timeline
      • Timestamp (optionally configured to show date only or date plus time)
      • Wikis
      • Work Item and Work Item lists
    3. When you are done customizing the attribute, click OK.
  9. To edit an attribute of the type category that the selected work item type is associated with:
    1. In the Attributes section, select the attribute and click Edit.
    2. You can modify the name of the attribute, set or clear read-only, modify the dependency list, and possibly modify other configurable values.
    3. When you are done modifying the attribute, click OK.
  10. Click Save to save your changes. If you modified anything that is associated with a type category, all work item types in the project that are associated with that type category are updated.

What to do next

After you add a type category, you must bind that type category to a workflow. After you add a type, you must bind that type to an editor presentation.

To manually update existing work items with new or modified custom attributes, see Updating work items with new or modified attributes.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki