Track user stories, issues, bugs, and other work items in Azure Boards

TFS 2017 | TFS 2015 | TFS 2013

Track the features and requirements you're developing, code defects or bugs, and other details using work items. Work items are similar to GitHub issues, but offer different types to track various types of information.

If you're just getting started, read the information provided in this article. To jump right in and start tracking work on a Kanban board, see Plan and track work. For a quick reference to various work item tasks and key concepts, see Work item quick reference.

Plan and track work

Use work items to track anything you need to track. Each work item represents an object stored in the work item data store. Each work item is based on a work item type. And work item types have a unique identifier within an organization or project collection. The available work item types depend on the process you used when your project was created (Agile, Scrum, or CMMI).

Tasks you can do using work items

Required permissions and access

As a member added to the Contributors group of a project, you can use most features provided under Boards or Work. Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. For details, see Stakeholder access quick reference.

To learn more about permissions and access, see Permissions and access for work tracking and Stakeholder access quick reference.

To add users to a project, see Add users to a project or team.

Work item types (WITs)

To track different types of work, different WITs are defined. The work item types available are based on the process used when your project was created—Agile, Basic, Scrum, or CMMI—as illustrated in the following images. The items in your backlog might be called user stories (agile) issues (Basic), product backlog items (Scrum), or requirements (CMMI). All four types are similar: they describe the customer value of the work and the work to do.

The following image shows the Agile process backlog work item hierarchy. User Stories and Tasks are used to track work, Bugs track code defects, and Epics and Features are used to group work under larger scenarios.

Conceptual image, Agile work item type

Each team can configure how they manage Bugs—at the same level as User Stories or Tasks—by configuring the Working with bugs setting. To learn more about using these work item types, see Agile process.

Each work item type belongs to a category. Categories are used to group work item types and determine which types appear on backlogs and boards.

Category Work item type Controls backlogs/boards
Epic Epic Epic portfolio backlogs and boards
Feature Feature Feature portfolio backlogs and boards
Requirement User Story (Agile)
Issue (Basic)
Product Backlog Item (Scrum)
Requirement (CMMI)
Product backlogs and boards and Sprints backlog
Task Task Sprints Taskboards
Bug Bug Dependent on how bugs are tracked

Along with the work items types that appear on backlogs and boards, there are work item types that track testing, reviews, and feedback. These types, listed in the following table by category, are available for all processes.


Work item type

Used to track specified types of work

Code Review Request

Code Review Request

Code Review Response

Code Review Response

A code review response is created for each person who's requested to provide review comments.

Feedback Request

Feedback requests track requests for feedback generated through the feedback request form. See Get feedback.

Feedback Response

Feedback Response

A feedback response is created for each person and for each item for which feedback is provided through the Microsoft Feedback Client. See Get feedback.

Shared Step

Shared Step

Shared steps are used to repeat tests with different data.

Shared Parameter

Shared Parameters specify different data and parameters for running manual test cases. See Repeat a test with different data.

Test Case

Test Case

Each test case defines a manual test.

Test Plan

Test Plan

Test plan group test suites and individual test cases together. Test plans include static test suites, requirement-based suites, and query-based suites.To learn more, see Create test plans and test suites.

Test Suite

Test Suite

Test suites group test cases into separate testing scenarios within a single test plan. Grouping test cases makes it easier to see which scenarios are complete. See Create test plans and test suites.

Ideally, work items are only created from the specific tool designed to support their usage. So, to prevent users from creating work items manually, there's a Hidden Types category. All of the categories listed in the previous table are added to the Hidden Types category except for the Test Case category.

Work item form

Each work item supports tracking data contained in work item fields. Also, it captures changes as updates are made within the History field. To learn more about each field, see Work item field index.

Each form contains multiple controls, as shown below and described in Work item form controls.

The new form and its corresponding features are available from the web portal. The new form is automatically available when you add projects to a new collection. For existing projects, an admin is required to enable the new form.

New web form

The new web form provides multiple experiences not provided with the old web form. To learn more, see New work item experience.

Screenshot of Work item form to track features or user stories, new web form.

