Edit

Add and update a work item

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

You add work items to plan and manage your project. Different types of work items track different types of work—such as user stories or product backlog items, tasks, bugs, or issues. Use work items to describe the work to be done, assign work, track status, and coordinate efforts within your team.

Note

This article shows how to add any type of work item. However, the recommended tool for adding backlog or portfolio items—such as, user stories, product backlog items, features, or epics— is to use the backlog or Kanban board to add new items. For more information, see Create your backlog, Define features and epics and Start using your Kanban board. To create test cases and link them to user stories, see Add, run, and update inline tests and Create test plans and test suites.

Prerequisites

  • You must be added to a project.
  • To view or modify work items, you must have your View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has this permission set. For more information, see Set permissions and access for work tracking.
  • To add new tags to add to work items, you must have Basic access or higher and have the project-level Create new tag definition permissions set to Allow. By default, the Contributors group has this permission set. Even if the permission is explicitly set for a Stakeholder, they don't have permission to add new tags, as they're prohibited through their access level. For more information, see Stakeholder access quick reference.
  • All project members, even members in the Readers group, can send emails containing work items.
  • You must be added to a project.
  • To view or modify work items, you must have your View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has this permission set. For more information, see Set permissions and access for work tracking.
  • To add new tags to add to work items, you must have Basic access or higher and have the project-level Create new tag definition permissions set to Allow. By default, the Contributors group has this permission set. Even if the permission is explicitly set for a Stakeholder, they don't have permission to add new tags, as they're prohibited through their access level. For more information, see Stakeholder access quick reference.
  • All project members, even members in the Readers group, can send emails containing work items.

Add a work item

You can start adding work items once you connect to a project.

Choose a Boards page—such as Work Items, Boards, or Backlogs. Then choose the plus icon and select from the menu of options.

Work, add artifact

Note

Depending on the process chosen when the project was created—Agile, Basic, Scrum, or CMMI—the types of work items you can create are different. For example, backlog items may be called user stories (Agile), issues (Basic) product backlog items (Scrum), or requirements (CMMI). All four are similar: they describe the customer value to deliver and the work to be performed.

For more information, see About processes and process templates. The Basic process requires Azure DevOps Server 2019.1 or later version.

Enter a title and then save the work item. Before you can change the State from its initial default, you must save it.

Agile process, User story work item form

You can add tags to any work item to filter backlogs and queries.

Work items you add are automatically scoped to your team's default area path and iteration path. To change the team context, see Switch project or team focus.

That's it!

Create as many work items as you need of the type you need to track the work you want to manage.

Update work items as work progresses

As work progresses, team members can update the state and reassign it as needed. While the workflow states differ for different work item types, they usually follow a progression from New or Active to Completed or Done.

Update the State of a User Story

The following image shows the workflow states for a user story. If you want to discard a work item, change the state to Removed, or you can delete it. For more information, see Move, change, or remove a work item.

Typical workflow progression:

  • The product owner creates a user story in the New state with the default reason, New user story
  • The team updates the status to Active when they decide to complete the work during the sprint
  • A user story is moved to Resolved when the team has completed all its associated tasks and unit tests for the story pass.
  • A user story is moved to the Closed state when the product owner agrees that the story has been implemented according to the Acceptance Criteria and acceptance tests pass.

Atypical transitions:

  • Change the State from Active to New.
  • Change the State from Resolved to Active.
  • Change the State from Resolved to New.
  • Change the State from Closed to Active.
  • Change the State from New to Removed.
  • Change the State from Removed to New.

User story workflow, Agile process

Removed work items remain in the data store and can be reactivated by changing the State.

With each update, changes are recorded in the History field, which you can view through the History tab.

View change history

To find work items based on their history, see History & auditing.

Capture comments in the Discussion section

Use the Discussion section to add and review comments made about the work being performed.

Screenshot showing the Discussion section within a work item form.

The rich text editor tool bar displays below the text entry area. It appears when you select each text box that supports text formatting.

Screenshot of Discussion section, Rich Text Editor toolbar.

Note

There isn't a Discussion work item field. To query work items with comments entered in the Discussion area, you filter on the History field. The full content of the text entered into the Discussion text box is added to the History field.

Mention someone, a group, work item, or pull request

To open a menu of recent entries you've made to mention someone, link to a work item, or link to a pull request, select or , or enter @, #, or !.

Screenshot of Discussion section, at-mention drop-down menu.

Enter a name or number and the menu list filters to match your entry. Choose the entry you want to add. To bring a group into the discussion, enter @ and the group name, such as a team or security group.

Edit or delete a comment

To edit or delete any of your discussion comments, choose Edit or choose the actions icon, and then choose Delete.

Screenshot of Discussion section, Edit, Delete actions.

Note

Editing and deleting comments requires Azure DevOps Server 2019 Update 1 or later version.

After updating the comment, choose Update. To delete the comment, confirm that you want to delete it.

A full audit trail of all edited and deleted comments is maintained in the History tab on the work item form.

Important

For on-premises Azure DevOps Server, you must configure an SMTP server for team members to receive notifications.

Add a reaction to a comment

Add one or more reactions to a comment by choosing a smiley icon at the upper-right corner of any comment. Or, choose from the icons at the bottom of a comment next to any existing reactions. To remove your reaction, choose the reaction on the bottom of your comment. The following image shows an example of the experience of adding a reaction and the display of reactions on a comment.

Screenshot of Discussion control, Add reactions to a comment.

Save a comment without saving the work item

Note

This feature is available starting in Azure DevOps Server 2022.1.

If you only have permissions to add to the Discussion of a work item, then you can do so by saving comments. This permission is controlled by Area Path nodes and the Edit work item comments in this node permission. For more information, see Set work tracking permissions, Create child nodes, modify work items under an area or iteration path.

Once you save the comments, you don't need to save the work item.

Screenshot of Discussion section, save comment.

Note

When you save changes made to the Discussion control, only the comment is saved. No work item rules defined for the work item type execute.

Follow a work item

When you want to track the progress of a single work item, choose the follow icon. This action signals the system to notify you when changes are made to the work item.

Work item form, Follow icon control

You'll only receive notifications when other project members modify the work item, such as adding to the discussion, changing a field value, or adding an attachment.

Notifications are sent to your preferred email address, which you can change from your user profile.

To stop following changes, choose the following icon.

Important

To support the follow feature, you must configure an SMTP server for team members to receive notifications.

Next steps

Create your backlog or Kanban quickstart

For descriptions of each field and work item form control, see Work item field index and Work item form controls.

Once you've added several work items, you can use additional features to get notified of changes, create queries, define status and trend charts, plus more.

For more clients that you can use to add work items, see Clients that support tracking work items.