About work items and work item types in Azure Boards

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

You use work items to track features and requirements you're developing, code defects or bugs, and issues or risks to your project. Each work item is based on a work item type that determines the work item fields available for tracking information. The work item types available to you differ depending on the process used when your project was created: Agile, Basic, Scrum, or CMMI.

Each work item represents an object stored in the work item data store, and is assigned a unique identifier within an organization or project collection. The available work item types depend on the process you used when creating your project.

If you're just getting started, read 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.

Track work with different work item types

To track different types of work, you choose a specific work item type. The following images show the default work item types available for the four default processes. 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 to do and provide fields to track information about that work.

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 Sprint backlogs and Taskboards
Bug Bug Dependent on team configuration for tracking bugs

The Issue (Agile and CMMI) and Impediment (Scrum) work item types are used to track non-work project elements that can impact work getting done. By default, they don't appear on any backlog or board.

For a list of other work item types, see Work item types to track testing, reviews, and feedback later in this article.

Track bugs as requirements or tasks

Teams have a choice for how they track bugs. They can track them along with requirements and have them show up on their product backlog and Kanban board. Or, they track them similar to tasks, in which case they typically link the bugs to a user story or product backlog item. A third option exists to not track them as requirements or tasks.

To configure the team bug tracking option, see Show bugs on backlogs and boards. For an overview of all team settings, see Manage teams and configure team tools.

Customize a work item type

You can add or modify the fields contained within a work item type, add a custom work item type, or change the work item types that appear on backlogs and boards. The method you use and what you can customize depends on the process model assigned to your project. To learn more, see the following articles:

Work item form and Details tab

The work item form shows the fields used to track information related to each work item. In general, you define and update a work item through it's work item form, although other methods are available to bulk import, export, update, and modify work items. For an overview of all form controls, see Work item form controls.

Each work item form contains several tabs. The Details tab contains the common fields, other fields defined for the work item type, and the Discussion control. Common fields defined for all work item types display at the top of the work item form. As shown in the following image, these fields include the following fields: Title, Assigned To, State, Reason, Area, and Iteration. You can update these fields at any time.

Screenshot of common fields in work item form for all work item types.

Common work tracking fields

The following common fields appear in most work items in the header area of the form. The only required field for all work item types is Title. When the work item is saved, the system assigns it a unique ID. The form highlights required field in yellow. For descriptions about other fields, see Work item field index.

Note

Additional fields may be required depending on customizations made to your process and project.

Field Usage
Title Enter a description of 255 characters or less. You can always modify the title later.
Assigned To Assign the work item to the team member responsible for performing the work. Depending on the context you are working in, the drop-down menu will list only team members or contributors to the project.
State When the work item is created, the State defaults to the first state in the workflow. As work progresses, you update it to reflect the current state.
Reason Automatically updates when the State is changed. Each State is associated with a default reason.
Area Choose the area path associated with the product or team, or leave blank until assigned during a planning meeting. To change the dropdown list of areas, see Define area paths and assign to a team.
Iteration Choose the sprint or iteration in which the work is to be completed, or leave it blank and assign it later, during a planning meeting. To change the drop-down list of iterations, see Define iteration paths (sprints) and configure team iterations.

Track active, open, resolved, or closed work items

Workflow states define how a work item progresses from its creation to closure. Workflow states also determine whether a work item appears on a backlog or board as described in How workflow category states are used in Azure Boards backlogs and boards.

The four main states that are defined for the User Story (Agile process) describe a user story's progression. The workflow states are New, Active, Resolved, Closed, and Removed. The following images illustrate the natural progressions and regressions for User Stories (Agile), Issues (Basic), Product Backlog Items (Scrum), or Requirements (CMMI). Similar progressions and regressions are defined for other work item types for each process.

Workflow states: User Story, Agile process

User Story workflow states, Agile process

Note

  • A work item can exist in one and only one state.
  • When all work is complete, set the work item State to
  • The Kanban board and Sprint Taskboard support viewing and updating the workflow state of requirements or tasks, respectively, using drag and drop. To learn more, see Start using your Kanban board and Update and monitor your Taskboard.
  • Depending on the View Options you select, work items in a Closed or Completed state won't appear on the backlog.
  • The Removed state supports removing a work item from appearing on the backlog. To learn more, see Move, change, or delete work items.
  • You can query work items by State and other fields to list work in progress, resolved, or completed. To learn more, see Query by assignment or workflow changes.

Assign work

You can only assign a work item to one person at a time. The Assigned To field is an identity field designed to hold a user identity that has been added to the project. 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.

Screenshot of Assigned To field in the work item form.

Note

  • 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 identity fields display the names you have most recently selected.
  • You can assign several work items at once from the backlog or query results, see Bulk modify work items for details.
  • To learn more about identity fields, see Query by assignment or workflow changes.

When Azure DevOps is configured with Azure Active Directory or Active Directory, then Azure DevOps synchronizes identity fields with these directories. Identity fields include Activated By, Assigned To, Closed By, Created By, and Resolved By.

