Creating work items

Create a work item to submit a defect, task, or other type of work request.

About this task

You can customize the predefined layout of the work item editor for the work item types that are provided with your process template. For information about process templates, see Working with process templates.


  1. In the Team Artifacts view, expand the project area node, right-click Work Items, and select New > Work Item. In the Create New Work Item wizard, select the work item type, such as Defect, Enhancement, or Task, and click Finish.

    Alternatively, click the down arrow next to New Work Item , select the project area, and select the work item type.

  2. Enter or select values for the following fields on the Overview tab:
    Field Description
    Summary A brief headline that identifies the work item.
    Type The type of work item. Commonly available types are Defect, Task, and Story. You can customize the project to include additional types.
    Severity An indication of the impact of the work item, such as Minor, Normal, Major, or Critical.
    Filed Against A category that identifies the 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. If you are unsure of the category, click Guess Category . This button suggests categories by using the text in the Summary and Description fields to search for similar work items.
    Found In The release that the work item refers to.
    Description A 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.
    Note: Uniform Naming Convention (UNC) path names are not supported in the Description and Discussion fields. UNC is a Windows format for specifying the location of resources.
    If you or a team member has edited the description of this work item in the web client, and has added extended rich text, then the Description field is read only in the eclipse client. To edit this field, you must edit it in the web client. Click Edit rich-text content in the web client.
    Edit righ-text content
    Tip: In the Summary, Description, and Discussion fields, you can use various shortcuts to connect to artifacts, refer to artifacts, and notify users.
    • To refer to other Jazz® artifacts, you can use short notations. When you save the work item, these notations become links to the artifacts.
      • Specify the type of artifact and its ID. For example: work item 123, defect 25, attachment 982.
      • Refer to artifacts in other work items. For example: task 50775, comment 4.
      You can also open a content assist dialog to select a work item by pressing Ctrl+Space. A list of recent work items is displayed. Either select a work item from the list, or select More work items to open the Select Work Items dialog. Press Ctrl+Space in the content assist dialog to toggle between displaying a list of user IDs, work items that you previously added to your Favorites folder, recent work items, and templates. To display only More work items in the content assist dialog page for user IDs, enter @ in the rich text editor. This applies only for the Discussion field, and not for Description field when extended rich text is enabled. Clicking Ctrl+Space brings up the editor, unless it detects a work item type. For example: pressing Ctrl+Space after the keyword defect brings up the dialog to select work items.
      Note: For Chinese, Japanese (Linux®), and Korean (Linux), press Alt+/.
    • To write to a team member in the Description field or in a comment in the Discussion section, enter the @ symbol followed by the user ID of the team member. To find the ID of a user, open a context assist dialog by pressing Ctrl+Space. Then, select a user from the list, or click More users to open the Select User dialog. After you save the work item, an alert is displayed in that team member's client, an event is displayed in the Event Log, and the team member receives a notification in their email client as specified in their user profile.
      • The alert is in the following format: User-name mentioned you in work-item-summary (work item number). For example, Bob mentioned you in Update header file (251).
      • The event contains the comment or part of the description that you enter after @user-ID. For example, On Feb 10, 2014, 6:45:43 PM Bob Smith mentioned you in comment 2: @bert: Should we fix this in 2.0M1?
    • To format your text entries, click Edit and select Bold or Italic.
  3. On the Links tab, add attachments, screen captures, and subscribers, and specify related work items. You can also associate the work item with one or more IBM® Rational® ClearCase® activities.
    Note: Attachments are available to the entire project area and their visibility is not limited to team area or work item.
    • To attach a file, click Add File and navigate to the file location. You can also drag files from another application, such as Windows Explorer, onto the Attachments section of the Links tab. The default size limit for attachments is 50 MB. If you have JazzAdmins permissions, you can change the size limit as follows:
      1. Log in to the administrative web interface.
      2. Click the Server tab, and then click Advanced Properties.
      3. Scroll to the Work Item Component section, and then edit the Maximum Attachment Size setting.
    • To add subscribers, in the Subscribers area, click Add. In the Select Users dialog, enter part or all of a user's name and click Search; then, select the user from the Matching users list and click Add. Subscribers receive email and feed notifications whenever someone modifies the work item. When you create a work item, you are added as a subscriber to that work item. To stop receiving notifications, you can remove yourself as a subscriber by selecting your name and clicking Remove.
    • To link the work item to another work item in the same repository, in the Links area, click Add. Click the option that represents the type of relationship to establish. For example, you can establish a parent-child relationship between work items, mark a work item as a duplicate of another work item, or indicate that one work item is blocked by another work item. To link the work item to a child work item, click Add Children. To link the work item to another work item in a different repository, click Add > Add Related Change Request, select the remote project area, and find and add the work item. To link to work items in project areas on other Jazz Team Servers, cross-repository communication must be configured and the project areas must be linked. For more information about cross-repository linking of work items, see Linking between AM artifacts and local work items.
    • If ClearCase is installed on your computer, you can associate the work item with one or more ClearCase UCM activities. In the Links area, click Add, and then click Add ClearCase Activities. In the URI field, enter a ClearCase activity selector, such as activity:actname@/pvob. When you specify the VOB tag, you must use forward slashes. You can retrieve information about the activities by opening them in the Links area.
  4. Optional: If you are working in a project that uses the Scrum process and you are creating a Story work item, you can specify the acceptance criteria. Open the Acceptance tab. In the Criteria of Acceptance field, enter the criteria for the test team to use to verify that the Story work item is complete.
  5. Click Save to save the work item.

What to do next

The work item is ready to be worked on. For information on working on work items, see Working on and resolving work items