Old web form

Screenshot of Work item form to track features or user stories, old web form.

Track work in the web portal

You can add and update work items from the web portal. To track work using other clients, see Best tools for adding, updating, and linking work items.

Web portal and clients that support tracking work items

You can add and update work items from the web portal and various clients. For an overview of all clients that connect to your project, see Tools and clients that connect to Azure DevOps.

Web portal

Use the web portal to accomplish the following tasks.

  • Backlogs: Which provide access to:
    • Product and Portfolio backlogs: Use to plan, prioritize, and organize the work for a team to do within a product or portfolio backlogs.
    • Boards: Use to implement Kanban practices and visualize the flow of work for a team.
    • Sprint backlogs: Use to plan work for a team to perform during a specific time frame referred to as a sprint.
  • Queries: Use to define a set of filter criteria to list work items for the purposes of sharing with others or performing bulk updates.
  • Plans: Use to review the schedule of stories or features your teams plan to deliver. Plans show scheduled work items defined that are assigned to sprints (iteration path) of selected teams against a calendar view. Requires installation of the Delivery Plans extension.

Track bugs as requirements or tasks

Many Scrum teams treat bugs the same as any backlog item or user story. Others see bugs as work that belongs to implementing a story, and then treat them as a task. Bugs, like product backlog items (PBIs) and user stories, represent work that needs doing. So, should you track your bugs along with other items in the product backlog items? Or, should you track your bugs as tasks linked to those backlog items? How does your team estimate work?

Based on how your team answers these questions, they can choose how they want to track bugs from one of these three choices. To change the team setting, see Show bugs on backlogs and boards.

For an overview of all team settings, see Manage teams and configure team tools.

Assign work items to a project member

You can only assign a work item to one person at a time. The Assigned To field is a person-name field designed to hold a user identity recognizable by the system. Within the work item form, choose the Assigned To field to select a project member. Or, you can begin typing the name of a project member to quickly focus your search to a select few.

Web work item form, Assign to field

Anyone who has write access to a project can assign work items, including users with Basic and Stakeholder access.

Note the following:

  • You can assign a work item only to users that have been added to a project or team
  • You can assign a work item to one and only one user at a time. If work is split across two or more users, consider creating separate work items that you'll assign to each user responsible for the work to complete
  • Over time, the drop-down menu of person-name fields will display the names you have most recently selected
  • Some drop-down menus that support assignment from a team backlog or board are automatically limited to users assigned to the team
  • The system shows the display name and adds the user name when required to disambiguate identical display names
  • You can assign several work items at once from the backlog or query results, see Bulk modify work items for details.

Assign work items to a sprint

To schedule work items to be worked on during a specific time period, you assign the Iteration Path. First, you define the Iteration Paths for use in the project, and then each team selects the Iteration Paths that they'll use. To learn more, see Assign work to sprints.

As shown in the following image, you can link work items to other work items. Depending on the work item type, the link type differs. Also, special link types support a hierarchy of work items using parent-child links and predecessor-successor links to track dependencies.

Work item link types, conceptual image

Also, several tools support linking to other objects, such as builds, releases, commits, pull requests, and more. The following image demonstrates.

Artifact-to-artifact link types

For a complete list of link types and supported features, see Linking, traceability, and managing dependencies and Link type reference.

Find or list work items

Use the search box to do an impromptu search for finding specific work items based on select field criteria. Or, create a query to do a managed search, which lists work items based on your query criteria. With managed searches, you can do other tasks, such as a work items triage, creating a trend or status chart, adding to the dashboard, and more.

To learn more, see these articles:

Use work item templates to quickly fill in forms

With work item templates, you can quickly create work items that have pre-populated values for your team's commonly used fields. For example, create a task template that sets the area path, iteration path, and discipline or activity whenever you use it to create a task.

To learn more, see Use templates to add and update work items.

Once you have a template defined, you can share it via email or a dashboard.

Customize a work item type

You can add or modify the fields contained within a work item type or add a custom WIT. To learn more, see Customize the On-premises XML process model.

Try this next