About work items and work item types

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

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 you created 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 hierarchy for the Agile process backlog work item:

  • User Stories and tasks are used to track work.

  • Bugs track code defects.

  • Epics and features are used to group work under larger scenarios.

    Diagram that shows Agile work item types.

Each team can configure how they manage Bug work items, at the same level as User Story or Task work items, by configuring the Working with bugs setting. For more information 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 nonwork project elements that can affect 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

Your team can choose how to 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 include or revise fields within a work item type. You can also introduce a personalized work item type, or adjust the display of work item types on backlogs and boards. The approach and extent of customization at your disposal get determined by the process model allocated to your project. For more information, see the following articles:

Work item form and Details tab

The work item form displays the fields used to track information associated with each individual work item. Define and update a work item through its respective work item form, in addition to other methods like bulk import, export, update, and modify work items.

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.

Work item form controls

Control Function
Copy to clipboard icon Copy URL of work item to clipboard (appears on hover over work item title)
Discussions icon Go to Discussions section
Open Actions menu for other work item tasks
Refresh icon Refresh work item with latest changes
Undo icon Revert changes to work item
History tab icon Open History tab
Links tab icon Open Links tab
Attachment tab icon Open Attachments tab
full screen icon / exit full screen icon Enter or exit full display mode of a section within the form
Collapse section icon/Expand section icon Collapse or expand a section within the form
New linked work item icon Add new work item and link to existing work item (might appear under Actions menu)
Change work item type icon Change work item type (Appears under Actions menu)
Change project icon Move work item to a different project (Appears under Actions menu)
Clone icon Copy work item and optionally change work item type (Appears under Actions menu)
Email icon Send email with work item (Appears under Actions menu)
Delete icon Recycle work item (Appears under Actions menu)
Storyboard icon Storyboard with PowerPoint (Appears under Actions menu)

Copy the URL

From the web portal, copy the URL from the web browser address or hover over the title and then select the copy icon. For other copy options, see Copy or clone work items.

Screenshot of copy hyperlink for a work item from web portal.

Use the Start storyboarding menu option

Important

Starting with Visual Studio 2019, the Azure DevOps Office Integration plug-in has deprecated support for Storyboarding with PowerPoint and Microsoft Project. Also, the Visual Studio Gallery for PowerPoint Storyboarding has been deprecated.

The Start storyboarding menu option is only available from the new web form. However, from the old web form, you can choose the Start Storyboarding link from the Storyboard tab from a backlog item, or open PowerPoint. See Storyboard your ideas using PowerPoint for requirements and usage.

You can storyboard your ideas using PowerPoint to bring your ideas to life with storyboard shapes, text, animation, and all the other features that PowerPoint Storyboarding provides. From any work item, you can open PowerPoint by choosing the Start storyboarding menu option.

Screenshot of Work item form, Start storyboarding menu option.

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, the drop-down menu lists 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 Closed.
  • The Kanban board and Sprint Taskboard support viewing and updating the workflow state of requirements or tasks, respectively, using drag and drop. For more information, 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. For more information, 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. For more information, 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 added to the project. Within the work item form, choose the Assigned To field to select a project member. Or, you can begin entering 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 configured with Microsoft Entra ID or Active Directory, 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 Microsoft Entra ID 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 Microsoft Entra ID or Set up groups for use in Azure DevOps Server deployments.

Use work item templates to quickly complete forms

With work item templates, you can quickly create work items that with prepopulated values for 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. For more information, 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 might not appear depending on your permission assignments. Also, additional options might 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 select your cursor within each text box. Each comment added is recorded in the History field. For more information, 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 is 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. For more information, see Link work items to deployments.

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. For more information, 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. For more information, 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. For more information, 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.

For more information, 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. For more information, 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 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. For more information, 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 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.For more information, 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 affect a 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. For more information, see Set permissions and access for work tracking and Stakeholder access quick reference.

Next steps