Updating work items

As you address the issues that are raised in a work item, periodically update the work item to describe its state and your work.

1. Find and open a work item to update by using one of the following methods:
   • If you know the work item number, enter it in the search field in the lower left portion of the workbench and press Enter.
   • In the Work Items view, run a query that retrieves work items that are assigned to you. Then, in the result set table, double-click a work item to open it.
   • In the My Work view, double-click a work item in one of the sections to open it.
2. Review the work item.
   1. On the Overview tab, review the text in the Description field and the comments in the Discussion section. You can edit the description field. However, 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.
      
   2. On the Links tab, review any attachments and related links, and check to see whether anyone is included on the Subscribers list to receive notification of work item updates.
   3. On the Approvals tab, review any approvals.
   4. On the History tab, review the history of changes to the work item, if any.
3. Start work on the work item. On the Overview tab, from the State list, select Start Working.
   Tip: You can indicate that you are starting work on a work item without opening it by right-clicking the work item and selecting Start Working.

   You might also want to set some of the empty fields. For example, set the value in the Planned For field to a planned iteration for resolving the work item, and set the date and time in the Due Date field.

   If you want to move a work item to another team area, there are permissions considerations to be aware of.

   Learn more about permissions related to saving a work item to a different team area:

   For illustrative purposes, the following example uses the Scrum process template. If you are using a different process template, make the appropriate adjustments.

   By default, in the Scrum process template, all users have the Everyone role with the following permissions, as defined on the Process Configuration tab of the project area editor. To view the permissions, in the Configuration pane, expand Team configuration > Permissions. In the Permissions pane, from the Roles list, select Everyone (default), and from the Permitted actions list, expand Work Items. The following permissions are enabled:

   • Work Items > Save Work Item > Modify the work item
   • Work Items > Save Work Item > Remove work item from team area

   The previous permissions allow users with the Everyone role the ability to move work items to a new team area.

   If the Everyone role is modified such that the Work Items > Save Work Item > Modify the work item permission is removed, a user with this role will receive an error similar to this one when they attempt to move a work item to a different team area:

   You don't have permission to perform the following actions:
      Modify the work item's summary (modify/summary)
      Modify the work item's subscriptions (modify/subscriptions) 
      Modify the work item's 'Filed Against' attribute (modify/category)

   Similarly, if the Everyone role is modified such that the Work Items > Save Work Item > Remove the work item from team area permission is removed, a user with this role will receive an error similar to this one when they attempt to move a work item to a different team area:

   You don't have permission to perform the following actions:
      Remove work item from team area (remove)

   For more information about permissions, see Permissions.

4. Collaborate with team members by using several fields on the Overview tab.
   • To enter a question or comment, in the Discussion section, click Add Comment and add text. Subscribers to the work item receive notification of your comment when you save the work item. When you add a comment, you are added as a subscriber. To see whether there are any subscribers, check the Quick Information section. To add subscribers, use the Links tab, described next.
     Tip: 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 several times. 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.

       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.
   • To chat with the submitter of the work item, next to Created By, right-click the submitter's name and select Chat.
   • To send an email to the submitter of the work item, next to Created By, right-click the submitter's name and select Send Mail.
5. 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.
   • 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 take a screen capture and attach it, click Add Screenshot. Position the frame to the area to capture. Use the arrows on the sides of the frame to expand or reduce the size to fit the area. Click to capture the area in the frame. You can use the pen, oval, and rectangle icons to highlight specific areas of the screen capture. Specify the graphics format in which to save the image. In the Attach to section, select the work item to which to attach the screen capture:
     • To select the current work item, click Work Item <ID>.
     • To create a new work item, click New Work Item and follow the instructions in the Create Work Item wizard.
     • To search for the work item, click Other Work Item to open the Select Work Item dialog.
   • 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 to work items on remote repositories.
   • 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.
6. Use the Approvals tab to specify one or more users who are responsible to approve the resolution of a work item.
7. Use the History tab to review the history of changes to the work item. For information, see Viewing work item history
8. 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.
9. Click Save to save your changes.
10. To resolve the work item, complete the next steps.
    1. In the State list, select Resolve.
    2. In the adjacent Resolution list, select an entry that describes how you resolved the work item; for example, Fixed, Works For Me, or Duplicate.
    3. In the Discussion section, enter a comment that further explains your actions.
    4. If you resolve a work item as a duplicate, you must also specify the other work item on the Links tab, Links section.
    5. Click Save to save your changes.