Add, update, and follow a work item

Add and update a work item

Azure Boards | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

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

For additional clients that you can use, see Best tools for adding, updating, and linking work items.

Prerequisites

  • You must connect to a project. If you don't have a project yet, create one.
  • If you're not on a project or team, get added now.
  • You must be a member of the Contributors group and granted Basic access or be granted Stakeholder access to add or modify work items. Or, you must have your View work items in this node and Edit work items in this node permissions set to Allow. To learn more, see Set permissions and access for work tracking.

Note

Users with Stakeholder access for a public project have full access to backlog and board features just like users with Basic access. For details, see About access levels.

Add a work item

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

Note

Your web portal uses either the New navigation or Previous navigation user interface. Choose the New navigation tab if the New Navigation feature is enabled. You'll see a vertical sidebar along with other navigational features when New Navigation has been enabled for the signed-in user or the organization. Choose Previous navigation when you see a top-level, blue-bar—indicating that New navigation isn't enabled. For more information, see Web portal navigation.

Note

Choose the New navigation tab for guidance. Azure DevOps Server 2019 supports the New Navigation user interface. For more information, see Web portal navigation.

Note

Choose the Previous navigation tab for guidance. TFS 2018 and earlier versions only support the previous navigation user interface. For more information, see Web portal navigation.

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

Choose the Previous navigation tab for guidance. New navigation isn't supported for TFS 2018 and earlier versions.

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 area and iteration paths. 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

Note that the location of the State field may differ depending on the work item type you are updating.

Update the State of an Issue

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

The following image shows the work flow states for a user story. If you want to discard a work item, change the state to Removed, or you can delete it. For details, see Remove or delete 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

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.

Discussion section within a work item form

The rich text editor tool bar displays below the text entry area when you click your cursor within the each text box that can be formatted.

Discussion section, New Rich Text Editor toolbar

Use the @mention control to notify another team member about the discussion. Simply type @ or use the  at-mention icon. and select or type their name. You can bring a group into the discussion by typing @ and the group name, such as a team or security group.

To reference a work item, use the #ID control or use the  #-work-item-id icon. Type # and a list of work items that you've recently referenced will appear from which you can select.

Use the  pull-request id icon to link to a pull request.

Use the @mention control to notify another team member about the discussion. Simply type @ and their name. To reference a work item, use the #ID control. Type # and a list of work items that you've recently referenced will appear from which you can select.

Important

For on-premises Azure DevOps Server or TFS, you must configure an SMTP sever in order for team members to receive notifications.

To reference a work item, use the #ID control. Type # and a list of work items that you've recently referenced will appear from which you can select.

Follow a work item

When you want to track the progress of a single work item, choose the  follow icon. This 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 members of your team modifies 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 sever in order for team members to receive notifications.

Try this next

To quickly add backlog items, such as user stories, requirements or bugs, see these topics:

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 additional clients that you can use to add work items, see Clients that support tracking work items.