You can grant access to a project by adding security groups that you created in Azure AD or Active Directory by adding accounts to existing or custom groups defined from the collection setting Security pages. For more information, see Add or delete users using Azure Active Directory or Set up groups for use in Azure DevOps Server deployments.

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.

Follow, Refresh, Revert, and Actions menu

The Follow, Refresh, Revert changes, and Actions menu controls appear on all work item forms.

Screenshot of Follow and Refresh icons, and Actions menu.

Note

Some menu options may not appear depending on your permission assignments. Also, additional options may appear based on Marketplace extensions added to your organization or other customizations made to the work item type.

Discussion control

With the Discussion control, project members can add and review comments made about the work being performed. The rich text editor tool bar displays below the text entry area when you click your cursor within each text box. Each comment added is recorded in the History field. To learn more, see View and add work items. To query the Discussion or History, see Query work item history and discussion fields.

Screenshot of Discussion section within a work item form.

The Deployment, Development and Related Work controls are special controls available in most work tracking forms.

Screenshot of Deployment control.

Screenshot of Development control.

Screenshot of Related Work control.

The Deployment control provides a quick view of whether a feature or user story has been deployed and to what stage. You gain visual insight into the status of a work item as it is deployed to different release environments and quick navigation to each release stage and run. To learn more, see Link work items to builds and deployments.

The Development and Related Work controls are used to support common linking tasks to development objects or other work items. These controls are available in most work items used to track work. The following table provides a short description of each control.

Screenshot of Development control.

Screenshot of Related Work control.

The Development control records all Git development processes that support completion of the work item. It also supports traceability, providing visibility into all the branches, commits, pull requests, and builds related to the work item. To learn more, see Drive Git development from a work item .

The Related Work control provides a quick view of linked work items, and supports adding a link to a parent work item. Also, you can quickly add and remove linked work items. To learn more, see Link user stories, issues, bugs, and other work items.

The History, Links, and Attachments tabs support auditing, traceability, and sharing information. These three tabs provide a history of changes, controls to add and remove links to work items, and controls to attach and remove files.

History: Review changes made to the work item

The History tab maintains a record of changes made to a work item over time. A record is made when changes are made to any of the common fields, description or other rich-text fields, Discussion control entries, or addition or removal of links or attachments.

The state change history diagram appears first. To see the entire history of state changes, choose Show all.

Screenshot of Work item form, Web portal, State change history diagram (web portal only).

Choose an entry in the left pane to view the details of changes made. To learn more, see Query work item history and discussion fields.

Screenshot of Work item form, History tab, Web portal, Details.

From the Links tab, you can add, remove, or view work items or other objects linked to the work item. Different link types are used to link to different objects, or to link to other work items.

Screenshot of Work item form, Links tab.

To learn more about linking, see the following articles:

Attachments: Attach files to a work item

From the Attachments tab, you can add, remove, or view files or images added to the work item. You can add up to 100 attachments to a work item. Attachments are limited to 60 MB. To learn more, see Share information within work items and social tools.

Track work in the web portal

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

  • Work items: Use to quickly find work items assigned to you or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated.
  • Boards: Use to implement Kanban practices, update the State, and visualize the flow of work for a team.
  • Backlogs: Use to plan, prioritize, and organize the work for a team to do within a product or portfolio backlogs.
  • Sprints: Use to plan work for a team to perform during a sprint.
  • Queries: Use to define a set of filter criteria to list work items for the purposes of sharing with others, performing bulk updates, or import/export operations.
  • Delivery 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.
  • Work items: Use to quickly find work items assigned to you or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated.
  • Boards: Use to implement Kanban practices, update the State, and visualize the flow of work for a team.
  • Backlogs: Use to plan, prioritize, and organize the work for a team to do within a product or portfolio backlogs.
  • Sprints: Use to plan work for a team to perform during a sprint.
  • Queries: Use to define a set of filter criteria to list work items for the purposes of sharing with others, performing bulk updates, or import/export operations.
  • Work items: Use to quickly find work items assigned to you or pivot or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated.
  • 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, update the State, and visualize the flow of work for a team.
    • Sprint backlogs: Use to plan work for a team to perform during 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.

Work item types to track testing, reviews, and feedback

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 most all processes.

Category and Work item type Used to track specified types of work
Code Review Request Tracks a code review request against code maintained in a Team Foundation version control (TFVC) repository. To learn more, see Day in the life of a Developer: Suspend work, fix a bug, and conduct a code review.
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 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 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 Each test case defines a manual test.
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 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.

Required permissions and access

Members added to the Contributors group of a project can use most features provided under the Boards hub. To add users to a project, see Add users to a project or team.

The following table summarizes the permissions that impact project member's ability to view and edit work items.

Level Permission
Area path View work items in this node
Area path Edit work items in this node
Project Create tag definition
Project Change work item type
Project Move work items out of this project
Project Delete and restore work items
Project Permanently delete work items

Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. To learn more about work tracking permissions and feature access, see Permissions and access for work tracking and Stakeholder access quick reference.

Try this next