Azure Devops Manual

Tell us about your PDF experience.
Azure Boards documentation

Plan, track, and discuss work across teams. Define and update issues, bugs, user stories,
& other work with customizable Scrum, Kanban, and Agile tools.
About Azure Boards
ｅ OVERVIEW
What is Azure Boards?
About work items
ｐ CONCEPT
About default processes
Agile process workflow
Get started
ｆ QUICKSTART
Sign up for Azure Boards
Plan & track work
Get started as a Stakeholder
Plan your project
ｅ OVERVIEW
About Backlogs & Agile project management
ｆ QUICKSTART
Create your backlog
Define features & epics
Organize your backlog

ｇ TUTORIAL
Bulk add or modify work items (Excel)
Bulk add or modify work items (Web)
Implement Kanban
ｆ QUICKSTART
Kanban board quickstart
ｇ TUTORIAL
Kanban board overview
Add columns
Customize your Kanban board
Implement Scrum
ｅ OVERVIEW
About Sprints & Scrum
ｇ TUTORIAL
Assign work to sprints
Set capacity
Monitor sprint burndown
List & manage work items
ｇ TUTORIAL
Create managed queries
Perform ad hoc searches

Define, triage, & manage bugs
Remove, delete, or restore work items
Collaborate
ｆ QUICKSTART
Connect Azure Boards to GitHub
Link GitHub commits, pull requests, & issues to work items
ｐ CONCEPT
Link work items to support traceability
ｇ TUTORIAL
Use work item templates
Add tags to work items
Azure Boards with Microsoft Teams
Configure & customize
ｐ CONCEPT
About teams & Agile tools
Configure & customize Boards
ｇ TUTORIAL
Set area paths
Set iteration (sprint) paths
Add a custom field
Customize the workflow
See more...
Agile at Scale
ｇ TUTORIAL
Portfolio management
Review team deliverables & plans
Implement Scaled Agile Framework®
Troubleshoot
ｃ HOW-TO GUIDE
Fix re-ordering & nesting issues
Set up your Backlogs & Boards
FAQs
Quick reference
ｉ REFERENCE
Work items quick reference
Query quick reference
Work item field index
Developer resources
ｉ REFERENCE
Azure DevOps CLI
REST API
What is Azure Boards?
Article • 06/27/2023
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS
2018
Azure Boards is a web-based service that enables teams to plan, track, and discuss work
across the entire development process, while it supports agile methodologies, including
Scrum and Kanban. Azure Boards provides a customizable platform for managing work
items, allowing teams to collaborate effectively and streamline their workflow. Sign up,
customize, and experience the benefits of using Azure Boards.
Use Azure Boards hubs

You can track and manage work and access various functions within each of the
following hubs.
Azure Functions
Boards
hub
Work Access lists of work items based on specific criteria, such as those assigned to you,
items ones you follow, and work items you viewed or updated.
Boards View work items as cards and update their status through drag-and-drop, similar to
physical sticky notes on a whiteboard. Use this feature to implement Kanban practices
and visualize work flow for a team.
Backlogs View, plan, order, and organize work items, including using a product backlog to
represent your project plan and a portfolio backlog to group work under features and
epics.
Sprints Access your team's filtered view of work items based on a specific sprint or iteration
path. Assign work to a sprint using drag-and-drop from the backlog. Interact with a
backlog list or card-based Taskboard to implement Scrum practices.
Queries Generate custom work item lists and perform various tasks, such as triage work, make
bulk updates, and view relationships between work items. Queries also allow for
creating status and trend charts that can be added to dashboards.
Delivery Management teams can view deliverables and track dependencies across multiple
Plans teams in a calendar view. Delivery plans support tasks such as viewing up to 15 team
backlogs, custom portfolio backlogs and epics, and work that spans several iterations.
Users can add backlog items to a plan, view rollup progress of features and epics, and
dependencies between work items.
Azure Functions
Boards
hub
Analytics Create highly sophisticated Power BI reports, based on Azure Boards data (work
views items). Access default Analytics views or create a custom view.
Azure Boards hubs UI
Benefits of using Azure Boards

The following table lists some of the benefits of using Azure Boards.
Benefit Details
Benefit Details
Start simply, Azure Boards offers predefined work item types for tracking features, user
scale as you stories, bugs, and tasks, making it easy to start using your product backlog or
grow Kanban board. It supports different Agile methods, so you can implement the
method that suits you best. You can add teams as your organization grows to
give them the autonomy to track their work as they see fit.
Use visual, Visual tools help teams quickly see and share progress with Kanban boards,
interactive product backlogs, built-in scrum boards and planning tools, and delivery plans.
tools
Customize Easily configure and customize Kanban boards, Taskboards, and delivery plans
easily through the user interface, as well as add custom fields, work item types, and
portfolio backlogs.
Use built-in Work item forms provide built-in discussion that you can use to capture
social tools and questions, notes, and communication as they occur. You can maintain a history
communication of what a team decides on any particular work item. You can also quickly bring a
team member or an entire team into the conversation by using @mentions.
Capture Work items are designed to track all the information you need. You can edit in
information, rich text, drag and drop inline images, and add larger attachments - up to 60
generous cloud MB and as many as 100. Also, you can link work items within a hierarchy or by
storage simple related links. Each work item form maintains a history of changes, so you
can review what changed, who made the change, and when.
Find what you Azure Boards provides easy-to-use tools to help you quickly find specific work
need quickly items as your project grows. You can follow work items to monitor updates and
and get changes, use pivot views to show work items assigned to you, use the query
notified of engine to filter work items based on any field, and use ad-hoc search with quick
changes inline filters. You can also personalize your alerts for work items that are
assigned to you or have been changed.
Monitor status With Azure Boards, you gain access to many tools to generate reports to
and progress support tracking status and trends. By using configurable dashboards, you can
with built-in add one or more widgets. You configure widgets to display the information and
dashboards data you want, such as the following bug burndown widget. Along with
and analytics dashboards, you have access to the Analytics service. This service is optimized
for fast read-access and server-based aggregations. By using Analytics views
and Power BI, you can create highly sophisticated reports on the project data of
interest.
Integrate with Project managers who want to use familiar tools can import and export work
Office item queries to and from Microsoft Office Excel or import and export work
items using .csv files. For more information, see Bulk import or update work
items using CSV files or Bulk add or modify work items with Excel
Benefit Details
Extend You can gain even greater functionality by adding Marketplace extensions,
functionality many of which are free. An extension is an installable unit that adds capabilities
to Visual Studio, Azure DevOps Services, or Visual Studio Code. You can find
extensions within these products or in the Visual Studio Marketplace , Azure
DevOps tab. Also, by using the REST API, you can create your own extensions or
tools to integrate with Azure DevOps Services.
Get updates It's easy to stay on top of changes as they occur, using the mobile browser, you
via a mobile can be notified and respond to changes made to work items.
browser
Start for free You can start for free and add up to five free users and unlimited stakeholders.
For more information, see our Training module, What is Azure Boards?
Connect Azure Boards to GitHub

You can connect Azure Boards with GitHub repositories to link GitHub commits, pull
requests, and issues to work items. Use GitHub for software development and Azure
Boards to plan and track work. Quickly open linked GitHub commits, pull requests, or
issues from the Kanban board. For more information, see GitHub & Azure Boards.
Implement Agile, Scrum, and Kanban processes

Azure Boards supports software development processes with default process models.
Each process includes a set of work item types with a natural hierarchy.
Basic provides the simplest model that tracks work through Issues, Tasks, and Epics.
Agile supports Agile planning methods (learn more about Agile methodologies at the
Agile Alliance), including Scrum, and tracks development and test activities separately.
This process works great if you want to track user stories and (optionally) bugs on the
Kanban board, or track bugs and tasks on the Taskboard.
Scrum tracks work using product backlog items (PBIs) and bugs on the Kanban board or
viewed on a sprint Taskboard.
This process supports the Scrum methodology as defined by the Scrum organization
Capability Maturity Model Integration (CMMI) supports a framework for process

improvement and an auditable record of decisions. With this process, you can track
requirements, change requests, risks, and reviews. This process supports formal change
management activities.
Configure dashboards and Power BI reports
Dashboards provide teams with customized views for status updates, progress tracking,
and trend analysis. Teams can share information and improve workflows with flexible
and tailored dashboard options.
Use Power BI to create customized reports based on Analytics service queries for
quantitative analysis of project data. For more information, see About dashboards,
charts, reports, & widgets and What is the Analytics service?.
Gain visibility through end-to-end traceability
With Azure Boards, you gain the advantage of full integration with the Azure DevOps
platform. Azure DevOps is designed to provide end-to-end traceability, tracking work
from requirements to deployment. Gain insight at each step of decision making and
software deployment. Some of the traceability tasks supported include:
Create a branch from a requirement

Create a pull request of updated branch
Validate the pull request using a build pipeline
Create and run inline tests on requirements
Merge the pull request into the main, default branch
Deploy changes into production with deployment status to Azure Boards
Monitor and report on requirements traceability
For more information, see End-to-end traceability and Cross-service integration and
collaboration overview.
Support independent, autonomous teams

A team in Azure Boards is a group of project members who work in a specific product
area represented by hierarchical paths called Area Paths. Define teams by their name,
members, and area paths and are essential for configuring Boards, Backlogs, Sprints,
and Delivery Plans in Azure Boards. For more information, see About teams and Agile
tools.
Azure Boards integrates with popular chat tools such as Microsoft Teams and Slack
through ChatOps. It also offers extensions that add new capabilities to your projects and
can be found in the Azure DevOps Marketplace . These extensions can help with
planning and tracking work items, sprints, scrums, and other project management tasks,
as well as collaboration among team members.
Related articles
Best tool to add, update, and link work items
Configure and customize Azure Boards
The DevOps journey at Microsoft
Agile culture
Practices that scale
About teams and Agile tools
Best practices for Agile project
management
Article • 03/23/2023
2018
Azure Boards provides a choice of Agile planning tools, many of which work in
combination with each other. This article provides a get-started guide for project
managers new to Azure Boards. If you and your teams want to take a minimal tracking
approach to plan and manage your projects, start with this guide. Also, if you're moving
from waterfall project management to Agile methods, start with this guide.
７ Note
If your team is committed to practicing Kanban or Scrum methods, see instead

About Boards and Kanban or the tutorials for implementing Scrum.
Most of the guidance in this article is valid for both the cloud and on-premises versions.
However, some of the features included in this article, such as Rollup, Analytics, and
some portfolio planning tools, are only available for the cloud at this time.
Configure your teams

Azure Boards provides each team a set of Agile tools to plan and track work. Each
project defines a default team, which you can start using immediately. However, if you
have several development or feature teams, we recommend that you define a team in
Azure DevOps for each feature team. This way, each team can work autonomously while
collaborating with each other.
Best practice tips:

Configure teams along the value streams your organization wants to deliver
Define a team for each development group of six to 12 developers
Configure development teams to support rollup to project management feature
teams
For more information about configuring teams, see the following articles:
Configure a hierarchy of teams
Add a team, move from one default team to several teams
Agile culture
Scale Agile to Large Teams
Configure your sprints

Sprints—specified by Iteration Paths—are defined for a project and then selected by
teams. A sprint cadence can vary between one week to four weeks or longer. Also, you
can define sprints within a hierarchy that includes release trains. You assign work to
sprints that teams commit to deliver at the end of the sprint. These Azure Boards tools
rely on sprint assignments to a team Sprint backlogs, Taskboard, and Forecast and
Delivery plans.
Best practice tips:
Define a sprint cadence for use by all teams within your product group
Define at least six or more iterations that support planning for the next six to 12
months
Determine how teams use iterations to manage backlog items
Unassigned sprint work is assigned to the default backlog, or
Unassigned sprint work is assigned to a designated future backlog sprint.
For more information about configuring sprints, see the following articles:
About Area and Iteration Paths, Define and assign Iteration Paths
Define Iteration Paths and configure team iterations
Choose your work item types

Determine which work item types your team can use to capture customer requirements
and development work. If your project is based on the Agile process, we recommend
using User Stories, Bugs, and Features.
If your project is based on another process, such as Basic, Scrum, or CMMI, you have a
choice from those shown in the following images. Also, each team can determine how
they want to track bugs.
Agile process
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.
Each team can configure how they manage Bugs—at the same level as User Stories
or Tasks—by configuring the Working with bugs setting. For more information
about using these work item types, see Agile process.
７ Note
Requirements specify expectations of users for a software product. In Azure Boards,

requirements are defined by work items that appear on your product backlog. They
correspond to User Stories (Agile), Product Backlog Items (Scrum), Issues (Basic), or
Requirements (CMMI) based on the process selected for your project. They also
belong to the Requirements Category which manages which work item types
appear on the product backlog.
Best practice tips:
Use Features to capture customer features you want to ship

Quickly add features or requirements from the backlog and fill in details later
Use Requirements—User Stories (Agile), Issues (Basic) Product Backlog Items
(Scrum), or Requirements (CMMI)—to break down Features into work the
development team owns
Use Bugs to capture code defects
Map Requirements to Features to track progress at the project management level
Size Requirements to be completed within a sprint
Size Features to be completed within a sprint or several sprints
Size Epics to be delivered quarterly or to some milestone objective
Let Developers use Tasks to break down their work as needed.
As project managers, you manage the Features and the development team manages the
Requirements. By mapping them using parent-child links, you gain visibility into the
progress of your features. Each work item you add to your team backlog is automatically
assigned the default area path and iteration path set for your team.
If you have larger initiatives or scenarios that require shipping several Features, you can
group these under Epics, again using parent-child links.
For more information about work item types, see the following articles:
Define features and epics

Create your backlog
Organize your backlog (map or reparent)
Create your product plan

Create your product plan using the Features Backlog. The development team then
creates their product plan using the Product Backlog. Periodically you should review and
refine your product plans.
Features backlog
Project managers initiate the product plan by adding features to the Features backlog.
Each feature should represent a shippable deliverable that addresses a customer need.
Product backlog
Development teams add User Stories to their product backlog so that the User Story is
automatically assigned the team's default Area Path and Iteration Path. Then, they can
map those stories under each Feature that represents the work required to implement
the Feature. Each User Story should be sized so that they can be completed within a
sprint.
Refine each backlog

Periodically review each backlog:
Define work to be performed

Reorder work items using drag-and-drop so that they appear in priority order
Open work items and add details
Assign work to team members or to sprints
Capture technical debt and nonfeature work required to support a healthy
ecosystem of delivery
Map unparented work to the Feature they belong to
(Optional) Estimate size of requirements to help determine team velocity and
support forecasting
 Tip
You can monitor team velocity based on estimates assigned to completed work or
a simple count of work items completed during sprints. However, to use the
Forecast feature, you must assign a value to the Story Points, Effort, or Size field. If
you don't want to estimate requirements, you can simply assign a value of 1 to
requirement estimates and then use the Forecast tool based on a count of work
items.
Best practice tips:

Periodically refine your backlog
Make sure features and requirements are sized appropriately
Define the acceptance criteria and the definition of done for features and work
Map unmapped work to Features
Set your view options to support the backlog tasks you want to accomplish
Forecast your backlog
For more information, see the following articles:
Refine your backlog

Create your backlog
Configure your backlog view
Forecast your product backlog
Use tags to support queries and filtering

With work item tags, team members can assign ad-hoc tags to work items. You can use
these tags to filter backlogs and boards, and query on work items. For tags to be useful
to the team, provide some general guidance on how your team should use tags.
Consider documenting this guidance in a central place, such as the project wiki.
The following image illustrates a Kanban board filtered on the web keyword that
displays cards with the Web tag.
Best practice tips:
Have a policy in place about how your teams use tags

Indicate how you use tags to support queries, filtering, reporting
Consider using tags to identify cross-team or cross-project dependencies
Add work item tags to categorize and filter lists and boards
Filter your Kanban board
Create a Wiki for your project
Forecast and milestone planning

To gain insight into what features can ship when, use the Forecast tool. This tool
requires that you provide estimates to the Story Points, Effort, or Size field for each
requirement. If you want to forecast on a simple count of work items, then assign the
value of 1 to requirement estimates.
Order the features backlog in priority order

As project managers, you should always have your features backlog in priority order,
which conveys to the development team which features are most important to complete
first.
Here the features backlog shows the sequence of features to ship.

Order the requirements backlog based on parent features
First you want to make sure you're completing the requirements needed to ship
features. As shown in the following image, the requirements backlog has been ordered
according to the features you want to ship. This ordering assumes that all requirements
in a feature must be complete to ship it. Also, Story Points have been assigned to each
User Story.
Forecast the requirements backlog
With estimates assigned to each requirement, you can set a team velocity. In the
following example, we specify 12 for the velocity, equivalent to stating that on average
the team can complete 12 Story Points per sprint. The Forecast tool shows which
requirements and features the team can complete within the next six sprints. Using the
Planning tool, you can quickly assign requirements to the forecasted sprints.
To see the full image, click the image to expand. Choose the close icon to close.
Getting good at estimates and having predictable team velocities are useful team goals
for process improvement.
Update your Features board

With a forecast of when a feature ships, you can update each feature's iteration path.
Quickly assign values to a feature by adding those fields to the card on the Kanban
board as shown in the following image.
Milestone planning
Milestone markers aren't used in Azure Boards work tracking, except for Delivery Plans.
Delivery Plans provide a calendar view and allow you to define a milestone marker.
However, you can use one or more of the following options to mark a work item as a
milestone:
Prepend or append the word Milestone in the title of your work item
Add a work item tag labeled Milestone
Add a custom field labeled Milestone and populate it with a pick list of milestones
Link work items using the Predecessor/Successor or Related link type to a
milestone work item
Assign a milestone work item to the sprint in which it's targeted for completion.
Manage dependencies
In Microsoft Project, you manage tasks that depend on the completion of other tasks by
linking them. To manage dependencies in Azure Boards, you can add similar linking by
adding Predecessor/Successor link types to work items. You add these links from the
Add link dialog for a work item.
Add link dialog

Azure Boards supports many link types to track related work. Choose the
Predecessor/Successor link types to track work with dependencies. A quick way to link
work items is to add a tag to work items that participate in producing or consuming
dependencies, create a query based on this tag, and then add the required links from
the triage mode of the query results.
The following Add link dialog illustrates how two work items are linked using the
Successor link type.
Visualize work item relationships
You can view dependencies and identify dependencies that have issues with Delivery
Plans. As shown in the following image, you can toggle the display of dependency lines
between linked work items. For more information, see Track dependencies using
Delivery Plans.
Minimum Viable Product versus Critical Path

Management
Azure Boards doesn't provide a native view of the critical path. In part, as Agile
methodologies favor a Minimum Viable Product (MVP) over Critical Path Management
(CPM). By using MVP, you identify the shortest path and dependencies by prioritizing
epics, features, stories and tasks. For more context, see The Critical Path on Agile
Projects and Running a lean startup on Azure DevOps .
Best practice tips:
Add a dependency tag to work items participating in dependency management

Use Predecessor/Successor link types to track dependencies of work owned by
other teams or within other projects
Create queries to track, add, and triage dependencies
Use Delivery Plans to view work that you have dependencies on from other teams
Use the Work Item Visualization Marketplace extension to visualize
dependencies for a specific work item within the work item form.
７ Note
Marketplace extensions are not supported features of Azure Boards and therefore
not supported by the product team. For questions, suggestions, or issues you have
when using these extensions, visit their corresponding extension page.
Link user stories, issues, bugs, and other work items

Triage work items
Track dependencies by using Delivery Plans
Work in sprints
Sprints allow the development team to focus on completing a preselected set of work.
Work assigned to a sprint appears on the team's sprint backlog. Sprint backlogs are
defined only for product backlogs, not for portfolio backlogs.
Sprint burndown chart

By updating the status of work daily throughout a sprint, you can easily track sprint
progress with the Sprint burndown chart, as shown in the following image.
Best practice tips
Each sprint, perform the following tasks:
Plan each sprint with your team

Use the team's Sprint backlog to review sprint deliverables
Ensure each sprint work item is assigned to a team member
Ensure each work item is scoped for completion within the sprint
Ensure the acceptance criteria for the work are well defined and understood
Update the status of sprint work items as work moves from a New to Active to
Completed state to track sprint burndown
Check in with other teams on dependencies that your team's work depends on
Monitor sprint progress using the Sprint burndown chart
Assign backlog items to a sprint

Configure and monitor sprint burndown
Review progress and feature deliverables

The three main tools you should use to review progress and deliverables are:
Features Kanban board
Features backlog with rollup columns
Delivery plans

Your Features board is another place to review progress and ensure the continuous flow
of deliverables. The following image illustrates a customized Features board. In progress
columns have been added such as Need more info, Spec Complete, In Progress, and
Customer Rollout. These provide a more natural set of states as Features get proposed,
researched, designed, developed, and then deployed to production.
Rollup
One quick and visual way to monitor progress is from the Features backlog. By adding
the rollup progress bar column, you can see what percentage of work items are
completed for each feature, as shown in the following image.
Delivery plans and multiple team deliverables
To review features delivered across several teams, configure a delivery plan. Delivery
plans provide an interactive board to review a calendar schedule of stories or features
several teams plan to deliver.
Best practice tips

Customize your Features Kanban board to support your team's processes
Add fields to cards so that you can update their values quickly and easily
Update the Iteration Path (Sprint) of Features as you gain clarity as to when they'll
ship
Review the Features board to talk through status, blocks/issues/risks/changes, and
update status
Use the filter feature to focus on tagged items, assigned by features, a specific
sprint and more
Add rollup columns to your Feature backlog to monitor overall progress based on
work item count completion
Use delivery plans to review features for several teams and discuss cross-team
dependencies
Add columns to your Kanban board

Customize cards
Display rollup progress or totals
Review team Delivery Plans
Process improvement
Continuous improvement is at the heart of Agile methods. To improve your processes,
you need to have shared goals and a shared plan. To initiate process improvement
activities, consider adding them through regular practices, such as:
Sprint planning
Setting sprint goals
Conducting regular retrospectives
Consider the following questions when setting goals:
What are you learning about your customers? What do you need to know?
What data is being measured? Is it actionable? What data needs to be measured?
How is the flow of deliverables? Is it as expected? Where can improvements be
made?
Are your team members empowered to do their best? What tools or information
would help them improve?
How well is information being shared? How well are teams collaborating?
How well is your team managing technical debt and closing bugs?
Some of the Agile tools you can use to support process improvement are team velocity,
team dashboards, and the Retrospectives Marketplace extension.
Team velocity
From the team velocity chart, you can gain an understanding as to how well the team is
planning and executing a sprint. As shown in the following example, the velocity chart
shows the planned, completed, completed late, and incomplete count of work items for
several sprints. Teams can review this chart to help determine how well they're
estimating and executing and how they might improve.
Team dashboards
Teams can define one or more dashboards to share information and monitor real-time
data on work progress.
Best practice tips
Identify process improvement goals that your team can agree to, write them down
and review them periodically
Use team dashboards to share information and work tracking charts which you and
your team review periodically
At sprint planning meetings, have your team identify at least one sprint goal
related to process improvement
Conduct regular retrospectives to capture what went well, what didn't go well, and
actions to improve
Maintain an improvement tracking board, such as that available with the
Retrospectives Marketplace extension.
View or configure team velocity

Add, rename, and delete dashboards
Scaling Agile - Practices that scale
Retrospectives Marketplace extension
Next steps
Related articles
Manage requirements
Work with multi-team ownership of backlog items
11 Reasons for using Azure Boards to plan and track your work
Industry articles
Agile and a continuous improvement mindset
What is KAIZEN™
Key concepts and work item tasks
Article • 08/23/2023
2018
Use this index to quickly access concepts and tasks related to work items and
information on adding and updating work items—such as users stories, features, tasks,
and bugs.
７ Note
The following features require that you enable the New Boards Hub preview
feature. These features are only available for Azure DevOps Services at this time. To
enable the New Boards Hub, see Manage or enable features.
Change the link type of an existing link

Filter the history tab
Reassign a checklist item
Move a card to a specific column position
Change the color of a swimlane on a Kanban board
Key concepts
Agile glossary
Agile process
Area Paths
Autocomplete work items
Assigned to
Basic process
Chart for work items widget

Charts
Client tools
CMMI process
Customization process models
Dependencies
Delivery plans
Filtering
Following
Inheritance process model
Iteration Paths
Keyboard shortcuts
Link types
Linking and traceability
Mobile browser
New Boards Hub
New work item widget
On-premises XML process model
Set permissions and access
Process guidance
Process models
Queries
Recycle bin
Remote linking
Rollup
Scrum process
State categories
Tags
Track bugs as requirements or tasks
Track dependencies
Visual Studio work item experience
Work item fields

Work item form
Work item form controls
Work item templates
Work item types
Work tracking limits
Workflow
Work item user tasks

Tasks listed below are available to users with Contributor permissions and Basic access.
Add a work item
Add Epics
Add Features
Add items to a backlog
Add items to a Kanban board
Add links
Add tags
Add tasks
Add to discussion
Apply a template to a work item
Assign work to a team member
Bulk add or remove tags
Bulk modify work items (Excel)
Bulk modify work items (Web)
Capture work item as a template

Change the link type
Change work item type
Copy or clone a work item
Copy work item URL
Copy list of work items
Create a branch
Create a work tracking chart
Define a work item template

Define work item URL
Delete work item tags
Delete work items
Display rollup
Send email of work item list
Export a work item list
Filter a backlog, board, or plan
Filter the History tab
Follow a work item
Forecast work items
Get notified of work item changes
Group work items
Link to cross-organization work items

Link to development objects
Link to GitHub commits and pull requests
Link to work items from a wiki
Link work items
List work items
List work items in a wiki
Manage bugs
Manage issues or impediments
Manage work item tags
Map work items
Move work items to a sprint
Move work items to another project
Open work items

Print work items
Prioritize backlog items
Query work item history
Query for work items
Reassign work items
Remove work items
Request feedback
Restore deleted work items
Start storyboarding
Track dependencies
Update status of tasks (Taskboard)

Update status of work items (Kanban board)
Use #ID to link
Use @mentions
View history
View work items (mobile)
View work items (web)
View work assigned to me
View work I'm following
View work I've recently viewed or updated
View work recently completed
View work recently created
View work where I'm mentioned
Administrative customization tasks

Tasks listed below must be performed by an administrator who has the necessary
permissions, as they affect all users and teams within a project.
You customize work item types using the Inheritance process model.
Add a checkbox (Boolean) field

Add a custom field
Add a custom work item type
Add/remove custom fields
Add/remove custom groups
Add/remove custom pages
Add/remove a custom control
Add/remove custom rules to a field
Add a person-name/Identity
Add a picklist (drop-down menu)
Add a rich-text (HTML) field
Add, edit, or remove a WIT workflow state
Change a field label

Change the WIT color or description
Change the reference process from Agile to Scrum
Change the reference process from Basic to Agile
Change the reference process from Scrum to Agile
Create a project
Define Area Paths

Define Iteration Paths
Delete field
Delete a WIT
Enable/disable a WIT
Modify a default pick list

Move the field within the layout
Remove a field from form
Restrict modification
Set required/default options
Set work tracking permissions
Related articles
Quick guide to default permissions and access
Sign up for Azure Boards
Article • 03/23/2023
Azure DevOps Services
Sign up for Azure Boards to plan, track, and discuss your work across your teams. For
more information, see What is Azure Boards?.
To sign up for all Azure DevOps Services, see Sign up, sign in to Azure DevOps.
Prerequisites
You must have the latest version of one of the following web browsers: Microsoft Edge,
Internet Explorer, Safari (Mac), Firefox, or Chrome.
Sign-up
1. From your web browser, open the Azure Boards sign-up page.
2. Select which account you want to use.
Start free: Choose this option when:

You have a Microsoft account and plan to sign in using your account email
address, phone number, or Skype ID. If you're a Visual Studio subscriber
and you get Azure DevOps as a benefit, use the Microsoft account
associated with your subscription.
You want to sign up using a general email address you want to use. A
project gets created based on your account name, but you can change the
project name later.
 Tip
You can sign up with any valid email address. Signing up for Azure
Boards enables your email address as a Microsoft account.
An organization and project get created based on your account
name. Sign in to your organization at any time by entering
https://dev.azure.com/{yourorganization} in your web portal. You
can change the organization or project settings at any time.
Start free with GitHub: Choose this option if you have an existing GitHub
account.
） Important
If your GitHub email address is associated with an Azure AD-backed

organization in Azure DevOps, you can't sign in with your GitHub
account, rather you must sign in with your Azure AD account.
If you've already signed up or have an organization set up to use Azure Boards,

choose the Sign in link.
3. Continue through the flow to finish signing up.
When you're done, you have an organization and a project that correspond to your
account name. Optionally, you can change the name or other settings for your
organization or project.
Sign in to your organization at any time

( https://dev.azure.com/{yourorganization} ).
Optional: Change your organization or project settings

An organization is your container for projects, users, and other resources. It groups
related projects and provides a centralized location for managing users, permissions,
and billing. It also has tools for planning, tracking, and collaborating on projects.
For more information about changing your organization settings, see the following
articles.
Rename an organization
Change the location of your organization
A project is a specific effort within an organization. Each project is associated with a

specific team and can have its own set of permissions, settings, and configurations.
For more information about changing your project settings, see the following articles.
Rename a project
Delete a project
Change the project visibility, public or private
Next steps
Add users or groups to your team or project
Related articles
Track issues and tasks
About access levels
Define organizations and projects
Plan and track work in Azure Boards
Article • 03/22/2023
2018
In this article, learn how to use Azure Boards to plan and track your work using an Agile,
Basic, Scrum, or Capability Maturity Model Integration (CMMI) process. For more
information, see About processes and process templates.
Agile process
The Agile process uses various work item types such as user stories, tasks, bugs,
features, and epics to plan and track work. Begin by adding user stories and
grouping them into features if needed. You can add tasks to a user story to track
more details.
Work item types Backlog hierarchy
Within each work item form, you can describe the work to be done, assign work to
project contributors, track status, and collaborate with others through the
Discussion section.
We show you how to add user stories and child tasks from the web portal and add
details to those work items.
Prerequisites
You must have Basic access and be a member of the Contributors or Project
Administrators group to add work items to a board and use all other board
features.
You must have Stakeholder access for a private project and be a member of the
Contributors or Project Administrators group to view boards, open and modify
work items, and add child tasks to a checklist. But, you can't reorder or reparent a
backlog item using drag-and-drop, nor update a field on a card.
You must have Stakeholder access for a public project and be a member of the
Contributors or Project Administrators group to have full access to all Boards
features.
For more information, see Default permissions and access for Azure Boards.
Open your Kanban board

A Kanban board is provisioned with the addition of each project and each team. You can
only create or add Kanban boards to a project by adding another team. For more
information, see About teams and Agile tools.
1. Sign in to your organization ( https://dev.azure.com/{your_organization} ) and go

to your project.
2. Select Boards > Boards.

3. Select a board from the All Team Boards dropdown menu.
Add work items to your board
Work items on your board are automatically assigned the default Area Path and
Iteration Path assigned to the team. For more information, see Configure team settings.
Agile process
1. From the Stories board, choose New item and the stories you want to track.
2. Enter return and the system assigns a work item ID to the user story.
3. Add as many user stories as you need.
 Tip
To quickly add features and child user stories, choose Features from the board
selector.
Add details to a board item
Select the issue or user story title to open it. Change one or more field values, add a
description, or make a note in the Discussion section. You can also choose the
Attachments tab and drag-and-drop a file to share the file with others.
Agile process
For example, here we assign the story to Raisa Pokrovskaya and add a discussion
note, at-mentioning Raisa.
Choose Save & Close when you're done.
Field descriptions
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're working in, the drop-down menu lists only team
members or contributors to the project.
７ Note
You can only assign work to a single user. If you need to assign work to more than
one user, add a work item for each user and distinguish the work to be done by
title and description. The Assigned To field only accepts user accounts that have
been added to a project or team.
State
When the work item is created, the State defaults to the first state in the workflow. As
work progresses, update it to reflect the current status.
Reason
Use the default first. Update it when you change state as need. Each State is associated
with a default reason.
Area (Path)
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 (Path)
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 and configure team iterations.
Description
Provide enough detail to create shared understanding of scope and support estimation
efforts. Focus on the user, what they want to accomplish, and why. Don't describe how
to develop the product. Do provide sufficient details so that your team can write tasks
and test cases to implement the item.
Acceptance Criteria
Provide the criteria to be met before the work item can be closed. Define what "Done"
means by describing the criteria for the team to use to verify whether the backlog item
or bug fix is fully implemented. Before work begins, describe the criteria for customer
acceptance as clearly as possible. Have conversations between the team and customers
to determine the acceptance criteria. These criteria help ensure a common
understanding within the team to meet customers' expectations. Also, this information
provides the basis for acceptance testing.
Priority
A subjective rating of the issue or task it relates to the business. You can specify the
following values:
1: Product cannot ship without the successful resolution of the work item, and it
should be addressed as soon as possible.
2: Product cannot ship without the successful resolution of the work item, but it
does not need to be addressed immediately.
3: Resolution of the work item is optional based on resources, time, and risk.
4: Resolution of the work item is not required.
Value Area
A subjective rating of the issue or task it relates to the business. You can specify the
following values:
Architectural: Technical services to implement business features that deliver
solution .
Business: Services that fulfill customers or stakeholder needs that directly deliver
customer value to support the business (Default).
Effort, Story Points, Size
Provide a relative estimate of the amount of work required to complete an issue. Most
Agile methods recommend that you set estimates for backlog items based on relative
size of work. Such methods include powers of 2 (1, 2, 4, 8) and the Fibonacci sequence
(1, 2, 3, 5, 8, etc.). Use any numeric unit of measurement your team prefers.
The estimates you set are used to calculate team velocity and forecast sprints.
Update work status
The State field tracks the status of a work item. With the Kanban board, you can quickly
update the status of backlog items by dragging and dropping them to a different
column.
Agile process
As work begins, drag the user story card from the Backlog column to the Active
column. Once work is ready for review, move it to the Resolved column. After it's
reviewed and accepted, move it to the Closed column.
 Tip
To add or rename columns as needed, see Customize your board.
Add tasks
Task checklists provide a quick and easy way to track elements of work that are
important to support completing a backlog item. Also, you can assign individual tasks to
different team members.
 Tip
Tasks that you create from the Kanban board are automatically assigned the Area
Path and Iteration Path of their parent work item and show up on your sprint
taskboard.
Tasks that you create from the sprint backlog or taskboard show up within tasks
checklists on the Kanban board.
Agile process
1. Select the actions icon for the story and select Add Task.
Enter a title for the task and select Enter when you're done.
2. If you have many tasks to add, keep entering your task titles and type Enter.
3. You can mark a task as done, expand or collapse the task checklist, or reorder
and reparent tasks.
Mark a task as done Reorder and reparent tasks Expand or collapse

the checklist
To mark a task as To reorder a task, drag it within To expand or collapse

complete, check the task the checklist. To reparent a the a task checklist, simply
checkbox. The task State task, drag it to another issue on choose the task
changes to Done. the board. annotation.
Add details to a task

If you have details you want to add about a task, choose the title, to open it. Change
one or more field values, add a description, or make a note in the Discussion section.
Agile process
Here we assign the task to Christie Church.

Field descriptions
In addition to the fields you can define for a backlog item—user story, issue, product
backlog item, or requirement—you can specify the following fields for a task to support
capacity and time tracking.
７ Note
There are no inherent time units associated with this field even though the
taskboard always shows "h" for hours in relationship to Remaining Work. You can
specify work in any unit of measurement your team chooses.
Field
Usage
Activity
The type of activity that's required to do a task.For more information about how this
field is used, see Capacity planning. Allowed values are:
Deployment
Design
Development
Documentation
Requirements
Testing
Discipline (CMMI process)
The type of activity that's required to do a task.For more information about how this
Analysis
Development
Test
User Education
User Experience
Original Estimate
The amount of estimated work required to complete a task. Typically, this field doesn't
change after it's assigned.
Remaining Work
The amount of work that remains to finish a task. You can specify work in hours or in
days. As work progresses, update this field. It's used to calculate capacity charts and the
sprint burndown chart.
If you divide a task into subtasks, specify Remaining Work for the subtasks only.
Completed Work
The amount of work spent implementing a task. Enter a value for this field when you
complete the task.
Task Type (CMMI only)
Select the kind of task to implement from the allowed values:

Corrective Action
Mitigation Action
Planned
Capture comments in the Discussion section
Use the Discussion section to add and review comments made about the work being
performed.
The rich text editor tool bar displays below the text entry area. It appears when you
select each text box that supports text formatting.
７ 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 ! .
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.
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.
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.
Save a comment without saving the work item
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.
７ 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.
Next steps
Customize your board
Related articles
Azure Boards FAQs
Add tags to issues or tasks
Get started as a Stakeholder
Article • 04/25/2023
2018
Stakeholders are users with free but limited access to Azure DevOps features and
functions. With Stakeholder access, you can add and modify work items, manage build
and release pipelines, and view dashboards. You can check project status and provide
direction, feedback, feature ideas, and business alignment to a team. For information
about working with pipelines, see Build your GitHub repository and Build OSS
repositories.
For more information, see the Stakeholder access quick reference. To compare
Stakeholder versus Basic access, see the feature matrix .
In this tutorial, learn how to:
＂ Understand Stakeholder access and available features

＂ Sign in to a project
＂ Understand work items and types
＂ Open your Kanban board
＂ Add work items
＂ Update work items
＂ View the backlog
＂ Find work items
Prerequisites
You must have Stakeholder access for a private project and be a member of the
Contributors or Project Administrators group. You can view boards, open and
modify work items, and add child tasks to a checklist. But, you can't reorder or
reparent a backlog item using drag-and-drop, nor update a field on a card.
You must have Stakeholder access for a public project and be a member of the
Contributors or Project Administrators group to have full access to all Boards
features. For more information, see Default roles and access for public projects
To get access as a Stakeholder, ask your organization owner or Project Collection

Administrator to add you to a project with Stakeholder access.
Sign in to a project
1. Select the link provided in your email invitation or open a browser window and
enter the URL for the web portal.
https://dev.azure.com/OrganizationName/ProjectName
2. Enter your credentials. If you can't sign in, ask the organization owner or Project
Administrator to add you as a member of the project with Stakeholder access.
Understand work items and types

Work items support planning and tracking work. Each work item is based on a work item
type and is assigned an identifier, which is unique within an organization or project
collection.
Different work items are used to track different types of work, as described in About
work items. 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.
Agile process
Open your Kanban board
You can view work items once you connect to a project.
1. In your project, and select Boards > Boards, and then select a team board from
the dropdown menu.
You can also enter a keyword in the search box or select View Board directory to
see a list of available team boards.
 Tip
Select the star icon to make a team board a favorite. Favorite artifacts (
favorite icon) appear at the top of the team selector list.
2. Check that you selected Stories for Agile, Issues for Basic, Backlog items for
Scrum, or Requirements for CMMI as the backlog level.
Add work items
From your board, select the plus sign, enter a title, and then select Enter.
For more information, see View and add work items from the Work Items page.
Update work items

The work item forms you see may differ from the following images. The basic
functionality is the same, however, changes have been made with different versions of
Azure DevOps.
Change status
Drag and drop a work item to move it downstream as you complete work.
Add details
To open a work item, double-click the title or highlight it, and then select Enter. Here we
show how to assign work. You can only assign work to a user who is added to the
project.
Agile process
For example, here we assign the story to Raisa Pokrovskaya and we add a
discussion note, at-mentioning Raisa. When you're done, select Save & Close.
Add more details by changing field values, adding a description or tags, and adding
comments. For more information, see the following articles:
Update fields: Descriptions and usage

Add tags to work items. As a Stakeholder, you can add existing tags to a work
item, but you can't add new tags.
View as Backlog
Check the product backlog to see how the team prioritized their work. Backlog items
appear in priority order. Work item types may include bugs depending on the process
used when your project was created.
From the Kanban board, choose View as Backlog.
You should see the list of backlog items listed in priority order. You can add a backlog
item, which goes to the bottom of the list. With Stakeholder access, you can't reprioritize
work.
Find work items

Choose Boards > Work Items > and then select an option from the dropdown menu.
Here we chose Assigned to me.
View, run, or email a work item query

View and add work items using the Work Items page
Next steps
Create your product backlog
Related articles
Add work items
Kanban quickstart
Access levels
Change access levels
About default processes and process
templates
Article • 05/02/2023
2018
Azure Boards offers various processes to choose from for managing work items.
Selecting the right process is essential for optimizing the workflow and ensuring the
success of a project. In this article, we explore the different processes available Azure
Boards and provide guidance on how to choose the most suitable one for your project.
When you create a project, you choose a process or process template based on the
process model for which your organization or collection was created. Before you choose
a process for your project, understand the following terms:
Term Description
Process Refers to the model used to support projects created for an organization or project
model collection. Only one process model is supported for a project at a time.
Process Defines the building blocks of the work item tracking system and supports the
Inheritance process model for Azure Boards. This model supports customization of
projects through a What You See Is What You Get (WYSIWYG) user interface.
Process Defines the building blocks of the work item tracking system and other subsystems
template you access through Azure DevOps. Process templates are only used with the Hosted
XML and On-premises XML process models. You can customize projects by modifying
and importing process template XML definition files.
７ Note

Create a project using the process of your choice
Customize your work tracking experience (process models)
Manage inherited processes
The work tracking objects contained within the default processes and process templates
—Basic, Agile, Capability Maturity Model Integration (CMMI), and Scrum—are the same
and summarized in this article.
Default processes
The default processes differ mainly in the work item types (WITs) they provide for
planning and tracking work.
Basic is the most lightweight and is in a selective Preview. Scrum is the next most
lightweight. Agile supports many Agile method terms, and CMMI provides the most
support for formal processes and change management.
７ Note
The Basic process is available with Azure DevOps Server 2019 Update 1 and later
versions.
Basic
Choose Basic when your team wants the simplest model that uses Issues, Tasks, and
Epics to track work.
Tasks support tracking Remaining Work.
Agile
Choose Agile when your team uses Agile planning methods, including Scrum, and tracks
development and test activities separately. This process works great if you want to track
user stories and (optionally) bugs on the Kanban board, or track bugs and tasks on the
taskboard.
You can learn more about Agile methodologies at the Agile Alliance.
Tasks support tracking Original Estimate, Remaining Work, and Completed Work.
Scrum
Choose Scrum when your team practices Scrum. This process works great for tracking
product backlog items (PBIs) and bugs on the Kanban board. You can also break down
PBIs and bugs into tasks on the taskboard.
This process supports the Scrum methodology as defined by the Scrum organization.
Tasks support tracking remaining work only.
CMMI
Choose CMMI when your team follows more formal project methods that require a
framework for process improvement and an auditable record of decisions. With this
process, you can track requirements, change requests, risks, and reviews.
This process supports formal change management activities. Tasks support tracking
Original Estimate, Remaining Work, and Completed Work.
If you need more than two or three backlog levels, you can add more based on the
process model you use:
Inheritance: Customize your backlogs or boards for a process

Hosted XML or On-premises XML: Add portfolio backlogs
Main distinctions among the default processes

The default processes are designed to meet the needs of most teams. If your team has
unusual needs and connects to an on-premises server, you can customize a process, and
then create the project. Or, you can create a project from a process and then customize
the project.
The following table summarizes the main distinctions between the WITs and states used
by the four default processes.
Tracking area
Basic
Agile
Scrum
CMMI
Workflow states
To Do
Doing
Done
New
Active
Resolved
Closed
Removed
New
Approved
Committed
Done
Removed
Proposed
Active
Resolved
Closed
Product planning (see note 1)

Issue
User story
Bug (optional)
Product backlog item
Bug (optional)
Requirement
Bug (optional)
Portfolio backlogs (2)

Epic
Epic
Feature
Epic
Feature
Epic
Feature
Task and sprint planning (3)

Task
Task
Bug (optional)
Task
Bug (optional)
Task
Bug (optional)
Bug backlog management (1)

Issue
Bug
Bug
Bug
Issue and risk management

Issue
Issue
Impediment
Issue
Risk
Review
７ Note
1. You can add these WITs from the product backlog or Kanban board. The
product backlog shows a single view of the current backlog of work that can
be dynamically re-ordered and grouped. Product owners can quickly prioritize
work and outline dependencies and relationships.
Also, each team can configure how they want bugs to show up on their
backlogs and boards.
2. With portfolio backlogs you can define a hierarchy of backlogs to understand
the scope of work across several teams and see how that work rolls up into
broader initiatives. Each team can configure which portfolio backlogs appear
for their use.
3. You can define tasks from the sprint backlog and taskboard. With capacity
planning, teams can quickly determine if they are over or under capacity for a
sprint.
Workflow states, transitions, and reasons

Workflow states support tracking the status of work as it moves from a new state to a
closed or a done state. Each workflow consists of a set of states, the valid transitions
between the states, and the reasons for transitioning the work item to the selected state.
） Important
For Azure DevOps Services and Azure DevOps Server 2019, the default workflow
transitions support any state to any state transition. You can customize these
workflows to restrict some transitions .See Customize work tracking objects to
support your team's processes.
Also, you can view the supported workflow transitions for each work item type by
installing the State Model Visualization Markeplace extension. This extension
adds a new hub under Boards labeled State Visualizer. On that page you can
choose a work item type and view the workflow state model.
The following diagrams show the typical forward progression of those WITs used to
track work and code defects for the three default processes. They also show some of the
regressions to former states and transitions to removed states. Each image shows only
the default reason associated with the transition.
Agile process
User story
Feature
Epic
Bug
Task
Most WITs used by Agile tools, ones that appear on backlogs and boards, support any-
to-any transitions. You can update the status of a work item using the Kanban board or
the taskboard by dragging it to its corresponding state column.
You can change the workflow to support other states, transitions, and reasons. For more
information, see Customize your work tracking experience.
Work item states

When you change the state of a work item to Removed , Closed , or Done , the system
responds as follows:
Closed / Done : Work items in this state don't appear on the portfolio backlog and
backlog pages. However, they do appear on the sprint backlog pages, Kanban
board, and taskboard. Also, when you change the portfolio backlog view to show
backlog items, for example, to view Features to Product Backlog Items, work items
in the closed and done state appear.
Removed : Work items in this state don't appear on any backlog or board.
Your project maintains work items as long as the project is active. Even if you set work
items to Closed , Done , or Removed , the data store keeps a record. You can use a record
to create queries or reports.
７ Note
Completed or closed work items don't display on the backlogs and boards once
their Changed Date is greater than 183 days (about a half a year). You can still list
these items using a query. If you want them to show up on a backlog or board,
then you can make a minor change to them which resets the clock.
If you need to permanently delete work items, see Remove or delete work items.
WITs added to all processes

The following WITs are added to all processes except the Basic process.
Your team can create and work with these types using the corresponding tool:
Tool Work item types
Microsoft Test Manager Test Plan , Test Suite , Test Case Shared Steps , Shared
Parameters
Request Feedback Feedback Request , Feedback Response
My Work (from Team Explorer), Code Code Review Request , Code Review Response
Review
Work items from these type definitions aren't meant to be created manually and are
then added to the Hidden Types category. Work item types added to the Hidden Types
category don't appear in the menus that create new work items.
WITs that support the test experience

WITs that support the test experience and work with Test Manager and the web portal
are linked together using the link types shown in the following picture.
From the web portal or Microsoft Test Manager, you can view which test cases are
defined for a test suite and view which test suites are defined for a test plan. However,
these objects aren't connected to each other through link types. Customize these WITs
as you would any other WIT. For more information, see Customize work tracking objects
to support your team's processes.
If you change the workflow for the test plan and test suite, you might need to update
the process configuration as described here. For definitions of each test field, see Query
based on build and test integration fields.
Related articles
Customize your work tracking experience.
Upload/download process templates
Configure features after an Azure DevOps Server upgrade
Azure DevOps support page
Promote an Agile culture within your
team
Article • 06/06/2023
2018
As your team grows, you want your tools to grow with it. And if you're an enterprise
adopting Agile methodologies, you want your Agile tools to support the business goals
of your enterprise.
However, successfully scaling Agile requires addressing both the culture and tools within
your organization.
７ Note
New to Agile? For more information, see Agile Culture and Scaling Agile to Large
Teams.
Enable autonomy
Organizations that aspire to be agile need to consider the twin obligations of creating
alignment across the enterprise and supporting team autonomy. A team needs
autonomy to be efficient. And enterprises need alignment across teams and the
organization to be efficient.
Too much alignment with insufficient team autonomy leads doesn't support innovation
or agility of teams to get things done. Too little alignment with each team running their
own program doesn't provide the insight and coordination required to meet business
goals.
With the right level of alignment across the organization and team autonomy,
individuals get empowered to innovate and inspired to collaborate to meet business
goals.
Create alignment
As you plan how you want to grow your Agile tool set, consider the following areas.
These areas are key to creating enterprise alignment while developing team autonomy.
Area
Create alignment
Support autonomy
Product vision
The organization defines the goals and roadmap for the organization. You can define
goals as epics and features that show up on the portfolio backlog.
A team determines how to best meet the roadmap. The team breaks down goals into
user stories or product backlog items using their team backlogs.
Team structure
Based on business goals, organizations determine the number and size of teams.
Vertically structured feature teams lead to greater autonomy and efficiency.
With teams, there should be some established roles, such as product owner and
development leads, but also room to rotate roles. For example, team members can take
turns acting as Scrum Master, developing sprint demos, running sprint retrospectives, or
crafting sprint emails.
Development cadence
Agile organizations need to release products and feature updates at regular intervals.
Establishing regular release and sprint schedules promotes the rhythm of the business.
Each sprint--a time boxed iteration of constant duration between two and four weeks—
includes planning, executing, delivering value, reflecting, and engaging in continuous
improvement.
All teams manage their work within the set sprint cadence. The team provides input into
the length of sprint that works best for them.
The team chooses the Agile methods that work for them, Scrum, Kanban, or a mix of
both. The team also takes ownership of starting and acting on their own set of
continuous improvement practices.
It's possible for some teams to execute in shorter sprints. For example, if an organization
sets a 2-week sprint cadence, some teams may choose to operate in 1-week sprints,
while still aligning with the organizational schedule.
Communication cadence
Just as sprints bring a natural rhythm to the flow of work, so too do regular
communications. By setting expectations for the types of communications they want to
see to stay aligned and how often they occur, organizations naturally create alignment
across teams and the enterprise.
Team sprint emails, bug bar status, and release team feature delivery status are
examples of such regular communications.
A team determines the details that they communicate and who develops the
communication. Their sprint emails may contain a summary of previous sprint
accomplishments and the next sprint plans or include a demo of recently completed
features.
Quality
Each organization needs to set the criteria and standards by which they assess quality
and set expectations for quality standards. A few ways they define the criteria are to set
exit criteria for new feature development, standards to manage technical debt, and bug
caps for teams or individuals.
Also, they can monitor bug status and trends by creating bug dashboards.
A team chooses how they meet the quality standards. They may stage bug bashes for
new features or at the end of each sprint. They may choose an individual to function as
a bug shield on a rotating basis.
Manage risk, track work
The organization determines how each functional unit communicates status and risk.
They establish a "contract of communication" as to the minimum required information
the organization needs.
Also, the organization provides the infrastructure to reduce risks. The organization owes
the teams anything they can do to reduce risks that are common across teams.
Beyond meeting the needs set by the organization, teams determine any other details
they need to manage and track to reduce their risks. Whether they use a white board
with sticky notes or a full Gantt chart, they manage the details. For example, teams may
add a backlog item to track a dependency they have on another team. Or they may
track their risks via a list of issues or impediments. Also, teams regularly contribute to
improving the process and infrastructure to support the organization's ability to manage
risk and gain insights.
Structure teams
As you scale, one of the most important tasks to consider is how you structure your
teams. Traditionally, horizontal team structures divide teams according to the software
architecture: user interface, service-oriented architecture, and data teams.
However, with the adoption of Agile practices, vertical team structures that span the
architecture provide greater team autonomy. Vertical teams can deliver on the features
they own by working across the software architecture. They also spread the knowledge
needed to work at all architecture levels throughout all the teams.
Configure your teams along the value streams that your organization wants to deliver.
For example, Fabrikam Fiber, organizes their teams into the following seven feature
teams.
Each team plans the features to deliver. They have the autonomy to determine how to
structure the data, architect the services, and design the web and mobile user interfaces.
They plan in adherence with the quality standards set by the organization and to which
all teams contribute.
Configure your Agile tools to scale

As your organization grows, you can scale your Agile tools in the following ways.
Add teams and filtered backlog views: You add teams to support team autonomy
and provide them with the tools they can configure and manage that supports
how they want to work. These tools include product backlogs, Kanban boards,
sprint backlogs, Taskboards, and others.
Also, you can configure teams to support a hierarchy of backlogs and portfolio
backlogs so that portfolio managers can review priority and progress across
several teams.
Set up sprints and releases: You can structure your iterations to support a flat set
of sprints, or a set of sprints embedded within scheduled releases. Each team
activates the set of sprints and releases that they need to participate in.
Manage portfolios: by setting up a hierarchy of teams and backlogs and activating

portfolio backlogs. Feature teams focused on a subset of the product backlog can
remain focused on just their backlog. Portfolio managers who want to view and
organize backlogs to track progress and dependencies can manage portfolio
backlogs of Features and Epics.
If you need other portfolio backlogs, for example, Scenarios or Initiatives, you can
add them as well.
Configure dashboards: With team dashboards, you can configure charts that track
progress within a team or across teams. Specifically, you can add status and trend
charts based on queries you create.
Group or categorize work: There are several ways to group work that you want to
track. Backlogs filter work items based on team area assignments. And portfolio
backlogs allow you to group backlog items under Features and Epics.
If you want to track and report on work items based on other groupings, you can.
You can add tags to work items and then filter backlogs or queries based on tags.
Also, you can add subarea paths to represent more granular feature areas.
Add folders and use team favorites: As your teams grow, you see a growing list of
work item queries, build definitions, and source code folders. By using folders,
subfolders, and team favorites, you can manage many of these lists more easily.
You can add team favorites for shared queries, source code, and build definitions.
Scale with teams and not projects

Often, organizations look at adding a project for each software development project.
We recommend that you add teams to scale your tools rather than add projects for the
following reasons:
Visibility: It's easier to view progress across all teams
Tracking and auditing: It's easier to link work items and other objects for tracking
and auditing purposes
Maintainability: You minimize the maintenance of security groups and process
updates.
For more information, see About projects and scaling your organization.
Related articles
Before you can create or work with any of the Agile tools, you need a project. If you
don't have one yet, you can create one.
If you're ready to move from one team to two teams, or configure several teams, see
Add teams. To add a team administrator or configure team assets, see Manage teams
and configure team tools.
For more information, see these articles:

Visibility across teams
Review team delivery plans
Implement Scaled Agile Framework® to support epics, release trains, and multiple
backlogs.
Agile culture industry resources

Nexus, the Exoskeleton of Scaled Scrum
Culture over process
The Culture Game - Tools for the Agile Manager
Scaled Agile Framework (SAFe)
Scaling Agile Software Development, - Disciplined Agility at Scale (White Paper)
Agile process work item types
Article • 06/06/2023
2018
The Agile process supports the following work item types (WITs) to plan and track work,
tests, feedback, and code review. With different WITs you can track different types of
work—such as features, user stories, and tasks. These artifacts get created when you
create a project using the Agile process and are based on Agile principles and values.
Along with the WITs, teams have access to a set of work item queries to track
information, analyze progress, and make decisions.
７ Note
You can customize the work tracking system for your project by creating and
customizing an inherited process and applying that process to your project. For
more information, see Inheritance process model.
Plan and track work with Agile

Build your project plan by creating a backlog of user stories that represent the work you
want to develop and ship. You track bugs, tasks, and blocking issues using the bug, task,
and issue WITs. To support portfolio management, teams create features and epics to
view a rollup of user stories within or across teams. For details about using Agile WITs,
see Agile process work item types and workflow.
The following image shows the essential flow for getting started. For more information,
see Get started with Agile tools to plan and track work.
Select one of the following images to go to the linked article.
７ Note
A work item is a database record that contains the definition, assignment, priority,
and state of work. Work item types define the template of fields, workflow, and
form for each type. Work items can be linked to each other to support tracking
dependencies, roll up of work, and reports.
List work items by using queries

You can manage your workload more effectively by frequently reviewing the status of
user stories and tasks. You can use the shared work item queries to list work items for a
current sprint or the product backlog.
７ Note
When you create a new project, there's no longer a default set of Shared Queries.
The definitions for Shared Queries were removed from the process template. For
on-premises deployments, you can add them to a custom process template as
described in Add work item queries to a process template.
You can view and run queries from the web portal or from the Team Explorer plug-in to
Visual Studio. You can also modify a query using the query editor to apply different filter
criteria and add queries to team dashboards.
Tips for shared queries

Manage work more effectively with the following tips:
Find work items assigned to you by adding @Me as the value for the Assigned To
field in one of the query clauses.
Modify any query by adding criteria to focus on a product area, an iteration, or
another field. To modify a query, open the query editor.
Open any query in Excel where you can update the fields of one or more work
items and publish your changes to the database for tracking work items.
Visualize status or progress by creating a pie-chart, column chart, or trend chart for
flat-list queries.
All valid users with standard access can create queries and folders under the My
Queries area. To create queries and query folders under Shared Queries, you must
have the Contribute permission set and have been assigned Basic access or
greater. For more information, see Set permissions on queries.
） Important
Starting with Visual Studio 2019, the Azure DevOps plug-in for Office has
deprecated support for Microsoft Project. Project integration and the
TFSFieldMapping command is not supported for Azure DevOps Server 2019 and
later versions, including Azure DevOps Services. You can continue to use Microsoft
Excel.
Monitor progress
All processes—Agile, Scrum, and CMMI—support building status and trend charts and
dashboards. Also, several charts are automatically built based on the Agile tools you use.
These charts display within the web portal.
Create light-weight charts

You can define a shared flat query and create a chart based on your tracking interests.
Chart types include status—pie, bar, column, stacked bar, and pivot—and trend—
stacked area, line, and area—charts.
Analytics widgets and Power BI reports

The Analytics Service can answer quantitative questions about the past or present state
of your projects. You can add Analytics widgets to a dashboard or use Power BI to create
charts and reports.
For more information, see What is the Analytics Service?
Agile process versions

As updates are made to the Agile process template, the version number is updated. The
following table provides a mapping of the versioning applied as updates are made to
the Azure DevOps on-premises process templates. For Azure Boards, the latest version is
always used. Each template provides a version element. This element specifies a major
and minor version.
Version Agile process name Major version
Azure DevOps Services Agile 18

Azure DevOps Server 2022
Azure DevOps Server 2020 Agile 17

Version Agile process name Major version
TFS 2018 Agile 16
For a summary of updates made to process templates, see Release Notes for Azure
DevOps Server.
Related articles
Create a project
Add work items to manage a project
Create a backlog
Use a Kanban board
Plan a sprint
Agile workflow in Azure Boards
Article • 06/02/2023
2018
When you use the Agile process in Azure Boards, the following work item types (WITs)
help your team to plan and track progress of your projects: epics, features, user stories,
tasks, issues/bugs. Once you define your WITs, you can use the Kanban board to track
progress by updating the status of those items.
To gain insight into a portfolio of features, scenarios, or user experiences, product

owners and program managers map user stories to features. When a team works in
sprints, they define tasks that automatically link to user stories. If you're new to the Agile
process, review the section Plan and track work with Agile to get started.
From the web portal or Microsoft Test Manager, testers can create and run test cases
against bugs and issues, which are used to track code defects and blocking issues.
Define user stories

Product owners typically define and stack rank user stories, which describe the work
involved for developing applications, requirements, and elements. The team then
estimates the effort and work to deliver the highest priority items.
Create user stories from the quick add panel on the product backlog page. From that
page, you can also drag-and-drop items to reorder them or map them to features.
You can open each user story to provide more details and estimate the story points.
Define Story Points so your team can use the forecast feature and velocity charts to
estimate future sprints or work efforts. By prioritizing the user stories on the backlog
page (that's captured in the Stack Rank field), product owners can indicate which items
should be given higher priority.
Use the guidance in the following table and the common fields used across work item
types when you complete the form.
Field/tab
Usage
Description
For user stories, provide enough detail for estimating how much work is required to
implement the story. Focus on who the feature is for, what users want to accomplish,
and why. Don't describe how the feature should be developed. Do provide sufficient
details so that your team can write tasks and test cases to implement the item.
Acceptance Criteria
Provide the criteria to be met before the bug or user story can be closed. Before work
begins, describe the customer acceptance criteria as clearly as possible. Conversations
between the team and customers to define the acceptance criteria help ensure that your
team understands your customers' expectations. You can use the acceptance criteria as
the basis for acceptance tests to more effectively evaluate whether an item is
satisfactorily completed.
Value Area
The area of customer value addressed by the epic, feature, requirement, or backlog
item. Values include:
solution
customer value to support the business (Default)
Story Points
Estimate the amount of work required to complete a user story using any numeric unit
of measurement your team prefers.
Agile velocity charts and forecast tools reference the values in this field. For more
information, see the Estimating white paper.
Priority
A subjective rating of the user story, feature, or requirement as it relates to the business.
Allowed values are:
1: Product can't ship without the feature.
2: Product can't ship without the feature, but it doesn't have to be addressed
immediately.
3: Implementation of the feature is optional, based on resources, time, and risk.
Risk
A subjective rating of the relative uncertainty around the successful completion of a user
story. Allowed values are:
1 - High
2 - Medium
3 - Low

performed.
７ Note


want to delete it.
the work item form.

path.
７ Note
Track progress
As work progresses, you change the State field to update the status. Optionally, you can
specify a reason. The state and reason fields appear on the work item form in the header
area.
Agile workflow states
When you update the workflow, teams know which items are new, in progress, or
completed. Most WITs support transition both forward and backward from each
workflow state. These diagrams show the main progression and regression states of the
user story, bug, and task WITs.
User Story Bug Task
A typical workflow progression for a user story follows:
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 gets moved to Resolved when the team has completed all its
associated tasks and unit tests for the story pass.
A user story gets 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.
Update status with Kanban or Taskboards

Teams can use the Kanban board to update the status of requirements, and the
Taskboard to update the status of tasks. Dragging items to a new state column updates
both the State and Reason fields.
You can customize the Kanban board to support more swimlanes or columns. For more
Map user stories to features

When you manage a suite of products or user experiences, you might want to view the
scope and progress of work across the product portfolio. You can view the scope and
progress of work by defining features and mapping user stories to features.
Using portfolio backlogs, you can drill down from one backlog to another to view the
level of detail you want. Also, use portfolio backlogs to view a rollup of work in progress
across several teams when you setup a hierarchy of teams.
Define tasks
When your team manages their work in sprints, they can use the sprint backlog page to
break down the work to be accomplished into distinct tasks.
Name the task and estimate the work it takes.

When you use the Agile process, teams forecast work and define tasks at the start of
each sprint. Each team member then performs a subset of those tasks. Tasks can include
development, testing, and other kinds of work. For example, a developer defines tasks to
implement user stories, and a tester defines tasks to write and run test cases.
When teams estimate work using hours or days, they define tasks and the Remaining
Work and Activity (optional) fields.
Field/tab
Usage
Original Estimate
change after it's assigned. You can specify work in hours or in days. There are no
inherent time units associated with this field.
Remaining Work
The amount of work remaining to complete a task. As work progresses, update this field.
This field is used to calculate capacity charts, the sprint burndown chart, and the
following SQL Server reports: Burndown and Burn Rate, Remaining Work, and Status on
All Iterations. If you divide a task into subtasks, specify hours for the subtasks only. You
can specify work in any unit of measurement your team chooses.
Completed Work
The amount of work spent implementing a task.
Activity
Select the type of activity this task represents when your team estimates sprint capacity
by activity.
Integrated in Build
Product build number that incorporates the code or fixes a bug.
Track test progress

Track testing progress with user stories and code defects.
Test user stories

From the web portal or Test Manager, you can create test cases that automatically link
to a user story or bug. Or, you can link a user story to a test case from the Links tab.
The test case contains multiple fields, many of which are automated and integrated with
Test Manager and the build process. For a description of each field, see Query based on
build and test integration fields.
The (links tab) captures the links to user stories and bugs in a test case. By linking
user stories and bugs to test cases, the team can track the progress made in testing
each item. By defining these links, you support information that appears in the Stories
Overview Report report.
Track code defects

You can create bugs from the web portal, Visual Studio, or when testing with Test
Manager.
Definitions for common work tracking fields

The following fields and tabs appear in most work items. Each tab gets used to track
specific information, such as History, Links, or Attachments. These three tabs

provide a history of changes, view of linked work items, and ability to view and attach
files.
The only required field for all work item types is Title. When you save a work item, the
system assigns it a unique ID. The form highlights required field in yellow. For
information about other fields, see Work item field index.
７ Note
Additional fields may be required depending on customizations made to your

process and project.
Field/tab
Usage
Title
Assigned To
State
work progresses, update it to reflect the current state.
Reason
Use the default first. Update it when you change state. Each State is associated with a
default reason.
Area
Iteration
assign it later, during a planning meeting. To change the drop-down list of iterations,
see Define iteration paths (sprints) and configure team iterations.
(History)
Review the audit trail that the system captures and capture additional information.
Every time that the work item is updated, information is appended to the history.
History includes the date of the change, who made the change, and which fields were
changed. You can also add formatted text to the history field.
(Links)
Add all types of links, such as hyperlinks, changesets, source files, and so on.
This tab also lists all links defined for the work item.
(Attachments)
Share more detailed information by adding files to the work item, such as email threads,
documents, images, log files, or other file types.
Customize work item types

For most work item types, you can add fields, change the workflow, add custom rules,
and add custom pages to the work item form. You can also add custom work item types.
For more information, see Customize an inheritance process.
Related articles
Create a project
Create a backlog
Use a Kanban board
Plan a sprint
Track issues
Issues are used to track events that may block progress or shipping a user story. Bugs,
on the other hand, are used to track code defects. You can add an issue from the New
work item widget added to a team dashboard, or from the New menu on the Queries
page.
Work items you add from the widget are automatically scoped to your team's default
area and iteration paths. To change the team context, see Switch team context.
Track business value

You can use the Priority field to differentiate the value of various stories. Or, you can add
a custom field to the User Story WIT that tracks the relative value of stories. To learn
how, see Customize a field for a process.
Backlog list order

The Stack Rank field is used to track the relative ranking of user stories, however by
default it doesn't appear on the work item form. The sequence of items on the backlog
page is determined according to where you've added the items or moved the items on
the page. As you drag items, a background process updates this field.
Manage Scrum process template objects
Article • 06/08/2023
2018
The Scrum process supports the following work item types (WITs) to plan and track
work, tests, feedback, and code review. With different WITs you can track different types
of work—such as product backlog items, tasks, bugs, and more. These objects get
created when you create a project using the Scrum process. They're based on Scrum
principles and values .
７ Note
Plan and track work with Scrum processes

You build your project plan by creating a backlog of work items that represent the
features, requirements, user stories, or other work to do. You track bugs, tasks, and
blocking issues using the bug, task, and impediment WITs. To support portfolio
management, teams create features and epics to view a rollup of their product backlog
items within or across teams. For more information, see Scrum process work item types
and workflow.
７ Note
For more information, see Scrum work item types and workflow.
List work items

Define work item queries to list work items for a current sprint or the product backlog.
７ Note

flat-list queries.
） Important
Excel.
Monitor work progress



charts and reports.
Scrum process versions

As updates get made to the Scrum process template, the version number gets updated.
The following table provides a mapping of the versioning applied as updates get made
to the Azure DevOps on-premises process templates. For Azure Boards, the latest
version always gets used. Each template provides a version element, which specifies a
major and minor version.
Version Scrum process name Major version
Azure DevOps Services Scrum 18

Azure DevOps Server 2020 Scrum 17

Version Scrum process name Major version
TFS 2018 Scrum 16
DevOps Server.
Related articles
Create a project
Create a backlog
Use a Kanban board
Plan a sprint
Manage Scrum process work item types
& workflow
Article • 06/08/2023
2018
To plan a software project and track software defects using Scrum, teams use the
product backlog item (PBI) and bug work item types (WITs). To gain insight into a
portfolio of features, scenarios, or user experiences, product owners, and program
managers can map PBIs and bugs to features. When teams work in sprints, they define
tasks that automatically link to PBIs and bugs.
７ Note
If you're new to the Scrum process, review About Sprints, Scrum and project
management.
Testers can create and run test cases and create bugs to track code defects using the
web portal or Microsoft Test Manager. Impediments track blocking issues.
Define PBIs and bugs

When you define a product backlog item, focus on the value that your customers gain
and avoid descriptions of how your team develops the feature. The product owner can
prioritize your product backlog based on each item's business value, effort, and relative
dependency on other backlog items. As your business requirements evolve, so does
your product backlog. Typically, teams specify details only for the highest priority items,
or those items assigned to the current and next sprint.
You can create PBIs and bugs from the quick add panel on the product backlog page.
Afterward, you can open each PBI or bug to provide more details and estimate the
effort. Also, by prioritizing the PBIs and bugs on the backlog page (which is captured in
the Backlog Priority field), product owners can indicate which items should be given
higher priority.
When you define the Effort for PBIs and bugs, you can use the forecast feature and
velocity charts to estimate future sprints or work efforts. When you define the Business
Value, product owners can specify priorities separate from the changeable backlog stack
ranking.
Use the following fields and fields used in common across work item types when you
complete the work item form. For more information, see Manage bugs.
Field/tab
Usage
Effort
Estimate the amount of work required to complete a PBI using any unit of measurement
your team prefers, such as story points or time. A numeric value is required.
Agile velocity charts and forecast tools reference the values in this field. For more
information, see the Estimating white paper.
Business Value
Specify a number that captures the relative value of a PBI compared to other PBIs. The
higher the number, the greater the business value.
Description
Provide enough detail for estimating how much work is required to implement the item.
Focus on who the feature is for, what users want to accomplish, and why. Don't describe
how the feature should be developed. Do provide sufficient details so that your team
can write tasks and test cases to implement the item.
Acceptance Criteria
Define what "Done" means by describing the criteria that the team should use to verify
whether the PBI or the bug fix has been fully implemented.
Before work begins on a PBI or bug, describe the criteria for customer acceptance as
clearly as possible. Conversations between the team and customers to determine the
acceptance criteria helps ensure a common understanding within the team to meet
customers' expectations. The acceptance criteria can be used as the basis for acceptance
tests so that the team can more effectively evaluate whether an item has been
satisfactorily completed.

performed.
７ Note


want to delete it.
the work item form.

path.
７ Note
Track progress
area.
Scrum workflow states
When you update the State, teams know which items are new, in progress, or
completed. Most WITs support transition both forward and backward from each
workflow state. These diagrams show the main progression and regression states of the
PBI, bug, and task WITs.
Product Backlog Item Bug Task
PBIs and bugs follow this typical workflow progression:
The product owner creates a PBI or a tester creates a bug in the New state with the
default reason, New backlog item
The product owner moves the item to Approved after it's sufficiently described
and ready for the team to estimate the level of effort. Most of the time, items near
the top of the Product Backlog are in the Approved state, while items toward the
middle and bottom are in a New state
The team updates the status to Committed when they decide to commit to
working on it during the sprint
The item gets moved to the Done state when the team has completed all its
associated tasks and the product owner agrees that it has been implemented
according to the Acceptance Criteria.
Update status with Kanban or Taskboards
Teams can use the Kanban board to update the status of PBIs, and the sprint Taskboard
to update the status of tasks. Dragging items to a new state column updates both the
State and Reason fields.
You can customize the Kanban board to support more swim lanes or columns. For other
customization options, see Customize your work tracking experience.
Map PBIs to features

scope and progress of work across the product portfolio. To do so, define features and
map PBIs to features.
level of detail you want. Also, you can use portfolio backlogs to view a rollup of work in
progress across several teams when you setup a hierarchy of teams.
Define tasks
Name the task and estimate the work it takes.
Teams can forecast work and define tasks at the start of each sprint, and each team
member completes a subset of those tasks. Tasks can include development, testing, and
other kinds of work. For example, a developer can define tasks to implement PBIs, and a
tester can define tasks to write and run test cases.
When teams estimate work using hours or days, they define tasks and the Remaining
Work and Activity (optional) fields.
Field/tab
Usage
Remaining Work
Indicate how many hours or days of work remain to complete a task. As work
progresses, update this field. It's used to calculate capacity charts, the sprint burndown
chart, and the Sprint Burndown (Scrum) report.
If you divide a task into subtasks, specify Remaining Work for the subtasks only. You can
specify work in any unit of measurement your team chooses.
Activity
Select the type of activity this task represents when your team estimates sprint capacity
by activity.
Track test progress
Test PBIs
to a PBI or bug. Or, you can link a PBI or bug to a test case from the (links tab).
The test case contains many fields, many of which are automated and integrated with
The (links tab) captures the links to all the PBIs and bugs in a test case. By linking
PBIs and bugs to test cases, the team can track the progress made in testing each item.
Track code defects

You can create bugs from the web portal web portal, Visual Studio, or when testing with
Test Manager.


files.
７ Note

Field/tab
Usage
Title
Assigned To
State
Reason
default reason.
Area
Iteration
(History)
(Links)
(Attachments)

Track impediments
Use the Impediment work item type to track events that may block progress or ship a
PBI. Use the Bug work item type exclusively to track code defects.
You can add an impediment from the New work item widget added to a team
dashboard, or from the New menu on the Queries page.
Backlog list order

The Backlog Priority field is used to track the relative ranking of PBIs, bugs, features, or
epics. However, by default it doesn't appear on the work item form. The sequence of
items on the backlog page is determined according to where you've added the items or
moved the items on the page. As you drag items, a background process updates this
field.
Related articles
Create a project
Create a backlog
Use a Kanban board
Plan a sprint
Understand CMMI process template
artifacts
Article • 04/25/2023
2018
The CMMI process supports the following work item types (WITs) to plan and track
work, tests, feedback, and code review. With different WITs you can track different types
of work—such as requirements, change requests, tasks, bugs and more. These artifacts
are created when you create a project using the CMMI process. They're based on the
Capability Maturity Model Integration (CMMI) process.
７ Note
Plan and track work with CMMI
Teams plan their project by capturing features and requirements. When teams work in
sprints, they define tasks and link them to requirements. To gain insight into a rollup of
requirements across teams, program managers link requirements to a feature. Blocking
issues are tracked using issues. For details on using these WITs, see CMMI process work
item types and workflow
７ Note
List work items with queries

You can use work item queries to list work items based on their type, such as change
requests, bugs, tasks, and requirements.
７ Note

flat-list queries.
） Important
Excel.
Monitor progress


charts and reports.
Related notes
Create a project
Create a backlog
Use a Kanban board
Plan a sprint
CMMI process versions

As updates are made to the CMMI process template, the version number is updated.
The following table provides a mapping of the versioning applied as updates are made
to the Azure DevOps on-premises process templates. For Azure Boards, the latest
version is always used. Each template provides a version element. This element
specifies a major and minor version.
Version CMMI name Major version
Azure DevOps Services CMMI 18

Azure DevOps Server 2020 CMMI 17

TFS 2018 CMMI 16
DevOps Server.
More CMMI guidance

The situations and working practices of development teams vary widely, and most
companies have their own well-established processes. For these reasons, the guidance
given here doesn't attempt to prescribe a development process in full. Instead, we
describe just the activities that are relevant to making best use of the CMMI process.
Background to CMMI: Provides an overview of CMMI and the six capability levels
that are intrinsic to the model.
Project management: Provides guidance to help you better understand how to

manage, plan, and coordinate the development and maintenance of software
products working with the CMMI model.
Engineering: Addresses the value-added activities for discovering the information

that is required to design and build software products
Using the CMMI template and guidance can help you achieve the aims of CMMI if you
use it as part of a process improvement program. Adapt this guidance to your own
situation, which depends on the type and history of the product that you're developing,
the project's scale, the background of the team members, and accepted practices in
your organization.
This guidance was developed in partnership with David Anderson. For more information,
see the following Web page: David J Anderson & Associates .
CMMI process work item types and
workflow in Azure Boards
Article • 02/24/2023
2018
Teams use the work item types (WITs) provided with the MSF for CMMI Process
Improvement 2015 (CMMI) process to plan and track progress of software projects.
Teams define requirements to manage the backlog of work and then, using the Kanban
board, track progress by updating the status of requirements.
To gain insight into a portfolio of requirements, product owners can map requirements
to features. When teams work in iterations, they define tasks that automatically link to
requirements.
Using Microsoft Test Manager and the web portal, testers create and run test cases and
define bugs to track code defects.
To support other CMMI processes, teams can track change requests, risks, issues, and
notes captured in review meetings. If you're new to the CMMI process, review the
section Plan and track work with CMMI to get started.
Define requirements
Create requirements from the quick add panel on the product backlog page. Later, you
can open each requirement to provide more details and estimate its size.
Or, you can bulk add requirements using a cvs file.
） Important
Microsoft Project Integration and the TFSFieldMapping command are not

supported for:
Visual Studio 2019 and Azure DevOps Office® Integration 2019

Azure DevOps Server 2019 and later versions, including Azure DevOps
Services.
However, full support for Microsoft Excel integration is maintained and supports
bulk import and update of work items. Alternatives to using Microsoft Project
include the following:
Delivery plans
A Marketplace extension such as Project Connect or GANTT chart .
Requirements specify the functions and product elements that teams need to create.
Product owners typically define and stack rank requirements on the product backlog
page. The team then scopes the size of the effort to deliver the highest priority items.
Use the following guidance and that provided for fields used in common across work
item types when filling out the form. For more information, see Plan a project.
Field
Usage
Description
Provide enough detail for estimating how much work will be required to implement the
requirement. Focus on who the requirement is for, what users want to accomplish, and
why. Don't describe how the requirement should be developed. Do provide sufficient
details so that your team can write tasks and test cases to implement the item.
In HTML fields, you can add rich text and images.
Impact Assessment
The customer impact of not implementing this requirement. You might include details
from the Kano model about whether this requirement is in the surprise, required, or
obvious categories. You capture this information in the rich-text HTML field that
corresponds to Impact Assessment.
Requirement Type (Required)
The kind of requirement to implement. You can specify one of the following values:
Business Objective
Feature (default)
Functional
Interface
Operational
Quality of Service
Safety
Scenario
Security
Value area
The area of customer value addressed by the epic, feature, requirement, or backlog
item. Values include:
solution
Size
Estimate the amount of work required to complete a requirement using any numeric
unit of measurement your team prefers. By defining the Size for requirements, teams
can use the Agile velocity charts and forecast tools to estimate future iterations or work
efforts. The Kanban Cumulative Flow Diagram references the values in this field. For
more information, see the Estimating white paper.
Original Estimate
You can specify work in hours or in days. There are no inherent time units associated
with this field.
Start Date/Finish Date
The target dates for when the work will start or finish.
Priority (Required)
A subjective rating of the requirement as it relates to the business. Allowed values are:
1: Product can't ship without the item.
2: (default) Product can't ship without the item, but it doesn't have to be addressed
immediately.
3: Implementation of the item is optional based on resources, time, and risk.
Triage (Required)
Indicates the type of triage decision that is pending for the work item. Use this field
when the work item is in the Proposed state and specify one of the following values:
Pending (default), More Info, Info Received, and Triaged.
Blocked
Indicates whether a team member is prevented from making progress toward

implementing a requirement or task or resolving a bug, change request, or risk. If an
issue has been opened to track a blocking problem, you can create a link to the issue.
You can specify Yes of No.
Committed (Required)
Indicates whether the requirement is committed in the project or not. You can specify
Yes or No (default).
Integrated In
Product build number that incorporates the requirement, change request, or fixes a bug.
User Acceptance Test (Required)
The status of the user acceptance test for a requirement. You can specify one of the
following values:
Pass
Fail
Not Ready (default)
Ready
Skipped
Info Received
You specify Not Ready when the requirement is in the Active state, and you specify
Ready when the requirement is in the Resolved state.
Subject Matter Experts
The names of team members who are familiar with the customer area that this
requirement represents.

performed.
７ Note


want to delete it.
the work item form.

path.
７ Note
Track work progress

area.
CMMI workflow states
These diagrams show the main progression and regression states for the Requirement,
Bug, and Task WITs.
Requirement Bug Task
The typical workflow progression for a requirement is:
The product owner creates a requirement in the Proposed state with the default
reason, New requirement.
The product owner updates the status to Active when they begin work to
implement it.
The team updates the status to Resolved when code development is finished and
system tests have passed.
Lastly, the team or product owner moves the requirement to Closed when the
product owner agrees that it has been implemented according to the Acceptance
Criteria and passed all validation tests.
Update work status with Kanban or Taskboards

Teams can use the Kanban board to update the status of requirements, and the sprint
taskboard to update the status of tasks. Dragging items to a new state column updates
both the State and Reason fields.
You can customize the Kanban board to support more swim lanes or columns. For more
customization options, see Customize your work tracking experience.
Map requirements to features

scope and progress of work across the product portfolio. You can do view scope by
defining features and mapping requirements to features.
level of detail you want. Also, you can use portfolio backlogs to view a rollup of work in
progress across several teams when you setup a hierarchy of teams.
The feature work item contains similar fields provided for requirements and includes
other fields, as the following table describes.
Define tasks
Name the task and estimate the work it will take.

When teams estimate work, they define tasks and estimate the hours or days to
complete tasks. Teams forecast work and define tasks at the start of an iteration, and
each team member does a subset of those tasks. Tasks can include development,
testing, and other kinds of work. For example, a developer can define tasks to
implement requirements, and a tester can define tasks to write and run test cases. By
linking tasks to requirements and bugs, they see the progress made on these items. For
more information, see Iteration activities.
Field
Usage
Task Type
Select the kind of task to implement from the allowed values:
Corrective Action
Mitigation Action
Planned
Discipline
Select the discipline this task represents when your team estimates sprint capacity by
activity.
Analysis
Development
Test
User Education
User Experience
This field is also used to calculate capacity by discipline. It's assigned to

type="Activity" in the ProcessConfiguration file. (2)
For more information, see Implement development tasks.
Original Estimate
Remaining Work
It's used to calculate capacity charts, the sprint burndown chart, and the Sprint
Burndown report. If you divide a task into subtasks, specify hours for the subtasks only.
You can specify work in any unit of measurement your team chooses.
Completed Work
The amount of work that has been spent implementing a task.
Track test progress

Test requirements
to a requirement or bug. Or, you can link a requirement to a test case from the
(links tab).
The test case contains many fields, many of which are automated and integrated with
The (links tab) lists all the requirements and bugs in a test case. By using linking, the
team can track the progress made in testing each item and supports information that
appears in the Requirements Overview Report report.
Track code defects

You can create bugs from the web portal web portal, Visual Studio, or when testing with
Test Manager.
Track change requests, risks, issues, and notes
captured in review meetings
Along with the requirement, feature, task, and bug WITs, you can track information
recommended by the CMMI process with the following WITS.
Change request to manage proposed changes to any work product that is under
change control.
Issue to track an event or situation that might block work or is blocking work on
the product. Issues differ from risks in that teams identify issues spontaneously,
generally during daily team meetings.
Risk to track the probability and degree of variance between actual and desired
outcomes. When you manage risks, you strategically minimize the variance
between the outcome that you want and the actual outcome.
Review to document the results of a design or code review. Team members can
capture the details of how the design or code meets standards in areas of name
correctness, code relevance, extensibility, code complexity, algorithmic complexity,
and code security.
You can add an issue from the New work item widget added to a team dashboard,
or from the New menu on the Queries page.


files.
７ Note

Field/tab
Usage
Title
Assigned To
State
Reason
default reason.
Area
Iteration
(History)
(Links)
(Attachments)

Related articles
Create a project
Create a backlog
Use a Kanban board
Plan a sprint
Backlog list order

The Stack Rank field is used to track the relative ranking of requirements, features, or
epics. However, by default it doesn't appear on the work item form. The sequence of
items on the backlog page is determined according to where you've added the items or
moved the items on the page. As you drag items, a background process updates this
field.
This field doesn't appear on the work item form.

Background to Capability Maturity
Model Integration (CMMI)
Article • 02/24/2023
2018
The definitive guide to the Capability Maturity Model Integration (CMMI) for
Development is published by the Software Engineering Institute as "CMMI: Guidelines
for Process Integration and Product Improvement." This book specifically describes the
CMMI for Development (CMMI-DEV) version 1.3, which is one of the models within the
CMMI product suite. You may also find "CMMI Distilled: A Practical Introduction to
Integrated Process Improvement" to be a useful and accessible book about CMMI.
７ Note
The guidance provided here is based on version 1.3 for CMMI and supports the
CMMI process available with Azure DevOps. No plans exist at this time to update
this content to support later versions.
Historical notes
The CMMI began in 1987 as the Capability Maturity Model (CMM), a project at the
Software Engineering Institute (SEI). SEI is a research center at Carnegie-Mellon
University, which was established and funded by the United States Department of
Defense. First published in 1991, the CMM for Software began as a checklist of critical
success factors. The model also built upon research at International Business Machines
(IBM) Corporation and 20th-century quality assurance leaders such as Philip Crosby and
W. Edwards Deming. Both the name, Capability Maturity Model, and the Staged
Representation five levels were inspired by Crosby's Manufacturing Maturity Model.
Applied mainly to defense programs, CMM achieved considerable adoption and
underwent several revisions. Its success led to the development of CMMs for a variety of
subjects beyond software. The proliferation of new models was confusing. In response,
the government funded a two-year project to create a single, extensible framework that
integrated systems engineering, software engineering, and product development. This
effort involved more than 200 industry and academic experts. The result was CMMI.
CMMI-DEV is a model. It isn't a process, nor a prescription to be followed. Instead,

CMMI-DEV provides a set of organizational behaviors that have proven to be of use in
software development and systems engineering. Why use such a model? What is its
purpose? And how best should it be used? These critical questions are perhaps the most
misunderstood issues with CMMI.
Why use a model?

Improvement efforts require a model of how your organization works, which functions
they need, and how those functions interact. A model gives you an understanding of
organizational elements and assists in discussions of how and what can and should be
improved.
A model offers the following benefits:
Provides a common framework and language to help communicate

Leverages years of experience
Helps users consider the large picture while focusing on improvement
Is often supported by trainers and consultants
Can help solve disagreements by providing agreed-upon standards
What is the purpose of the CMMI model?

The purpose of the CMMI model is to assess the maturity of an organization's processes
and to provide guidance on improving processes, with a goal of improved products.
Also, CMMI is a model for risk management and provide a way to measure an
organization's ability to manage risk. The ability to manage risk factors factors into an
organizations ability to deliver high-quality products. Another perspective on managing
risk is how well an organization performs under stress. A high maturity, high capability
organization can easily respond to unexpected, stressful events. A low maturity and
lower capability organization tends to panic under stress, blindly follow obviated
procedures, or throw out all process altogether and retrench back to chaos.
The CMMI, however, isn't a proven indicator of the economic performance of an

organization. Although higher maturity organizations may manage risk better and be
more predictable, evidence exists that higher maturity firms tend to be risk-averse. Risk
aversion can lead to a lack of innovation or evidence of greater bureaucracy that results
in long lead times and a lack of competitiveness. Lower maturity firms tend to be more
innovative and creative but chaotic and unpredictable. When results are achieved, they
are often the result of heroic effort by individuals or managers.
What's the best way to use the CMMI model?

The model was designed to be used as the basis for a process improvement initiative,
with its use in assessment only a support system for measuring improvement. There has
been mixed success with this usage. It is all too easy to mistake the model for a process
definition and try to follow it, instead of a map that identifies gaps in existing processes
that may need to be filled. The fundamental building block of CMMI is a process area
that defines goals and several activities that are often used to meet them. One example
of a process area is Process and Product Quality Assurance. Another is Configuration
Management. It is important to understand that a process area is not a process. A single
process may cross multiple process areas, and an individual process area may involve
multiple processes.
The CMMI-DEV is really two models that share the same underlying elements. The first
and most familiar is the Staged Representation, which presents the 22 process areas
mapped into one of five organizational maturity levels. An appraisal of an organization
would assess the level at which it was operating, and this level would be an indicator of
its ability to manage risk and, as, deliver on its promises.
Levels 4 and 5 are often referred to as higher maturity levels. There is often a clear
difference between higher maturity organizations, which demonstrate the quantitative
management and optimizing behaviors, and lower maturity organizations, which are
merely managed or following defined processes. Higher maturity organizations show
lower variability in processes and often use leading indicators as part of a statistically
defensible management method. As a result, higher maturity organizations tend to be
both more predictable and faster at responding to new information, assuming that
other bureaucracy doesn't get in the way. Where low maturity organizations tend to
demonstrate heroic effort, high maturity organizations may blindly follow processes
when under stress and fail to recognize that a process change may be a more
appropriate response.
The Continuous Representation models process capability within each of the 22 process
areas individually, which allows the organization to tailor their improvement efforts to
the processes that offer the highest business value. This representation is more in line
with Crosby's original model. Appraisals against this model result in profiles of capability
rather than a single number. Because the organizational maturity level is the level that
most managers and executives understand, there are ways of mapping the results of a
continuous model assessment into the five stages.
Using the staged model as a basis for a process improvement program can be
dangerous when implementers forget that the CMMI isn't a process nor a workflow
model. Instead, the CMMI is designed to provide goals for process and workflow to
achieve. Meeting such goals improves the maturity of the organization and the
likelihood that events unfold as planned. Perhaps the biggest failure mode is making
achieving a level the goal and then creating processes and infrastructure simply to pass
the appraisal. The goal of any process improvement activity should be measurable
improvement, not a number.
The Continuous model has enjoyed success as a guide to process improvement. Some
consulting firms choose only to offer guidance around the Continuous model. The most
obvious difference is that a process improvement program that is designed around the
Continuous model doesn't have artificial goals that are determined by maturity levels.
The Continuous model also lends itself to applying process improvement in areas where
it is most likely to leverage an economic benefit for the organization. Therefore, those
who follow the Continuous model are more likely to receive positive feedback from an
initiative that is based on the CMMI model. Moreover, positive feedback is more likely to
lead to the development of a virtuous cycle of improvements.
Elements of the CMMI model

The following table lists the 22 process areas that comprise the CMMI model (version
1.3):
Acronym Process Area
CAR Causal Analysis & Resolution
CM Configuration Management
Acronym Process Area
DAR Decision Analysis & Resolution
IPM Integrated Project Management
MA Measurement & Analysis
OID Organizational Innovation & Deployment
OPD Organizational Process Definition
OPF Organizational Process Focus
OPP Organizational Process Performance
OT Organizational Training
PI Product Integration
PMC Project Monitoring & Control
PP Project Planning
PPQA Process & Product Quality Assurance
QPM Quantitative Project Management
RD Requirements Definition
REQM Requirements Management
RSKM Risk Management
SAM Supplier Agreement Management
TS Technical Solution
VER Verification
VAL Validation
In the Staged Representation, the process areas are mapped against each stage, as
shown in the following illustration.
In the Continuous Representation, the process areas are mapped into functional
groupings, as shown in the following illustration.
Each process area is made up of required, expected, and informative components. Only
the required components are actually required to satisfy an appraisal against the model.
The required components are the specific and generic goals for each process area. The
expected components are the specific and generic practices for each specific or generic
goal. Note that, because an expected component is merely expected and not required,
this indicates that a specific or generic practice can be replaced by an equivalent
practice. The expected practices are there to guide implementers and appraisers. If an
alternative practice is chosen, it's up to the implementer to advise an appraiser and
justify why an alternative practice is appropriate. Informative components provide
details that help implementers get started with a process improvement initiative that is
guided by the CMMI model. Informative components include subpractices of generic
and specific practices and typical work products.
Only generic and specific goals are required. Everything else is provided as a guide. For
examples of expected and informative components, the CMMI literature pulled data
from large space and defense-systems projects. These projects might not reflect the
type of projects that are undertaken in your organization, nor may they reflect more
recent trends in the industry, such as the emergence of Agile software development
methods.
Related articles
CMMI process
Software Engineering Institute Releases Version 1.3 of CMMI Product Suite
CMMI for Development: Guidelines for Process Integration and Product
Improvement, Third Edition
CMMI for Development: Guidelines for Process Integration and Product
Improvement (SEI Series in Software Engineering)
What is Agile Development?
Default permissions and access levels
for Azure Boards
Article • 02/24/2023
2018
As a member of an Azure Boards project, you can use most features to track work.
Limitations to select features are based on the access level and security group to which a
user is assigned. The Basic access level and higher supports full access to all Azure
Boards features. Stakeholder access level provides partial support to select features,
allowing users to view and modify work items, but not use all features. The built-in
security groups—Readers, Contributors, and Project Administrators—and team
administrator role grant permissions to specific features.
In the tables provided in this article, a ✔️indicates that the corresponding access level
or security group has access to a feature by default.
７ Note
Team administrators can configure settings for their team's tools. Organization
owners and members of the Project Administrators group can configure settings
for all teams.
For a comparison chart of Stakeholder versus Basic access, see the Feature matrix . To
assign or change an access level, see Add users and assign licenses. If you need to grant
specific users select permissions, you can do so.
Work item feature access

You can use work items to track anything you need to track. For more information, see
Understand how work items are used to track issues, tasks, and epics.
Task or permission
Readers
Contributors
Project admins
View work items in this node (Area Path permission)
✔️
✔️
✔️
Edit work items in this node (Area Path permission)
✔️
✔️
Edit work item comments in this node (Area Path permission)
✔️
✔️
Create tag definition
✔️
✔️
Change work item type (Project-level permission)
✔️
✔️
Move work items out of this project (Project-level permission)
✔️
✔️
Email work items
✔️
✔️
✔️
Apply a work item template
✔️
✔️
Delete and restore work items (Project-level permission) (able to restore from the
Recycle bin)
✔️
✔️
Permanently delete work items (Project-level permission)
✔️
Provide feedback (through the Microsoft Feedback client)
✔️
✔️
Request feedback
✔️
✔️
７ Note
Work items are subject to rules applied to them. Conditional rules based on user or
group membership are cached for your web browser. If you find yourself restricted
to update a work item, you may have encountered one of these rules. If you believe
you've encountered an issue that doesn't apply to you, see Work item form
IndexDB caching issues. To learn more about conditional rules, see Rules and rule
evaluation.
Boards feature access

Boards present work items as cards and support quick status updates through drag-
and-drop.
Task
Readers
Contributors
Team admins
Project admins
View boards and open work items
✔️
✔️
✔️
Add work items to a board; update status through drag-and-drop
✔️
✔️
Reorder work items or reparent child items through drag-and-drop; update a field on a
card
✔️
✔️
Add child items to a checklist
✔️
✔️
Assign to a sprint (from card field)
✔️
✔️
Configure board settings
✔️
Backlogs features access
Backlogs display work items as lists. A product backlog represents your project plan and
a repository of all the information you need to track and share with your team. Portfolio
backlogs allow you to group and organize your backlog into a hierarchy.
Task
Readers
Contributors
Team admins
Project admins
View backlogs and open work items
✔️
✔️
✔️
Add work items to a backlog
✔️
✔️
Use bulk edit features
✔️
✔️
Add child items to a backlog item; prioritize or reorder a backlog; parent items using the
Mapping pane; Assign items to a sprint using the Planning pane
✔️
✔️
Configure team settings, backlog levels, show bugs, work days off
✔️
Sprints feature access
Sprints provide a filtered view of work items that a team has assigned to specific
iteration paths or sprints.
Task
Readers
Contributors
Team admins Project admins
View sprint backlogs, taskboards, and open work items
✔️
✔️
✔️
Add work items to a sprint backlog or taskboard
✔️
✔️
Prioritize/reorder a sprint backlog or taskboard; add child items to a backlog item;

reassign items to a sprint using the Planning pane
✔️
✔️
View team capacity and work details
✔️
✔️
Set team capacity
✔️
✔️
✔️
✔️
Define team sprints
✔️
Queries and semantic search

Queries are filtered lists of work items based on criteria that you define by using a query
editor.
 Tip
By default, Contributors can't create and save shared queries. We recommend that
Project Administrators create a query folder for each team and give the team
administrators or the team group query permissions to manage their folder. You
need Delete permissions to rename or move a shared query or folder, and
Contribute permissions for the folder where you move the query to. For more
information, see Set permissions on queries and query folders.
Task
Readers
Contributors
Project admins
View and run managed queries, view query charts
✔️
✔️
✔️
Create and save managed My queries, query charts
✔️
✔️
Create, delete, and save Shared queries, charts, folders
✔️
Stakeholder access
Stakeholder access supports business owners. It also supports analysts and other team
members who don't manage the work of a project, but need to view and add ideas to
the backlog, add context and information to work items, and review status and progress.
All members of an organization who don't use Visual Studio but want to contribute to
work item tracking and monitor progress can be assigned as a stakeholder. Note, even if
you change the permission level for a user assigned Stakeholder access, the user is
blocked from accessing the feature.
７ Note
For public projects, Stakeholder access gives users full access to all work-tracking
features. For more information, see Stakeholder access quick reference.
Related articles
Get started as a stakeholder
Add another team
Add a team administrator
Manage teams and configure team tools
Grant or restrict access to select features and functions
Set permissions and access for work tracking
Article • 08/23/2023
2018
To manage work tracking effectively, you can grant or restrict access to different
features. Do so by assigning specific permissions to users or groups for a particular
object, project, or collection. You also can define custom rules for processes or projects
that apply to specific users or groups, thereby controlling their actions accordingly. For
most features, we recommend that you add users to the project's Contributors group,
which grants comprehensive access and ensures a seamless and efficient work tracking
experience.
７ Note
For public projects, Stakeholder access gives users greater access to work
tracking features and full access to Azure Pipelines. For more information, see
Stakeholder access quick reference.
Prerequisites
To set work tracking permissions, you must be a member of the Project
Administrators group or have explicit permissions to manage the work tracking
area as described in this article.
Understand roles and permission levels for

work tracking
The following table summarizes the different permissions you can set at the object,
project, or collection level. The team administrator role provides access to add and
modify team resources. Also, see Default permissions for Boards, Backlogs, Sprints,
Delivery Plans, Test Management, and Queries, further in this article.
Role or permission level
Functional areas set

Team administrator role
Add a team administrator
Define and edit team dashboards
Add and manage team-level work item templates
Add team administrators
Object-level permissions
Modify work items under an area path
Create and edit nodes under an area path or iteration path
Define and edit queries or query folders
Define and edit Delivery Plans
Project-level permissions
Create work item tags
Move work items out of a project
Permanently delete work items
Edit shared work item queries
Add teams and team administrators)
Edit project-level permissions
Project collection-level permissions

Includes all permissions you can set at the collection-level.
Create, delete, or edit a process (Inheritance process model)
Delete field from account (Inheritance process model)
Manage process permissions (Inheritance process model)
Edit collection level permissions
Project collection-level permissions include all permissions you can set at the
collection-level.
For more information, see Add groups.
Default permissions for Boards, backlogs, and sprints
Boards default permissions
Task
Readers
Contributors
Team admins
Project admins
View boards and open work items
✔️
✔️
✔️
Add work items to a board; update status through drag-and-drop
✔️
✔️
Reorder work items or reparent child items through drag-and-drop; update a field on a
card
✔️
✔️
Add child items to a checklist
✔️
✔️
Assign to a sprint (from card field)
✔️
✔️
Configure board settings
✔️
Backlogs default permissions

Task
Readers
Contributors
Team admins
Project admins
View backlogs and open work items
✔️
✔️
✔️
Add work items to a backlog
✔️
✔️
✔️
✔️
Add child items to a backlog item; prioritize or reorder a backlog; parent items using the
Mapping pane; Assign items to a sprint using the Planning pane
✔️
✔️
Configure team settings, backlog levels, show bugs, work days off
✔️
Sprints default permissions
Task
Readers
Contributors
Team admins Project admins
View sprint backlogs, taskboards, and open work items
✔️
✔️
✔️
Add work items to a sprint backlog or taskboard
✔️
✔️
Prioritize/reorder a sprint backlog or taskboard; add child items to a backlog item;

reassign items to a sprint using the Planning pane
✔️
✔️
View team capacity and work details
✔️
✔️
Set team capacity
✔️
✔️
✔️
✔️
Define team sprints
✔️
Create child nodes, modify work items under

an area or iteration path
Area path permissions let you grant or restrict access to edit or modify work items, test
cases, or test plans assigned to those areas. You can restrict access to users or groups.
You can also set permissions for who can add or modify areas or iterations for the
project.
７ Note
Project members with permissions to create or edit Area Paths or Iteration Paths
can't set team Area Paths and Iteration Paths. To configure team settings, you must
be added to the team administrator role or be a member of the Project
Administrators group.
Do the following steps to define both areas and iterations for a project.
1. Choose Project settings > Project configuration > Boards, and then select Areas
or Iterations to modify Area Paths or Iteration Paths.
2. Choose the ... context menu for the node you want to manage and select Security.
3. Select the group or project member, and then change the permission settings. To
add a user or group, enter their name in the search box.
For example, here we added the Disallow Access Group, and disallowed members
of this group the ability to view, modify, or edit work items in the Account
Management area path.
You can specify two explicit authorization states for permissions: Deny and Allow.
In addition, permissions can exist in one of the three other states. For more
information, see About permissions, access, and security groups.
4. (Optional) Choose the Inheritance slider to disable inheritance. Disabling

Inheritance persists all inherited permissions as explicit Access Control Entries
(ACEs).
5. When you're done, close the dialog. Your changes automatically save.
Default permissions for work items
Task or permission
Readers
Contributors
Project admins
View work items in this node (Area Path permission)
✔️
✔️
✔️
Edit work items in this node (Area Path permission)
✔️
✔️
Edit work item comments in this node (Area Path permission)
✔️
✔️
✔️
✔️
Change work item type (Project-level permission)
✔️
✔️
Move work items out of this project (Project-level permission)
✔️
✔️
Email work items
✔️
✔️
✔️
Apply a work item template
✔️
✔️
Delete and restore work items (Project-level permission) (able to restore from the
Recycle bin)
✔️
✔️
Permanently delete work items (Project-level permission)
✔️
Provide feedback (through the Microsoft Feedback client)
✔️
✔️
Request feedback
✔️
✔️
７ Note
Work items are subject to rules applied to them. Conditional rules based on user or
group membership are cached for your web browser. If you find yourself restricted
to update a work item, you may have encountered one of these rules. If you believe
you've encountered an issue that doesn't apply to you, see Work item form
IndexDB caching issues. For more information, see Rules and rule evaluation.
Use custom rules

Custom rules don't control permissions, but they affect whether a user can modify a
work item or set the value of a work item field. Azure Boards supports the following
work tracking customizations that support business workflows.
Customization Examples
Apply rules upon work item creation, - Make a field read-only

state change, and specified state. - Make a field required
Apply rules when a field value is empty, - Clear the value of a field if it's empty or meets
set to a specific value, or change or not certain criteria
changed to a value. - Set a predefined value for the field if it's empty or
meets specific conditions
- Copy the value of one field to another field
- Hide a field based on certain conditions or values
Apply rules that dictate what state a - Reassign a work item based on state changes
work item can get moved to from a - Specify that a work item can only transition from
given state. "State A" to "State B"
- Manage the state transitions of parent work items
based on the state changes of their child work items
Apply rules based on user or group Specify rules that restrict a group from creating a
membership of the user modifying a work item, transitioning a work item to a closed or
work item. completed state, or changing the value of a field
There are some restrictions for applying custom rules to system fields. For example, you
can't specify rules that set or clear the value for Area Path or Iteration Path as they're
system fields. For more information, see Rules and rule evaluation and Sample rule
scenarios.
Set permissions on queries or query folders

You can specify who can add or edit query folders or queries at the object-level. To
manage permissions for a query or query folder, you must be the creator of the query or
folder, a member of the Project Administrators or Project Collection Administrators
group or granted explicit access through the object's Security dialog.
Query folder permissions dialog

For more information, see Create managed queries to list, update, or chart work items.
Default permissions for queries
 Tip
By default, Contributors can't create and save shared queries. We recommend that
Project Administrators create a query folder for each team and give the team
administrators or the team group query permissions to manage their folder. You
need Delete permissions to rename or move a shared query or folder, and
Contribute permissions for the folder where you move the query to. To learn more,
see Set permissions on queries and query folders.
Task
Readers
Contributors
Project admins
✔️
✔️
✔️

✔️
✔️
✔️
Adhoc searches are powered by a semantic search engine.
Set permissions for work item tags

By default, all users of the Contributors group can create and add tags to work items. To
set permissions for a group or user to restrict this ability, you can set the Create tag
definition to Deny at the project-level. To learn how, see Change the permission level
for a project-level group.
Manage permissions for Delivery Plans

Delivery Plans are an object within a project. You can manage permissions for each plan
like the way you manage permissions for shared queries or query folders. The creator of
a Delivery Plan and all members of the Project Collection Administrators and Project
Administrators groups have permissions to edit, manage, and delete plans.
Users granted Stakeholder access for private projects have no access to delivery plans,
while users granted Stakeholder access for public projects has the same access as
regular Contributors granted Basic access. For a comparison chart of Stakeholder versus
basic access, see the Feature Matrix .
To edit the permissions for a Delivery Plan, you must be the creator of the plan, a
member of the Project Administrators or Project Collection Administrators group, or
granted explicit permission through the plan's Security dialog.
1. Open Boards > Delivery Plans.

2. To grant permissions to a group or user to manage or edit a specific plan, choose
More options to open the Security dialog for the plan.
3. Add a user, team group, or other security group who you want to grant
permissions to or restrict access. For details, see Change project-level permissions.
By default, nonadministrators can't delete or edit a plan.
4. With the user or group selected, set the permission you want them to have to
Allow. Manage set to Allow enables the user to manage permissions for the plan.
5. When you're done, close the dialog. Your changes automatically save.
Default permissions for Delivery Plans
Task
Readers
Contributors
Team admins
Project admins
View delivery plans
✔️
✔️
✔️
Create, edit, or delete a delivery plan, Contributors can only edit or delete plans that
they create
✔️
✔️
Manage permissions for a delivery plan, Contributors can only manage permissions for
plans that they create
✔️
✔️
Move or permanently delete work items

By default, Project Administrators and Contributors can change the work item type and
delete work items by moving them to the Recycle Bin. Only Project Administrators can
permanently delete work items and test artifacts. Project admins can grant permissions
to other team members as needed.
For example, as a project admin you can grant a user, team group, or other group
you've created to have these permissions. Open the Security page for the project and
choose the user or group you want to grant permissions. To learn how to access project-
level Security, see Change project-level permissions.
７ Note
The Move work items out of this project permission requires the Inherited process
model for the project.
In the following example, we granted members who are assigned to the team
administrator role, and who belong to the Team Admin group, permissions to move
work items to another project and permanently delete work items.
Manage test plans and test suites
In addition to the project-level permissions set in the previous section, team members
need permissions to manage test artifacts that are set for an area path.
Open the Security page for area paths and choose the user or group you want to grant
permissions.
Set the permissions for Manage test plans and Manage test suites to Allow.
To have full access to the Test feature set, your access level must be set to Basic + Test
Plans. Users with Basic access and with permissions to permanently delete work items
and manage test artifacts can only delete orphaned test cases.
Default permissions for test management
Test plans, test suites, test cases and other test artifacts are specific work item types that
support manual and exploratory testing. For more information, see Set test permissions
at the project level.
Permission
Level
Readers
Contributors
Project Admins
View test runs
Project-level
✔️
✔️
✔️
Create test runs

Delete test runs
Project-level
✔️
✔️
Manage test configurations

Manage test environments
Project-level
✔️
✔️
Delete and restore work items
Project-level
✔️
✔️
Permanently delete work items
Project-level
✔️
View work items in this node
Area Path
✔️
✔️
✔️
Edit work items in this node

Manage test plans
Manage test suites
Area Path
✔️
✔️
７ Note
The Change work item type permission doesn't apply to test-specific work items.
Even if you choose this feature from the work item form, changing the work item
type is disallowed.
Area permissions for web-based test case management and test execution control
access to the following actions.
The Manage test suites permission enables users to do the following tasks:
Create and modify test suites

Add or remove test cases to/from test suites
Change test configurations associated with test suites
Modify the suite hierarchy by moving a test suite
The Manage test plans permission enables users to do the following tasks:
Create and modify test plans

Add or remove test suites to or from test plans
Change test plan properties such as build and test settings
Customize an inherited process

By default, only Project Collection Administrators can create and edit processes.
However, these admins can grant permissions to other team members by explicitly
setting the Create process, Delete process, or Edit process permissions at the collection
level for a specific user.
To customize a process, you need to grant Edit process permissions to a user account
for the specific process.
７ Note
Users added to the Project-Scoped Users group can't access Process settings if the
Limit user visibility and collaboration to specific projects preview feature is
enabled for the organization. For more information including important security-
related callouts, see Manage your organization, Limit user visibility for projects
and more.
1. Open the … context menu for the inherited process and choose Security. To open
this page, see Customize a project using an inherited process.
2. Enter the user name, set the applicable permissions to Allow, and then exit. The
page automatically saves.
７ Note
Each process is a securable unit and has individual access control lists (ACLs) that
govern creating, editing, and deleting inherited processes. At the collection level,
project collection administrators can choose the inherited processes. When you
create a new inherited process, the process creator and project collection
administrators have full control of the process and can also set individual ACLs for
other users and groups to edit and delete the process.
More access options for work items

For more information about options for customizing work item types to support
restrictions, see Restrict access, Restrict modification of work items based on a user or
group.
Grant team members additional permissions

For teams to work autonomously, you may want to provide them with permissions that
they don't have by default. Suggested tasks include providing team administrators or
team leads permissions to:
Create and edit child nodes under their default area path
Create and edit child nodes under an existing iteration node
Create shared queries and folders under the Shared Queries folder.
By default, team members inherit the permissions afforded to members of the project
Contributors group. Members of this group can add and modify source code, create and
delete test runs, and create and modify work items. They can collaborate on a Git
project or collaborate with other team members and check in work to the team's code
base (TFVC).
Related articles
Grant or restrict access
Rules and rule evaluation
Permissions and groups reference
Delete test artifacts
Grant or restrict access using
permissions
Article • 03/23/2023
2018
You can grant or restrict access to resources that you manage in Azure DevOps. You may
want to open up or close down access to a select set of features and for a select set of
users. While the built-in security groups provide a standard set of permission
assignments, you may need more security requirements not met by these assignments.
If you're new to administrating permissions and groups, review Get started with
permissions, access, and security groups to learn about permission states and
inheritance.
In this article you learn how to do the following tasks:
＂ Recommended method for granting and restricting permissions

＂ Delegate tasks by assigning select permissions to specific roles
＂ Limit user visibility to organization information
＂ Limit people picker to project users and groups
＂ Restrict access to view or modify objects
＂ Restrict modification of work items based on a user or group
 Tip
Because you set many permissions at an object-level, such as repositories and area
paths, how you structure your project determines the areas you can open up or
close down.
Recommended method for granting and

restricting permissions
For maintenance purposes, we recommend you use either the built-in security groups or
custom security groups to manage permissions.
You can't change the permission settings for the Project Administrators group or the
Project Collection Administrators group, which is by design. However, for all other
groups, you can change the permissions.
If you manage a few users, then you may find changing individual permissions a valid
option. However, custom security groups allow you to better track roles and permissions
assigned to those roles.
Delegate tasks to specific roles

As an administrator or account owner, it's a good idea to delegate administrative tasks
to those team members who lead or manage an area. Several of the main built-in roles
that come with default permissions and role assignments are:
Readers
Contributors
Team Administrator (role)
Project Administrators
Project Collection Administrators
For a summary of permissions for the above roles, see Default permissions and access,
or for the Project Collection Administrators, see Change project collection-level
permissions.
To delegate tasks to other members within your organization, consider creating a

custom security group and then granting permissions as indicated in the following table.
Role
Tasks to perform
Permissions to set to Allow
Development lead (Git)
Manage branch policies
Edit policies, Force push, and Manage permissions

See Set branch permissions.
Development lead (TFVC)
Manage repository and branches
Administer labels, Manage branch, and Manage permissions

See Set TFVC repository permissions.
Software architect (Git)
Manage repositories
Create repositories, Force push, and Manage permissions

See Set Git repository permissions
Team administrators
Add area paths for their team

Add shared queries for their team
Create child nodes, Delete this node, Edit this node See Create child nodes, modify work
items under an area path
Contribute, Delete, Manage permissions (for a query folder), See Set query permissions.
Contributors
Add shared queries under a query folder, Contribute to dashboards
Contribute, Delete (for a query folder), See Set query permissions

View, Edit, and Manage dashboards, See Set dashboard permissions.
Project or product manager
Add area paths, iteration paths, and shared queries

Delete and restore work items, Move work items out of this project, Permanently delete
work items
Edit project-level information, See Change project-level permissions.
Process template manager (Inheritance process model)
Work tracking customization
Administer process permissions, Create new projects, Create process, Delete field from
account, Delete process, Delete project, Edit process
See Change project collection-level permissions.
Process template manager (Hosted XML process model)
Edit collection-level information, See Change project collection-level permissions.

Project management (On-premises XML process model)
Edit project-level information, See Change project-level permissions.
Permissions manager
Manage permissions for a project, account, or collection
For a project, Edit project-level information

For an account or collection, Edit instance-level (or collection-level) information
To understand the scope of these permissions, see Permission lookup guide. To request
a change in permissions, See Request an increase in permission levels.
You can also grant permissions to manage permissions for the following objects:
Set Git repository permissions
Manage Git branch permissions
Set TFVC repository permissions
Administer build and release permissions
Manage Wiki permissions.
Limit user visibility to organization and project

information
） Important
The limited visibility features described in this section apply only to

interactions through the web portal. With the REST APIs or azure devops CLI
commands, project members can access the restricted data.
Guest users who are members in the limited group with default access in
Azure AD, can't search for users with the people picker. When the preview
feature's turned off or when guest users aren't members of the limited group,
guest users can search all Azure AD users, as expected.
By default, users added to an organization can view all organization and project
information and settings. To restrict access to only those projects that you add users to,
you can enable the Limit user visibility and collaboration to specific projects preview
feature for the organization. To enable this feature, see Manage or enable features.
With this feature enabled, users added to the Project-Scoped Users group can't view
most Organization settings and can only connect to those projects to which they've
been added.
２ Warning
When the Limit user visibility and collaboration to specific projects preview
feature is enabled for the organization, project-scoped users are unable to search
for users who were added to the organization through Azure Active Directory
group membership, rather than through an explicit user invitation. This is an
unexpected behavior and a resolution is being worked on. To self-resolve this issue,
disable the Limit user visibility and collaboration to specific projects preview
feature for the organization.
Limit people picker to project users and groups

For organizations that manage their users and groups using Azure Active Directory
(Azure AD), people pickers support searching all users and groups added to Azure AD,
not just those users or groups added to a project. People pickers support the following
Azure DevOps functions:
Selection of a user identity from a work tracking identity field such as Assigned To
Selection of a user or group using @mention in a work item discussion or rich-text
field, a pull request discussion, commit comments, or changeset or shelveset
comments
Selection of a user or group using @mention from a wiki page
As shown in the following image, you simply start typing into a people picker box until
you find a match to a user name or security group.
Users and groups who are added to the Project-Scoped Users group can only see and
select users and groups in the project they're connected to from a people picker. To
scope people pickers for all project members, see Manage your organization, Limit
identity search and selection.
Restrict access to view or modify objects

Azure DevOps is designed to enable all valid users to view all objects defined in the
system. You can restrict access to resources by setting the permission state to Deny. You
can set permissions for members that belong to a custom security group or for an
individual user. To learn more about how to set these types of permissions, see Request
an increase in permission levels.
Area to restrict
Permissions to set to Deny
View or contribute to a repository
View, Contribute
See Set Git repository permissions or Set TFVC repository permissions.
View, create, or modify work items within an area path
Edit work items in this node, View work items in this node
See Set permissions and access for work tracking, Modify work items under an area
path.
View or update select build and release pipelines
Edit build pipeline, View build pipeline

Edit release pipeline, View release pipeline
You set these permissions at the object level. See Set build and release permissions.
Edit a dashboard
View dashboards
See Set dashboard permissions.
Restrict modification of work items or select
fields
For examples that illustrate how to restrict modification of work items or select fields,
see Sample rule scenarios.
Next steps
Remove user accounts
Related articles
Troubleshoot permissions
Rules and rule evaluation
Default permissions and access
Permission lookup guide
Get started with permissions, access, and security groups
Permissions and groups reference
Change project-level permissions
Change project collection-level permissions
About Kanban boards
Article • 06/01/2023
2018
Your Kanban board provides you with a visual interactive space for you and your team
to plan and show progress. Your team can track the critical information it needs by
seeing which work items are in progress, where the bottlenecks are, who work is
assigned to, and more.
As work progresses from idea to completion, you update the items on the board. Each
column represents a work stage. Each card represents a work item and supports quick
status updates through drag-and-drop, similar to sticky notes on a physical whiteboard.
Both Kanban boards and Taskboards support visualizing the flow of work and
monitoring metrics to optimize that flow. Kanban boards track requirements, are sprint-
independent, and provide a cumulative flow chart for monitoring progress. Each sprint is
associated with a Taskboard that supports tracking tasks defined for the sprint. You can
monitor progress through capacity charts and the sprint burndown chart. For more
information, see Update and monitor your Taskboard.
Product and portfolio Kanban boards

Each product and portfolio backlog has a corresponding Kanban board. Kanban boards
are associated with a team and display work items that are based on the area and
iteration paths that the team selected. For more information, see Define iteration (sprint)
paths and configure team iterations.
To maximize a team's ability to consistently deliver high-quality software, Kanban

emphasizes two main practices. The first is to visualize the flow of work. This practice
requires you to map your team's workflow stages and configure your Kanban board to
match. The second is to constrain the amount of work in progress, which requires you to
set work-in-progress (WIP) limits. You're then ready to track progress on your Kanban
board and monitor key metrics to reduce lead or cycle time. To get started, see Use your
Kanban board.
Kanban concepts and terms
See the following table of terms and available tools used in tracking work using Kanban
boards and Kanban methods.
Concept Description
or Term
Blocker An issue that prevents work from progressing. You can highlight work that is
blocked by using tags and changing the card color. For more information, see
Customize cards, Define style rules to highlight cards.
Bottleneck A constraint in the system that limits the flow of work. Identifying bottlenecks
makes it easier to reduce their effect and provides a mechanism for controlling work
flowing through the process. For more information, see Manage columns, Identify
bottlenecks.
Card Card reordering lets you change the priority order and forces cards to maintain the
reordering backlog priority when you drag and drop them on the board. For more information,
see Reorder cards.
Cumulative The in-context CFD report shows the count of items in each Kanban column for the
flow past 30 weeks or less. From this chart, you can gain an idea of the amount of work
diagram in progress and lead time. Work in progress counts unfinished requirements. For
(CFD) more information, see Cumulative flow, lead time, and cycle time guidance.
Cycle time Cycle time is the time calculated for a work item from first entering an In Progress
category state to entering a Completed state category. For more information, see
Cumulative flow, lead time, and cycle time guidance. You can gain valuable metrics
and visualize the cycle time for a team and a configurable time period by adding the
Cycle Time widget to the dashboard.
Concept Description
or Term
Definition Criteria that a team specifies for each stage of work to share and standardize on
of done what makes up work being done at that stage.
Kanban An interactive, electronic sign board that supports visualization of the flow of work
board from concept to completion and lean methods. Azure DevOps provides a Kanban
board for each product and portfolio backlog. For more information, see Kanban
basics and Kanban board features and epics and Track work in swimlanes.
Kanban A Kanban column maps to a stage of work. The default columns map to the
columns workflow states of the work item types that appear on the Kanban board. You
configure the columns to map workflow states of your team. For more information,
see Map the flow.
Lead time Lead time is the time calculated for a work item from first entering a Proposed
category state to entering a Completed state category. For more information, see
Cumulative flow, lead time, and cycle time guidance. You can gain valuable metrics
and visualize the lead time for a team and a configurable time period by adding the
Lead Time widget to the dashboard.
Live Live updates is a Kanban board view option that when enabled automatically
updates refreshes the Kanban board as other team members move or reorder cards. For
more information, see Enable live updates.
Product An interactive list of work items that corresponds to a team's project plan or
backlog roadmap for what the team plans to deliver. The product backlog supports
prioritizing work, forecasting work by sprints, and quickly linking work to portfolio
backlog items. You can define your backlog items and then manage their status
using the Kanban board. Each team can customize its product backlog. For more
information, see Create your backlog.
Product A type of work item that defines the applications, requirements, and elements that
backlog teams plan to create. Product owners typically define and stack rank product
item backlog items, which are defined with the Scrum process. For more information, see
Scrum process work item types and workflow.
Portfolio An interactive list of work items, similar to the product backlog that supports
backlog organizing or grouping work under features epics, or scenarios. Portfolio backlogs
work similarly to product backlogs in that you can prioritize work and view the tree
hierarchy of work. For more information, see Define features and epics.
Swimlanes A swimlane is a configurable row on a Kanban board, used to support different

service class levels of work. For more information, see Speed up work with
swimlanes.
Concept Description
or Term
Split The Split columns feature lets your team implement a pull mechanism within the
columns workflow process. Without split columns, teams push work forward, to signal that
they've completed their stage of work. However, pushing it to the next stage
doesn't necessarily mean that a team member immediately starts work on that item.
With split columns, your team knows exactly how many items sit idle, waiting for
work to begin. For more information, see Manage columns.
Task A task is a type of work item used to track work required to complete a user story or
checklists product backlog item. You can add tasks from your Kanban board that appear as a
checklist of work to be done. As you complete a task, you can update its status by
checking the checkbox for the task. For more information, see Add tasks or child
items as checklists.
Task Task switching, also referred to as context switching or multitasking, is when a team
switching member shifts their attention among different tasks. Limiting task switching can
allow a person to work more efficiently by minimizing the amount of time required
to redirect cognitive function to a new activity.
User story A type of work item that defines the applications, requirements, and elements that
teams plan to create. Product owners typically define and stack rank user stories.
User story is defined with the Agile process. For more information, see Agile process
work item types and workflow.
Work in Work that has been started but isn't done or completed.
progress
(WIP)
WIP limit A WIP limit is a constraint that a team applies to one or more workflow stages to
help prevent potential bottlenecks that hinder the continuous flow of work in the
system. For more information, see Work in Progress limits.
Workflow Workflow states are defined for each work item type to support tracking the status
states of a work item, from its creation to its completion. These states define the workflow
process: actions, steps, or stages that a piece of work goes through from inception
to completion. The State and Reason fields differ depending on the work item type
and process selected for the project. For more information, see Customize the
workflow.
Workflow State categories determine how the Kanban board treats each workflow state. The
state state categories used by the backlogs are Proposed, In Progress, Resolved, and
categories Completed. For more information, see Workflow states and state categories.
Agile glossary
Project management and navigation glossary
Use Kanban board controls
You can quickly switch from the backlog view to the board view using the Backlog and
Board links. Use the following icons to enable other user interface features.
Control Function
Backlog Switch to backlog view
Board Switch to Kanban board view
Filter by keywords, tags, or fields
Enable live updates
Customize the board and configure team settings:

Cards | Card reordering | Columns | Swimlanes | CFD chart | Backlogs | Working days |
Working with bugs
/ Enter or exit full screen mode
Open keyboard shortcuts

Enter ? to open the Kanban board keyboard shortcuts. The following image isn't
exhaustive.
For more information, see Keyboard shortcuts for Azure DevOps and Team Explorer.
Configure & customize your Kanban board
Your Kanban board is highly configurable to support your team's workflow. Each team
can configure each board with the following tasks:
Configure boards
Configure card displays
Manage columns
Set WIP limits
Set Definition of Done
Add swimlanes
Reorder cards
Enable backlog and board levels
Work with bugs
Add or remove fields from cards
Define card styles
Apply tag colors
Enable/disable annotations
Define inline test behavior on cards
Add details and estimates to your backlog items
Define tasks or child items for backlog items
Add, run, and update inline tests
Along with these team configurations, you can customize your project by adding or
modifying work item types, the workflow, and add customized portfolio backlogs and
boards.
Can you define a board configuration that multiple teams

can subscribe to?
Answer: No. Each team controls their own team settings and board configurations.
Update work item status

Once you've configured your Kanban board, you can add work items directly to the
board. Update the status of work by dragging a card to another column on the Kanban
board. You can even change the order of items as you move a card to a new column. For
more information, see Workflow states and state categories.
Display leaf node work items
While you can create a hierarchy of backlog items, tasks, and bugs—we don't
recommend that you create same-category hierarchies. In other words, don't create
parent-child links among work items of the same type, such as story-story, bug-bug, or
task-task. The last node in a same-category hierarchy may only appear on Kanban
boards, sprint backlogs, and Taskboards. For example, if you link items within a same-
category hierarchy that is four levels deep, only the items at the fourth level appear on
the Kanban board, sprint backlog, and taskboard.
Rather than nest requirements, bugs, and tasks, we recommend that you maintain a flat
list. Only create parent-child links one level deep between items that belong to a
different category. For more information, see Fix re-ordering and nesting issues, How
backlogs and boards display hierarchical (nested) items.
Reorder and reparent work items

All backlogs and boards support drag-and-drop to reorder and reparent work items.
Updates made to one team's backlogs and boards are reflected in other team backlogs
and boards that share the same area path. You may need to refresh the page to view the
changes.
You can only use drag-and-drop to reorder or reparent work items assigned to area
paths selected for your team. When the Parents view option is enabled, work items may
appear on your backlog that your team doesn't own. Anything that appears with the
information icon can't be reordered nor reparented as another team owns it.
Update columns
Each team can customize the Kanban board columns and swimlanes. The values that get
assigned to Kanban board fields may differ from what you expect when another team
updates the work item from a different board.
Even if the management team and the feature teams configure their Kanban board
columns with identical workflow mapping, one team's Kanban board items aren't
reflected on another team's Kanban board. Only when the work item moves to a column
that maps to a workflow state does the card column reflect the same on all boards.
For more information, see Manage columns.
Provide 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 more information 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.
Customize your project and board inheritance

If you need more than three board levels, you can add more. For more information, see
Customize your backlogs or boards for a process.
You can also add or modify the fields defined for a work item type (WIT), add a custom
WIT, or modify the workflow. For more information, see Customize an inheritance
process.
Next steps
Use your Kanban board
Related articles
Configure a cumulative flow chart
Cumulative flow, lead time, and cycle time guidance
Lead time and cycle time widgets
About work items
Work across projects FAQs
What is Agile?
Use your Kanban board
Article • 06/01/2023
2018
Kanban boards provide an intuitive and visual way to manage your projects, track work
items, and collaborate with your team effectively. If you have a project, you already have
a Kanban board. Let's get started!
In this article, learn how to:
＂ Open your Kanban board

＂ Map the flow of how your team works
＂ Set work in progress limits
＂ Track work in progress
＂ Add work items
＂ Update work item status
＂ Update card fields
＂ Filter your board
＂ Invite others to work on your board
＂ Enable live updates
＂ Monitor metrics
７ Note
You can only create or add Kanban boards to a project by adding another team.
Kanban boards only get created when a project or team gets created. For more
Prerequisites
Boards are automatically created when you create a project or add a team. Each team
has access to their own product and portfolio boards as described in About teams and
Agile tools.
You must connect to a project. If you don't have a project yet, create one.
You must be added to a team or project.
To add work items and exercise all board features, you must be granted Basic
access or higher.
To view or modify work items, 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.
Users with Stakeholder access for a private project can add work items and update
status through drag-and-drop, but cannot update fields displayed on cards. They
can add tasks and change task status.
Users with Stakeholder access for a public project have full access to board
features just like users with Basic access.
７ Note
monitoring metrics to optimize that flow. Kanban boards track requirements, are
sprint-independent, and provide a cumulative flow chart for monitoring progress.
Each sprint is associated with a Taskboard that supports tracking tasks defined for
the sprint. You can monitor progress through capacity charts and the sprint
burndown chart. For guidance on using the Taskboard, see Update and monitor
your Taskboard.
Open your Kanban board from the web portal

Your Kanban board is one of two types of boards available to you. The other is the sprint
Taskboard. Kanban boards track requirements, are sprint-independent, and provide a
cumulative flow chart for monitoring progress. Each sprint is associated with a
Taskboard that supports tracking tasks defined for the sprint. You can monitor progress
through capacity charts and the sprint burndown chart. For guidance on using the
Taskboard, see Update and monitor your Taskboard. For an overview of the features
supported on each backlog and board, see Backlogs, boards, and plans.
1. Check that you selected the right project, and select Boards > Boards. Then select
the correct team from the team selector menu.
To select another team's board, open the selector. Then select a different team, or
select the Browse all team boards option. Or, you can enter a keyword in the
search box to filter the list of team backlogs for the project.
 Tip
2. Check that you selected Backlog items for Scrum, Stories for Agile, or
Requirements for CMMI as the backlog level.
To switch to the product backlog, select Stories backlog. To switch to a Taskboard, see
Update and monitor your Taskboard.
Map the flow of how your team works

When you first open your Kanban board, you have one column for each workflow state.
Your actual columns vary based on the process used to create your project.
1. Identify your team's workflow stages, which most likely don't map to the default
states. For your team to have a functional board, configure the board to match
your workflow stages.
For example, for user stories, the New, Active, Resolved, and Closed states track
progress from idea to completion.
2. Manage your Kanban columns, so they match your workflow stages. Keep the
number of columns to a minimum while still representing the key handoffs that
occur for your team.
Set WIP limits

Set WIP limits for each workflow stage, so that when work items exceed the limit, the
column count displays as red. Teams can use this color as a signal to focus immediately
on activities to bring the number of items in the column down. For more information,
see Set WIP limits.
Track work in progress

See the estimated size of work for each item that displays at the bottom right of each
card. Add items to your backlog in the first column. When priorities change, move items
up and down within a column. And, as work completes in one stage, update the status
of an item by moving it to a downstream stage.
Update your Kanban board as work progresses to help keep your team in sync. Also,
you can see and share the value stream your team is delivering to customers.
） Important
Work items that appear on more than one team's Kanban board can yield results
that don't meet your expectations because each team can customize its Kanban
board columns and swimlanes. The values assigned to Kanban Board Column,
Board Column Done, and Board Lane fields might differ from what you expect
when another team updates the work item from a different board. For more
information, see Add, review, and update work items in Azure Boards.
Add work items

To add a work item, select the plus sign, enter a title, and then select Enter.
The system automatically saves the work item with the title you entered. You can add as
many work items you want by using this method.
To add details to any work item, select the title. Or, you can directly modify any field that
displays. For example, you can reassign a work item by selecting Assigned To. For a
description of each field, see Create your backlog, Add details and estimates. You can
also add tasks or child items as checklists on your cards.
７ Note
Update work item status

As work completes in one stage, update the status of an item by dragging it to a
downstream stage.
７ Note
Update card fields

You can quickly update a field or reassign ownership directly from the board. If the field
you want to update isn't showing, then customize the card, so it displays. For more
information, see Customize cards.
Filter your board with keywords, field values, or tags
You can apply filters interactively to focus on a subset of work. For example, you can
filter the board to focus on work assigned to at team member for a specific sprint. To
start filtering, choose Filter . For more information, see Filter your backlogs, boards,
and plans.
In the following example image, we filtered all items assigned to Jamal and Raisa.
Invite others to work on your Kanban board

All members of a project can view and contribute to your Kanban board. To invite users
to contribute, copy the URL of your Kanban board and send it to those users.
To add users to your project, see Add users to a project.
Enable live updates

Enable live updates to automatically refresh your Kanban board when changes occur.
With live updates enabled, you no longer have to select F5 to see the latest changes. To
view or modify work items, View work items in this node and Edit work items in this
node permissions must be set to Allow. By default, the Contributors group has this
permission set. Users with Stakeholder access for a private project can add work items
and update status through drag-and-drop, but can't update fields displayed on cards.
They can add tasks and change task status.
Choose the view options icon and move the slider for Live updates to On.
Monitor metrics
As with most Agile practices, Kanban encourages monitoring key metrics to fine tune
your processes. After your team has used the Kanban board for several weeks, check out
your Cumulative Flow Diagram (CFD).
Choose the Analytics tab, and then choose View full report for the CFD as shown in the
following image.
Use the interactive controls to choose the time frame, swimlanes, and workflow states or
Kanban board columns.
Hover over a point in time to show how many work items are in a particular state.
The following example image shows that on July 3, 101 items were in a Researching
state.
 Tip
The selections you make only get set for you, and persist across sessions until you
change them.
By monitoring these metrics, you can gain insight into how to optimize your processes
and minimize lead time. For more information, see Configure a cumulative flow chart.
You can also add Analytics widgets to your dashboard. The Analytics Service is in
preview and provides access to several widgets. For more information, see the following
articles:
Widgets based on the Analytics Service

Add a widget to a dashboard
What is the Analytics Service?
Can I view a Kanban board of work items

defined by a query?
The Query Based Boards Marketplace extension supports viewing a flat-list query of
work items as a Kanban board. The query can contain different work item types and
work items defined in different projects.
Next steps
Expedite work using swimlanes
Related articles
Filter backlogs, boards, queries, and plans
Kanban key concepts
Cumulative flow diagram
Add tasks or child items as checklist
items
Article • 03/22/2023
2018
Many teams find Kanban boards ideal for tracking work. Kanban boards are ideal
because they support visualization the flow of work that is in progress. It also allows
team members to quickly add new items and update work item status in a Kanban
board. If you're new to working with the Kanban board, see Kanban overview.
With checklists or to do lists, you continue to enjoy lightweight tracking. You gain
visibility into which tasks, bugs, or other child items are in progress or completed. For
example, here we show several tasks and bugs for work in progress, both yet to do and
those items marked as completed. By adding the Issue work item type to the Iteration
backlog, issues can be added as checklists.
In this article, you'll learn:
＂ Summary of checklist features

＂ How to add checklist items from your Kanban board
＂ How to mark a checklist item as done
＂ How to expand or collapse a checklist
＂ How to reorder and reparent checklist items or reassign them to a sprint
Overview of checklist features
Checklists are a feature of all Kanban boards, both product and portfolio backlog levels.
All Kanban board levels support checklists. For a view of default backlog
hierarchies, see Plan and track work.
Adding a checklist item automatically adds a parent-child link between the parent
work item and the checklist item.
For the product-level board:
When Bugs are managed with tasks, they're available to add and track within a
checklist.
When Bugs are managed with requirements, you can add tasks to bugs that
are tracked on the board. Teams make this choice via Board settings, Working
with bugs.
Marking any checklist item as "done" moves the work item State to done, closed,
or completed.
Teams can remove select checklist features by disabling them on the Annotations
tab of the Board settings.
Tasks or other child items that you create from the Kanban board are automatically
assigned to the sprint/iteration path of the parent work item under which you
define them.
Any work item type added to the backlog hierarchy is available to add using the
checklist feature.
To add work item types to track as checklists, add them to the next-lower
hierarchical backlog. To learn how, see Customize your backlogs or boards
(Inheritance process) or Process configuration XML element reference (On-
premises XML process).
 Tip
If you find that you don't use this feature, you can disable it from the common
configurations dialog.
Prerequisites
Agile tools.
access or higher.
work tracking.
７ Note
monitoring metrics to optimize that flow. Kanban boards track requirements, are
sprint-independent, and provide a cumulative flow chart for monitoring progress.
Each sprint is associated with a Taskboard that supports tracking tasks defined for
the sprint. You can monitor progress through capacity charts and the sprint
burndown chart. For guidance on using the Taskboard, see Update and monitor
your Taskboard.

Your Kanban board is one of two types of boards available to you. The other is the sprint
Taskboard. Kanban boards track requirements, are sprint-independent, and provide a
cumulative flow chart for monitoring progress. Each sprint is associated with a
Taskboard that supports tracking tasks defined for the sprint. You can monitor progress
through capacity charts and the sprint burndown chart. For guidance on using the
Taskboard, see Update and monitor your Taskboard. For an overview of the features
supported on each backlog and board, see Backlogs, boards, and plans.
1. Check that you selected the right project, and select Boards > Boards. Then select
the correct team from the team selector menu.
To select another team's board, open the selector. Then select a different team, or
select the Browse all team boards option. Or, you can enter a keyword in the
 Tip
2. Check that you selected Backlog items for Scrum, Stories for Agile, or
Requirements for CMMI as the backlog level.
To switch to the product backlog, select Stories backlog. To switch to a Taskboard, see
Add one or more child items to a checklist

In this example, tasks are added to the product Kanban board using the checklist
feature. You can use the same procedures to add any other supported checklist item
from your board.
1. To start adding tasks, open the menu for the work item.
2. If you have many tasks to add, keep entering their titles and choose Enter after
each title.
3. If you have details you want to add about a task, open the item by choosing the
title.
７ Note
Tasks that you create from the Kanban board appear on your sprint Taskboard.
Also, tasks that you create from the sprint backlog or Taskboard appear within
tasks checklists on the Kanban board.
Mark a checklist item as done

When you complete a task or other checklist item, choose the checkbox to change its
status to Done, Closed, or Completed.
The State of the work item is updated from Active to Closed for projects based on an
Agile or CMMI process, and from To Do to Done for projects based on a Scrum or Basic
process.
 Tip
No matter the number of workflow states a checklist item has, checking it moves it
to its closed or completed state.
Expand or collapse a checklist on a Kanban

board
Upon first opening the Kanban board, you'll see an unexpanded view of checklists.
Choose the checklist summary to expand a collapsed checklist. Choose the same
summary to collapse an expanded checklist.
Reorder tasks, reparent tasks, or reassign tasks
to a sprint
You can drag a task within a work item to reorder it. Or, you can drag the task to
another work item on the Kanban board to reparent it.
７ Note
Users with Stakeholder access can't drag-and-drop tasks or reorder and reparent
tasks.
Tasks or other child items you add as checklists are automatically assigned to the
Iteration Path of their parent work item. To reassign a checklist item to a different sprint,
you must open the item and change its Iteration Path. Or, open the sprint backlogs
where it's currently defined and drag it to the new sprint using the Planning pane. For
more information, see Assign backlog items to a sprint.

Checklist items show the avatars of those team members assigned to the item. You can
view the avatar assignment of checklist items, or reassign a checklist item by choosing
the item's …Work items action menu and selecting Assigned to.
７ Note
Avatar images and the Assign to menu option requires you to enable the New
Boards Hub preview feature. To enable this feature, see Manage or enable
features.
Configure the Kanban board

To configure or change the layout of the Kanban board, see Customize your boards.
Related articles
Kanban board features and epics
Interactively filter backlogs, boards, queries, and plans
Add, run, update manual tests
Create a new branch, drive Git development
Use Kanban board controls
REST API resources

To programmatically create work items, see the REST API, Work Items reference.
Add Kanban board features and epics
Article • 02/24/2023
2018
If you track progress on your backlog with Kanban, you can also use Kanban boards to
track epics and features.
And, as with child task checklists for backlog items, you can quickly define and track the
progress of child items for your features or epics. Here we see several stories defined for
features, both in progress and completed.
＂ How to add epics and features using your portfolio backlogs

＂ Keyboard shortcuts for working with the Kanban board
For information on managing features and epics as a list and examples for features and
epics, see Define features and epics.
Prerequisites
Agile tools.
access or higher.
work tracking.

Your Kanban board is one of two types of boards available to you. For an overview of
the features supported on each backlog and board, see Backlogs, boards, and plans. To
switch to the product backlog, choose Stories backlog. And, to switch to the taskboard,
choose Sprints and then choose Taskboard.
1. (1) Check that you've selected the right project, (2) choose Boards>Boards, and
then (3) select the correct team from the team selector menu.
To choose another team's board, open the selector and select a different team or
choose the Browse all team boards option. Or, you can enter a keyword in the
 Tip
Choose the star icon to favorite a team board. Favorited artifacts (

favorited icon) appear at the top of the team selector list.
2. Select Features or Epics from the backlog selector menu.
Add epics or features

Add new items to a feature or epic through the item's Action menu. For descriptions
of fields used to support features and epics, see Define features and epics.
When you have many items to add, keep entering your task titles and press Enter. If you
have details you want to add about to a work item, hover over the item and press Enter.
Related articles
If you're new to working with the Kanban board, see Kanban overview
For more information on working with a checklist on a Kanban board, see Add tasks or
child items as checklists. You can run the same operations for the features and epics
Kanban boards as you do with the Kanban board for the product backlog. These
operations include:
Mark an item as done

Reorder and reparent work items
To customize the columns, swimlanes, or cards for each Kanban board, make sure you
first select the board. Then, choose the or gear icon to open the Settings dialog.
See these articles for details:
Add columns
Customize cards
REST API resources

To programmatically interact with Kanban board and other team settings, see the REST
API, Boards reference.
Interactively filter backlogs, boards,
queries, and plans in Azure Boards
Article • 02/24/2023
2018
With filter functions, you can interactively apply one or more filters to an Azure Boards
tool. Each tool is already filtered to show a subset of work items according to the tool
function. For example, Backlogs and Boards display work items based on the selected
Area Paths and Iteration Paths for the team. Query Results list work items based on the
query clauses you've defined.
You enable the filter feature by choosing Filter.
From these tools, you may still have a large number of work items listed or displayed.
Interactive filtering supports your ability to focus on a subset of them. You can apply
one or more filter functions to each of the Azure Boards tools.
Use filters to complete these tasks:
In daily scrum meetings, filter the Kanban board to focus on assigned work for a
specific sprint.
Or, if your team uses the Sprints Taskboard, filter for a team member's completed
assigned work.
To focus on a group of work items, filter based on the Parent Work Item, by Area
Path, or Tags.
To triage work items, create a query and filter to focus on similar work grouped by
Area Path or Tags.
Supported filter functions

Filter functions are available from all Azure Boards tools: Work items, Boards, Backlogs,
Sprint Backlogs and Taskboards, Queries, and Delivery Plans. The set of features
supported depends on the tool and Azure DevOps version. (Use the content selector to
view the filters available for your version.)
The following table indicates the supported options based on the tool indicated with a
✔️or is listed.
Backlogs and boards are subject to filters defined for the team as described in Set up
your Backlogs and Boards. Other tools have predefined filters based on the view, query
filter clauses, or settings you select.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
Semantic search, Work Items
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes
1. While the Parent Work Item isn't a filter function for Backlogs or Query Results,
you can add the Parent field as a column and then do a keyword/phrase search on
the Parent title to effectively filter on parent work items. The Parent field is
supported for Azure DevOps Server 2020 and later versions. See also the Parent
field and Parent Work Item section later in this article.
2. The Parent Work Item filter is supported for Sprint Backlogs and Taskboards for
Azure DevOps Server 2020 and later versions.
Additional filter, sort, group, reorder, and rollup functions

Along with the standard filter functions summarized in the previous table, the following
table indicates which tools have more filters you can apply, sort, group, reorder, and
rollup functions. Some functions, such as reorder, don't work when the filter function is
enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
Completed Work Items
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
Completed Child items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
1. The Work items page is subject to filters based on the view selected. Boards and
Backlogs are subject to filters defined for the team as described in Set up your
Backlogs and Boards. Completed and In Progress work items are determined
based on the state categories assigned to the workflow state as described in How
workflow states and state categories are used in Backlogs and Boards.
2. Grouping is supported through portfolio backlogs and boards, parent-child links,
and tree hierarchy. Tree hierarchies are flattened when filtering is applied and
reinstated when filtering is cleared.
3. Backlogs and Sprint Backlogs support reordering. However, when filtering is
enabled, reordering isn't supported.
4. Taskboards provides a Group by function based on People or Stories.
5. Query Results supports multi-column sort.
6. Work items appear in the order defined for the team Sprint backlog, which it
inherits from the team product backlog.
7. Semantic search supports sorting search results by the following fields—Assigned
To, Changed Date, Created Date, ID, State, Tags, Title, and Work Item Type—and
Relevance.
To learn more about these other functions, see the following articles:
Reorder cards (Kanban Boards)
About backlogs, Work with multi-team ownership of backlog items
Parent Work Item filter and Parent field

The Parent Work Item filter enables you to focus on one or more select features or
epics. This filter function was added in July 2016 and made available in Azure DevOps
Server 2017 and later versions.
The Parent field was added to Azure Boards in July of 2019 and then made available
with the release of Azure DevOps Server 2020. You can add the Parent field to a list
through the Column Options dialog, except for the Work items tool. You can also add
the Parent field to cards on the Kanban Boards and Taskboards.
Persistence and saving filter options

Once you set the filter options for a specific view, your settings persist until you change
them. There's no save button or other action you need to take.
７ Note
You can't set default filter options, nor set filter options for other members in your
team.
Prerequisites
All project members can exercise filter functions.
All filter functions are set only for the current user until the user clears them.
To filter using fields, first add the field as a column or to the card. For example, to
filter by Assign To, Iteration Path, or Work Item Type—or the contents of any
other field—add those fields to show on the cards, backlog, plan, or list.
To add columns or fields, see the following articles:
For Backlogs and Queries, see Change column options

For Boards, see Customize cards
For Taskboards, see Customize a sprint Taskboard
For Plans, see Review team delivery plans.
Open and clear filter functions
1. From the Azure Boards tool, choose the view you want. For example:
For Work items, choose the Assigned to me, Following, Mentioned, or other
view
For Backlogs and Boards, choose the backlog level you want, such as Stories,
Features, or Epics
For sprint Backlogs and Taskboards, choose the iteration
For queries, define the query filter criteria of interest.
2. Choose any other view settings available for your view. For example:
For Work items, from the View options menu, enable/disable Completed
Work Items
For Backlogs, from the View options menu, enable/disable In Progress items
or Completed Child items
For Taskboards, from the Person menu, choose All, Unassigned, or a specific
team member.
3. For list views, add columns to display fields containing text you want to filter on or
possibly sort on. For card views, add fields to display on cards containing text you
want to filter on.
4. Open the filter function.
Choose Filter . Or, enter the Ctrl+Shift+f keyboard shortcut.
For example, here we open the filter toolbar for the Kanban board, Backlog items.
5. Choose the filters of interest.
The filter icon changes to a solid icon, Filter , to indicate filtering is applied.
The page refreshes to show only those work items that meet all the selected filter
criteria.
Inactive functions
When filtering is applied, the following functions are disabled or altered.
For backlogs, the add-a-backlog-item panel, reordering (stack ranking), and

forecasting tools are disabled.
For backlogs set to Show Parents, the tree hierarchy is flattened, unless you enable
the Keep hierarchy with filters from the View Options menu. See [Filter your
backlog and maintain the hierarchy](#keep hierarchy) provided later in this article.
Clear or dismiss filtering

To clear and dismiss filtering, choose Clear and dismiss filtering .
Filters remain in place until you explicitly clear them. When you refresh your backlog,
board, or other tool, or sign in from another browser, filters remain set to your previous
values.
Once the board is filtered, you can choose the filter icon to hide the drop downs and
view the applied filters on the board. The filter icon turns opaque to signify a filtered
board.
Filter your backlog and maintain the hierarchy

You can filter your backlog and maintain the hierarchy of work by choosing show
Parents and Keep hierarchy with filters from the View Options menu. Use these options
when you want to show work items assigned to one or more team members, work item
types, area or iteration paths, or combination of these and keywords. The hierarchy is
maintained and work items that match the filter criteria are shown in bold text.
Filter logic and Boolean operators
Applying Boolean operators to filters is only supported for tags, as described in Filter
based on tags later in this article. All other filters are applied with an implicit AND
operator.
Apply keyword and ID filters

The keyword filter function filters lists or cards based on the fields displayed via Column
Options or board settings. Also, you can enter a value for an ID, even the ID field is
visible. As such, when filtering, consider what fields contain the keyword text or tags you
want to filter on and make sure it's displayed.
Filtering is case-insensitive.
Ignore characters by keyword filter criteria
The filter criteria ignores the following characters: , (comma), . (period), / (forward
slash), and \ (back slash).
Filter a board using a keyword

Here we filter the Kanban board to only show those cards that include 'web', either in
the title, tag, or field.
Filter a backlog by using a keyword

Here we filter the Backlog with Show Parents enabled, to only show work items that
include 'web'.
The filtered set is always a flat list, even if you've selected to show parents.
Filter based on a field

With filtering turned on, choose one or more values from the multi-select drop-down
menu for each field available to you. The values for these fields are populated as follows:
Area: The Node Name, which specifies the last node of an Area Path, of valid Area
Paths and for which there are work items assigned to that Area Path
Assigned To: All users who are currently assigned to work items on the board plus
Unassigned
Iteration: All Iteration Paths selected for the current team and for which there are
work items assigned to that iteration
Work item type: Work item types defined for the Requirements Category (product
backlog) or Features or Epic categories (feature or epic portfolio backlogs), subject
to work items being assigned to the work item types
Tags: All tags assigned to work items on the board
Parent Work Items: All features defined for the team, or all epics defined for the
team when viewing the Features board
７ Note
Filter options are dependent on the work items that meet the filter criteria. For
example, if you don't have any work items assigned to Sprint 4, then the Sprint 4
option won't appear in the filter options for the Iteration Path.
Filter a Kanban board by using select field values

You can filter by select field values using the Kanban board for your product backlog
(Stories, Product Backlog Items, or Requirements) or a portfolio backlog (Features or
Epics).
For example, here we filter for all items assigned to Jamal and Raisa.
Kanban board filter logic
Cards are filtered based on the assignments made in the following order and logic:
1. Assigned to: Show all cards that are assigned to user 1 OR user 2 AND
2. Iteration: Show all cards that are assigned to Iteration 1 OR Iteration 2 AND
3. Work Item type: Show all cards that are work item type 1 OR work item type 2 AND
4. Tags: Show all cards that have tag 1 AND or OR tags 2, based on your selection of
AND | OR . AND
5. Parent Work Items: Show all cards that have Parent Work Item 1 OR Parent Work
Item 2.
Filter a backlog by using fields

Here we show a filtered backlog based on the keyword "issues". Filtered pages show the
filtered icon. The filtered set is always a flat list, even if you've selected to show a
hierarchical backlog view.
Filter based on the Parent Work Item
You can use the Filter by parent feature to filter by select parent work items using the
Kanban board for your product backlog (Stories, Product Backlog Items, or
Requirements) or a portfolio backlog (Features).
You can use this feature only when you've created features or epics and linked them to
user stories or features, respectively. A quick and easy way to create the links is to map
them using drag-and-drop. Mapping creates parent-child links between the work items.
７ Note
The Filter by parent feature doesn't support filtering of parent work items of the
same work item type. For example, you can't filter the Stories backlog by specifying
user stories that are parents of nested user stories.
To start filtering, choose Filter . Choose one or more values from the multi-select
drop-down menu for the Parent Work Item. These values are derived from the Features
you've defined.
Here, we choose two features on which to filter the board.

The final board displays just those stories linked as child work items to the selected
features.
Filter based on tags

If you've added tags to your work items, you can filter your work using one or more
tags. For backlogs and query results, add Tags as a column option before filtering on
tags.
Check the boxes of those tags that you want to filter on. Keep the OR selection to do a
logical OR for all the tags you selected. Or, choose the AND option to do a logical AND
on all the selected tags.
To learn more about tags, see Add tags to work items to categorize and filter lists and
boards.
Filter the history view within a work item form

In addition to all the filter features described earlier in this article, you can also filter the
history view within a work item form.
To quickly find revisions made that contain a keyword, or made by specific people or to
a specific field, enable the filter feature by choosing Toggle filter.
For more information, see Query work item history and discussion fields.
Related articles
Set up your Backlogs and Boards
About backlogs
Change column options
Customize cards
Customize a sprint Taskboard
Tags
Query work items that you're following
Add, run, and update inline tests in
Azure Boards and Azure DevOps
Article • 02/24/2023
2018
Similar to task checklists, you can quickly define inline tests, or a set of manual tests
cases, for a backlog item from your Kanban board. Not only can you add tests, you can
run them and update their status. If you're new to working with the Kanban board, see
Kanban overview. If you're new to testing, see Exploratory and manual testing scenarios
and capabilities.
＂ How to add inline tests to a backlog item from your Kanban board
＂ How to run tests and update the status of tests
＂ How to expand or collapse inline tests
＂ How to reorder or reparent inline tests
Tests you create from the Kanban board are automatically linked to the user story or
backlog item.
Prerequisites
access or higher.
work tracking.
To view or run tests, you must have Basic access or higher. Users with Stakeholder
access can't view or run tests.

1. To view your Kanban board, open your project from a web browser and choose (1)
Work, (2) Boards, and then (3) select the team's board from the selector.
To choose another team's board, open the selector and select a different team or
choose the Browse all team boards option. Or, you can enter a keyword in the
 Tip
Choose the star icon to favorite a team board. Favorited artifacts (

Add inline tests

1. To start adding tests, open the menu for the work item.
Adding inline tests is the same as adding test cases to a test suite. A default test
plan and test suite are automatically created under which the manual test cases are
grouped.
For example, a test suite is created for each user story, and all inline tests are
added to that suite. Below, user story 152 is highlighted which has three manual
tests defined with IDs of 153, 155, and 161.
To learn more about test plans and test suites, see Plan your tests.
2. If you have many tests to add, keep entering each title and select Enter.
To add details to the test case, open it. You can select the title, double-click the
inline item, or open the context menu and choose Open.
See Create manual tests to learn more about defining tests.
Before running the test, you must add details.
Run the inline test

Run the test by selecting Run test from the actions menu for the inline test.
Microsoft Test Runner starts in a new browser instance. For details on running a test, see
Run manual tests.
Update the status of an inline test from the

action menu
You can update the status of the test from the actions menu.
Updating the
status of tests enable you to track test results.
Why doesn't the Kanban board show the status for test suites and plans already created
in Test?
Expand or collapse inline tests

Upon first opening the Kanban board, you'll see an unexpanded view of checklists.
Select the inline test summary to expand a collapsed set of tests. Select the same
summary to collapse an expanded list.
Copy or reparent a test

To reparent a test, drag and drop the test onto a different user story.
This action automatically changes the linked relationship of the test to point to the new
user story.
To create a copy of a test to add to a different user story, select the test, press the CTRL
key, and then drag and drop the test onto the card of the user story.
Related articles
Use inline tests for lightweight traceability and to manage manual tests for user stories
or other backlog items that they support. To learn more about test case management,
see Create manual tests.
If you find that you don't use this feature, you can disable it from the common
configurations dialog.
Other ways you can quickly add linked items and objects to user stories from the
Kanban board:
Add tasks or child items as checklists

Create a new branch, drive Git development
To start web-based exploratory testing for a user story, you need to install the Test &
Feedback Marketplace extension . For more information, see Install the Test &
Feedback extension.
Test status in the Kanban board

Test integration with the Kanban board makes it easy for teams to get started with
manual testing and then take advantage of the full testing capabilities in Test Manager
later, when required. When test cases are created from the Kanban board and updated
afterwards in Test Manager, or the other way around, when users create requirement-
based suites with Test Manager and update them in Test Manager, the Kanban board
shows the correct status. However, the Test status in Kanban board doesn't work if the
requirement-based suite has more than one configuration assigned to it. In such
scenario, the Kanban board only shows the test outcome for the default configuration.
As such, it's recommended to use Test Manager to manage/track the testing progress
across multiple configurations.
About configuring and customizing
Azure Boards
Article • 07/19/2023
2018
You can configure and customize Azure Boards in many ways, to better manage your
portfolio, dependencies, and monitoring. We recommend the tasks covered in this
article especially for administrators who are responsible for managing multi-team
projects.
Quick access to common tasks:
Customize cards | Manage columns | Expedite work with swimlanes | Configure your
backlog.
７ Note
Most of the guidance in this article is valid for both the cloud and on-premises
versions. However, some of the features included in this article, such as Rollup,
Analytics, and some portfolio planning tools, are only available for the cloud at this
time.
If you're just getting started as a Project Administrator, see also Get started as an
administrator.
Considerations
To make the most of Azure Boards, understand how your teams use their tools and
functions (for example, Scrum, Kanban, and Scrumban), and their dependencies on
configurations and customizations. The following table summarizes the primary items
you should consider as you structure your project.
Project level
How many teams you want to define
How to structure area paths to support portfolio management views
Field customizations
Custom work item types (WITs)
Portfolio backlog customizations
Workflow customizations
Team level
How you use your product backlog to plan and prioritize your work
Whether you track bugs as requirements or as tasks, or not use bugs at all
Whether or not you use tasks to track time and capacity
How you use portfolio backlog levels
How you inform upper management of progress, status, and risks
Customize your work tracking building blocks and tools to support business needs and
communicate the usage guidelines to your team.
Work item types and portfolio backlogs

When you create a project in Azure Boards, you first select a process. Each process
(Agile, Basic, Scrum, and CMMI) supports a hierarchy of WITs, including product and
portfolio backlogs. Default WITs for each process are listed in corresponding tabs, with
backlogs under Requirements and tasks under Task.
Agile process
You can add custom WITs at each level, and even add custom portfolio backlogs. Here,
for example, is a project that added Objectives and Key Results as custom WITs and
corresponding portfolio backlogs to the Scrum process.
Work tracking options and recommended

usage
Teams can choose which WITs they use to track their work. The following table
summarizes the main options, recommended usage, and supported tasks and tools.
Work tracking options
Tasks and tools supported
Tasks only
Not recommended
There's no way to quickly enter new tasks in a backlog nor prioritize a backlog of tasks.
Also, there's no support for calendar views, cross-team views, or portfolio planning
Requirements with child-dependent tasks
Supports Scrum methods

Recommended for teams that follow Scrum methods and want to track time associated
with work.
Quickly define and prioritize backlog items: Product backlog
Forecast sprints using team velocity: Forecast
Plan sprints: Backlog Planning tool
Plan and track capacity: Sprint capacity tool
Track estimated and remaining work: Taskboard
Monitor sprint burndown based on remaining work such as hours or days: Sprint
burndown
Conduct daily scrums, update and monitor task status: Sprint Taskboard
Estimate work: Define Story Points, Effort, or Size
View progress bars, counts, or sums of rollup on tasks: Rollup
Track dependencies across teams and projects: Delivery Plans
Many teams start out using Scrum methods to track and plan their work using the tools
available through the Sprints hub. The Sprints tools support estimating and tracking
remaining work and use of capacity planning. If you don't plan on using these tools,
then adding child-dependent tasks is optional. Developers might add them as a
checklist of items they need to complete a user story or backlog requirement.
Requirements only, such as user stories (Agile), issues (Basic), product backlog items
(Scrum), requirements (CMMI)
Supports Kanban and Scrumban methods

Recommended for teams that follow Kanban or Scrumban methods, estimate work
using Story Points, Effort, or Size, and don't track time associated with work.
Quickly define and prioritize backlog items: Product backlog
Plan sprints: Backlog Planning tool
Estimate work: Define Story Points, Effort, or Size
Forecast sprints using team velocity: Forecast
Monitor sprint burndown based on requirement estimates: Sprint burndown
Update requirement status: Kanban board
Requirements grouped under portfolio WITs, such as epics and features
Supports calendar views, cross-team views, and portfolio planning

Recommended for organizations with several teams that want to view rollups and
calendar views associated with multiple teams, and take advantage of all portfolio
planning tools.
Quickly define and prioritize portfolio items: Portfolio backlogs
Quickly define child user stories of portfolio items: Portfolio checklists
Map work items to features and epics: Mapping tool
View cross-team progress calendar view: Delivery plans
View calendar view of all team features: Feature Timeline
View calendar view of a specific epic: Epic Roadmap
View progress bars, counts, or sums of rollup on child items: Rollup
Options to configure and customize
The following table shows the areas you can configure and customize and the tools
impacted by those customizations. You can customize each area at the Organization,
Project, or Team level as noted, or a combination of two. For a description of the
Standard tools, Analytics tools, and Portfolio planning tools, see What is Azure Boards,
In-context reports: Work tracking, and Plans (Agile at scale).
Configure or customize
Standard tools
Analytics
Portfolio planning tools
Area paths, project configuration, and team subscriptions (Project, Team)

Boards>All tools
Backlogs>All tools
Sprints>All tools
Velocity
Burndown trend
Delivery plans
Feature timeline
Epic Roadmap
Portfolio plans (Beta)
Iteration paths, project configuration, and team subscription (Project, Team)

Backlogs>Sprint planning
Sprints>Sprint backlogs
Sprints>Sprint capacity
Sprints>Taskboard
Velocity
Burndown trend
Delivery plans
Feature timeline
Epic Roadmap
Portfolio plans (Beta)
Show bugs on backlogs & boards (Team)
Custom WITs, Product backlog (Process)
Custom WITs, Taskboard (Process)
Boards>Product board
Backlogs>Product backlog
Backlogs> Mapping tool
Sprints>Sprint backlogs
Sprints>Taskboard
Velocity
Custom WITs, Portfolio backlog (Process)

More portfolio backlogs (Process)
Boards>Portfolio boards
Backlogs>Portfolio backlogs
Backlogs> Mapping tool
Velocity
Custom workflow (Process)

Sprints>Taskboard
Custom field (Process)

Rollup progress bars, sum, or count
Area paths, product teams, and portfolio

management
Use area paths to group work items by product, feature, or business areas and to
support teams responsible for work assigned to those areas. You can define a
hierarchical set of area paths or a flat set. Typically, you define a hierarchical set of area
paths to support a business hierarchy that wants to track progress of several teams.
Area paths and hierarchical grouping

The two main ways to group work items are by area path and by parenting them under
a portfolio WIT as described early in this article. The two aren't mutually exclusive. Here
are their differences:
Area paths assigned to a team determine what work items appear in a team view:
product backlog, portfolio backlog, delivery plans, or other portfolio planning tool
Grouping work items under a parent feature or epic determine what rollup views
are supported and how work appears in a portfolio planning tool
You can also assign tags to work items to group them for query and filter purposes. So
when you structure your teams and projects, make sure you understand how you use
these grouping tools to support your business needs. Your choices impact the use of
portfolio planning tools.
Area path-dependent tools

To perform the following tasks, you must define area paths:
Query and chart work items based on Area Path

Assign work to more than one team
Work with management and feature teams
Filter a backlog, query, board, or plan using Area Paths
 Tip
You can define your area path structure and assign area paths to teams. Or, you can
add a team and create the area path with the team name at that time. If teams are
fully independent, create a flat set of area paths. However, if you want to create a
hierarchy of teams, then you'll want to create a tree-hierarchy of area paths. For
more information, see Configure a hierarchy of teams.
To use the following tools, teams must subscribe to area paths:
Boards> all tools

Backlogs> all tools
Sprints> all tools
Delivery plans
Rollup
Analytics> all
Area paths and team assignments

Each project has a default team and default area path. In some cases, there's only one
team to plan and track work. As organizations grow, however, you might add more
teams to manage the backlog and sprints.
The following example shows area paths and their assignments to teams, which support
portfolio management views for the Account Management and Service Delivery teams.
About area paths
Agile culture.
Recommendations:
Consider what upper management needs to know and how to best support them
Consider how you want to use rollup both for a team and portfolio management
Define epics and scenarios for large initiatives that take two or more sprints to
complete
Create hierarchical area paths to support sub categories of features and product
areas
Define requirements for work that can be accomplished in a single sprint and can
be assigned to a single individual
Define tasks to track more granular details or when you want to track time spent
working
 Tip
You can only assign a work item to a single individual. When you define work
items, consider how many work items you need and who to assign them to.
Choose the Node Name field as a column option to view the leaf area node in a
backlog list or board card. For more information, see Customize cards.
Don't create parent-child links among work items of the same type, such as
story-story, bug-bug, task-task.
Most Azure Boards tools support a filtered view of work items based on area path or
iteration path. You can also apply more filters based on keyword, assignment, WIT, and
more.
Bugs as requirements or tasks

Each team can choose how they want to manage bugs. Some teams like to track bugs
along with requirements on the backlog. Other teams like to track bugs as tasks
performed in support of a requirement. The bugs then appear on their Taskboard.
If you use the Scrum process, your default setup is to track bugs along with product
backlog items (PBIs). If you work in a project based on the Agile or CMMI processes,
bugs don't automatically appear on your backlog.
Determine with your team how you want to manage bugs. Then, change your team
settings accordingly.
 Tip
After you refresh a backlog or board and you don't see bugs where you expect
them, review How backlogs and boards display hierarchical (nested) items. Only
leaf nodes of nested items appear on sprint Taskboards.
System WITs on a backlog

To track issues or impediments along with your requirements or in a portfolio backlog,
add them to your custom Inherited process. For more information, see Customize your
backlogs or boards (Inheritance process).
Rollup, hierarchy, and portfolio management

Rollup columns allow you to view progress bars or totals of numeric fields or
descendant items within a hierarchy. Descendant items correspond to all child items
within the hierarchy. You can add one or more rollup columns to a product or portfolio
backlog.
Here we show Progress by all Work Items, which displays progress bars for ascendant
work items based on the percentage of descendant items that have been closed.
Delivery Plans supports rollup views of epics, features, and other custom portfolio
backlogs.
Iteration paths sprints releases & versioning

Iteration paths support Scrum and Scrumban processes where work is assigned to a set
time period. Iteration paths allow you to group work into sprints, milestones, or other
event-specific or time-related period. Each iteration or sprint corresponds to a regular
time interval referred to as a sprint cadence. Typical sprint cadences are two weeks,
three weeks, or a month long. For more information, see About area and iteration paths.
Iteration paths can be a flat list, or grouped under release milestones as shown in the
following image.
While Iteration Paths don't impact Kanban board tools, you can use Iteration Paths as a
filter on boards. For more information, see Filter your Kanban board.
Define iteration paths and assign them to teams when you want to use the following
tools:
Assign work items to sprints using the Planning pane

Query and chart work items based on Iteration Path
Sprints> all tools
Delivery Plans, a calendar view of team deliverables
Velocity chart and Sprint burndown chart
 Tip
If a team hasn't subscribed or selected an iteration path, that iteration path won't
appear in a team view or tool.
Time tracking
Most organizations following Scrum processes use time estimates for Sprint capacity
planning. Azure Boards tools fully support tracking time for this purpose. The main field
used is the task Remaining Work field, which typically zeros out at the end of the sprint.
However, some organizations require time tracking to support other purposes, such as
for billing or maintaining time allocation records. Time values for estimated work and
completed work are of interest. The Agile and CMMI processes provide these fields—
Original Estimate, Completed Work, Remaining Work—for use in tracking time. You can
use them for that purpose. However, Azure Boards provides limited native support for
time tracking. Instead, consider using a Marketplace extension to support your other
time tracking requirements.
７ Note
The Original Estimate , Completed Work , Remaining Work fields were designed to
support integration with Microsoft Project. Integration support with Microsoft
Project is deprecated for Azure DevOps Server 2019 and later versions, including
the cloud service.
Process changes that impact all teams

Any change made to a process that's applied to a project impacts all teams in that
project. Many changes don't cause much disruption to the teams they support, but the
following changes do.
Custom fields
Adding custom fields to a WIT doesn't impact any specific tool. The fields appear in the
corresponding work items. If you add a custom numeric field, but, you can use it to
support rollup on backlogs and the following reporting tools:
In-context Velocity report and dashboard widget

In-context Sprint Burndown report and dashboard widget
Dashboard Burndown and Burnup widget
７ Note
All default and custom fields are shared across all projects in a collection or
organization. There is a limit of 1024 fields that you can define for a process.
Custom WITs
The following table shows the effects when you add a custom WIT to a specific category.
Task
Requirement
Epic or feature
Child work items of the new WIT appear on the product backlog
Work items based on the new WIT appear on the sprint backlogs and Taskboards
Work items based on the new WIT appear on the product backlog and Kanban
board
Each team must configure the Kanban board to support the new WIT
Work items based on the new WIT appear on the corresponding portfolio backlogs
and Kanban boards
Each team must configure the Kanban boards to support the new WIT
The new WITs may not appear on one or more of the portfolio planning tools
Custom workflow
Each process supports a default workflow. This workflow defines the default columns
that appear on the Kanban boards and sprint Taskboards.
Agile process
Workflow states: User Story, Agile process

Sometimes, teams want to track the status of their work that goes beyond these default
states. Support is provided in one of the following ways:
Add custom workflow states to the WIT: This option impacts all teams and requires
that they update their Kanban board configuration.
Add columns to a Kanban board: This option only impacts the team that adds the
columns.
Both workflow states and Kanban columns appear in the Cumulative Flow diagram for a
team. Individuals can choose which columns appear in the chart. For more information,
see Cumulative flow diagram.
Who can make changes?

Since process-level, project-level, and team-level settings can have a wide impact,
changes are restricted to users with the following required permissions.
Process-level changes
To create, edit, or manage Inherited processes and apply them to projects, you must be
a member of the Project Collection Administrators group. Or, you must have the
corresponding permissions Create process, Delete process, Edit process, or Delete a
field from organization set to Allow. See Set permissions and access for work tracking,
Customize an inherited process.
About the inheritance process

Customize a project
Create and manage a process
Project-level changes
To add Area Paths or Iteration Paths, you must be a member of the Project
Or, to add, edit, and manage Area Paths or Iteration Paths under a specific node, you
must have been granted one or more of the following permissions set to Allow:
Create child nodes

Delete this node
Edit this node
View permissions in this node
Define area paths & assign to a team

Define iteration paths (sprints) & assign team iterations
Team-level changes
To configure team tools, you must be a team administrator or a member of the Project
Team administrators do the following operations:
Add team members

Subscribe to area and iteration paths
Configure backlogs and other common team settings
Configure Kanban boards
Manage team notifications
For more information on configuring backlogs and boards, see Manage and configure
team tools.
Next steps
Get started as an administrator
Related articles
Azure Boards Configuration and Customization FAQs
Inherited process model
Manage and configure team tools
Manage columns on your Kanban board
Article • 06/29/2023
2018
The Kanban board helps you visualize your team's workflow, including the types of work
and handoffs that occur regularly as your team progresses work items. Each column on
your Kanban board corresponds to work that your team does before that stage is
considered done.
７ Note
To manage columns on a sprint Taskboard, see Customize a Taskboard.

To manage columns on a backlog or in query results, see Change column
options.
Prerequisites
To configure team settings, you must be added to the Team Administrator role or
be a member of the Project Administrators security group. To get added, see Add
a team administrator or Change project-level permissions.
You must be assigned Basic access or higher to exercise all backlog and board
features. Users with Stakeholder access can only edit work items on the board and
add existing tags to a work item. Stakeholders can't add work items or update
fields displayed on cards. For more information, see About access levels.
Complete the following tasks, so you don't need to revisit your configuration.
Process Administrator
Add custom work item types that you want to appear on your backlog or
board. For more information, see Add and manage work item types.
Customize your product and portfolio backlogs. Customization ensures that
the chosen work item types appear on the backlogs and boards. For more
information, see Customize backlogs and boards.
Customize workflow states. Each workflow state appears as a column on the
Kanban board. For more information, see Customize a workflow.
We recommend that you review the following articles:
Kanban overview
Set up your backlogs and boards
Workflow states and state categories
Map workflow states

The Kanban board uses the Work item type and State categories to group work items
that you want handled in the same manner.
1. Identify your team's workflows. See the following table of example workflows and
their descriptions.
Workflow Description
Backlog Make a prioritized list of work items that the team isn't yet ready to work on
Analyze Identify well-understood and shared acceptance criteria, along with overall
work required to develop and test the item
Develop Code and run unit tests for the item
Test Run exploratory, automated, integration, and other tests
Done Hand off to production because the item is ready
2. Know your work item types and on which boards they appear.
Work item type category Work items appear here
Requirement Only on the product board
Feature Only on the Feature portfolio board
Epic Only on the Epic portfolio board
Custom Only on a custom portfolio board
 Tip
We recommend that you map each workflow state to a Kanban column, as if

it's not mapped, it doesn't appear on the Kanban board.
3. Specify the workflow State for each work item type and column, using one of the
following four categories.
State Description
category
Proposed The first Kanban board column is automatically mapped to the default state
for each work item
In Progress Work flow state must be specified for each WIT and column
Completed Can only map to the last Kanban board column
Removed Workflow state doesn't need to be specified
７ Note
When you add bugs or other work items to a Kanban board, it may create new
workflow states that require adjustments to column-to-state mappings in the
following situations:
When a team admin shows bugs on backlogs and boards

When a project admin adds work item types to backlogs and boards
When a project collection or project admin customizes the workflow for a
work item type in the Requirement category using inherited process or on-
premises XML process
Add and edit columns

Column titles and choices depend on the process that you used to create your project
and whether your team has chosen to treat bugs like requirements or like tasks.
Do the following steps to add and edit your columns.
1. Open your Kanban board.
2. Select Configure team settings to configure the board and set general team
settings.
3. Select Columns and then a column tab to see all the settings that you can modify.
Your initial column settings look similar to the settings shown in the following
image.
4. Change your column titles to map to your workflow stages. You can add, rename,
and move columns to support more stages.
Rename the first three columns to Backlog, Analyze, and Develop. Then, add a
column and label it Test.
You can rename a column directly from the Kanban board.
Or, you can open the dialog and change one or more settings for a Kanban
column.
5. To change the column order, drag the column tab to the position that you want.
6. To delete a column, first make sure that the column doesn't contain any work
items. If it does, move the items to another column. Then:
a. Open Settings, select Columns, and select Actions from the column tab.
b. Select Remove from the menu.
7. Change state mappings as needed for added columns, added workflow states, or
added WITs.
Usually, you need to update state mappings when you change the Working with
bugs setting, add WITs to the Requirement category, or customize the workflow.
8. When you're done with your changes, select Save.

Update status and handoff items
Drag-and-drop your work items to update the status. For example, to signal when work
can start in a downstream stage, drag items to the next column.
You can move an item from one column to any other column on the board, forward and
back. To hand off work to another team member, reassign it directly from the board.
Team members who receive the handoff can set alerts to get immediate email
notifications of their newly assigned work.
Change your team's priorities

Drag an item up or down within a column.
Track Kanban column status
Use the query tool to list a subset of work items for review, triage, update, or chart
generation. For example, you can create a query to list all active user stories (specify two
clauses: Work Item Type=User Story and State=Active ).
Specify WIP limits, split columns, and definition of done
Split columns
Because each column corresponds to a stage of work, you can quickly see the number
of items in progress at each stage. However, a lag often exists between when work gets
moved into a column and when work actually starts. To counter that lag and reveal the
actual state of work in progress, you can turn on split columns. When they're split, each
column contains two subcolumns, Doing and Done.
Split columns let your team implement a pull mechanism within the workflow process.
Without split columns, teams push work forward, to signal that they've completed their
stage of work. However, pushing it to the next stage doesn't necessarily mean that a
team member immediately starts work on that item.
With split columns, your team knows exactly how many items sit idle, waiting for work
to begin. You have greater visibility into the quantity of items that sit idle at each stage
throughout your workflow process.
Move items into the Doing and Done columns

With split columns turned on, you update status of items on the Kanban board in the
same way you have before. However, now when you've completed work on an item, you
move it into Done, instead of a downstream column. When the next team member
becomes free to work on the next high priority item, they pull it into Doing and reassign
it to themselves.
For example, as a team member completes their coding task, they move the item into
Done under the Develop column. When the tester is ready to test the item, they pull it
into Doing under the Test column.
Identify bottlenecks
Split columns provide you even greater insight into how many items sit idle in a Done
column. Your team can readily see when items pile up, which signal a potential
bottleneck.
By reviewing the frequency of pile ups and where they occur, your team can adjust their
processes to eliminate the bottlenecks. Workflow processes that incur no or few
bottlenecks correspond to perfect flows. No item sits in a queue for any
Choose which columns you want to split

Before you split columns, ensure you mapped each stage of your team's process to a
Kanban column. Only split columns where clear hand-offs exist and you want teams to
pull the item into the next stage.
1. Open your Kanban board and choose the gear icon to configure the board and
set general team settings.
2. Choose Columns and then choose the column tab that you want to split. Add a
check mark in the checkbox to cause the column to split.
７ Note
There are different column titles and choices based on the process used to
create your project and whether your team chose to treat bugs like
requirements or like tasks.
3. When you're done, choose Save.
 Tip
You can filter queries and create charts using the Board Column Done field.
List work items in a Doing or Done column

You can query for work items in a split column using the Board Column Done field. This
field takes of a value of False when in the Doing column and True when in the Done
column.
For examples on querying Board columns, see Query by assignment or workflow

changes.
Add the Definition of Done to a column

When your team advances from one stage to the next in their work, it's crucial that they
have a shared understanding of what constitutes as "done." You can define the criteria
for the Definition of Done in each Kanban column. By doing so, the team can identify
the necessary tasks that need to be completed before advancing an item to the next
stage. This task also implements one of the core Kanban tenets, make processes and
policies explicit.
Team members can quickly double-check the criteria by choosing the Information
tooltip info icon.
2. Choose the gear icon to configure the board and set general team settings.
3. Choose Columns and then a column tab to configure the Definition of Done for
that column.
Do more tasks
In the following table, we've listed tasks and their associated articles, so you can do
more with your Kanban board.
Article Task
Interactively filter backlogs, Filter your board to focus on select work based on assignment to
boards, queries, and plans a team member or sprint, tags, or parent feature.
Update status Update workflow status through drag-and-drop operations.
Change priorities Reorder cards to change priority of work items.
Customize cards View and quickly assign values to key field.

Article Task
Track board column status Create queries and charts based on board columns.
View and configure a Review a cumulative flow diagram based on column assignments.
cumulative flow diagram
Related articles
Accelerate work with swimlanes
Show bugs on backlogs and boards
Enable live updates
Azure Boards FAQs
REST API Boards reference
Customize cards on a Kanban board
Article • 06/06/2023
2018
The Kanban board presents work items in the form of cards, where each card represents
a work item that facilitates information sharing, progress tracking, and task assignment.
These cards provide quick insights for you and your team. You can update a field on a
card without having to open the corresponding work item. You can also apply style rules
to highlight specific cards and tasks based on your set criteria.
If you're new to working with the Kanban board, see Kanban overview.
７ Note
This article addresses customization of a Kanban board. For information on

customizing a Taskboard, see Customize sprint Taskboards.
Prerequisites
See the section, Card customization sequence
Card customization options

You can show fields on cards based on what your team frequently refers to or updates
when using the Kanban board. You can also add fields with information that you can use
to filter the board.
７ Note
You can customize a work item type which is different than customizing the card
displayed on the Kanban board. You customize a work item type by adding fields,
changing the workflow, adding custom rules and more. You can also add custom
work item types and custom backlog levels. For more information, see Customize
an inheritance process.
Within the Settings dialog for the Kanban board, you have the following customization
options.
Setting Customization action
Fields Add or remove fields from cards. Includes adding the Parent field to cards.
Styles Add styling rules to change card color and title style based on field criteria.
Tag colors Specify a tag color and enable or disable a tag color.
Annotations Enable or disable annotations to appear on cards.
Tests Configure how you want tests to appear and behave on the cards.
Card reordering Choose expected behavior when reordering cards on the board.
７ Note
Each team can customize the cards for their Kanban board. Board settings are not
inherited from other teams that they may share portions of area paths.
Card customization sequence

Before you configure the cards, make sure the following tasks are complete, or you
might need to revisit your configuration.
Process Administrator:
1. Add custom work item types that you want to appear on your backlog or board.
For more information, see Add and manage work item types.
2. Customize your product and portfolio backlogs to ensure all the work item types
you want to have appear on the backlogs and boards. For details see Customize
backlogs & boards.
3. Customize each work item type to have any custom fields you want to show. For
more information, see Customize a workflow.
Team Administrator:
1. Meet with your team and determine how the team wants to manage bugs, similar
to requirements or tasks.
2. Add any tags you want to customize on cards to work items.
3. Meet with your team and determine which annotations should appear on cards
and how they want to configure inline tests.
Open your Kanban board settings

If you're not a team admin, get added as one. Only team and project admins can
customize the Kanban board.
You can customize cards that appear on the Kanban board for your product backlog or
portfolio backlog such as features and epics. You follow similar steps, however you start
from the corresponding portfolio backlog.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ).
3. Choose the backlog level that you want to customize.
4. Choose the gear icon to configure the board and set general team settings.
Choose which fields appear on cards

You can edit a card field from the Kanban board, except for read-only fields like the
Change By and Changed Date. This quick update feature is useful when you need to
update many work items at once.
Do the following steps to update fields. To add a custom field, you must first add it to
the process used to customize the project.
1. From the board settings page, choose Fields and then choose a work item type to
see all the settings that you can modify. Your initial column settings appear similar
to the following image.
Your choices vary based on the process used to create your project and whether
your team has chosen to treat bugs like requirements or like tasks.
2. Add check mark in the box next to the fields that you want to appear on the board.
If you want work estimates to show, check Show Effort, which corresponds to the
following fields: Effort (Scrum), Story Points (Agile), and Size (CMMI).
3. To add a field, select the plus icon and enter the name of a field you want to
add.
4. To remove a field, select the delete icon next to the field.
5. When you're done, select Save.
７ Note
To show the Title of the parent work item, choose the Parent field. Choosing the
Parent title from a card opens the parent work item. To change the parent work
item, open the child work item and remove the link and add a different parent work
item. You can filter your board based on parent work items, whether the Parent
field is added to cards or not.
Define style rules to highlight cards

With styling rules, you can cause cards to change color when their corresponding work
items meet criteria that you set. Here, we highlight severity 1 bugs by having the cards
display as yellow.
Examples of styling rules

Which rules should you apply to highlight work items? Here are a few examples and
their associated criteria.
Work items Criteria
High priority items Priority = 1
High effort items Effort 20 or Story Points 20
Stale items unchanged in the last 5 days Changed Date @Today-5
Title contains a key word Title Contains Yes
Severity 1 bugs Severity = 1 - Critical AND Work Item Type = Bug
High value business items Business Value 50
Items assigned to specific feature area Area Path Under Fabrikam Fiber\Phone
Contains specific tag Tags Contain RTM

Work items Criteria
Blocked tasks (Scrum process only) Blocked = Yes
You can apply style rules to change the color of cards on Kanban boards and
Taskboards.
1. From the board settings page, select Styles to specify a style rule.
2. Select + Add styling rule. Select the color to apply to the card and define the
criteria for the style rule.
In the following example, we show the Styles page for the Dashboard.
 Tip
Note the following information about style rules:
The criteria you specify works in a similar fashion as when constructing a query.
All clauses are considered AND clauses, grouping clauses isn't supported.
Card rules apply to all work items that meet the rule criteria.
Rule color applies to work items based on the order in which rules are listed. If you
add more than one style rule, make sure that you move them in the order of most
importance. Drag them into the order you want them applied.
You can quickly enable and disable a style rule.
In the following example, we add a Stale tasks rule, which highlights tasks that haven't
changed in the last five days.
3. To copy or delete a style rule, choose the actions icon and select Clone or
Delete.
Assign tag colors

Before you set tag colors, add tags to backlog items that you want to highlight with
color.
1. From the Settings dialog, select Tag colors, and then + Add tag color. Then, select
the tag and the color you want to appear on the cards.
 Tip
If tags don't display on the cards, select Fields and make sure that you've
checked Show Tags.
Enable or disable annotations

All applicable annotations for the selected board are enabled by default. These
annotations include all work item types added to the next level backlog, GitHub, and
Tests. Disable any unused annotations or ones that you want to restrict for a specific
backlog level.
When you disable an annotation, you also disable the feature to add the associated
object from the Kanban board. For example, if you disable the Tests annotation, you
disable the ability to add tests from the currently selected Kanban board.
Complete the following steps to manage annotations.
1. From your board settings page, select Annotations .

2. Check those annotations that you want enabled. For example, to enable tasks but
disable tests, check the following boxes.
７ Note
GitHub annotations requires Azure DevOps Server 2019 Update 1 or later

version. For more information, see Link GitHub commits, pull requests, and
issues to work items.
As shown in the following examples, the Task and Test annotations indicate that two
each of tasks and tests are defined for the work item.
Task annotations Test annotations No annotations

Task annotations Test annotations No annotations
For more information, see Add tasks or child items as checklists and Add, run, and
update inline tests.
Configure inline tests

You can control the test plan where you create inline tests through the Kanban board.
Choose to create a new test plan for each new test that you add or add all new tests to a
selected test plan.
1. From the board settings page (product backlog only), choose Annotations. Make
sure that Test annotation is enabled, a requirement to configure inline tests.
2. Select Tests, and then choose the options you want. Choose an existing test plan
from the actions icon results.
 Tip
In a test plan, a test case can exist in multiple test suites. For example, you
may define several test suites for each product feature and the test cases test
scenarios across features. The test case might exist in both feature's test suite
with the same configurations and test steps. Because of this setup, the tester
might run the same test case multiple times for the same product version. To
avoid the redundancies that can occur under this scenario, you should choose
Show same outcome of the tests in multiple suites under the same plan
checkbox. When checked, the Test Points of the same Test Case and
configuration, shows the same latest outcome. When the tester runs any one
test, the output is synced with all other test points (which are of the same Test
Case work item and same configuration) in the Test Plans. The tester can use
the outcome and choose not to run the test again.
3. Select Save.
Open the test plan, test suite from a card

From a card on the Kanban board, you can go to the underlying test plan and test suite
under which the tests are created. Choose the open icon to open another browser
tab showing Test and associated test plan and test suite that controls the inline tests.
Reorder cards
You can drag any work item to any column or swimlane on the Kanban board. You can
even change the order of items as you move a card to a new column.
In addition to the dynamic card reordering, you can also move a card to a specific
column position.
７ Note
The last column, typically the Closed or Done column, is always ordered by Closed
Date with the most recently closed items appearing towards the top of the column.
In all other columns, cards are ordered by the backlog order or they're reordered
based on the Card reordering setting selected.

You can reorder the work items within a Kanban board column by choosing …Work
items action menu, selecting Move to position, and then specifying a value in the
dialog.
７ Note
The Move to column position feature requires you to enable the New Boards Hub
preview feature. To enable this feature, see Manage or enable features.
Specify a value within the range listed, which corresponds to the number of items
currently in the column.
Set the team preference for reordering cards

If you want to preserve the backlog priority when you move a card to a new column,
you can change the Kanban board card reordering setting for your team.
1. Open your Kanban board. If you're not a team admin, get added as one. Only team
and project admins can customize the Kanban board.
2. Select the gear icon to configure the board and set general team settings.
3. Select Card reordering and select from the two reordering behaviors listed.
The setting you choose applies to all active Kanban boards for your team.
Related articles
Setup your backlogs and boards
Configure status badges
Select backlog navigation levels for your team
Set working days
Set up swimlanes
Set Work in Progress limits
Article • 07/03/2023
2018
An essential Kanban practice—Work in Progress limits, referred to as "WIP limits"—

constrains the amount of work your team undertakes at each work stage. It's designed
to focus your team on completing items before starting new work. While counter-
intuitive at first, many teams find WIP limits helps them increase their productivity and
improve their software quality.
You define WIP limits for each work stage, corresponding to each intermediate column.
The limit sets a soft constraint on the number of items allowed within the column.
Nothing prevents you from moving more items into the column and exceeding the limit.
Your Kanban board shows the count of items at each stage next to each limit.
Setting WIP limits is simple, but adhering to the limits takes a team commitment.
Successful adoption of WIP limits involves a culture change. It moves teams from a focus
on individual productivity to one of team productivity.
For more information, see Kanban overview.
Prerequisites
Determine initial WIP limits

Have your team determine the initial WIP limits to set and how to use and monitor
them. Few rules apply to what numbers to set as they can vary based on several factors.
Take the following actions to help you determine what limits to set:
Set limits based on current works in progress. Count the items present in your
existing Kanban columns.
Set limits that don't exceed two or three items per team member that works within
a stage. For example, if you have three team members and each team member can
work on no more than two tasks at a time, the resulting WIP limit is 6 (= 3
developers X 2 tasks/developer).
Start with low limits to help your team discover bottlenecks more quickly and
identify process issues to address.
Keep within WIP limits

After you've set your WIP limits, you'll want to track how well your team keeps within
the limits.
Respecting WIP limits means teams don't pull items into a column if doing so causes the
number of items in the column to exceed the column limit. When they do, your Kanban
board provides immediate feedback. This feedback should act as a signal to the team to
focus immediately on activities to reduce the number of items in the column.
Although simple in theory, keeping within WIP limits can force individuals, teams, and
organizations out of their comfort zone. Team members who like to multitask might feel
constrained. Others might find themselves without work as they wait for work to
complete at an upstream stage.
To gain the advantages of constraining work-in-progress, have your team meet

frequently to discuss the process changes taking place.
Identify bottlenecks
To optimize the flow of value, you naturally want to identify and eliminate bottlenecks.
Bottlenecks indicate waste exists in the overall workflow process.
By monitoring your Kanban board over time, you can learn where bottlenecks occur.
When several items sit in a column unworked for several days, a bottleneck has
occurred. Bottlenecks typically occur when WIP limits are too high. However, no
bottlenecks could indicate that WIP limits are too low.
Taking periodic snapshots of your Kanban board can visually catalog where work flows
smoothly and where bottlenecks appear.
Such snapshots can show your team the following information:
How many items on average exist within a workflow stage/column

How many items are being worked versus team members who work within a
workflow stage/column
How many and which items remained in a workflow stage/column for long periods
of time
How many items did the team complete at the end of a one, two, or three week
period
Eliminate waste
Because bottlenecks signal waste in your workflow process, you need to identify the
source of the waste. Kanban defines waste as anything not strictly needed to produce
desired outcomes.
Common wastes in software development include:

Unused code or features
Defects leading to rework
Delays or time spent waiting for something
Handoffs from one person, team, or business process to another
Insufficient requirements
Slow or poor communication
Eliminating waste calls for team discussions to identify causes and solutions acceptable
to the team.
Set WIP limits

With an understanding of how you want to use WIP limits, do the following steps to set
them. If you haven't mapped your team's work flow to Kanban columns, do that first.
3. Choose Columns and then a column tab to set the WIP limit for that column.
７ Note
Different column titles and choices are available based on the process that
was used to create your project and whether your team has chosen to treat
bugs like requirements or like tasks.
WIP limits, challenges, and solutions

Teams occasionally exceed WIP limits by one or two items. However, if your team
frequently exceeds the limits by three or more items, they should review processes or
adjust the limits.
After a team has worked with WIP limits for several weeks, discuss the challenges team
members have. Then, decide which solutions they'd like to use and adjust the limits as
needed. The following list, although not exhaustive, indicates some of the common
challenges teams come across and proven solutions to overcome them.
WIP challenges
Social dynamics. When it comes to following rules, team members can feel
challenged. Some naturally want to rebel. Others don't see that the rule applies to
them or don't see what they do as breaking the rules. Some team members may
take on extra work that's outside the scope of what's been agreed to. And, still
others don't want to give up multitasking as they believe it's the key to their
productivity and individual achievement.
Variability of work in progress. Wide variability in the size of work items—users

stories and bugs—can negatively influence the overall workflow. For example,
items with estimates that vary in size from 4 hours to 14 days, or 2 to 55 story
points, can't be counted the same when it comes to constraining work in progress.
Ignoring systemic problems. Instead of addressing workflow problems when

bottlenecks occur, teams soldier on, putting in more time to overcome the
bottleneck.
Culture change. Adopting WIP limits introduces changes to the system, culture,
and team.
Solutions for managing WIP

Build a culture of team productivity. Address the natural tension that exists
between individual productivity versus team productivity. Identify ways in which
team members can enhance the overall productivity of the team and workflow
process.
Size work to minimize variability. Before work starts on any item, the team should
discuss the overall size of work required and determine if it can be broken down
into smaller tasks.
Focus on the flow of high priority items. When idle, team members ask how they
can help move an upstream item forward. When blocked or challenged to deliver
an item on time, team members ask for help with completing an item.
Resource team capacity for each work stage. Bottlenecks can occur when there
aren't enough specialists who work in a particular stage. Determine ways to either
increase team skills within each work stage, or add resources as needed to meet an
understaffed work stage.
Build shared understanding. Continuously strive to increase the team's

understanding of how to work using Kanban practices. Take actions that allow
team members to contribute to process changes. Consider scheduling regular
retrospectives or team meetings to discuss what works well and what needs
changing. Document team policies to limit ambiguity.
Use metrics to adjust processes. Periodically check Kanban metrics of work in

progress and lead time to determine when changes need to be made.
Manage culture changes mindfully. People want to do their best work—a core
tenet underlying Kanban and its associated disciplines. Apply change management
principles as you adopt new practices. Create greater ownership within the team
for the success of implementing WIP limits.
Related articles
Split columns
Speed up work
Add the Definition of Done to a column
Customize cards
Expedite work using swimlanes
Article • 05/12/2023
2018
Your Kanban board helps you visualize the flow of work as it moves from defined to
completed. When you add swimlanes, you can also visualize the status of work that
supports different service-level classes. You can create a swimlane to represent any
other dimension that supports your tracking needs.
Prerequisites
Types of swimlanes
You can use up to 50 swimlanes to sort work on your Kanban board to track items that
you differentiate as follows:
High priority items

Service-level class
Date-driven requirement
Dependency for or from another team
Blocked items
Technical debt or other engineering work that's not a specific user story
Track work in swimlanes

Once you've set up your swimlanes, you can drag items into a swimlane, and also
reorder them within the lane.
 Tip
Enter o to expand all swimlanes and u to collapse all swimlanes. To move the
focus up or down, enter the ↑↓ up/down arrows. For more information, see
Keyboard shortcuts.
When you have many swimlanes or cards on your board, you may encounter
slow performance when dragging a card. We recommend that you use
swimlanes in conjunction with card styles, tags, and board filters to manage
your work items. If you have a lot of cards in the default lane, place that lane
lower on the board to enhance performance when dragging a card to another
swimlane.
７ Note
The default lane appears unlabeled on the Kanban board. You can rename it to
anything you like, but, you can't delete it or apply rules.
You can also focus on a single swimlane by collapsing all other lanes.
） Important
Add or remove a swimlane

Which swimlanes support your tracking needs? Once you've identified one or two, add
them to your Kanban board.
and project administrators can customize the Kanban board.
2. Choose Configure board settings to configure the board.
3. Choose Swimlanes, choose Add swimlane, and then enter the name of the
swimlane you want to add. For example, here we enter Expedite. You can optionally
select the more actions icon to insert a new swimlane above or below another
swimlane.
７ Note
The following images show the user interface that displays when the New
Boards Hub preview feature is enabled. Some features are only available
when the New Boards Hub is enabled as described in Key concepts and work
item tasks in Azure Boards. For example, the ability to choose the swimlane
color is only supported when the New Boards Hub feature is enabled. To
enable it, see Manage or enable features.
4. To set the color of the swimlane, choose a color from the drop-down menu. To
reset the swimlane to the default, choose Reset to default color.
5. To reorder a swimlane, choose the up or down menu selector to move it up or
down. To remove a swimlane, choose the trash bin icon, but first move all items
out of the lane.
6. When you're done with your changes, choose Save.
Set up swimlane rules

Swimlane rules are similar to style rules, but instead they allow you to set up conditions
on your Kanban board to automatically move work items into specific lanes. For
example, you can set up a lane for each person on your team. When you assign the
work item, it gets placed into that lane.
Swimlane rules get executed in order, so once the rule is met, it executes and moves on
to the next work item. For example, Lane 1 has a rule that says "where priority = 1" and
Lane 2 has a rule that says "where priority = 2". If the work item is set to priority = 1, it
gets moved into Lane 1.
The following limits apply to swimlanes:
Up to five rules per lane

Max of 25 rules total
Only AND rules are supported
Complete the following steps to set up swimlane rules for your Kanban board.
1. From your Kanban board, choose the gear icon to Configure board settings.
2. Select Swimlanes, select the swimlane or + Add swimlane, and then select + Add
criteria.
3. Choose from the dropdown menus for each of the following entries: Field,
Operator, and Value, and then choose Save. For more information, see the
examples in the next section.
 Tip
You can't assign rules to the Default lane, but you can optionally rename it.
When your board refreshes, your work items are listed within the appropriate swimlane.
Examples of swimlane rules

The following examples show some of the ways you can use and set up swimlane rules.
Track priority. We created rules for the Work Item Type and Priority fields, so
work items automatically go into the appropriate swimlane.
Settings
Kanban board results

Track the parents of your work items. We created rules for the Work item type
field, so you can quickly see parents (features) and children (user stories and bugs)
in their own swimlanes on the Kanban board.
Settings

Track each person's work on your team. We created rules for the Assigned to
field, so that when you assign a work item, it's placed into that user's lane.
Settings

Query for work items based on swimlane
You can track which work items have been added to a Kanban board swimlane by
creating a query and using the Board Lane field.
Next steps
Customize cards
Related articles
Query by assignment or workflow changes
Add columns
Split columns
REST API resources

To programmatically interact with the Kanban board and other team settings, see the
REST API, Boards reference.
Article • 03/03/2023
2018
As your team identifies code defects or bugs, they can add them to the backlog and
track them similar to tracking requirements. Or, they can schedule bugs to be fixed
within a sprint along with other tasks.
When you track bugs as requirements, they appear on the product Backlogs and Kanban
boards. When you track bugs as tasks, the bugs appear on Sprint Backlogs and
Taskboards. For more information about other work item types, see Add other work item
types to backlogs or boards.
You can define your team's tracking setting for the Agile, Scrum, and CMMI processes.
The Bug work item type isn't defined for the Basic process, so there isn't a team setting
for Basic. Instead, you should track bugs and code defects using the Issue work item
type.
７ Note

Prerequisites
To configure team settings, you must be added to the Team Administrator role or be a
member of the Project Administrators security group. To get added, see Add a team
administrator or Change project-level permissions.
Choose from options for bug tracking

The following table summarizes the options teams have for tracking bugs. Before you
make your choice, we recommend you review the information provided in Define,
capture, triage, and manage bugs, which provides an overview of the Bug work item
type and supported tools for managing bugs.
Option
Choose when you want to...
Track bugs as Requirements

Prioritize (stack rank) bugs along with requirements
Estimate Bug effort for forecasting
Update bug status on Kanban board
Include Bugs in Velocity charts and Cumulative Flow Diagrams
Can use the Forecast tool to support sprint planning
Can drag and drop bugs onto Planning pane to assign bugs to a sprint
Can view Bugs on Delivery Plans
７ Note
Bugs are assigned to the Requirements Category
Track bugs as Tasks

Estimate work for bugs similar to tasks
Update bug status on sprint Taskboards
Link bugs to requirements as child items
７ Note
Bugs are assigned to the Task Category
User Stories (Agile), Product Backlog Items (Scrum), or Requirements (CMMI)
are the natural parent work item type for Bugs
Bugs won't be visible on Delivery Plans
Bugs don't appear on backlogs or boards

Manage bugs using queries
７ Note
Bugs are associated with the Bugs Category and won't appear on either
backlogs or boards
Bugs won't be visible on Backlogs, Boards, Sprint Backlogs, Taskboards, or
Delivery Plans
Can't drag and drop bugs onto Planning pane to assign bugs to a sprint
Set your team's preference for bug tracking

You can change settings from a backlog or board view, or from Project settings > Team
configuration.
In the following steps, we show how to change it from the board view.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ) and

select your project.
3. Choose Board settings to configure the board and set general team settings.
4. Choose Working with bugs and then choose the option that best meets your
team's way of working.
6. To see the changes, open or refresh the team's backlog or Kanban board.
Nest items
When you manage bugs with requirements or tasks, they appear on one or more of
your Agile tool backlogs and boards. However, if you nest items—create parent-child
links of items that belong in either the Requirements or Task categories—not all items
may appear on your backlogs and boards. To learn more about how nested items are
treated, see How backlogs and boards display hierarchical (nested) items.
 Tip
If, after refreshing a backlog or board, you don't see bugs where you expect to see
leaf nodes of nested items appear on the Kanban or task boards.
Add other work item types to your backlogs or

boards
Bugs are a common item that teams want to track, and choose how they track them. For
more information, see Manage bugs.
However, what if you want to track other work item types on your backlogs and boards?
You can add other work item types—such as change requests, issues, or impediments—
by customizing your process or project, based on the process model you use. For
details,
For the Inheritance process model, see Customize your backlogs or boards for a
process.
For Hosted XML and On-premises XML process models, see Add a work item type
to a backlog and board.
For an overview of process models, see Customize your work tracking experience.
Create, list, and manage bugs

Bugs that are managed with requirements can be added through the product backlog
or Kanban board. When bugs are managed along with tasks, you can add them to a
sprint backlog or task board. Or, capture them using other tools. For more information,
see Define, triage, and manage bugs.
 Tip
Effort should automatically be part of a bug, but if you don't see it, customize the
bug work item type for it to appear.
You can review bugs defined for your project by creating a query and specifying the
Work Item Type=Bug. Or, open a predefined query, Active Bugs (Agile and CMMI), or
Work in Progress (Scrum).
Related articles
Define, capture, triage, and manage bugs
Enable backlog levels of interest to your team
Triage work items
View and configure a Cumulative Flow
Diagram
Article • 02/24/2023
2018
You use cumulative flow diagrams (CFD) to monitor the flow of work through a system.
There are two CFD charts: the in-context report you can view from a team backlog or
Kanban board and the CFD widget you can add to a dashboard.
CFDs help teams monitor the count of work items as they progressively move through
various workflow states. These diagrams can show the flow of epics, features, user
stories, issues, product backlog items, or requirements, depending on the process
selected for your project:
Agile
Basic
Scrum
Capability Maturity Model Integration (CMMI)
Use this article to learn how to:
＂ Configure the Cumulative Flow Diagram widget (Analytics)

＂ View and configure the CFD in-context report (Analytics)
The CFD shows the count of items in each Kanban column for the selected time period.
From this chart, you can gain an idea of the amount of work in progress and lead time.
Work in progress counts unfinished requirements. Lead time indicates the amount of
time it takes to complete a requirement once work has started.
７ Note
The in-context report always uses the blue-green color theme. However, the
Analytics-based Cumulative flow diagram widget provides support for choosing
different color themes.
For the CFD to provide useful information, you'll want to update the status of work
items to reflect progress as it occurs. You can quickly make these updates through your
Kanban board.
For usage guidance, see Cumulative flow, lead time, and cycle time guidance.
Prerequisites
You must be a member of a project. Get added to a project or create one.
To add a widget to a team dashboard, you need to be a member of the team. You
must have Basic access or greater, have dashboard permissions, or be a team
admin or project admin.
Boards must be enabled. If disabled, none of the work tracking Analytics widgets
display. To re-enable it, see Turn an Azure DevOps service on or off.
Open your backlog from the web portal
1. Check that you selected the right project, and select Boards > Backlogs. Then
select the correct team from the team selector menu.
To select another backlog, open the selector and then select a different team or
select the View Backlog directory option. Or, enter a keyword in the search box to
filter the list of team backlogs for the project.
2. To view the in-context reports for the product backlog, check that you selected
Stories for Agile, Issues for Basic, Backlog items for Scrum, or Requirements for
CMMI as the backlog level. Or
View the CFD in-context report

CFD reports are available for each backlog level, both product and portfolio backlogs.
Each report provides interactive controls to provide each user the view of interest to
them.
1. You open the CFD for your product or portfolio backlog by choosing Analytics.
The Average work in progress value excludes completed work items.
2. To select a portfolio backlog, select it from the backlog selector menu.

3. Next, select View full report for the Cumulative Flow Diagram.
4. Use the interactive controls to select the time frame, swimlanes, and workflow
states or Kanban board columns. You can select a rolling period of 14 days or up to
180 days.
Hover over a point in time to show how many work items are in a particular state.
The default setting for the Cumulative Flow Diagram-Average work in progress
includes completed work items since the team started tracking work.
For example, On July 3, 101 items were in a Research state.

The selections you make are only set for you, and persist across sessions until you
change them.
5. To add the report to a dashboard, select the actions icon and select Copy to
Dashboard.
Select the dashboard and select OK.
6. To return to the Analytics summary, select the back arrow.
Add the Cumulative Flow Diagram widget to

your dashboard
1. If you haven't yet configured your Kanban board, do that now. Define the columns
and swimlanes that support your workflow processes.
2. If you want fixed scope CFD charts, make sure that you've defined the sprint
iterations for those sprints of interest.
3. To add a CFD chart to your team dashboard, see Add a widget to a dashboard.
Add the Cumulative Flow Diagram widget.
4. Select the actions icon and select the Configure option to open the
configuration dialog. Modify the title, and then select the values you want to
monitor:
Team
Backlog level
Swimlanes
Time period
Configure the CFD widget
1. For a continuous flow diagram, select Rolling period and specify the number of
days you want to view on the chart.
Or, for a fixed scope view, select and specify the Start date. Select this view if your
team employs a Scrumban process or follows a standard sprint process.
The main difference between these two types of CFD charts is that the fixed scope
CFD will provide information (in most cases) of scope change.
2. Select the color. You can distinguish the CFD for different teams by choosing
different colors.
3. Select Save when done. The following image shows an example CFD chart showing
30 days of data.
Next steps
Related articles
Add columns
Add swimlanes
Widget catalog
Marketplace widgets
Lead Time and Cycle Time widgets
Article • 02/24/2023
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Both lead time and cycle time widgets are useful to teams. They both indicate how long
it takes for work to flow through their development pipeline. Lead time measures the
total time elapsed from the creation of work items to their completion. Cycle time
measures the time it takes for your team to complete work items once they begin
actively working on them.
The following diagram illustrates how lead time differs from cycle time. Lead time is
calculated from work item creation to entering a completed state. Cycle time is
calculated from first entering an In Progress or Resolved state category to entering a
Completed state category. To understand how workflow states map to state categories,
see How workflow states and state categories are used in Backlogs and Boards.
These measures help teams plan, spot variations in efficiency, and identify potential
process issues. The lower the lead and cycle times, the faster the throughput your team
has.
In this article you'll learn:
＂ How to install and configure the Lead Time and Cycle Time widgets (Analytics)
＂ How to interpret the scatter-plot control charts
＂ How moving average and standard deviation are calculated in the charts
To learn more, see Cumulative flow, lead time, and cycle time guidance.
Prerequisites
Add the widget to your dashboard

1. (Optional) If you haven't yet configured your team's Kanban board, do that now.
Define the columns and swimlanes that support your workflow processes.
2. If you haven't yet added the widget to your dashboard, do that now. There are two
widgets: Cycle Time and Lead Time. Select the one you want to display and
configure.
Configure the Cycle Time and Lead Time

widgets
The Configuration dialog is the same for the Cycle Time and Lead Time widgets. You
configure these widgets for a team. To learn more about teams, see Add teams.
1. Select the context menu icon and select Configure to open the configuration
dialog. Modify the title, and then select the values you want to monitor:
Team
Backlog level
Swimlane
Field criteria
Time period
To select a Swimlane, you must select a Backlog.
７ Note
You can only select work item types that have been added to a backlog. To
add work item types to a backlog, see Customize your backlogs or boards
(Inheritance process). For On-premises XML process, see Process
configuration XML element reference.
2. To further filter the work items used to calculate the lead or cycle time, specify the
Field Criteria. For example, all the work items whose Release field is set to
Milestone 1.
７ Note
Supplying no values to the filter may lead to selection of all workitems, or may
be an invalid filter argument depending on type of filter criteria.
3. For a continuous flow, select Rolling period and specify the number of days you
want to view on the chart.
Or, for a fixed scope view, select and specify the Start date. Select this view if your
team employs a Scrumban process or follows a standard sprint process.
The main difference between these two types of charts is that the fixed scope chart
will provide information (in most cases) of scope change.
4. Select Save when done. The following image shows an example Lead Time chart
showing 60 days of data.
For your
lead/cycle time charts to provide useful data, your team must quickly update the
status of those work items that the widgets track.
Interpret the scatter-plot control charts

Both Lead Time and Cycle Time widgets display as scatter-plot control charts. They
display summary information and provide several interactive elements.
Example Lead Time widget

The chart dots represent completed work items where their position on the horizontal
axis represents the date the team completed them. Their position on the vertical axis
represents the calculated lead time or cycle time.
Larger dots represent multiple work items with the same lead/cycle time
Dot color corresponds to the work item type displayed in the legend
Dark gray dots correspond to a mix of work item types.
Summary elements
Days on average (average lead time or cycle time) for the main work item types
configured for the chart. This number may not be equal to the average cycle/lead
time of all work items. It depends on configurations used for widgets. The average
number is calculated based on each day the team takes time for work item.
The number of backlog work items used in the chart calculations; if there are more
than three types of work items, you'll see a summary for Other
The black trend line indicates the moving average
The band around the trend line shows the standard deviation.
Interactive elements
Hover over any dot to see which work items contributed to the data point and the
lead/cycle time for those items
Select a dot to open the work item or query that lists the work items
To filter the chart, select a work item type in the legend ( , , or other icon) to
filter on that type; to return to the original chart, refresh the dashboard.
Moving average and standard deviation

calculations
The daily moving average value corresponds to the average of data points that fall
within the moving average window. The time-based moving average window is
calculated based on the current day and previous N days. N corresponds to 20% of the
number of days the chart displays, rounded down to the nearest odd number.
Here's an example. If the chart displays the last 30 days, then N = 5 days:
20% of 30 days is 6 days rounded down to the nearest odd number which is 5.
The moving average window for April 10 corresponds to the previous 5 days. So, the
April 10 moving average is the average of all data points that fall on April 5 through
April 10.
If you don't have data points that fall within the moving average window, the chart
doesn't show a moving average line. This scenario can occur if you're starting out and
there aren't enough days to calculate a moving average.
The standard deviation appears as a band that encompasses the moving average.
Standard deviation is calculated based on all data points falling within the same moving
average window. Like moving average, if no data points fall within the moving average
window, the chart doesn't plot standard deviation.
Related articles
We recommend your team review the lead/cycle time charts before or during each
retrospective. Use lead time to help estimate delivery times and track service level
agreements (SLAs). Use cycle time to identify potential process issues, spot variations in
trends, and help with planning.

About Kanban
Workflow states and state categories
Agile, Scrum, and CMMI processes
About work items and work item types
Article • 08/22/2023
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.
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) Product backlogs and boards and Sprints backlog
Issue (Basic)
Product Backlog Item
(Scrum)
Requirement (CMMI)
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.

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:
Customize your work tracking experience

About process customization and inherited processes
Hosted XML process model.
Work item form and Details tab

The work item form displays the fields used to track information associated with each
individual work item. You can define and update a work item through its respective work
item form, in addition to other methods like bulk importing, exporting, updating, and
modifying 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.
Control Function
Copy URL of work item to clipboard (appears on hover over work item title)
Go to Discussions section
Open Actions menu for other work item tasks
Refresh work item with latest changes
Revert changes to work item
Open History tab
Open Links tab
Open Attachments tab
/ Enter or exit full display mode of a section within the form
/ Collapse or expand a section within the form
Add new work item and link to existing work item (May appear under Actions
menu)
Change work item type (Appears under Actions menu)
Move work item to a different project (Appears under Actions menu)
Copy work item and optionally change work item type (Appears under Actions
menu)
Control Function
Send email with work item (Appears under Actions menu)
Recycle work item (Appears under Actions menu)
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.
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
descriptions about other fields, see Work item field index.
７ Note

Field Usage
Title Enter a description of 255 characters or less. You can always modify the title later.
Assigned Assign the work item to the team member responsible for performing the work.
To 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.
Field Usage
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.
Agile process
Workflow states: User Story, 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 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 entering the name of a project member to quickly focus your search to a
select few.
７ 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 Azure Active Directory 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 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 complete forms

With work item templates, you can quickly create work items that have prepopulated
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. 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.
Choose Follow to get updates when changes are made to the work item. For more
information, see Follow changes made to a user story, bug, or other work item or
pull request.
Choose Refresh to update the work item form with the latest changes that
someone else may have made while you had the work item open.
Choose Revert changes to undo any changes you made to the work item form.
To exercise a task available from the Actions menu, see the following articles:
New linked work item
Change type
Move to team project
Create copy of work item...
Send email with work item
Delete
Templates
New branch...
Customize
７ 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 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.
Deployment, Development, and Related Work

controls
The Deployment, Development and Related Work controls are special controls
available in most work tracking forms.
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. For more information, see Link work items to builds and 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.
History, Links, and Attachment tabs

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.
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.
Links: Link work items to other work items or objects

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.
To learn more about linking, see the following articles:

Linking, traceability, and managing dependencies
Link type reference
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 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 Used to track specified types of work

Work item type
Code Review Tracks a code review request against code maintained in a Team Foundation
Request 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 A code review response is created for each person who's requested to provide
Response review comments.
Feedback Feedback requests track requests for feedback generated through the
Request feedback request form. See Get feedback.
Feedback A feedback response is created for each person and for each item for which
Response feedback is provided through the Microsoft Feedback Client. See Get
feedback.
Shared Step Shared steps are used to repeat tests with different data.
Shared Shared Parameters specify different data and parameters for running manual
Parameter 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.
Category and Used to track specified types of work
Work item type
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. For more information, see Set permissions and access for
work tracking and Stakeholder access quick reference.
Next steps
Add a work item
Related articles
Key concepts and work item tasks in Azure Boards
Web portal navigation
Backlogs, portfolios, and Agile project management
About Kanban and Agile project management
Agile, Scrum, and CMMI processes
Key concepts and work item tasks
Article • 08/23/2023
2018
Use this index to quickly access concepts and tasks related to work items and
information on adding and updating work items—such as users stories, features, tasks,
and bugs.
７ Note
The following features require that you enable the New Boards Hub preview
feature. These features are only available for Azure DevOps Services at this time. To
enable the New Boards Hub, see Manage or enable features.

Filter the history tab
Change the color of a swimlane on a Kanban board
Key concepts
Agile glossary
Agile process
Area Paths
Autocomplete work items
Assigned to
Basic process

Charts
Client tools
CMMI process
Customization process models
Dependencies
Delivery plans
Filtering
Following
Iteration Paths
Keyboard shortcuts
Link types
Linking and traceability
Mobile browser
New Boards Hub
New work item widget
Set permissions and access
Process guidance
Process models
Queries
Recycle bin
Remote linking
Rollup
Scrum process
State categories
Tags
Track dependencies
Visual Studio work item experience
Work item fields

Work item form
Work item templates
Work item types
Work tracking limits
Workflow
Work item user tasks

Tasks listed below are available to users with Contributor permissions and Basic access.
Add a work item
Add Epics
Add Features
Add items to a backlog
Add items to a Kanban board
Add links
Add tags
Add tasks
Add to discussion
Apply a template to a work item
Assign work to a team member
Bulk modify work items (Excel)
Bulk modify work items (Web)
Capture work item as a template

Change the link type
Change work item type
Copy work item URL
Copy list of work items
Create a branch
Create a work tracking chart

Define work item URL
Delete work item tags
Delete work items
Display rollup
Send email of work item list
Export a work item list
Filter a backlog, board, or plan
Filter the History tab
Follow a work item
Forecast work items
Get notified of work item changes
Group work items
Link to cross-organization work items

Link to development objects
Link to GitHub commits and pull requests
Link to work items from a wiki
Link work items
List work items
List work items in a wiki
Manage bugs
Manage issues or impediments
Manage work item tags
Map work items
Move work items to another project
Open work items

Print work items
Prioritize backlog items
Query work item history
Query for work items
Reassign work items
Remove work items
Request feedback
Restore deleted work items
Start storyboarding
Track dependencies
Update status of tasks (Taskboard)

Update status of work items (Kanban board)
Use #ID to link
Use @mentions
View history
View work items (mobile)
View work items (web)
View work assigned to me
View work I'm following
View work I've recently viewed or updated
View work recently completed
View work recently created
View work where I'm mentioned
Administrative customization tasks

Tasks listed below must be performed by an administrator who has the necessary
permissions, as they affect all users and teams within a project.
You customize work item types using the Inheritance process model.
Add a checkbox (Boolean) field

Add a custom field
Add/remove custom fields
Add/remove custom groups
Add/remove custom pages
Add/remove a custom control
Add/remove custom rules to a field
Add a person-name/Identity
Add a picklist (drop-down menu)
Add a rich-text (HTML) field
Add, edit, or remove a WIT workflow state
Change a field label

Change the WIT color or description
Change the reference process from Agile to Scrum
Change the reference process from Basic to Agile
Change the reference process from Scrum to Agile
Create a project
Define Area Paths

Delete field
Delete a WIT
Enable/disable a WIT
Modify a default pick list

Move the field within the layout
Remove a field from form
Restrict modification
Set required/default options
Related articles
Quick guide to default permissions and access
View and add work items using the
Work Items page
Article • 05/02/2023
Visual Studio 2019 | Visual Studio 2022
View work items that you created or are assigned to you. The Work Items page provides
several personalized pivots, as shown in the following image, and interactive filter
functions to streamline listing work items. Use this page to quickly find work items
defined across teams within a project.
７ Note
The Work Items page is available from Azure DevOps Services, Azure DevOps
Server 2019 and later versions, and Visual Studio 2019 RC1.
Prerequisites
You must be added to a project. To get added, Add users to a project or team.
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 won't have permission to add new tags, as
they are prohibited through their access level. For more information, see
All project members, even those who belong to the Readers group, can email work
items.
Open Work Items

You can start viewing and adding work items once you connect to a project.
Web portal
(1) Check that you've selected the right project, then (2) choose Boards>Work
Items.
７ Note
Depending on the process chosen when the project was created—Agile, Basic,
Scrum, or CMMI—the types of work items you can create differ. For example,
backlog items may be called user stories (Agile), issues (Basic), product backlog
items (Scrum), or requirements (CMMI). All three are similar: they describe the
customer value to deliver and the work to be performed.
For more information, see About processes and process templates.
View work items

Using the drop-down menu, you can focus on relevant items inside a project using one
of seven pivots. Additionally, you can filter and sort each pivot view. You can also use an
Azure DevOps CLI command to view details about a work item.
Web portal
Assigned to me: lists all work items assigned to you in the project in the order
they were last updated. Doesn't include items moved to the Removed
category state. To open or update a work item, simply click its title.
Following: lists work items that you're following.
Mentioned: lists work items in which you've been mentioned in the last 30
days.
My activity: lists work items that you've recently viewed or updated.
My team(s): lists work items that your team members have recently viewed or
updated.
Recently updated: lists work items recently updated in the project.
Recently completed: lists work items completed or closed in the project.
Recently created: lists work items created within the last 30 days in the
project.
Add a work item

Adding a work item is just one click away. Choose the work item type from the New
Work Item drop down menu. You can also use an Azure DevOps CLI command to add a
new work item.
７ Note
New work items are assigned the last Area Path and Iteration Path selected by the
user.
Web portal
For example, here we choose User Story.
 Tip
Work items you add are automatically scoped to the currently selected team's
area and iteration paths. To change the team context, see Switch project or
team focus.
Enter a title and then save the work item. Before you can change the State from its
initial default, you must save it.
You can add tags to any work item to filter backlogs, queries, and work item lists. Users
with Basic access can create new tags by default, users with Stakeholder access can only
add existing tags.
Filter to create personal views

You can filter each work item pivot view by entering a keyword or using one or more of
the fields provided, such as work item type (Types), State, Area Path, and Tags. The page
remembers the filters you set for each pivot, supporting personalized views across all
pivots. To learn more about filtering, see Filter backlogs, boards, queries, and plans.
Web portal
Add columns and sort by a column
From the web portal, you can sort your view by one of the column fields that you select
from the Column Options dialog. For more information, see Change column options.

performed.
The rich text editor tool bar displays below the text entry area. It appears when you click
your cursor within each text box that supports text formatting.
７ Note
There is no 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.

Choose one of these icons-- , , or --to open a menu of recent entries you've
made to mention someone, link to a work item, or link to a pull request. Or to open the
same menu, you can type @, #, or !.
you want to add. You can bring a group into the discussion by entering @ and the
group name, such as a team or security group.

If you need to edit or delete any of your discussion comments, choose Edit or choose
the actions icon and then choose Delete.
After updating the comment, choose Update. To delete the comment, you'll need to
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.

reaction, as well as the display of reactions on a comment.

path.
７ Note
Copy selected items to the clipboard or email

them
To select several items in a sequence, hold down the shift key from a web portal page.
To select several non-sequential items, use the Ctrl key. Then, you can use Ctrl+c to
copy the selected items to a clipboard. Or, you can open the context menu for the
selected work items, click ( actions icon), and then select an option from the menu.
Open a view as a query

From the web portal, you can open any view, filtered view, or selected set of work items
as a query. Choose Open in Queries or the Open selected items in Queries option from
the context menu.
Queries provide other features that you can use, including:
Edit one or more fields of several work items

Add or remove tags from several work items
Change the work item type
Delete work items
Apply work item templates
And more
For more information, see Bulk modify work items. To learn more about queries, see Use
the query editor to list and manage queries and Query fields, operators, and macros.
Work Items page controls

Use the following three controls to manage your views in the web portal.
Control Function
View/hide completed items
Turn filtering On/Off
Related articles
Azure Boards FAQs
Move, change, or delete work items (Recycle Bin)
Manage or enable features
Use work item form controls
Keyboard shortcuts
Work across projects
Add and update a work item
Article • 06/27/2023
2018
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.
For other clients that you can use to add and update work items, see Best tools for
adding, updating, and linking work items.
Prerequisites
items.
Add a work item
You can start adding work items once you connect to a project.
Browser
Choose a Boards page—such as Work Items, Boards, or Backlogs. Then choose the
plus icon and select from the menu of options.
７ 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.
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.
Browser
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.
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.
To find work items based on their history, see History & auditing.
Use the Discussion section to add and review comments made about the work
being performed.
７ Note
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.

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 ! .
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.

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.

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.
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.
７ Note
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.
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.
Next steps
To quickly add backlog items, such as user stories, requirements, or bugs, see these
articles:
Create your backlog 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.
Article • 02/24/2023
2018
specific sprint.
assigned work.
Path, or Tags.
Area Path or Tags.

✔️or is listed.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes

enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
Relevance.


７ Note
team.
Prerequisites

view
Features, or Epics
Work Items
team member.
want to filter on.
criteria.
Inactive functions


values.
board.

operator.



include 'web'.

Unassigned
７ Note

Epics).
AND | OR . AND
Item 2.

７ Note
you've defined.

features.

tags.
boards.

Related articles
About backlogs
Customize cards
Tags
Manage requirements
Article • 02/21/2023
2018
Become familiar with the essential concepts to manage projects using Agile tools. Gain
an overview of Azure DevOps tools and features to manage requirements. This article
maps Agile requirements management tasks by project managers to the tools Azure
DevOps supports. More detailed information is provided under Related articles.
７ Note
Requirements management is a continuous process throughout a project lifecycle—

encompassing the processes of documenting, analyzing, prioritizing, tracking, and
collaborating with stakeholders to agree on work to be performed. A single
requirement corresponds to a capability which a project outcome—product, service,
architecture, performance—should conform.
Agile requirements management supports the following scenarios.
＂ Define and track status of requirements

＂ Analyze and prioritize requirements
＂ Assign requirements to timeboxes
＂ Group and organize requirements
＂ Manage dependencies
＂ Determine what can ship and when
＂ Monitor and report on progress
When managing requirements using Agile methods, you'll also perform within an Agile
culture which supports the following principles and methods:
＂ Alignment within the organization

＂ Autonomous teams
＂ Kanban and lean management
＂ Scrum
Capture requirements
You capture requirements using work items, where each work item is based on a work
item type. You have a choice of work item types to use based on the process you select.
Or, you can add a custom work item type.
７ Note

Work item fields and form

You can 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 is assigned a unique identifier.
Each work item supports tracking data contained in work item fields. Also, it captures
changes as updates are made within the History field and comments made in the
Discussion section. The following image shows a sample work item form for the User
Story work item type.
Example work item form

In a nutshell, you use work items to support these tasks:
Add information, update status, assign to team members, link work items, and
attach files
Assign work to a timebox or sprint
Quickly fill in work item fields using work item templates
Contribute to a queryable discussion thread
Prioritize work and triage work items.
Other features that support end-to-end traceability are the Development and
Deployment sections. These sections support the following tasks and insights:
Create a new branch or pull request from a work item

Complete the pull request
Perform a squash merge
Create a branch for several work items
Link a work item to existing development and build objects
View the release stages associated with the work item within the work item form in
real time
View the status of releases within those work items that are associated with
commits in the build and release pipelines
Work item types

Different work item types support capturing different information and workflow
processes. Each work item is based on a work item type. The following images illustrate
the default work item types used to capture requirements and code defects. They are
based on the four system processes—Agile, Basic, Scrum, or Capability Maturity Model
Integration (CMMI).
Each Azure DevOps project is defined based on one of these customizable processes.
Each team can determine how they want to track bugs.
Default work item types
Agile process

You can add custom work item types or customize the default work item types.
Supported customizations include the following additions:
Add custom fields and workflow states
Add custom rules to support business workflow processes
Add custom portfolio backlogs and customize backlogs and boards
Add custom controls to work item forms to gain enhanced functionality.
Add work items to product backlog or board

Capturing requirements typically starts by adding a Title to a product backlog. You add
details later.
Capture requirements on the product backlog
Import and update requirements using Excel

Alternatively, you can import and update requirements you've defined through a .csv file
or Excel spreadsheet. These tools support a flat list or a hierarchy of work items. As
shown in the following image, a hierarchy of Epics, Features, and User Stories are
defined in Excel and then imported to Azure DevOps.
Import requirements from Excel

Functional and non-functional requirements
Any work that you or a development team need to track can be captured using work
items. You can use the same type of work item to capture both functional and non-
functional requirements. Non-functional requirements specify criteria associated with
system operations rather than specific product or service functionality.
You can differentiate your requirements using tags, the Business Value field, or a custom
field.
Maintain requirement specifications

Requirements often require specifications to provide details that aren't readily captured
within the work item. You can use Azure DevOps to maintain and version control your
requirements under an Azure Repos repository. Or, you can use a project wiki to provide
a central source and repository for specifications.
You can then link your specifications or attach them to your requirements.
Analyze and prioritize requirements

Once you have a working backlog, you'll want to get it in priority order. You'll want to
review and refine your requirements and make sure the acceptance criteria is well-
defined. These tasks are supported through the following Azure Boards tools:
Product backlog: Supports drag-and-drop of work items to get them in priority

order. Supports bulk-edit of work items to change assignments or update fields.
Query Results, Triage mode: Supports review of a list of work items and their
forms so that you can quickly update work items and add details.
Here the features backlog shows the sequence of features to ship.
Prioritize feature backlog
Group and organize requirements

The product backlog starts out as a flat list. However, often you want to group
requirements that support specific features or business objectives. Azure Boards
supports this by providing portfolio work item types, portfolio backlogs and boards, and
a Mapping tool to quickly link requirements to a portfolio work item.
Work item tags are another way you can group requirements.
Epics, features, and portfolio backlogs

You group requirements under Features, and Features under Epics, using parent-child
hierarchical links. This type of grouping is recommended for organizations with several
teams that want to view rollups associated with multiple teams and to take advantage of
all portfolio planning tools.
By grouping work within a hierarchy, you can manage a portfolio of features that are
supported by different development and management teams. Also, you can view a
rollup of estimates, progress bars, and more on product backlogs.
Group User Stories under Features using Mapping
Use tags to group work items

With work item tags, team members can assign ad-hoc tags to work items. You can use
these tags to filter backlogs and boards as well as query on work items. For example, the
following image illustrates a Kanban board filtered on the web keyword which displays
cards with the Web tag.
Filter backlogs and boards based on tags

Implement Kanban or Scrum
Two of the major Agile methods are Kanban and Scrum. Azure Boards supports both
methods. Or, teams can adapt them to use a combination of methods such as
Scrumban.
Implement Kanban
Each product and portfolio backlog is associated with a corresponding Kanban board.
Both backlogs and boards are associated with a team, and display work items based on
the area and iteration paths selected by the team.
Each board supports many Kanban practices such as defining columns and swimlanes,
setting Work-in-Progress (WIP) limits, defining the Definition of Done, and more. As
work completes in one stage, you update the status of an item by dragging it to a
downstream stage.
Example Kanban board

Each team can quickly configure their board and the cards to support their business
needs.
Implement Scrum
Sprint backlogs and Taskboards provide a filtered view of work items a team has
assigned to a specific iteration path, or sprint. From your requirements backlog, you can
drag-and-drop work items onto an iteration path, and then view that work in a separate
Sprint Backlog.
Example Sprint Backlog
Supported Scrum practices include the following tasks:
Assign requirements to a sprint

Add tasks to requirements
Set sprint capacity for team members
Adjust work to fit sprint capacity
Share your sprint plan
Filter, update tasks, and update task status
Monitor sprint burndown

By updating the status of work daily throughout a sprint, you can easily track sprint
progress with the Sprint burndown chart, as shown in the following image.
Example Sprint burndown chart
Manage dependencies
In Microsoft Project, you manage tasks that depend on the completion of other tasks by
linking them. To manage dependencies in Azure Boards, you can link work items using
the Predecessor/Successor link type. Once you've linked work items, you can view link
relationships using the Work Item Visualization Marketplace extension. The following
image illustrates link relationships among several work items.
Minimum Viable Product versus Critical Path

Management
Azure Boards doesn't provide a native view of the critical path. In part, as Agile
epics, features, stories, and tasks.
Perform milestone planning

Two tools that support planning what can ship when are team velocity and forecasting.
Team velocity
One of the advantages of working in sprints is that you gain insight into team velocity.
Velocity provides an indication of how much work a team can complete during a sprint
based either on a count of completed work items or the sum of requirement estimates.
Example team Velocity chart
Forecast requirements
The Forecast tool requires that you provide estimates to the Story Points, Effort, or Size
field for each requirement.
With estimates assigned to each requirement, you can set a team velocity. In the
example below, we specify 12 for the velocity, equivalent to stating that on average the
team can complete 12 Story Points per sprint. The Forecast tool shows which
requirements and features the team can complete within the next six sprints. Using the
Planning tool, you can quickly assign requirements to the forecasted sprints.
Example Forecast of requirements backlog
]../boards/media/best-practices/forecast-product-backlog-ordered-
parent.png#lightbox)
If you want to integrate your requirements planning with Microsoft Project tools, you
may do so via a Marketplace extension.
Milestone markers
Delivery Plans provide a calendar view and allow you to define a milestone marker.
milestone:
Simply prepend or append the word Milestone in the title of your work item
milestone work item
Assign a milestone work item to the sprint in which it's targeted for completion.
Assign requirements to timeboxes

You can quickly assign work items to a sprint through drag-and-drop from the product
backlog to the sprint listed within the Planning pane.
Example assign requirements to sprints
Monitor and report on progress

The three main tools you'll want to use to review progress and deliverables are:

Features backlog with rollup columns
Delivery plans

Your Features board is another place to review progress and ensure the continuous flow
of deliverables. The following image illustrates a customized Features board. In progress
columns have been added such as Need more info, Spec Complete, In Progress, and
Customer Rollout. These column labels provide a more natural set of states as Features
get proposed, researched, designed, developed, and then deployed to production.
Example of Features board with customized columns

Rollup
One quick and visual way to monitor progress is from the Features backlog. By adding
the rollup progress bar column, you can see what percentage of work items are
completed for each feature, as shown in the following image.
Example of Requirements backlog showing progress rollup
Delivery plans and multiple team deliverables

To review features delivered across several teams, configure a delivery plan. Delivery
plans provide an interactive board to review a calendar schedule of stories or features
several teams plan to deliver.
Example of multi-team Delivery Plan

Get notified of changes
Azure DevOps provides a robust alert system, allowing project members to set alerts for
themselves, a team, or a project.
As changes occur to work items, code reviews, source control files, and builds, you can
receive email notifications. For example, you can set an alert to be notified whenever a
bug that you opened is resolved or a work item is assigned to you. You can set personal
alerts, team, project, or organization alerts.
Related articles
To learn more about any of the concepts introduced in this article, refer to the following
articles.
Agile and Agile culture
What is Agile?
Agile culture
Best practices for "light-weight" Agile project management
Scaling Agile - Practices that scale
Work items, work item types, and process models
About work items

Add work item tags to categorize and filter lists and boards
About processes and process templates
About process customization and inherited processes
Bulk add or modify work items with Excel
About Area and Iteration Paths (sprints)
Work tracking, process, and project limits
Backlogs and boards

Create your backlog
Refine your backlog
Tasks supported by Backlogs, Boards, Taskboards, and Plans
Kanban
Start using your Kanban board

Customize cards
Scrum
Scrum and best practices
Dependency management

Triage work items
Milestone planning
The Critical Path on Agile Projects
Running a lean startup on Azure DevOps
Monitor and report on progress

Maintain specifications and share information
About Wikis, READMEs, and Markdown

Share information within work items and social tools
Notifications
Default and supported notifications
Manage personal notifications
Manage notifications for a team or group
Define, capture, triage, and manage
software bugs in Azure Boards
Article • 06/27/2023
2018
How do you track and manage defects in your code? How do you make sure software
problems and customer feedback get addressed quickly to support high-quality
software deployments? And, how do you make good progress on new features and
address your technical debt?
At a minimum, you need a way to capture your software issues, prioritize them, assign
them to a team member, and track progress. And, you want to manage your code
defects in ways that align with your Agile practices.
To support these scenarios, Azure Boards provides a specific work item type to track
code defects named Bug. Bug work items share all the standard features of other work
item types with a few more. For an overview of standard features, see Track work with
user stories, issues, bugs, features, and epics.
Bugs also provide the following additional features:
Options for each team to choose how they want to track bugs
Test tools to capture bugs
Built-in integration across Azure DevOps to track bugs linked to builds, releases,
and tests
７ Note
Bug work item types aren't available with the Basic process. The Basic process
tracks bugs as Issues and is available when you create a new project from Azure
DevOps Services or Azure DevOps Server 2019.1 or later versions.
Prerequisites
items.
 Tip
To report a bug, a user must have at a minimum, Stakeholder access and Edit work
items in this node permission set to Allow for the Area Path where they add the
bug. For more information, see Set permissions and access for work tracking
Bug work item type

The following image shows the Bug work item type for the Scrum process. The Bug work
item type for Agile and CMMI processes tracks similar information. It's designed to
appear on the product backlog along with requirements or on the Taskboard along with
tasks.
７ Note
The images you see from your web portal may differ from the images you see in
this article. These differences result from updates made to your web app, options
that you or your admin have enabled, and which process was chosen when creating
your project—Agile, Basic, Scrum, or CMMI. The Basic process is available with
Azure DevOps Server 2019 Update 1 and later versions.
Fields specific to bugs
The Bug work item type uses some bug-specific fields. To capture both the initial issue
and ongoing discoveries, use the fields described in the following table. For information
about fields specific to the Bug defined for the Capability Maturity Model Integration
(CMMI) process, see Bugs, issues, and risks field reference. For information about all
other fields, see Work item field index.
Field, Group, or Tab
Usage
Steps to Reproduce
(friendly name=Repro Steps)
Use to capture enough information so that other team members can fully understand
the code defect. Include actions taken to find or reproduce the bug and expected
behavior.
System Info
Found In Build
Information about the software and system configuration that is relevant to the bug and
tests to apply. The System Info and Found in Build fields are automatically filled in
when you create a bug through a testing tool. These fields specify information about the
software environment and build where the bug occurred. For more information, see Test
different configurations.
Acceptance Criteria
Provide the criteria to meet before the bug can be closed. Before work begins, describe
the customer acceptance criteria as clearly as possible. Teams should use this criteria as
the basis for acceptance tests, and to evaluate whether an item has been satisfactorily
completed.
Integrated in Build
Specifies the name of the build that incorporates the code that fixes the bug. This field
should be specified when you resolve the bug. For on-premises Azure DevOps, to access
a drop-down menu of all builds that have been run, you can update the FIELD
definitions for Found in Build and Integrated in Build to reference a global list. The
global list is automatically updated with each build that is run. For more information, see
Query based on build and test integration fields.
For information about how to define build numbers, see build number format options.
Priority1
1: Product requires successful resolution of the work item before it ships and
addressed soon.
2: Product requires successful resolution of the work item before it ships, but
doesn't need to be addressed immediately.
3: Resolution of the work item is optional based on resources, time, and risk.
Severity1
A subjective rating of the impact of a bug or work item on the project or software
system. For example: If a remote link within the user interface—a rare event—causes an
application or web page to crash—a severe customer experience, you might specify
Severity = 2 - High and Priority = 3. Allowed values and suggested guidelines are:
1 - Critical: Must fix. A defect that causes termination of one or more system
components or the complete system, or causes extensive data corruption. And,
there are no acceptable alternative methods to achieve required results.
2 - High: Consider fix. A defect that causes termination of one or more system
components or the complete system, or causes extensive data corruption.
However, an acceptable alternative method exists to achieve required results.
3 - Medium: (Default) A defect that causes the system to produce incorrect,
incomplete, or inconsistent results.
4 - Low: A minor or cosmetic defect that has acceptable workarounds to achieve
required results.
Deployment
The Deployment control supports links to and display of releases that contain work
items. To use the control, you must enable settings for the release. For more
information, see Link work items to releases later in this article.
Development
The Development control supports links to and display of links made to development
objects. These objects include Git commits and pull requests, or TFVC changesets and
versioned items. You can define links from the work item or from the commits, pull
requests, or other development objects. For more information, see Link work items to
development later in this article.
Notes:
1
To change the menu selection or picklist, see Customize the work tracking experience.
The customization method depends on the process model used by your project.
Choose how your team tracks bugs

Your team can track bugs as requirements or as tasks. To support the team choice,
consider the following factors.
Size of your team. Smaller teams can maintain a lightweight footprint by tracking
bugs as requirements.
Organization requirements to track work. If your team is required to track hours,
then choose to track bugs as tasks.
How your team organizes work. If your team relies on the product backlog to
prioritize work and add bugs, track bugs as requirements.
Tools your team wants to use such as the Planning pane, velocity chart, forecast,
rollup, and delivery plans. Tracking bugs as tasks prevents use of several of these
tools.
The following table summarizes the three options teams have to track bugs. To learn
more and to set the option for your team, see Show bugs on backlogs and boards.
Option

７ Note
Track bugs as Tasks

７ Note

７ Note
backlogs or boards
Delivery Plans
Customize work item type

You can customize the Bug and other work item types. Or, create custom types to track
software issues or customer feedback. With all work item types, you can customize the
following elements:
Add or remove custom fields

Add custom controls or custom tabs within the work item form
Customize the workflow states
Add conditional rules
Choose the backlog level in which work items appear
Before you customize your process, we recommend you review Configure and
customize Azure Boards.
To customize your particular process, see Customize an inheritance process.
Add or capture bugs

You can define bugs from several different Azure DevOps tools. These include backlogs
and boards and testing tools.
 Tip
By default, the Title field is the only required field when creating a bug. You can
quickly add bugs in the same way you add user stories or product backlog items
using Azure Boards. If you want to make some fields required, do that by adding
conditional rules based on a state change. For more information, see Add a rule to
a work item type (Inheritance process).
Add a bug from your backlog or board

If your team chose to manage bugs with requirements, you can define bugs from your
product backlog or Kanban board. For more information, see Create your product
backlog or Start using your Kanban board.
Add a bug from the product backlog
Add a bug from the product backlog
 Tip
When you add a bug from your product backlog or Kanban board, the bug is
automatically assigned the default Area Path and Iteration Path defined for the
team. For more information, see Team defaults referenced by backlogs and
boards.
Add a bug from your sprint backlog or Taskboard

If your team chose to manage bugs with tasks, you can define bugs from your Kanban
board, product backlog, Sprint backlog, or Sprint Taskboard. You add a bug as a child to
a product backlog work item.
Add a linked child bug from the Kanban board

You add a bug in the same way you add a task to a backlog item. For more
information, see Add tasks or child items as checklists.
Add a linked child bug from the Sprint Backlog
You add a bug in the same way you add a task to a Sprint backlog. For more
information, see Add tasks to backlog items.
Create a bug from a testing tool

The two testing tools you can use to add bugs while testing include the web portal Test
Runner and the Test & Feedback extension.
Test Runner: When running manual tests, you can choose to Create bug. For more
information, see Run manual tests.
Test & Feedback extension: When running exploratory tests, you can choose to
Create bug or Create task. For more information, see Exploratory testing with the
Test & Feedback extension
Bug lifecycle and workflow states

As with all other work item types, the Bug work item type has a well-defined workflow.
Each workflow consists of three or more States and a Reason. Reasons specify why the
item transitioned from one State to another. The following images illustrate the default
bug workflow defined for the Agile, Scrum, and CMMI processes.
Agile Scrum CMMI

For Scrum bugs, you change the State from Committed (similar to Active) to Done. For
Agile and CMMI, you first resolve the bug and select a reason that indicates the bug is
fixed. Typically, the person who created the bug then verifies the fix and updates the
State from Resolved to Closed. If more work has been found after a bug has been
resolved or closed, you can reactivate it by setting the State to Committed or Active.
７ Note
The Agile process bug work item type previously had a rule which reassigned the
bug to the person who created it. This rule has been removed from the default
system process. You can reinstate this automation by adding a rule. For an
Inheritance process, see Apply rules to workflow states, Automate reassignment
based on state change.
Verify a fix
To verify a fix, a developer or tester attempts to reproduce the bug and look for more
unexpected behavior. If necessary, they should reactivate the bug.
When verifying a bug fix, you might find that the bug wasn't fixed or you might disagree
with the resolution. In this case, discuss the bug with the person who resolved it, come
to an agreement, and possibly reactivate the bug. If you reactivate a bug, include the
reasons for reactivating the bug in the bug description.
Close a bug
You close a bug once it's verified as fixed. However, you might also close a bug for one
of the following reasons. Reasons available to select depend on the project process and
the bug transition states.
Agile process:
Deferred: Defer bug fix until the next product release.

Fixed: Bug is verified as fixed.
Duplicate: Bug tracks another bug currently defined. You can link each bug with
the Duplicate/Duplicate of link type and close one of the bugs.
As Designed: Feature works as designed.
Cannot Reproduce: Tests prove that the bug can't be reproduced.
Obsolete: The bug's feature is no longer in the product.
Copied to Backlog: A user story has been opened to track the bug.
Scrum process:
Not a Bug: Bug is verified that it isn't a bug.

Removed from the backlog: Bug is verified that it isn't a bug. Remove the bug
from the backlog.
Work finished: Bug has been verified as fixed.
CMMI process:
Deferred: Defer bug fix until the next product release.

Rejected: Bug is verified that it isn't a bug.
Verified: Bug is verified as fixed.
 Tip
Once a bug has been closed and the fix is actively released in deployments,
recommended practice is to never reopen it due to regression. Instead, you should
consider opening a new bug and link to the older, closed bug.
It's always a good idea to describe any more details for closing a bug in the Discussion
field to avoid future confusion as to why the bug was closed.
Automate bug closure when merging pull requests

If your team uses a Git repository, you can set the State in linked bugs and other work
items to close upon successful merging of pull requests. For more information, see Set
work item state in pull request later in this article.
List and triage bugs

Most teams, whatever option they chose to track bugs, define one or more bug queries.
With queries, you can list active bugs, unassigned bugs, stale bugs, bug trends, and
more. You can then add queries and query charts to your team dashboards to monitor
bug status and progress.
Bug queries
Open a shared query or use the query editor to create useful bug queries, such as the
following options:
Active bugs by priority ( State <> Done or State <> Closed )

In Progress bugs ( State = Committed or State = Active )
Bugs to fix for a target release ( Tags Contains RTM )
Recent bugs - bugs opened within the last three weeks ( Created Date > @Today-21 )
Once you have the queries of interest to your team, you can create status or trend
charts. You can also add the chart you create to a dashboard.
Triage mode in query results

Once you've started coding and testing, you'll want to hold periodic triage meetings to
review and rank your bugs. Typically, the project owner runs the bug triage meetings.
Team leads, business analysts, and other stakeholders who can speak about specific
project risks attend the triage meetings.
The project owner can define a shared query for new and reopened bugs to list bugs to
be triaged.
From the query results page, you can quickly move up and down within the list of bug
work items using the up and down arrows. As you review each bug, you can assign it,
add details, or set priority. For more information, see Triage work items.
Organize and assign bugs to a sprint

If your team tracks bugs as requirements, view the list of active bugs from your backlog.
With the filter function, you can focus solely on bugs. From the product backlog, you
can also do the following tasks:
Organize bugs on your backlog, stack rank against other items (stack ranking is
disabled when filtering is enabled)
Assign bugs to a sprint from your backlog using the Planning pane
Parent bugs to Features or other portfolio backlog items using the Mapping pane
View rollup of work to portfolio backlog items.
If your team tracks bugs as tasks, use managed queries to list and triage bugs. Then,
within each sprint, you'll see the bugs assigned to the sprint from the Sprint backlog or
Taskboard.
Taskboard items versus query list items

You might notice and wonder why the items shown on a sprint Taskboard can differ
from a query list created in a corresponding sprint backlog.
It's possible to assign tasks or bugs to an iteration but not have them linked to a parent
backlog item. These items appear in the created query, but might not show up on the
Taskboard itself. The system runs the query and then applies a few background
processes before displaying Taskboard items.
These reasons can cause work items that belong to the Task Category to not appear on
a sprint backlog or Taskboard:
The task or bug hasn't been linked to a parent backlog item. Only bugs and tasks
you've linked to a parent product backlog item (Scrum), user story (Agile), or
requirement (CMMI) with an iteration path set to the sprint appears on the sprint
backlog page.
The task or bug is a parent of another task or bug, or the user story is a parent of
another user story. If you've created a hierarchy of tasks, bugs, or user stories, only
the child-level tasks or the child-level stories at the bottom of the hierarchy
appear.
The task's or bug's linked parent corresponds to a backlog item defined for
another team. Or, the area path of the task's or bug's parent backlog item differs
from the task's or bug's area path.
Create inline tests linked to bugs

When your team tracks bugs as requirements, you can use the Kanban board to add
tests to verify bug fixes.
Update bug status

You can update the bug status by dragging and dropping bugs to a new column on a
board.
If your team tracks bugs as requirements, you use the Kanban board as shown in
the following image. For more information, see Get started with your Kanban
board.
If your team tracks bugs as tasks, you use the Taskboard. For more information, see
Customize your board to track intermediate states
You can add intermediate columns to track your bug status on the board. You can also
define queries that filter based on the status of a Board Column. For more information,
see the following articles:

Kanban board change queries
Automate bug reassignment based on workflow state

To automate select actions, add custom rules to your Bug work item type. For example,
add a rule as shown in the following image. This rule specifies to reassign a bug to the
person who opened the bug once it's resolved. Typically, that person verifies that the
bug is fixed and closes the bug. For more information, see Apply rules to workflow
states (Inheritance process).
Set work item state in pull request
When you create a pull request, you can set the state value of the linked work items in
the description. Follow the syntax: {state value}: #ID . When you merge the pull
request, the system reads the description and updates the work item state. In the
following example, we set work items #300 and #301 to Resolved, and #323 and #324
to Closed.
Integration across Azure DevOps
One of the methods used by Azure DevOps to support integration is to link objects to
other objects. Along with linking work items to work items, you can also link work items
to other objects. Link to objects such as builds, releases, branches, commits, and pull
requests as illustrated in the following image.
You can add a link from the work item or from the build and release objects.
Link work items to development

The Development control supports linking to and displaying links made to builds, Git
commits and pull requests. Or, when a TFVC repository is used, it supports links to
changesets and versioned items. Choosing the link opens the corresponding item in a
new browser tab. For more information, see Drive Git development from a work item.
Link work items to releases
The Deployment control supports links to and display of releases that contain the work
items. For example, the following image shows several releases that contain links to the
current work item. You can expand each release to see details about each stage. You can
choose the link for each release and stage to open the corresponding release or stage.
For more information, see Link work items to deployments.
Link work items to pipeline runs
Pipelines are often defined to automatically run when a new commit occurs to a Git
repository. Work items associated with the commit pipelines appear as part of the
pipeline run if you customize your pipeline settings. For more information, see
Customize your pipeline.
Create or edit a work item upon a build failure
If you use classic pipelines (not YAML), you can create work items on a build failure. For
more information, see Build options, Create a work item on failure.
Monitor bug status, assignments, and trends

You can track the bug status, assignments, and trends using queries that you can then
chart and add to a dashboard. For example, here are two examples showing active bug
trends by State and Active Bugs by Priority over time.
To learn more about queries, charts, and dashboards; see About managed queries and
Charts, and Dashboards.
Use Analytics views and the Analytics service to create

bug reports
The Analytics service is the reporting platform for Azure DevOps, replacing the previous
platform based on SQL Server Reporting Services.
Analytics views provide pre-built filters to view work items. Four Analytic views are
supported for bug reporting. You can use these views as defined or further edit them to
create a custom, filtered view.
Bugs - All history by month

Bugs - Last 26 weeks
Bugs - Last 30 days
Bugs - Today
To learn more about using Analytic views, see What are Analytics views and Create an
active bugs report in Power BI based on a custom Analytics view.
You can use Power BI to create more complex reports than what you can get from a
query. For more information, see Connect with Power BI Data Connector.
Marketplace extensions
There are multiple bug-related Marketplace extensions. See Marketplace for Azure
DevOps .
For more information on extensions, see Azure Boards extensions developed by
Microsoft.
Next steps
Triage work items
Related articles
Use templates to add and update work items
Move, change type, or delete work items
Product backlog and Kanban board

Create your backlog
Organize your backlog, map child work items to parents
Refine your backlog
Kanban board
About Boards and Kanban
Kanban board quickstart
Reorder cards
Sprint backlog and Taskboard

Scrum and working with sprints best practices
Add tasks
Update the Taskboard
Integration within Azure DevOps

Follow a work item or pull request
Configure run or build numbers
Industry resources
Good and Bad Technical Debt (and how TDD helps) by Henrik Kniberg
Managing Technical Debt posted by Sven Johann & Eberhard Wolff
Manage issues or impediments in Azure
Boards
Article • 06/27/2023
2018
If you have known issues you want to track, you can do so by defining an impediment
(Scrum) or issue (Agile or CMMI). Impediments and issues represent unplanned
activities. Resolving them requires more work beyond what's tracked for actual
requirements. Use the impediment work item type to help you track and manage these
issues until you can resolve and close them.
Don't confuse impediments with bugs. You track impediments that may cause problems
with delivering one or more requirements. For example, you may have to fix feature
ambiguity, personnel or resource issues, problems with environments, or other risks that
influence scope, quality, or schedule. Other issues that deserve tracking are decisions
that require several stakeholders or product teams to weigh in on.
） Important
Issues and Impediments discussed in this article are defined for projects created
with the Agile, Scrum, or CMMI process. By default, these work item types don't
appear on the product backlog or taskboard.
If your project was created using the Basic process, which tracks work using Epics,
Issues, and Tasks, then you track Issues using the product backlog. For more
information, see Track issues and tasks.
＂ When to use issues versus tasks

＂ How to capture issues or impediments as a work item
＂ Add issues or impediments to your product backlog
Prerequisites
items.
７ Note
Define a task
You use issues or impediments to track items that may block work from getting done. In
general, you link these items to user stories or other work items using a Related link
type.
Define tasks when you want to create a checklist of tasks. You can also define tasks if
you use Scrum methods and track work using the Remaining Work field. By linking
requirement work item types to tasks using the Parent-Child link type, the tasks appear
on the taskboard for each linked user story.
Add an issue or impediment

Open Boards>Work Items, and choose the plus icon, and then select from the New
work item menu of options.
Choose the pin icon to have it show up within the add drop down menu.
Customize issue tracking

Issues and impediments don't appear on your backlog by default. Instead, you track
them using queries. To track them on a backlog, see the next section, Add issues or
impediments to your product backlog.
Add issues or impediments to your product

backlog
If you want to track issues or impediments along with your requirements or a portfolio
backlog, you can track them by adding them to your custom Inherited process. For
more information, see Customize your backlogs or boards (Inheritance process).
Related articles
Add work items
Manage bugs or code defects
Create your backlog
Link work items and other objects
Article • 07/25/2023
2018
You can link work items to other work items to manage dependencies and see
relationships within your work. These work items can be within the same project or in
different projects in your organization. You can also link work items to other objects
such as versioned items, or network resources, and external (Git) builds and commits.
Prerequisites
Backlogs automatically get created when you create a project or add a team. Each team
has access to their own product, portfolio, and sprint backlogs as described in About
teams and Agile tools.
You must be added to a project as a member of the Contributors or Project

Administrators security group.
To add or modify work items, you must be granted Stakeholder access or higher.
Contributors group has this permission set to Allow. For more information, see Set
To use the Planning pane, your team administrator must define iteration (sprint)
７ Note
Users with Stakeholder access for public projects have full access to backlog and
board features, like users with Basic access. For more information, see Stakeholder
access quick reference.
Link several work items

1. From the web portal, open a backlog or query results page, and multi-select the
work items you want to add a link to.
2. Open the … context menu of one of the selected work items, choose Add link, and
then choose Existing item... or New item....
In the following example, we multi-select from the product backlog and choose
Existing item....
Link to an existing work item

From the Add link dialog, choose from the following link types. For more information,
see Link type reference.
Duplicate: When two work items capture the same information; close one of the
work items and keep the other one active.
Parent/Child: When you want to break down work items into smaller items--for
example, break down features into stories, or stories into tasks.
Predecessor-Successor: When you want to track tasks that must be completed
before you can start others.
Related: When the work items being linked are at the same level--such as two user
stories that define features that overlap one another--or to link work items that are
defined in different projects or managed by different teams.
 Tip
Don't nest work items of the same type. While the system allows you to nest work
items of the same type--such as, linking bugs to bugs or bugs to user stories when
tracking both types on your product backlog--it can cause problems. For example,
drag-and-drop of work items on a backlog or display of items on a Kanban board
may not work. For more information, see Fix display, reordering, and nesting
issues.
Browser
1. From the Add link dialog, select the link type, enter a work item ID, and then
choose OK.
In the following example, we use the Related link type to link three items to
the bug with ID of 400.
You can only add links one at a time. (You can no longer enter their IDs separated
by commas or spaces.) To quickly find work items of interest, use work item search.
2. To view the work items selected for linking, you can choose the .
3. If you're working from the Query Results page, bulk save the work items
you've modified. When you work from a backlog, work items automatically
save.
７ Note
The Edit link feature requires you to enable the New Boards Hub preview feature.
1. Open your work item and select Links.
2. Select More actions > Edit link.
3. Choose the link type to change to, and then select Save.
4. Save the work item.
Link to a new work item

Here, we've selected to add a link to the selected work items.
1. Specify the link type, work item type, and title of the new work item. Choose OK.
2. A work item of the type you selected opens. Enter additional information and Save
the work item.
3. If you're working from the Query Results page, bulk save the work items you've
modified.
Link to a remote work item
You can link work items to objects defined in other Azure DevOps organizations as long
as both organizations use the same Azure Active Directory to manage users.
1. Choose from one of the following two remote link types supported.
Consumes From/Produces For: When you want to track dependencies of

work items that are defined in different organizations and managed by
different teams.
Remote Related: When the work items being linked are defined in different
organizations and managed by different teams, but don't have strong inter-
dependencies.
2. From the Add link dialog, select the link type, enter the URL of the remote work
item, and then choose OK.
In the following example, we use the Remote Related link type to link to work item
ID 350 that exists in the remotelinkingtest2 organization, RemoteLinking project.
The link tab maintains a count of all links to the work item. The Remote Link Count field
maintains a count of the number of links added to a work item that link to a work item
defined in another project or organization.
The following example shows two remote links, indicated by the cloud icon, added
to a user story.
Link several work items to a new git branch
You can add a new git branch and link them to existing work items at the same time.
From a backlog or query results page, multi-select the work items you want to link to a
new git branch, choose the actions icon, and then New branch.... For more
information, see Link work items to Git development objects.
Link work items to a build in same or other
projects
You can link work items to existing builds from the Add link dialog. These builds can be
within your project or to other projects in your organization or collection.
1. From the Links tab of a work item, choose Add link>Existing item.
2. From the Add link dialog, choose one of the build link types—Build, Found in
build, Integrated in build— and specify the build number.
If you don't know the build number—a combination of the pipeline and build
name—you can search for it by choosing the icon.
3. From the Link builds dialog, choose the parameters to filter your search of builds.
If linking to a build in a different project, then first choose the Project whose build
you want to link to.
For example, you can specify a build number, select a build pipeline, a build result
—such as, All, succeeded, partially succeeded, failed, or canceled. Or, with All
selected for Result, choose Find to list the available builds to link to.
4. Choose the build from the list you want to link to and then choose OK.
5. From the Add link dialog, choose OK to complete the operation.

Link work items to pull requests
1. In the description of your pull request, enter # to trigger the #ID work item picker.
You see a list of 50 work items that you've recently modified or are assigned to
you.
2. Enter up to five keywords that match the work item type, ID, or title to narrow the
list of suggested work items.
View list of linked objects

To view the list of all objects linked to a work item, open the work item and choose the
Links tab. The links tab indicates the count of all linked objects.
Linked objects are grouped under their link type, with a count within each group. You
can expand or collapse each group, and sort within each group by State, Latest Update,
or Comment by choosing the corresponding column title.
For example, the following Links tab shows a portion of the 64 linked objects for a work
item.
Links prefaced with the red exclamation mark indicate that the build, release, or
other object has been deleted. This is usually due to retention policies which
automatically delete these objects after a certain time period has passed.
When you create a pull request, you can set the state value of the linked work items in
the description. Follow the syntax: {state value}: #ID . When you merge the pull
request, the system reads the description and updates the work item state. In the
following example, we set work items #300 and #301 to Resolved, and #323 and #324
to Closed.
More options for modifying links in bulk
Other features you can use to quickly link or change links that use the parent-child link
type (some features are version-dependent, see the linked article for details):
To quickly link backlog items to portfolio backlog items with parent-child links, use
the mapping pane to organize your backlog. Or, you can choose to Show Parents
and drag-and-drop items within the tree hierarchy.
To create and link tasks to backlog items, use the sprint backlog page.
To indent ( ), outdent ( ), and change the tree hierarchy, use a tree query in
Visual Studio.
To add or delete work items or change the link structure, you can use Excel. See
Bulk add or modify work items with Excel.
Use Azure CLI to add, remove, and show links

You can add, remove, and show details of links made to a work item using link types
supported by your organization with the az boards work-item relation command. For
more information, see Get started with Azure DevOps CLI.
Link types include work link types, remote link types, hyperlinks, and attached files. For a
list of all link types that you can specify, run the az boards work-item relation list-type
command.
Azure CLI
az boards work-item relation add
az boards work-item relation remove
az boards work-item relation show
In the following examples, the organization is fabrikam and the project ID corresponds
to cebd7ef5-4282-448b-9701-88c8637581b7. The table format is used to show the
output. For other formats, see Output formats for Azure CLI commands.
Link work items

To link one or more work item to a single work item, enter the az boards work-item
relation add command.
Syntax
Required parameters include the ID of the work item to link to and the link type.
Supported link types include Parent, Child, Related, Remote Related. For a list of all link
types that you can specify, run the az boards work-item relation list-type command.
For work items defined within the same organization, you must specify the work item ID
or target URL. For work items defined in a remote organization, you must specify the
target URL. You can specify multiple values by separating IDs or URLs with a comma.
Azure CLI
az boards work-item relation add --id

--relation-type
[--detect {false, true}]
[--org]
[--target-id]
[--target-url]
Example
The following command links work item ID=2807 to work item ID=2794 with the Child
link type. The command returns a list of all links currently defined for the work item.
Azure CLI
az boards work-item relation add --id 2794 --relation-type Child --target-id

2856 --output table
Are you sure you want to remove this relation(s)? (y/n): y
Relation Type Url
--------------- -----------------------------------------------------------
--------------------------------------
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
88c8637581b7/_apis/wit/workItems/2850
Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
To view the information for the linked work items, enter one of the URLs listed in your
browser.
Remove work item links

To remove one or more linked work items from a single work item, enter the az boards
work-item relation remove command.
Required parameters include the ID of the work item to remove the link from and the
link type. You can only remove links to work items defined in the same organization. You
can specify any of the supported link types except remote link types.
You must specify the target work item ID. You can specify multiple values by separating
IDs or URLs with a comma.
Syntax
Azure CLI
az boards work-item relation remove --id

--relation-type
--target-id
[--org]
[--yes]
Example
The following command removes the link to work item ID=2794 from work item
ID=2856 to work item with the Child link type. The command returns a list of all links
currently defined for the work item.
Azure CLI
az boards work-item relation remove --id 2794 --relation-type Child --

target-id 2807 --output table
Are you sure you want to remove this relation(s)? (y/n): y
Relation Type Url
--------------- -----------------------------------------------------------
--------------------------------------
browser.
Show details of links made for a single work item

To view the work items linked to a single work item, enter the az boards work-item
relation show command. For a list of all link types that can be returned, run the az
boards work-item relation list-type command.
Syntax
Azure CLI
az boards work-item relation show --id

[--org]
Example
The following command lists the details of links defined for work item ID=2931 in the
fabrikam organization in table format.
Azure CLI
az boards work-item relation show --id 2931 --output table

Relation Type Url
--------------- -----------------------------------------------------------
------------------------------------------------------------------------
Related https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
Successor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
Remote Related https://dev.azure.com/fabrikam-fiber5/847568d2-6541-4a99-
a240-228510ccbff7/_apis/wit/workItems/1777
Predecessor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
Attached File https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-
88c8637581b7/_apis/wit/attachments/1cc6c026-b4ed-420c-bfe6-065be726cba7
browser. Choose the URL for an attached file to download the attachment.
Related articles
Link test cases to user stories
Overview of end-to-end traceability
Map backlog items to portfolio backlog items
Link work items to Git development objects
Link GitHub commits and pull requests to work items
Use Excel to edit tree-topology links
Copy or clone work items and more
Article • 08/17/2023
2018
There are two types of copy functions you can use. The first is to copy or duplicate a
single work item, referred to as copy or clone.
The second function is to copy a multi-selected list of work items to the clipboard,
referred to as copy as HTML or copy to clipboard.
７ Note
this article. These differences result from updates made to Azure DevOps Services.
However, the basic functionality available to you remains the same unless explicitly
mentioned.
Prerequisites
You must be added to a project.
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
All project members, even members in the Readers group, can send emails
containing work items.

Copy a work item when you want to create a new work item that's a duplicate of an
existing one. When you copy a work item, you create a new work item with a new ID,
but the fields of the new work item are prepopulated with the same values as the
original work item. You can then modify the fields of the new work item as needed. A
related link to the original work item gets created and any parent link is copied over. No
history or attachments are copied over from the original work item.
Clone a work item when you want to create an exact copy of an existing work item,
including all the fields and attachments, but with a new ID. Cloning is useful when you
want to create a new work item that's the same as an existing one, with no field
modifications needed.
In other words, copy a work item to create a new work item with prepopulated values
that you can adjust, and clone a work item to create an exact copy.
７ Note
Some fields might get copied, depending on the on-premises version you're
working with and how you customized your work item types. If the work item type
of the work item that you clone has no state transition rule that says to clear the
Closed By field when the State is New or Active, then that field gets copied. The
current system out-of-box templates have this rule defined, which was added to
TFS 2018 and later versions.
1. From the web portal, open the work item you want to copy or clone, open the …
context menu, and choose Create copy of work item.
2. Choose the project and work item type if different from the copied work item.
Optionally change the Title and provide more details.
Optionally, check one or more of the boxes:
Include existing links: To include all Related and external links in the copied
work item. A Related link gets created automatically for the work item
copied, and included in the Discussion section. There's no method for
disabling this feature.
Include existing attachments: To include attachments in the copied work
item
Include child work items: To include existing links to child work items in the
copied work item. This feature isn't recursive. Only those work items directly
linked as children to the work item being copied are included. This option
appears even if there are no child items linked to the work item.
７ Note
When you copy the work item to a different project, Include child work
items is disabled.
When you copy a work item and choose to Include child work items, a
copy is made of each child work item and linked to the copied work item
through a Parent-Child link.
The Include child work items feature requires installation of Azure
DevOps Server 2020.1 update.
3. In the work item form that opens, update other fields as needed. All work items
start in the New state.
 Tip
Copied or cloned work items always have an ID that is greater than the work items
from which they were copied or cloned.

If you have a large number of work items whose type you want to change, use Change
work item type. If the Change work item type option isn't available to you, you can
export a set of work items using Excel or CSV, copy them to a new list, and reimport
them by specifying a different work item type. See Bulk add or modify work items with
Excel or Import or update work items in bulk by using CSV files.
Copy a list of work items

You can copy an HTML formatted table of selected items from either a backlog page or
query results list. Then, you can send an email of this list using your choice of email
client, or paste the list into a Word document, Excel spreadsheet, or other application.
1. From the web portal, open a backlog or query results page, and multi-select the
work items you want to copy to the clipboard.
2. Open the … context menu of one of the selected work items, and then choose
Copy to clipboard or Copy as HTML.
Here we multi-select from the product backlog and choose Copy to clipboard.
Paste the contents into your email client
Paste the contents of the clipboard into your email client or other application. To open a
linked work item, requires users to have read access to the project or area node for
those work items.
The formatted table contains a link to each work item included in your selected results
list. A link to a query that opens only those work items selected is also provided.
Copy the URL

Browser
Copy the URL from the web browser address or hover over the title and then select
the copy-to-clipboard icon.
Related articles
Copy or clone test plans, test suites, test cases, and other test items
Bulk modify work items
Move work items and change the work item type
Remove, delete, or restore work items
Prepopulate fields using work item templates
Azure Boards FAQs
Tutorial: Follow changes made to a user
story, bug, or other work item or pull
request
Article • 06/27/2023
2018
To get notified of changes made to a specific work item or a pull request, you can
choose to follow them. The Follow feature provides an improvised way of getting
notified on a case-by-case basis.
If you want to subscribe to receive notifications automatically based on changes that

occur based on your targeted set of criteria, see Manage personal notifications. For
example, you can create a subscription to automatically get notified whenever a work
item that you created or that was assigned to you is modified.
７ Note
Notification subscriptions allow you to personalize the notifications you receive

automatically based on additional criteria you specify for yourself, a team, or a
project. For example, you can create a subscription and add field criteria to receive
changes based on one or more of the following templates.
This article shows you how to:
＂ Follow a work item

＂ Follow a pull request
＂ Manage work items that you're following
Prerequisites
Connect to a project. If you don't have a project yet, create one.
Administrators security group. To get added, Add users to a project or team.
To view or follow work items, you must be granted Stakeholder access or higher.
For more information, see About access levels. Also, 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 view or follow pull requests, you must have Basic access or higher.
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.
If you want to specify conditions on when you'll get notified of changes, choose the
gear icon and choose from the options provided.
By default, you're Subscribed to receive a notification when any change is made to the
work item. Choose Not Subscribed to receive notification only when you're
@mentioned. Or choose Custom to receive notifications when one of the checked fields
changes, State, Assigned To, or Iteration Path.
You'll only receive notifications when other members of your team modify the work
item, such as adding to the discussion, changing a field value, or adding an attachment.
user profile
To stop following changes, choose the following icon.
Follow a pull request

To track the progress of a single pull request, choose the actions icon for the pull
request, and select the Follow option. This signals the system to notify you
when changes are made to the PR.
You'll only receive notifications when other members of your team modify the PR, such
as adding to the discussion or adding an attachment.
user profile.
To stop following changes, open the PR context menu and choose the
Following icon.
Manage work items that you're following

You can review and manage all the work items you've selected to follow.
Open Boards>Queries, choose All, and under My Queries, choose Followed work
items.
From this view, you can view all items you're following across all projects. Also, you can
complete similar actions supported with a query results view, such as:
Refresh the view

Add or remove visible columns
Sort the order of specific columns
Filter results by text or tags
Set work item pane
Enter full screen mode.
You can also view and manage work that you're following from Boards>Work Items and
pivot to Following.

You can use the @Follows macro in a work item query to filter a list based on work
items you're following along with other query filters.
For example, the following query shows how to query across all projects for active work
items that you're following. You use the ID field and the In operator with the @Follows
macro.
Next steps
Add, update, and follow a work item
Related articles
Manage personal notifications
View and update work items via the mobile work item form
Q: Can I add someone else to follow a work item or PR?

A: No, you can't add another team member to follow a work item or pull request at this
time. You can subscribe them to get notified based on select criteria, such as when a
work item is create or modified, or a pull request is created. For more information, see
Manage team notifications.
Use @mentions in work items and pull
requests
Article • 03/23/2023
2018
The @mention control allows you to quickly add a user or group to a work item or pull
request discussion. Using the people picker of the @mention control, you can select a
project member or group from the search list, and they receive an email notifying them
of your comment.
(Azure AD), people pickers support searching all users and groups added to Azure AD,
not only those users and groups added to your project. To limit the set to project
members and groups, see Manage your organization, Limit identity search and
selection.
７ Note
You can post an @mention via API. Get the Azure DevOps User Id, and then add
the following html code: <div><a href="#" data-vss-mention="version:2.0,{user
id}">@John Doe</a> Testing mentioning</div> For more information, see the
Microsoft Power Automate Community forum post.
Use the @mention control to start or continue a discussion within the following areas:
A work item discussion or any rich-text field

A pull request discussion
Commit comments
Changeset or shelveset comments
Identity search selection

When you leave a code comment in a pull request, enter @ to trigger the @mention
people picker. From the people picker, you see a list of users you've recently mentioned.
To do a directory search, choose a name or enter the name of the user you're looking
for.
２ Warning
If you have permission to invite users to the organization, regardless of whether the
Restrict invitations policy is disabled, you can @mention a user who isn't part of
your organization. This action invites that user to your organization. For more
information, see Restrict new user invitations from project and team
administrators.
To filter the list, enter the user name or alias until you've found a match.
You can also use group mentions. Enter the name of a team or a security group, choose
Search, and then select from the options listed.
To @mention a user you've never selected previously, continue to enter the entire name
to do your search against the full directory.
Names of mentioned users appear in blue text. Choose the @mention link name to
open the user's contact information. The contact information provides more context for
why they were added to the conversation.
７ Note
Don't copy/paste @mention users from a previous comment. While the resulting
formatting looks identical to a properly entered mention, it doesn't register as a
true mention nor send an email notification.
Upon completion of your selection and text entry, your @mention user receives an
email alerting them about the mention.
Use the @mention control in pull request discussions, commit comments, changeset
comments, and shelveset comments.
Limited identities in search selection

In general, people pickers search and select any user or group added to an
organization's Azure AD.
(Azure AD), people pickers provide support for searching users and groups added to the
Azure AD. For organizations that want to limit the search and selection to only those
users and groups added to a specific project, they can do so by enabling the Limit user
visibility and collaboration to specific projects preview feature for their organization.
） Important
The limited visibility features described in this section apply only to
interactions through the web portal. With the REST APIs or azure devops CLI
commands, project members can access the restricted data.
Guest users who are members in the limited group with default access in
Azure AD, can't search for users with the people picker. When the preview
feature's turned off or when guest users aren't members of the limited group,
guest users can search all Azure AD users, as expected.
When the Limit user visibility and collaboration to specific projects preview feature is
enabled for an organization, the list of identities you can select from a people picker is
limited in one of the following ways:
Users added to the Project-Scoped Users group are only able to select from an
identity list that contains users and groups added explicitly to the project they're
connected to.
If all project members are added to the Project-Scoped Users group, then people
pickers are limited to only those users and groups added to the project. All project
members can only select identities that match users and groups added explicitly to
the project they're connected to.
２ Warning
When the Limit user visibility and collaboration to specific projects preview
feature is enabled for the organization, project-scoped users are unable to search
for users who were added to the organization through Azure Active Directory
group membership, rather than through an explicit user invitation. This is an
unexpected behavior and a resolution is being worked on. To self-resolve this issue,
disable the Limit user visibility and collaboration to specific projects preview
feature for the organization.
Related articles
Pull requests
Add work item tags to categorize and
filter lists and boards
Article • 06/27/2023
2018
Tagging work items helps you quickly filter the product backlog or a work item query by
categories that you define. A tag corresponds to a one or two keyword phrase that you
define and that supports your needs to filter a backlog or query, or define a query.
Tags are a better choice to filter work items than using text strings as described in
Guidance to create high-performing queries.
You can add and modify tags from the web portal, from Team Explorer plug-in for Visual
Studio. Also, you can open a query in Excel to modify tags in bulk.
７ Note
Tags are a shared resource, they're associated with a project and not a team. If your
project contains multiple teams, all teams add to and work from the same set of
tags.
Prerequisites
items.
７ Note
Users with Stakeholder access for public projects are allowed to add new tags.
Add tags to a work item

Tags should be 400 characters or less and not contain separators such as a , (comma),
; (semicolon), or other formatting character.
 Tip
We recommend that you don't use the @ character in a tag. Tags that start with the
@ character can't be used in a work item query. The @ character signifies a macro
within a query and therefore the tag isn't recognized as a tag.
From the web portal, open a work item and add a tag. Choose Add tag and type your
keyword. Or, select from the list of previously assigned tags.
To add several tags at one time, type a comma between tags. Tags are case sensitive.
Tags that appear in the tag bar are already assigned to the work item. To unassign a tag,
choose the x on the tag, .
７ Note
By default, all Contributors and Stakeholders of public projects are granted

permissions to add new and existing tags. Stakeholders in private projects can add
tags that are already defined, but not add new tags. To grant or restrict permissions
to create new tags, you set the permission Create tag definition at the project-
level. To learn more, see Change project-level permissions.
You can bulk update work items to add or remove tags from the web portal. You bulk
modify tags in the same way as you bulk modify other fields using the web portal. Or,
you can use Excel to bulk add or remove tags.
７ Note
Bulk modify of tags from the Visual Studio or other supported clients isn't
supported.
Query for work items based on tags

To query work items based on tags, add a clause for each tag you want to use to
support your query.
 Tip
You can use the Contains or Does Not Contain operators. Tags that start with the @
character can't be used in a work item query as the query editor interprets the @
character as a macro. To learn more about queries, see Create managed queries.
For example, here we query for all work items that are tagged either Web or Service .
 Tip
To understand how AND/OR clauses are grouped, see Create and save managed
queries, Group clauses. To view the WIQL syntax for a query, install the WIQL
query editor extension which allows you to see the WIQL version of any query
editor entry.
７ Note
The ability to query for work items that don't have any tags attached to them is not
a supported feature. If you'd like to up vote the request to support this feature, you
can do so on our Developer Community page, Be able to search for empty tags .
Show tags in your backlog or query results

Choose Column Options to add the Tags field to the product backlog or a work item
query. If the option doesn't appear, choose More commands to select it from the
menu of options.
All tags that have been added to the listed work items appear.
Filter lists using tags
From the web portal, you can filter backlogs, boards, and query results using tags.
Begin by choosing Filter .
Check the boxes of those tags that you want to filter on. Keep the OR selection to run a
logical OR for all the tags you selected. Or, choose the AND option to run a logical AND
Delete, remove, or manage tags
You can't delete a tag itself. However, if you delete a tag from all work items to which it's
currently assigned, the system deletes the tag. The system automatically deletes
unassigned tags after three days of disuse.
If you misspell a tag, don't assign the misspelled tag to any work item and the system
automatically deletes it within three days.
Another option is to install the Marketplace Tags Manager , which adds a Tags page
under Boards or Work to manage tags.
Color-code tags on boards

You can highlight tags on Kanban board cards by color-coding them. These colors only
appear on the Kanban board that you configure. They don't appear on backlogs or
Taskboards. For more information, see Customize cards, color-code tags.
Chart work items and group by tags
７ Note
You can't group a query-based chart by tags, however, you can group a Chart for
Work Items widget by tags that you add to a dashboard. This feature is in public
preview. To enable it, see Manage or enable features and turn on Enable group by
tags for work item chart widget on dashboard.
To group a Chart for Work Items widget by tags, complete the same steps provided in
Track progress with status and trend query-based charts, Add a chart widget to a
dashboard. Make sure that your flat-list query contains Tags in the query clause or as a
column option. Then, choose Tags for the Group by selection. To filter the chart to show
only some tags, choose the Selected tags radio button and then choose the tags you
want the chart to display.
Related articles
Use the query editor to list and manage queries
Show tags on cards
Bulk modify work items from the web portal
Bulk modify work items from Excel
Marketplace extension
Marketplace Tags Manager
Limits on the number of tags

While no hard limit exists, creating more than 100,000 tags for a project collection can
negatively impact performance. Also, the autocomplete dropdown menu for the tag
control displays a maximum of 200 tags. When more than 200 tags are defined, begin
entering to cause the tag control to display relevant tags.
You can't assign more than 100 tags to a work item or you'll receive the following
message:
TF401243: Failed to save work item because too many new tags were added to
the work item.
Save the work item with the tags (100 or less) that you've added, and then you can add
more tags.
Limit queries to fewer than 25 tags. More than that amount and the query likely times
out.
Send an email with work items
Article • 09/29/2023
2018
Using work items to track your work provides a host of benefits, including the ability to
easily share information. You can capture most information within the work item
Description or other rich-text formatted field. If you need to maintain the information in
a different format, you can easily link to or attach a file.
Supported tasks
Emailing lists of work items is a common way to share work tracking information. The
following table indicates which tasks or features are supported from the web portal and
Visual Studio.
７ Note
The tasks/features listed in the following table aren't available when you're
connected to a GitHub or third-party Git repository. Also, they aren't available from
Visual Studio under the following conditions:
If you're set to use the new Git Tool as described in Git experience in Visual
Studio.
） Important
We strongly recommend that everyone use the default view instead of the legacy
view. It is designed for you to quickly access a list of work items based on your
assignment, following, mentioned, or recent updates. The legacy view is no longer
being enhanced and we expect to remove it in a future release of Visual Studio.
Task/feature
Web portal
Visual Studio
Email summary list with links to work item(s)
✔️
✔️
Print work item(s)
✔️
Email link to a work item query
✔️
✔️
Email query results
✔️
✔️
Export query result as CSV
✔️
Prerequisites
７ Note
Make sure you provide members of your organization Stakeholder access who
want to contribute to the discussion and review progress. These are typically
members who don't contribute to code, but want to view work items, backlogs,
Kanban boards, and dashboards.
Email a single item

You can quickly email a summary of one or more work items. Summaries include the
values assigned to these fields: work item ID, title, work item type, assigned to, state,
and tags.
） Important
If you use the built-in email feature, you can only send the email to individual
address for a project member that is recognized by the system. Adding a team
group or security group to the to line isn't supported. If you add an email account
that the system doesn't recognize, you receive a message that one or more
recipients of your email don't have permissions to read the mailed work items.
Web portal
From the web portal, open the work item, choose the actions icon, and select
the Email work item option. The first 200 items in the list appear in a formatted
table.
Email summary lists with links to items
Another way to share items is by emailing summary lists, such as a sprint summary plan
or active bugs list. You can share items from a backlog or query results list.
Depending on the option and client you choose, summary lists may or may not include
a hyperlink to the work item ID.
Web portal
To email items from the web portal: Open a backlog or query and highlight the
items from the list. Open the context menu for one of the selected items and select
to email them.
If you want to mail a list of all items in the backlog or query, choose the actions
icon, and select the Email option.
Copy formatted list of work items

With this option, you can copy an HTML formatted table of selected items. You can then
email this list using your choice of email client.
1. From the web portal, open a backlog or a list of query results.
2. Select the work items you want to copy.

The formatted table contains a link to each work item included in your selected
results list.
3. Paste the contents of the clipboard into your email client or other application. To
open a linked work item, requires users to have read access to the project or area
node for those work items.
Print items
Open a query in Visual Studio that contains a work item that you want to print, select or
highlight those items, and then select the Print option from the context menu.
） Important
We strongly recommend that everyone use the default view instead of this legacy
view. It is designed for you to quickly access a list of work items based on your
assignment, following, mentioned, or recent updates. The legacy view is no longer
being enhanced and we expect to remove it in a future release of Visual Studio.
Print work items as cards
Some teams want to work with physical cards when planning or updating their physical
Kanban or Scrum task boards. There's no native support for printing work items as
cards. However, you may find a solution from the Azure DevOps Marketplace .
Copy the URL to a single work item
７ Note
All URLs you copy, regardless of the client you use to copy them, opens the work
item in the web portal.
Web portal
From the web portal, copy the URL from the web browser address or hover over
the title and then select the copy-to-clipboard icon.
Export list as CSV
From any query, you can export a list of work items as a comma-delimited list. Open the
query, choose the actions icon, and choose Export to CSV. For more information,
see Bulk import or update work items using CSV files.
You may find other ways to share information by exporting work items to other
applications such as Microsoft Word. For more information, review the Marketplace
extensions that support Microsoft Word .
Related articles
Send email with work item
Move work items from one team to
another team
Article • 03/30/2023
2018
When you add a team or your teams undergo reorganization, you may need to move
work items assigned to one team to new Area Paths owned by another team. All work
items are assigned to an Area Path, even if it is at the top of the hierarchy for the
project.
Work items that belong to the Requirements category appear on a team's backlog
based on their assignment to the Area Path(s) owned by a team. Assigning other work
items to a team's Area Path(s) support queries based on team ownership.
To learn how to add a team, see Create or add a team.
Prerequisites
To change the Area Paths of work items, you must be a project member and have
permissions to view and edit work items under the Area Path nodes. To learn
about these permissions, see Set work tracking permissions, Create child nodes,
modify work items under an area or iteration path.
To use Azure CLI commands, you must first install Azure CLI as described in Get
started with Azure DevOps CLI.
Move work items under teams

From the web portal, you can perform bulk updates of the Area Path.
1. Create a query of all work items you want to reassign.
2. Multi-select those items, which belong to each team, and bulk edit the area path.
3. After you bulk modify, do a bulk save.
Move a work item using Azure CLI

You can use the az boards work-item update to move a single work item by updating it's
Area Path.
Azure CLI
az boards work-item update --id

[--area]
[--assigned-to]
[--description]
[--discussion]
[--fields]
[--iteration]
[--open]
[--reason]
[--state]
[--title]
Parameters
id: Required. The ID of the work item to update.
area: Optional. Absolute path of an area. Example: --path
\ProjectName\Area\AreaName.
assigned-to: Optional. Name of the person the work item is assigned to Jamal.
description: Optional. Description of the work item.
discussion: Optional. Comment to add to a discussion in a work item.
fields: Optional. Space separated "field=value" pairs for custom fields you want to
set.
iteration: Optional. Absolute path of an iteration. Example:
\ProjectName\Iteration\IterationName.
open: Optional. Open the work item in the default web browser.
reason: Optional. Reason for the state of the work item.
state: Optional. State of the work item, for example, Active.
title: Optional. Title of the work item.
Example
You can only move one work item at a time using Azure DevOps CLI. In this example, we
move work item ID=148 under the Fabrikam Fiber\Production Planning area path.
Azure CLI
az boards work-item update --id 148 --area "Fabrikam Fiber\Production

Planning" --output yaml
The YAML output listed below provides information on each of the fields defined for the
work item.
YAML
fields:
Microsoft.VSTS.Common.Priority: 2
Microsoft.VSTS.Common.StackRank: 1500000001.0
Microsoft.VSTS.Common.StateChangeDate: '2021-11-23T22:26:28.27Z'
Microsoft.VSTS.Common.ValueArea: Business
System.AreaPath: Fabrikam Fiber\Production Planning
System.AssignedTo:
_links:
avatar:
href:
https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.
NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
displayName: Jamal Hartnett
id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
imageUrl:
uniqueName: fabrikamfiber4@hotmail.com
url: https://spsprodeus27.vssps.visualstudio.com/A5d5b8da6-3db7-4829-
baf9-1e500c21cc12/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
System.BoardColumn: Backlog
System.ChangedBy:
_links:
avatar:
href:
imageUrl:
System.ChangedDate: '2022-05-19T22:58:52.93Z'
System.CommentCount: 0
System.CreatedBy:
_links:
avatar:
href:
imageUrl:
System.CreatedDate: '2021-11-23T22:26:28.27Z'
System.Description: <div>This user story is for documentation
purposes. </div>
System.IterationPath: Fabrikam Fiber\Release 2\Sprint 1
System.Reason: New
System.State: New
System.TeamProject: Fabrikam Fiber
System.Title: Test the Request feedback functionality
System.WorkItemType: User Story
WEF_10182DA5BCCD4CE2A43629FFBD290EF2_Kanban.Column: Backlog
id: 148
relations:
- attributes:
isLocked: false
name: Child
rel: System.LinkTypes.Hierarchy-Forward
url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-
2e5f2eb66c99/_apis/wit/workItems/152
- attributes:
isLocked: false
name: Child
- attributes:
isLocked: false
name: Child
- attributes:
isLocked: false
name: Child
rev: 5
Verify your team backlog

After you move work items from one team to another team, check your team backlog to
ensure the items appear. See Create your backlog.
If you encounter any problems, review Set up your project's backlogs and boards.
Related articles
Create or add a team
Modify work items in bulk in Azure
Boards
Article • 07/12/2023
2018
Use bulk modify when you need to quickly make the same change to many work items.
For example, you might want to change the priority of several bugs or reassign several
tasks to the same team member. Use the web portal to quickly modify one or more
fields for work items that contain the same value.
 Tip
To add work items in bulk or update multiple fields with different values, use CSV
Import. You can't complete a bulk add of work items through the web portal.
With bulk modify, you may edit fields and add or remove tags. You can also reassign
work or move work to a specific sprint. You can also use bulk modify to change the work
item type or move work items to other projects. The options available to you depend on
the platform you work from and the permissions you've been granted.
＂ How to multi-select work items from a list and open the context menu
＂ Edit one or more fields of several work items
＂ Assign work from a backlog to a sprint using drag-and-drop
＂ Add or remove tags from several work items
Prerequisites
Supported tasks
All of the following actions can be completed by team members that belong to the
Contributors group. Members provided with Stakeholder access can run multi-select,
bulk edit, change type, email, and copy as HTML/copy to clipboard actions. For more
information, see Work as a stakeholder.
Area
Task
Multi-select work items

Multi-select-query results
Multi-select-backlog
Link work items

Link to a new item
Link to an existing item
New branch1
Bulk edit/update/delete
Edit field(s)
Assign to
Move to iteration
Change position
Change parent
Add/remove tags
Update from template1
Delete 1
Copy, clone, change type, move, or email work items

Clone or copy a single item 2
Copy as HTML/Copy to clipboard
Email selected item(s)
Change work item type1
Move items to another project1, 3
７ Note
1. You can't perform certain functions on work items whose WITs belong to the
Hidden Types Category. This includes all work items that track tests—such as
test cases, shared steps, and shared parameters—code review requests and
responses, and feedback requests and responses.
2. You can choose to copy or clone a single work item from a query results list or
from the Actions menu of the work item form. You can only perform a clone
or copy action for a single work item. Choose Copy work item when you want
to create a copy of a work item and change its work item type. Choose Clone
when you want to create another instance of the work item without changes
to its work item type.
3. You must be a member of the Project Administrators group or be granted
explicit permissions to Move work items.
Select multiple items and open the context menu

To select several items in a sequence, hold down the shift key. To select several non-
sequential items, use the Ctrl key. Then, you can either drag the selected items to a new
position within the backlog, to a different sprint.
To open the context menu, select ( ) or ( ), and then choose the option from the
menu.
Here, we use the context menu to move several non-sequential items to the current
sprint.
 Tip
Use the backlog Create Query feature to create a query with the backlog items. You
can then open the query within the web portal or Excel to perform additional bulk
updates.
Reassign work items

With work items selected, open the context menu for any selected item, and reassign all
of them. By doing reassigning them, you can quickly assign them to a member of your
team or to another sprint or iteration.
To learn more about the Assign To and Iteration Path fields, see Query by assignment,
workflow, or Kanban board changes and Query by area or iteration path.
Edit one or more fields

To assign or modify several fields, choose Edit from the context menu of one of the
selected work items. Enter a value for each field that you want to update.
1. For audit purposes, you can type a description for your bulk update task. To learn
more about each field, see the Work item field index.
2. From the Query results page, you must save all work items that you bulk-modified.
When you bulk modify items from the backlog, they're automatically saved. Work
items shown in bold text indicate that local changes haven't yet been saved to the
data store. The Save items button may be in a different place in the UI than shown
in the picture below, depending on the layout of your browser and the specific
version in use.

From any product, sprint, or portfolio backlog, you can drag a multi-selected list of work
items and drop it onto a sprint in the Planning pane to change it's iteration path. (Not
supported for users with Stakeholder access.)
1. To open the Planning pane, choose the view options icon and select Planning.
You can choose to set In Progress items to On or Off.
The set of sprints selected for your team appears. If you don't see any sprints
listed, you can add sprints or select existing sprints for your team's use. To learn
how, see Define sprints.
2. You can drag and drop items from the Backlog onto a sprint.
This action updates the Iteration Path of the backlog items and any of its child
tasks to the sprint you selected.
Modify rich-text fields in bulk

Rich-text fields support entry of HTML syntax tags to support formatting. Rich-text fields
correspond to the Description, Acceptance Criteria, Repos Steps, and others listed in
Query samples for select fields.
You can bulk update a rich-text field by using the bulk modify tool, selecting the field,
and entering the text with syntax in the Value field. Or, you can create a work item
template with the text you want to use and complete a bulk update by applying the
template to the selected work items. For details on using work item templates, see Use
templates to add and update work items
For a worked example using templates showing entry of HTML formatted syntax, see
Sample work item templates, Add guidance in a rich-text field.
Modify tags in bulk

From the Edit work items dialog, select Tags (Add) or Tags (Remove).
Here we choose to add the Service tag to the selected work items.
Related articles
To add fields or customize a work item form, see Customize your work tracking
experience. The method you use depends on the process model that supports your
project.
Migrate or change a large number of work items

For large scale, organizational moves, use the REST API calls for Work item batch
operations.
At this time, you can't move work items to a different organization or collection. You can
only migrate work item information by exporting and then importing them using Excel.
Add multiple values to a field

If you have implemented a custom control that supports multiple values , you can use
Excel to bulk edit the field, but you can't modify it using the web portal. In the web
portal, you can only select a single value for the field.
Add or modify Azure Boards work items
in bulk with Microsoft Excel
Article • 02/24/2023
2018
When you need to add or modify many work items, using Microsoft Excel can save you
time. Excel supports adding work items, updating existing work items, adding links and
attachments to multiple work items, and more. You can also use native Excel features to
support other actions, such as summing a column, copy-and-paste rows, fill down data
into cells, and more.
In this article you'll learn how to complete the following tasks:
＂ Choose the type of list or query to support your task

＂ Use select Excel features when connected to Azure Boards
＂ Import or update work items, either a flat list or hierarchy tree list
＂ Publish and refresh your work items
＂ Convert a flat-list to a tree-list, change your list type or query
＂ Add work items to your worksheet
＂ Add and remove work item fields from your worksheet
＂ Select user accounts for identity or person-named fields
＂ Link work items, find work items to link to, edit links, and more
＂ Add attachments to one or more work items
＂ Open a work item from Excel to add additional information (opens in web portal)
＂ Edit Area and Iteration Paths (opens in web portal)
For information about connecting to Excel, see Connect Azure Boards to an Office client.
For answers to specific questions about the integration of Excel and Azure DevOps, see
FAQs: Work in Excel connected to Azure Boards .
７ Note
If you don't have access to Excel, you can still perform bulk import and update
using CSV formatted files. For more information, see Bulk import or update work
items using CSV files.
Prerequisites
７ Note
macOS isn't supported. Even if you've installed Visual Studio for Mac, connection to
Azure DevOps from Excel isn't supported.
Installed Microsoft Excel 2010 or later version, including Microsoft Office Excel 365
Installed Azure DevOps Office Integration 2019 (free) .
７ Note
The only way to get the Azure DevOps Office Integration plug-in is by
installing one of the latest editions of Visual Studio or the Azure DevOps
Office Integration installer. The plug-in supports connection to Azure Boards
and Azure DevOps Server from Excel.
To connect to an Azure Boards project, you need to be a member of the project. If

you don't have an Azure Boards project yet, you can create one.
To view or modify work items, you must have these permissions set to Allow: View
work items in this node and Edit work items in this node. By default, the
For more information, see Stakeholder access quick reference.
To use the Select User feature, you need to install Visual Studio (at least VS 2015.1
or later version or Team Foundation Server Office Integration 2015 Update 2 or
later version . You can download the free version of Visual Studio Community.
Get this feature to avoid data validation errors by misspelling user names and
when you must assign user names from a large group of user accounts.
To learn more about compatibility requirements, see Compatibility with Azure DevOps
Server.
Choose list and query type

When you work in Excel connected to Azure Boards, you're always working with a query
type and a list type. Queries correspond to the queries you create using the Query
Editor.
Query types:
None: Indicates it's an input list.
Query title: Indicates the list of work items is tied to the specified query.
List types:
Flat list: Simple list of work items that shows a single Title column. No link
management is supported.
Tree list: Hierarchical list of work items that support creating and updating tree
topology links, such as Parent-Child links, between work items. These lists
include two or more Title columns.
You can add, modify, publish, and refresh work items using any query type and list type.
Query types
Azure Boards supports three query types. The icon next to each query indicates the
query type. The first two query types, Flat list of work items and Work items and direct
links are imported as flat list queries.
Only the Tree of work items queries import as a tree list. Direct links queries are
imported as a flat list into Excel as modifying multiple types of links aren't a supported
feature in Excel.
Tree lists
You can bulk add a nested list of work items, such as a work breakdown structure or a
hierarchical set of user stories and customer experiences. For example, you can add a
nested list of tasks, subtasks, and bugs, as shown in the following illustration, or linked
tasks to product backlog items.
Here's how a three-level nested tree of items appears in Excel.

Parent-child links or other tree topology link types support creating a hierarchical
backlog structure. The work item types that participate in the hierarchy differ with
different processes and are shown in the following images.
Agile process
To import a hierarchical list, see Add or import a hierarchical list of work items later in
this article.
My queries versus shared queries

You can open in Excel any query you've defined in Azure Boards. That includes queries
defined under My Queries and Shared Queries. However, if you plan to share the
workbook with other team members, then you should only work with a Shared Query.
Other team members can't use the workbook or worksheet if it's based on a personal
query stored under your My Queries folder.
Use list and query types

In general, you Use a flat list to bulk add or modify several types of work items at once,
such as backlog items, tasks, bugs, or issues. Use a tree list to bulk add or modify work
items and their tree-topology links.
Here's some more guidance:
Use an input list, flat list: To import a list of work items or create new work items,
no hierarchy
Use an input list, tree list: To complete top down planning and import
hierarchically linked work items
Use a query list, tree list: To view and modify the hierarchy of link relationships of
many existing work items.
Use a query list, flat list: To bulk update a list of work items or create new work
items, no hierarchy
Use Excel features

You can use most Excel features when working with a list of work items. For example,
you can use the following features:
Format a cell or apply conditional formatting to a cell or column

Cut and paste from one cell to other cells
Cut and paste a single row
Sum a column or add other formulas
Fill down cells
Filter
Add multiple worksheets to your workbook
Each worksheet in Excel can contain a different input list or query. However, all
worksheets within the workbook must connect to the same project within an
organization or project collection.
The following features work slightly differently when working with a worksheet
connected to Azure Boards.
Each cell or column of cells corresponds to a work item field. Each field is
associated with a data type. Excel won't allow you to enter data into a cell that
doesn't meet the data type and requirements for that field.
You can only insert a single row at a time within the worksheet.
You can copy and paste multiple rows within the worksheet.
To move a work item within a hierarchy, cut the entire row and paste it under the
work item you want as its parent.
Use Outdent and Indent to change the location of a work item within the tree.
Undo (Ctrl Z) may not work. If you do something that you want to revert, you can
refresh the worksheet.
We recommend you publish and refresh your worksheet often to make sure your local
work remains in sync with Azure Boards data store.
To learn more about Excel, see Basic Excel tasks .
Sort work items

You can sort work item flat lists using the Excel sort feature .
However, if you're working from a tree list, you don't want to do any type of sort. Doing
so changes the tree structure and as such, the links between work items.
If you want to use Excel to manage the order of your work items as they appear in a
team backlog, you can do that by using the Stack Rank or Backlog Priority field (Agile or
Scrum process). You can set values in these fields, publish your worksheet, and refresh
your backlog. Your backlog items should appear reordered based on lowest to highest
number. However, the next time the backlog is reordered from the backlog, the values
you entered are subject to change.
If you want to maintain a certain order of work items, consider adding a custom field to
manage the sort order, and then use that within Excel to sort your flat list of work items.
This option, however, won't change the order that appears in your backlog.
Tasks you can and can't do with Excel

You can do the following tasks:
Add tags and bulk update work items with tags as described in Add work item tags
to categorize and filter lists and boards. Add the Tags field to your worksheet. Add
multiple tags separated by a semicolon (;).
You can add simple text to a rich-text field, but if you're updating several work
items in bulk, you may lose formatting in existing work items.
You can work offline and then reconnect and publish your changes. For more
information, see Connect Azure Boards to an Office client, Work offline, and
reconnect.
You can't do the following tasks from an Excel worksheet:
You can't delete work items

You can't change the work item type of an existing work item
You can't move work items to another project
You can't import or update test case steps or other test artifacts
You can't add work items in any other State than the new State
You can't add to a work item discussion thread
You can't link to a remote work item.
Import work items as a flat list

1. Open Excel and connect to your Azure Boards project. Use one of the four
methods provided in Connect Azure DevOps project to Excel.
７ Note
When you connect to Azure Boards in the cloud, the Team Project Collection
is automatically selected as there is only one collection associated with your
Azure DevOps Services organization. When you connect to Azure Boards in an
on-premises server, you choose the Team Project Collection prior to choosing
the project.
2. In Excel, start with a blank worksheet. If you don't see the Team ribbon (or the
Team menu if you use Excel 2007), see Azure DevOps Office integration issues.
3. Choose New List from the Team ribbon.

4. From the New List dialog, choose Input list.
5. Your worksheet is now bound to your project as an input list (Query[None]), flat
list.
6. Specify the titles of the work items you want to add and their work item type.
Notice how the State and Reason fields automatically fill in with default values
once your select the work item type.
7. Publish your worksheet.
Make sure your cursor is in a cell that contains data. Otherwise, the Publish button
might appear disabled.
Notice how IDs are now assigned to your work items.
8. To assign values to other fields, open Choose Columns, add the fields, make the
assignments, and publish your changes.
 Tip
If you're adding work items that you want to appear on a team backlog, make
sure that you add and specify the team's Area Path and Iteration Path. If you
need to add Area Paths or Iteration Paths, choose the Edit Areas and
Iterations link. The link opens a web browser to the Project Settings page. For
more information, see Define area paths and assign to a team and Define
Iteration Paths and configure team iterations.
9. To open a work item to add more information, Choose the work item you want to
open and then choose Open in Web Access. Before you do, make sure you publish
any changes you've made.
A web browser opens and displays the work item.
If you make changes to the work item, you should then immediately refresh your
worksheet to capture the changes.
Import work items as a tree list

You can add a hierarchy of work items linked using parent-child links or other tree
topology link type.
） Important
Don't sort a tree list. Sorting a tree list can change the hierarchical link
relationships.
1. Starting from Step 5 from the previous procedure, convert your flat list, input list
into a tree list. Choose a cell within the flat list and then choose Add Tree Level.
If the Add Tree Level is disabled, you're working from a query list. To convert your
list to a tree list, you must first reconfigure your list to an input list.
2. Choose the link type to use when adding work items to a hierarchy, and then
choose Convert. The most usual choice is Parent-Child. You can only select from
tree topology link types. For more information, see Link type topologies and
restrictions.
Note the List type has changed to Tree, and a second Title column appears.
3. To add more levels to the hierarchy, choose Add Tree Level again. For example, if
you want to add a hierarchy of Epics, Features, and User Stories, you'll want to
have Title 1, Title 2, and Title 3 columns.
If you want to add tasks, add another tree level to have four title columns. To
remove a column, see Remove a tree level.
4. Save your Excel file.
5. Enter the Work Item Type and Titles for the hierarchy you want to import. The
State fields automatically fill in with default values once you select the work item
type.
IDs are now assigned to your work items. In the background, the link type you
selected is used to link each work item in the hierarchy. Epics are linked to
Features, Features are linked to User Stories.
7. To check the links made, choose a work item and choose Links and Attachments.
For example, here we show the Child and Parent links created for a Feature that
was imported.
8. To enter a row under a work item where you want to add a child, choose the row
and then choose Add Child.
10. To change the hierarchy, cut and paste the row of a work item to place it under the
new parent. Make sure that you select the entire table row. When you publish the
change, the old hierarchical links are deleted and the new hierarchical link are
created.
You can use the or indent/outdent icons to demote or

promote a work item within the tree hierarchy. Verify that the column to the left or
right of the parent work item's title is a Title column. The header at the top of the
column should read Title n, if it doesn't, add a tree level.
Remove a tree level
1. First, publish changes that you've made to work items before you remove a tree
level. Removing a tree level requires a refresh, which overwrites data in the work
item list. You'll lose any data you haven't published.
2. Next, delete any content under the tree-level Title number column you want to
remove—the highest numbered column—. This column should be the highest
numbered column in the tree.
3. Refresh your worksheet. The column containing empty values for the Title is
removed.
You'll receive an error message if you attempt to delete the column.
Useful tips when working with a tree list

Excel interprets the data in the Title columns to determine the pattern of links
between work items. When you publish changes, any of the following conditions
can result in an error, an invalid link, or a tree link to be created between incorrect
work items:
A row between the work items is blank within the hierarchy
The Title of a work item is in the wrong column. Make sure you enter a title for
each child work item.
Within a row, multiple Title columns contain data. Enter text in only one of the
title columns within each row.
The list was sorted. Don't sort a tree list. Sorting a tree list can change the
hierarchical link relationships. If you do sort a tree list, you can recover from this
operation by immediately refreshing.
To resolve an error, see Resolve invalid links.
A parent-child linked work item can only have one parent. You can't add the same
work item task to two backlog items. Instead, you need to define distinct work
item tasks.
Update work items in bulk with a query list

The easiest way to bulk update many work items is to create a query with the work
items you want to update, and then open that query in Excel.
 Tip
Follow these tips to keep your work in sync:
When you first open a saved worksheet, use (Refresh) to download the
latest data from the data store.
Enter data for additional fields by adding columns to the worksheet using
Choose Columns.
To avoid data conflicts, publish your additions and modifications often.
To prevent loss of data before you publish or refresh, save your workbook
periodically.
1. From the web portal or Visual Studio, create the work item query that contains the
work items you want to update. For more information, see Create and save
managed queries with the query editor.
3. If you opened your query from the web portal or Visual Studio, you're done. Make
any changes you want. Open Choose Columns, add fields, make assignments, and
publish your changes.
4. If you start from Excel, open a blank worksheet. You can add a worksheet to an
existing workbook, as long as you're choosing a query from the same project the
workbook is bound to.
6. From the New List dialog, choose Query list, and select the query you want from
the drop-down menu.
The icon next to each query indicates the query type. The first two query types, Flat
list of work items and Work items and direct links are imported as flat list queries.
Only the Tree of work items queries import as a tree list.
7. With the work items imported to Excel, make the modifications you want and
If you're working with a tree list, see also the information provided in Import a
hierarchical list of work items.
Enable Tree commands

If the Tree group commands aren't available, your worksheet is configured as a flat list,
query list. Convert the list to either an input list or a list based on a tree query to enable
the Tree group commands. To learn how, see the next section on Change your list type
or query.
Change your list type or query

You can change the work items listed in your worksheet. Specifically, you can:
Change your flat list to a tree list

Change from a query list to an input list
Change from an input list to a query list
Change the query your worksheet references
If you want to change your flat list to a tree list, you can. However, if your list is a query
list, then you first need to reconfigure the list. You'll know that it's a flat list, query list as
the Tree group commands are disabled.
To convert your query list to an input list, follow these steps.
1. First, publish whatever changes you have made.
2. Next, on the Team ribbon, choose Configure, List.
3. Choose Refresh work items only and then Apply.
This choice changes the query list to an input list.
4. To convert from an input list to a query list, choose Refresh from query, select the
query, and then Apply.
Add existing work items to your worksheet
If you're working from a query, modify your query to contain the work items you want.
Then refresh your list. The other work items appear in your list.
If you're working with an input list, complete these steps.
1. From the Team ribbon, choose Get Work Items.
2. Choose the method you want from the three options available.
If the work items are defined in another project, then first select the Project. Then,
make your selections:
Query. Use this method when you've defined a query that contains the set or
superset of work items you want.
IDs. Use this method when you know the IDs of the work items that you want
to link to. In the IDs box, type the IDs of the work items that you want to find,
separated by commas or spaces.
Title contains. Use this method to find work items that have a common word
or phrase in the title field. In the and type list, select the type of work item
that you want to retrieve.
７ Note
To minimize the time required to run the query, narrow the filter criteria of the
search.
3. Choose Find.
Only those work items defined for the selected project and specified work item
type are listed. To sort on a column field, choose the column Title.
4. In the list of returned work items, select the check-box of one or more work items.
Select each work item that should link to the current work item. You can also
press the SHIFT key while clicking to select a range of work items, or press
the CTRL key while clicking to select multiple work items.
Choose Select All to select all work items in the list.
Add or remove column fields

If you start your worksheet with a New List, you'll see only a set of default field columns.
You can add columns using the Choose Columns on the Team ribbon.
If you start your worksheet from an existing query, you'll see all the column fields
defined for the query. From there, you can add columns using the Choose Columns.
However, your additions don't modify the underlying query.
1. To assign values to other fields, choose Column Options to add the fields of
interest.
To filter the fields based on work item type, select the Work item type.
To move or remove a field, choose the field and then select the > or < icons.
To change the field sequence, move the field up or down in the list using the
up and down arrows.
You can add a rich-text field, such as the Description field, however you may
lose some of the formatting upon publish.
2. Once the fields appear in the worksheet, assign values and publish your updates.
When working with identity fields, ones that accept user accounts, see the next
section, Select user accounts.
3. Save your worksheet.
Select user accounts

You can use the Select User feature to find user accounts and assign values to person
named fields. Also, this feature provides access to the most recently used (MRU) values.
If your team contains several hundreds or thousands of user accounts, you'll want to use
this feature.
 Tip
Without the Select User feature, you must enter user names exactly as they are in
the database, or you'll receive data validation errors upon trying to publish.
1. If you haven't installed or updated to the latest version of Visual Studio (at least VS
2015.1 or later version , do that now. You need the latest update to access the
Select User feature.
2. Choose an identity or person-named field to activate the Select User feature in the
Team ribbon.
An identity or person-named field is a field that contains a user identity. These

fields are typically synchronized to a database of user accounts, such as Azure
Active Directory, Active Directory, or a Workgroup.
3. Begin entering the name of the user account and the Assign User dialog
automatically filters the results until you can select the account of interest.
Enter a letter to tab to the start of names beginning with that letter. Enter only user
names as account aliases aren't recognized.
You'll notice that as you select user names, Excel remembers your recent selections
and you can select the user accounts directly from the field.
Link work items

You can complete many actions from the Links tab of the Links and Attachments dialog.
Specifically, you can:
Review the existing links defined for the selected work item
Add links to selected work items to one or more work items or select objects
Delete links
Open a linked work item (opens in the web portal)
Edit the link type of an existing link
Add columns to the Link list and sort on that list
For more information on linking work items, see Link user stories, issues, bugs, and
other work items.
View and add links

You can't use the Links and Attachments dialog to bulk update work item links. You can
only bulk update tree-topology link types using a tree list.
1. To link a work item to other work items, choose the work item and then choose
Links and Attachments. From the Links tab, choose Link to and then choose the
Link Type and work item(s) you want to link to. Choose OK and then Publish.
When finished, choose Close to dismiss the dialog.
2. To link several work items to the same work item(s), multi-select them by using
Ctrl-click for consecutive rows, or Shift-click for non-consecutive rows.
Find work items to link to

From the Add link dialog, you can open a secondary dialog to choose one or more work
items to link to. If you're going to find and list work items to link to by using a saved
query, first define the query to use.
From the Add link dialog, choose the Browse button (Visual Studio) to open the
following dialog.
The Choose Linked Work Items dialog works in the same way as the Get Work Items
dialog. For more information, see Add existing work items to your worksheet described
earlier in this article.
Add columns to the links list

1. From the Links tab, choose the Columns icon, and add the fields you want
displayed. Here we add the Assigned to and State fields.
2. To reorder the links, choose the field to sort the list on that field.
This dialog works in the same way as the Get Work Items dialog. See Add existing work
items to your worksheet described earlier in this article.
Open a linked work item

From the Links tab, choose the linked work item, right-click to open the context menu,
and choose Open Linked Item.
The work item opens in your web portal.
Edit the link and change the link type

You can edit any link listed. You can change the link type and the work items linked to.
1. Choose the link and choose the Edit icon.
2. Change the link type as needed.

3. To change the work item linked to, enter the ID of the work item, or choose
Browse to find the work item(s) to link to.
The Choose Linked Work Items dialog works in the same way as the Get Work
Items dialog. For more information, see Add existing work items to your worksheet
described earlier in this article.
Add attachments
To add attachments, choose the work item, then Links and Attachments, and then
the Attachments tab.
Choose the file you want to attach, then choose OK and then Publish.
To add the same attachment(s) to several work items, multi-select them by using
Create a report
You can create a report or chart from the web portal for flat-list queries. See Track
progress by creating status and trend query-based charts.
） Important
You can only create an Excel report using New Report from an on-premises Azure
DevOps Server. These reports require that your project's project collection is
configured to support SQL Server Analytics Server.
You can create a report using the New Report feature based on a flat list of work items.
For more information, see Create Excel reports from a work item query.
Resolve publishing errors

To resolve publishing errors that arise when working in Excel, see one of the following
articles:
Resolve data conflicts: A data conflict occurs when a field value is changed in Azure
Boards since the last time you published from Excel.
Resolve data validation errors: A data validation error occurs if a field value violates
the rules for that field and work item type.
Resolve invalid links in a tree hierarchy: An invalid link occurs if a team member
view work items in Excel as a hierarchy or tree list, and then moves a work item or
sorts the list such that it breaks the dependencies between work items. You can
resolve this error by reviewing the error message and repositioning work items to
reflect the work item structure.
Address Error TF208104: Hierarchical Link Relationship Is Locked:

If you receive error TF208104, the changes you made to the fields are published.
But your changes to the link hierarchy aren't published. At least one of the link
relationships defined for the work item is locked by another process, such as
Project Server integration.
Related articles
Bulk modify work items (web portal)
Azure DevOps Office integration issues
FAQs: Work in Excel connected to Azure Boards
Bulk import or update work items using CSV files
View and add work items
Basic Excel tasks
Import & update bulk work items with
CSV files
Article • 06/06/2023
Import and export work items in bulk using a CSV formatted file in Azure DevOps. While
you can continue to use Excel for bulk import and updates, you can use the native
import/export feature that doesn't require Excel. For more information, see Bulk add or
modify work items with Excel.
７ Note
The export feature is available with Azure DevOps Server 2019 Update 1 and
later versions. The import feature is available with Azure DevOps Server 2020 and
Azure DevOps Services.
Import new work items

All work items that you import get created in a New state. This rule means that you can't
specify field values that don't meet the field rules for the new state. For example, when
you create a new user story with the Agile process, the State = New and the Reason =
New. You can't specify any other values.
1. Create a local import.csv file and open it in Visual Studio Code or Excel.
2. The file must contain the Work Item Type and the Title fields. You can include
other fields as needed. For a list of default fields, see Work item field index.
In the following example, we include the Priority field.
CSV
Work Item Type,Title,Priority

Issue,Fix issues with code,1
Issue,Merge testing modules,3
Issue,Open private preview for select customers,2
Issue,Enable feature for customer champs,2
Issue,Remove old test code,2
3. From the web portal for your project, open Boards > Queries, and then select the
Import Work Items option.
4. Select your CSV file and then choose Import.
The import process loads the imported work items into the queries view in an
unsaved state. No IDs get assigned.
5. Verify the results and then select Save items to save the work items.
７ Note
Don't assign IDs to new work items that you're adding, otherwise you receive
an error message similar to the following if you do so.
6. The system highlights those work items with data issues. Resolve the data issues
before you save the work items. In this example, an invalid value has been entered
into the Priority field. Fix the data by opening the work item directly. Instead, use
bulk edit to fix several work items with the same issue.
 Tip
You can add parent-child links between work items you import by indenting the
title columns as shown in the example later in this article, Can I import a CSV file
that have parent-child links?. However, you can't specify any other link types when
importing or updating work items.
Update existing work items
1. To update work items, create a query that contains all the columns you want to
export and possibly edit. Save your query and select Export to CSV to save the
data.csv file to your local machine.
The exported file should look similar to the following syntax:
CSV
ID,Work Item Type,State,Assigned To,Title,Tags

"1043","Issue","To Do",,"Fix issues with code",
"1044","Issue","To Do",,"Merge testing modules",
"1045","Issue","To Do",,"Open private preview for select customers",
"1046","Issue","To Do",,"Enable feature for customer champs",
"1047","Issue","To Do",,"Remove old test code",
2. Make the edits to your work items. Your CSV file must contain the ID, Work Item
Type, Title, and State fields. Any other fields you want to include are optional.
７ Note
When you import identity fields, enter the name and email in the following
format "Display Name <email>" . For example, to assign work to Jamal
Hartnett, specify "Jamal Hartnett <fabrikamfiber4@hotmail.com>" . If you
specify a value that isn't recognized as a valid user to the system, you may
encounter problems with the import.
In the following example, we change several values on existing working items.

ID,Work
"1043","Issue","To Do","Jamal Hartnett

<fabrikamfiber4@hotmail.com>","Fix issues with code",architecture
<fabrikamfiber4@hotmail.com>","Merge testing modules",testing
"1045","Issue","To Do","Raisa Pokrovskaya
<fabrikamfiber5@hotmail.com>","Open private preview for select
customers","customer focus"
<fabrikamfiber5@hotmail.com>","Enable feature for customer
champs","customer focus"
"1047","Issue","To Do","Christie Church
<fabrikamfiber1@hotmail.com>","Remove old test code",architecture```
3. Save the file and import (see steps 4-6 from the previous import section.)
4. The results list with work items that contain value changes appear highlighted in
bold. Select Save Items to apply the changes.
5. Work items with data issues get highlighted in red and must be resolved before
you can save them. In this example, an invalid value appears in the Assigned To
field. Fix the data by opening the work item directly. You can use bulk edit if you
have many work items with the same issue.
Export list as a CSV file
query, select the actions icon, and then select Export to CSV.
Export and import work items to a different

project
You can use this feature to export work items from one project and import them to
another project. However, before you import them to another project, you must remove
the work item ID. You get an error if you attempt to import new work items to a project
with an ID specified.
Import or update rich-text fields

You can update or import rich-text fields such as the Description or Acceptance Criteria
fields. Rich-text fields are HTML formatted fields. Replace lines ending in CRLF by
surrounding sentences with ... .
For example, you can import the following work item, which includes three lines of text
in the Description field.
CSV
Work Item Type,Title,Description

"Product Backlog Item","Hello World Web Site - 8"," You can
include bold text And italic text
 Underline text"
FAQs
Q: Can I import new items and update existing items in

the same CSV file?
A: Absolutely! Leave the ID field empty for any new work items. In the following
example, the last entry for an Epic doesn't specify an ID.
CSV
ID,Work Item Type,Title,Assigned To,State,Priority,Tags

"16504","Issue","Fix issues with code",,"To Do","1",
"16505","Issue","Merge testing modules",,"To Do","3",
"16506","Issue","Open private preview for select customers",,"To Do","2",
"16507","Issue","Enable feature for customer champs",,"To Do","2",
"16508","Issue","Remove old test code",,"To Do","2",
,"Epic","Track Telemetry for data imports",,"To Do","2",
Q: How do I add multiple tags?

A: You can add multiple tags separated by a semicolon. For more information, see Tasks
you can and can't do with Excel.
Q: Can I import a CSV file that has parent-child links?

A: Yes, you can add child work items by indenting title columns. The following example
adds three child issues under the already defined Epic.
CSV
ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags

"165","Epic","Track Telemetry for data imports",,,"To Do","2",
,"Issue",,"Fix issues with code",,"To Do","1",
,"Issue",,"Open private preview for select customers",,"To Do","2",
,"Issue",,"Enable feature for customer champs",,"To Do","2",
Q: How do I know if my imported file has errors?
A: You can test by adding tags with spaces and hyphens, for example, and include it in
the export. The import should match the same format. Any problems with the
formatting of your CSV file appear in the Results page of the import view. You can't
import the work items until the formatting and syntax is correct.
The work item results always list the data errors found for individual work items. Fix each
error either from the web portal, or in the CSV file and import again.
Q: Why am I getting errors for some identity values?

A: When you use the Web UI, the identity picker goes through extra steps to validate the
user. First it checks to see if the person is a valid user in the org. If not, it searches on the
identity in Azure Active Directory (Azure AD). If the user's in Azure AD but not in the org,
that user gets added to the valid identities. When you import via CSV, for performance
reasons, the identity picker doesn't go through these extra steps. It only checks to see if
there's a matching UPN already in the org. If it doesn't find a matching UPN, it reports
that the identity is unknown.
Q: Does CSV import support all work item types?

A: No, the CSV import doesn't support the following work item types:
Code Review Request

Code Review Response
Feedback Request
Feedback Response
Test Case
Test Plan
Test Suite
Shared Parameter
For more information, see Bulk import or export test cases.
Related articles
Bulk move work items and change the
work item type in Azure Boards
Article • 02/24/2023
Often you find that someone created a work item of the wrong work item type (WIT) or
within an incorrect project. You can correct these issues for individual work items or bulk
modify several work items. You can also remove work items added to your backlog or
taskboard that aren't relevant anymore.
 Tip
For TFS 2018 and earlier versions, you can't change the work item type for an
existing work item, but you can copy the work item and specify a new type. Also, if
you have several work items with type changes you want to make, you can export
them using Excel, and then re-add them as a new type.
To remove, delete, or restore deleted work items, see Remove, delete, or restore work
items.
＂ How to change the work item type of one or more work items
＂ How to move one or more work items to another project
 Tip
From the web portal, you can multi-select several work items from a backlog or
query results page and perform a bulk update using the associated feature. To
change, move, delete, or restore several work items at the same time, see Bulk
modify work items.
Prerequisites
You must be a member of the Contributors or Project Administrators security
group. To get added, Add users to a project or team.
To 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 change the work item type, you must be granted Stakeholder access or higher.
To move work items to another project, you must be a member of the Project
Administrators group or have the Move work items out of this project permission
set to Allow. By default, the Contributors group doesn't have this permission set.
Users granted Stakeholder access don't have access to this feature.
７ Note
Users with Stakeholder access for a public project have full access to all work
tracking features just like users with Basic access. For more information, see
For more information, see Set permissions and access for work tracking or Change
project-level permissions.
） Important
You can't change type or move work items whose work item types support test
management or that belong to the Hidden Types Category. This includes all work
items that track tests—such as test cases, shared steps, and shared parameters—
code review requests and responses, and feedback requests and responses.

Changing the work item type refreshes the work item form with the fields defined for
the type selected. For example, you can change a bug to a task and the form refreshes
with the fields defined for a task.
７ Note
You can't change the work item type if the project is defined on a collection that
uses the On-premises XML process model. Also, you can't change the work item
type of work items associated with test management.
You can change a single work item or several multi-selected work items to a new type.
1. Open a work item, choose the actions icon, and select the Change type...
option.
Or, from the backlog or query results page, multi-select several work items whose
type you want to change. You can select several work items of the same type or
different type so long as you want to change them all to the same work item type.
Choose the actions icon, and select the Change type... option.
） Important
From the Query Results page, the Change type… option becomes unavailable
if you have checked the Query Editor's Query across projects checkbox.
2. Select the type and optionally enter a comment.

Comments are automatically added to the Discussion control and an entry is made
to the History control. Also, the system automatically resets the State and Reason
fields to the default initial values for the work item type that you move.
3. Save the work item(s) to complete the change.
７ Note
The system automatically resets the State and Reason fields to the default
initial values of the specified type. However, in some cases you may need to
open the work item to change the State or Reason field to a value supported
by the changed-to work item type.
From the Query Results page, save all work items that you bulk-modified. When
you bulk modify items from the backlog, they're automatically saved. Work items
shown in bold text indicate that local changes haven't yet been saved to the data
store. The system automatically saves each work item. Refresh the page to reflect
your changes.
Move a work item to another project

When you discover that a work item belongs to a different project within your
organization or collection, you can move it where it belongs. You can move a single
work item or several multi-selected work items.
Note the following:

You can only move work items from one project to another project within the
organization or collection.
You can only move work items whose type exists in the project you're moving it to.
For example, you can't move User Stories to a project based on the Scrum process
that doesn't contain User Story as a work item type.
You can't move work items associated with test management.
To move work items to another project, you must be a member of the Project
Administrators group or be granted explicit permissions to move work items.
Users granted Stakeholder access don't have access to this feature even if granted
permission.
1. Open the work item and choose the Move... option from the work item form's
Actions menu.
If you don't see the option, then you haven't been granted permissions to move
work items out of the project.
Or, from the backlog or query results page, multi-select several work items that
you want to move to another project. You can select several work items so long as
you want to move them all to the same project.
Choose the actions icon to open the context menu of one of the selected work
items, and choose the Move… option.
2. Select the destination project and choose the other options available, including
changing the work item type. Optionally enter a comment.
７ Note
Child work items are not moved. They remain in the origin project, but the
Parent-Child links remain in place.
Comments are automatically added to the Discussion control and an entry is made
to the History control. Also, the system automatically resets the State and Reason
fields to the default initial values for the work item type that you move.
Related articles
Remove or delete work items
Remove, delete, or restore work items in
Azure Boards
Article • 02/24/2023
2018
Work items can live forever in your work tracking data store. You never have to delete
them. However, you might want to set up a work item management process for one of
the following actions:
Change state: Remove work items from appearing on backlogs and boards by
changing the work item State to Remove or Cut. The state available to you is based
on the workflow assigned to the work item type.
Delete: Remove work items from backlogs, boards, and queries. Deleted work
items are moved to a Recycle Bin.
Restore: Recover deleted work items by restoring them from the Recycle Bin.
Destroy: Permanently delete work items, which deletes all data from the work
tracking data store.
７ Note
The ability to archive work items or projects isn't a supported feature at this time.
To move a work item from one project to another, or to change the work item type, see
Move work items, change work item type.
７ Note
For information about the Azure Artifacts Recycle Bin, see Delete and recover
packages.
Prerequisites
In general, members of the Contributors group can remove, delete, and restore work
items. To permanently delete work items, you must be a member of the Project
Administrators group, or be granted the required permission. Users with Stakeholder
access can view the contents of the Recycle Bin, but can't restore or permanently delete
items in the bin regardless of the permissions they're granted.
Task
Required permission(s)
Change state to Remove or Cut

Have the Area Path permission set to Allow: Edit work items in this node
By default, members of the Contributors group have this permission.
Delete work items and

Restore work items
Have the project-level permission set to Allow: Delete and restore work items
Have Basic access or higher.
By default, members of the Contributors group have this permission.
Permanently delete or destroy work items

Have the project-level permission set to Allow: Permanently delete work items
By default, members of the Project Administrators group have this permission.
Delete or destroy work items from the command line

Have the project-level permission set to Allow: Permanently delete work items
By default, members of the Project Administrators group have this permission.
For a simplified view of permissions assigned to built-in groups, see Permissions and
access.
７ Note
Users with Stakeholder access for a public project have full access to all work
tracking features just like users with Basic access. For more information, see
Remove or delete multiple work items

You can act on individual work items or bulk modify several work items.
From the web portal, you can multi-select several work items from a backlog or query
results page. You can also do a bulk update using the associated feature. To delete or
restore several work items at the same time, see Bulk modify work items.
Remove work items

By changing the State of a work item to Removed, you effectively remove it from a
backlog or board view (product, portfolio, and sprint backlogs, Kanban board, and
Taskboards). The Removed state corresponds to the Removed workflow category state. If
you define custom workflow states, any state you map to the Removed workflow
category state act in a similar way.
To cause removed items to not show up in queries, you must add a clause that filters on
the State field.
７ Note
The Removed state isn't supported with the Basic process. It is only supported with
the Agile, Scrum, and CMMI process work item types. The Basic process is available
when you add a project to Azure DevOps Services or Azure DevOps Server 2019
Update 1 .
Delete work items

Deleted work items won't appear in your backlogs, boards, or queries. Deleted items are
moved to a Recycle Bin from which you can recover them if needed. To delete a test
case, test plan, or other test-related work item types, see Delete test artifacts.
You can delete work items in one of the following ways:
From within the work item form

From the Work Items page More Actions menu
From the Kanban board card context menu
From a backlog or query results page.
1. To initiate a delete operation:
From the work item form, open the work item, choose Actions, and select
Delete.
To delete several work items, multi-select them from a backlog or a query results
list, choose the context menu, and then select Delete.
To delete a work item from your Kanban or taskboard, choose the context
menu for the card and select Delete.
2. Confirm you want to actually delete the item(s).

Restore or destroy work items
You can't open work items that have been moved to the Recycle Bin. Also, you'll only
see the Permanently delete option if your Permanently delete work items project-level
permission is set to Allow.
You restore deleted work items or permanently delete them from the web portal Recycle
Bin.
1. Choose Boards>Work Items and then choose the Recycle Bin.
If you don't see the Recycle Bin option, choose More commands … and choose it
from the menu of options.
2. A new browser tab opens with the query that lists work items added to the Recycle
Bin.
3. Select the items you want to restore and then choose Restore.
Optionally, you can choose to permanently delete the items.

4. Confirm your selection.
７ Note
Deleted test artifacts won't appear in the Recycle Bin and can't be restored. Deletion
of test artifacts deletes the selected test artifact and all of its associated child items,
such as child test suites, test points across all configurations, testers (the underlying
test case work item doesn't get deleted), test results history, and other associated
history.
Delete or destroy work items from the

command line
You can delete or destroy a work item with the az boards work-item delete command.
To get started, see Get started with Azure DevOps CLI.
７ Note
You can restore work items you delete, but you can't restore work items you
choose to destroy.
Azure CLI
az boards work-item delete --id

[--destroy]
[--org]
[--project]
[--yes]
Parameters
id: Required. The ID of the work item.
destroy: Optional. Permanently delete this work item.
org: Azure DevOps organization URL. You can configure the default organization
using az devops configure -d organization=ORG_URL . Required if not configured as
default or picked up using git config . Example: --org
https://dev.azure.com/MyOrganizationName/ .
project: Name or ID of the project. You can configure the default project using az
devops configure -d project=NAME_OR_ID . Required if not configured as default or
picked up using git config .
yes: Optional. Don't prompt for confirmation.
Example
The following command permanently deletes the bug with the ID 864 and doesn't
prompt you for confirmation.
Azure CLI
az boards work-item delete --id 864 --destroy --yes
Delete and restore processes

When you delete a work item, the following actions occur:
Generates a new revision of the work item

Updates the Changed By/Changed Date fields to support traceability
Preserves the work item completely, including all field assignments, attachments,
tags, and links
Causes the work item to become non-queryable and, as such, won't appear in any
work tracking experience, query result, or report
Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are
updated to remove deleted work items
Removes work tracking extensions
Preserves trend data except for the latest value
Removes the work item from the data warehouse/cube similar to as if it was
permanently removed.
When you restore a work item, the following actions occur:
Causes a new revision of the work item to be made

Updates the Changed By/Changed Date fields to support traceability
Becomes queryable
All fields remain unchanged
History contains two new revisions, one for deletion, and one for restore
Reattaches work tracking extensions
Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are
updated to include the restored work items
Restores trend data
Adds the work item back to the data warehouse/cube
Sets the area or iteration path fields to the root node if the previous area path or
iteration paths were deleted.
Use a REST API to delete, restore, and destroy

work items
To programmatically delete, restore, and destroy work items, see one of the following
REST API resources:
Recycle bin REST API Reference

Work Items - Delete REST API Reference
Related articles
Delete test artifacts
Stakeholder access quick reference
Delete test artifacts in Azure Boards
Article • 02/24/2023
2018
While test artifacts such as test plans, test suites, test cases, and so on, are all types of
work items, the method for deleting them differs from deleting non-test work items.
） Important
We only support permanent deletion of test artifacts such as test plans, test suites,
test cases, shared steps and shared parameters. Deleted test artifacts won't appear
in the recycle bin and cannot be restored. Deletion of test artifacts not only deletes
the selected test artifact but also all its associated child items such as child test
suites, test points across all configurations, testers (the underlying test case work
item doesn't get deleted), test results history, and other associated history.
When you delete test artifacts, the following actions occur:
1. Removes the deleted test artifact from the test case management (TCM) data store
and deletes the underlying work item
2. Runs a job to delete all the child items both from the TCM side and the underlying
work items. This action may take time (up to a few minutes) depending on the
number of artifacts to be deleted.
3. Causes all information in the work item tracking data store and TCM data store to
be deleted and cannot be reactivated nor restored.
Prerequisites
To delete test runs, you must be a member of the Project Administrators group or
have the project-level Delete test runs permission set to Allow.
To delete test plans and test suites, you must be a member of the Project
Administrators group or have the Area Path node-level Manage test plans or
Manage test suites permission set to Allow.
To manage or delete test artifacts, you must also have your access level set to
Basic + Test Plans or Visual Studio Enterprise. This level provides access to the full
Test Plans feature set. Users with Basic access and with permissions to permanently
delete work items and manage test artifacts can only delete orphaned test cases.
That is, they can delete test cases created from Work that aren't linked to any test
plans or test suites.
To delete test artifacts, the following restrictions and operations apply:
Users with Basic access and with permissions to permanently delete work items
and manage test artifacts can only delete orphaned test cases. That is, they can
delete test cases created from Work that aren't linked to any test plans or test
suites.
When you delete a test plan, test suite, test case, shared steps, or shared
parameters, you not only permanently delete them, you also delete all associated
test artifacts such as test results.
You can't bulk delete test artifacts. If test artifacts are part of a bulk selection to be
deleted, all other work items except the test artifact(s) get deleted.
Work item types that support the test

experience
The following image illustrates the set of work item types that support the test
experience and work with Microsoft Test Manager. These work item types are linked
together using the link types shown.
From the web portal or Microsoft Test Manager, you can view which test cases are
defined for a test suite, and which test suites are defined for a test plan. However, these
objects aren't connected to each other through link types. For definitions of each field
used in these work item types, see Query based on build and test integration fields.
Delete a test case, test suite, or test plan

1. To delete a test case, test suite, or test plan, open it from the web portal and
choose the Permanently delete option from the actions menu. (Bulk deletion isn't
supported from a query results page.)
７ Note
You'll only see the Permanently delete option if you have the necessary
permissions and access.
2. Confirm you want to actually delete the item.

3. You can also delete a test plan directly from Test Plans. To delete a test plan, open
Test Plans and choose More Actions for the plan you want to delete, and
choose Delete.
4. To delete shared steps and shared parameters, you need to first manually remove
all references to them before you can delete them.
Related articles
Create a test plan
Control how long to keep test results
Set permissions and access for work tracking, Manage test artifacts
Use templates to add and update work
items in Azure Boards and Visual Studio
Article • 05/02/2023
2018
Visual Studio 2022 | Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015
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 template that
defines the area path, iteration path, and activity to use when creating a task.
You can use work item templates to create work items or bulk update several work
items. For examples that show usage of work item templates, see Sample work item
templates.
７ Note
Work item templates are distinct from process templates. For more information, see
About processes and process templates or these specific articles for the default
process templates: Basic, Agile, Scrum, or CMMI.
Supported template tasks

The availability of template task options depends on the client and platform version
available to you. Add and manage work item templates from the web portal or from
Visual Studio 2015 or earlier versions. Visual Studio 2015 and earlier versions support
working with templates by installing the Microsoft Visual Studio Team Foundation Server
2015 Power Tools . These templates only appear in your view of Team Explorer.
As shown in the following table, a ✔️indicates the task is available from the web portal
or from Visual Studio 2015 or earlier versions. (Make sure that you've selected the content
version based on your platform version).
Task
Web portal
Visual Studio 2015

Capture a work item as a template
✔️
✔️
Manage work item templates

(Define, edit, delete, copy link, create copy, and rename)
✔️
✔️
Copy link (URL) of a template
✔️
✔️
Add a work item using a template
✔️
✔️
✔️
✔️
Apply a template to one or more work items
✔️
✔️
Add or remove tags from templates
✔️
Define a template using a hyperlink
✔️
 Tip
The templates you define through the web portal are distinct from those you define
through Visual Studio. Web portal templates can only be managed and applied to
work items through the web portal. Similarly, Visual Studio templates can only be
managed, viewed, and applied to work items in Visual Studio. However, you can use
the URLs of both template types to add work items through the web portal.
Prerequisites
To add, capture, edit, or delete work item templates through the web portal, you
must be a member of the team under which you add them.
To apply a work item template, you must be a Contributor of the project and a
member of the team under which the work item template is defined.
To add, capture, or edit work item templates through Visual Studio Team Explorer,
install the Microsoft Visual Studio Team Foundation Server 2015 Power Tools .
These templates only appear in your view of Team Explorer.
Capture a work item as a template

The steps to capture a work item differ based on the platform, version, and client you
use.
Web portal
Templates captured through the web portal are assigned a GUID.
1. From the web portal, open a work item that you'll use as the basis for a
template.
2. Choose the actions icon to open the menu. Choose Templates and then
Capture.
Name the template, select the team for which you want to save it under, and
optionally define or clear fields. Save the template when finished.
3. Once you've saved the template, choose Copy link to capture the URL for the
template.
4. You can paste the URL link into a browser to create a work item, or provide it
to others for their use to add work items. For example, you can add it as a
hyperlink to a project wiki, a dashboard via a Markdown widget, or other
shared network resource.
Use the URL whenever you want to add a work item of the type you've
defined with its predefined values.
Manage work item templates

You can view the list of templates defined for each work item type, and also add, edit,
copy, delete, rename, and copy the link of a template. All templates are defined and
managed for a team.
Web portal
You must be a member of the team to add or edit team templates.
1. From the web portal, open settings for a team.
Choose Project Settings.

Expand Boards and choose Team configuration. If you need to switch to a
different team, use the team selector.
2. Choose Templates.
From here, you can choose any work item type to view or add templates for
that type.
Manage templates for a work item type

Choose the work item type to view the templates defined for each type.
For example, choose User Story to view templates defined to capture user
stories.
Create a work item template
1. From the work item type page, choose the New template to create a
template from scratch.
2. Name the template and optionally add and remove fields. Save the template
when finished.
Once you've saved the template, select Copy link to capture the URL for the
template that you can use to add work items using the template.
Edit, rename, or copy a link to a template
1. From the work item type page, choose the actions icon for an existing
template to access the menu options to Edit, Delete, or Copy link.
2. To rename a template, choose to edit the template, change the name, and
then save your changes.
Create a copy of a template

1. To duplicate an existing template, choose the actions icon for an existing
template and select the Create copy option.
2. Name the template and optionally add and remove fields. Save the template
when finished.
Delete a template
1. From the web portal, open Project Settings>Team configuration>Templates.
2. Choose the actions icon to open the menu, and choose Delete.
3. Choose Delete from the Delete template confirmation dialog that displays.
As indicated in the confirmation dialog, you can't recover a template once it's
deleted.
Add a work item using a template

The main method for adding a work item using a template is to open the template link
within a browser window. To get the template link, see the next section Copy the link to
a template.
You can share these links through email, a network share, or a team dashboard.
Copy the link to a template

Use the URL whenever you want to add a work item of the type you've defined with its
predefined values. Copy the link to a shared network or send to your team via email.
Also, consider adding a link to the team dashboard.
Web portal
1. Go to Project Settings.
Expand Boards and choose Team configuration. Then, choose Templates.

2. Choose the work item type whose template you want to copy.
3. Choose the actions icon to open the menu, and choose Copy link.
You can save the URL as a text file or add the URL to a web page as a
hyperlink.
Apply a template to new or existing work

item(s)
You can apply a template to a single work item or do a bulk update of several work
items.
Web portal
Apply a template within a work item

1. Open a new work item or an existing work item that you want to update using
the fields defined within a template, choose the actions icon to open the
menu, select Templates, and then select the name of a predefined template.
Only those templates defined for teams that you belong to appear.
 Tip
Refresh your browser to discover the latest templates that have been
added. If you don't see any templates, it may be that there are none
defined for the work item type.
2. Save the work item for the changes to be applied. The fields changed are
noted in the History field.
Apply a template to several work items

1. To bulk update several work items, first select them from the backlog or a
query results list, and then open the actions menu for one of them. All work
items you select must be of the same work item type. For example, all user
stories or all bugs.
2. Choose the template to apply.

3. Field changes are automatically applied and work items saved. To learn more
about bulk updates, see Bulk modify work items.
Add or remove tags from templates

You can add tags to a template and they'll be applied to the work item when you use
the template. To add two or more tags, delimit them with a comma (,).
If you don't specify tags to remove, then all tags present in a work item remain defined.
They'll remain defined even when you apply a work item template to an existing work
item.
Define an unplanned work item template using

a hyperlink
You can specify a work item template that specifies several field values using the
following syntax. Use the URL whenever you want to add a work item of the type you've
defined with its predefined values.
URL
https://dev.azure.com/{OrganizationName}/{ProjectName}/_workItems/create/{Wo
rkItemType}?
[FieldReferenceName 1]={FieldValue 1}&
. . .
For example, the following syntax specifies a work item task with title TaskTitle. It
specifies values for the Assigned To, Description, Tags, Activity, and Iteration Path fields.
URL
https://dev.azure.com/{OrganizationName}/{ProjectName}/_workItems/create/Tas
k?
[System.Title]=TaskTitle&
[System.AssignedTo]=Jamal+Hartnett&
[System.Description]=
Always+include+Remaining+Work+and+links+to+any+related+bugs+or+user+stori
es.&
[System.Tags]=Web;+Phone;+Service&
[Microsoft.VSTS.Common.Activity]=Development&
[System.IterationPath]=Fabrikam+Fiber%5CIteration+1
 Tip
There is a 2000 character limit imposed by some browser clients.
You can save the URL as a text file or add the URL to a dashboard or web page as a
hyperlink.
Add a template link to a team dashboard

You can add links to a Markdown widget that appear on your team dashboard in the
web portal. These links open a work item with the template defined fields predefined.
For example, the following widget contains links to three templates.

To learn more about the Markdown widget see Add Markdown to a dashboard,
Markdown widgets.
Related articles
Azure Boards FAQs
Sample work item templates
View sample work item templates in
Azure Boards
Article • 08/22/2023
2018
Work item templates can help save time and provide guidance to your team when
defining user stories, features, bugs, or tasks. Teams use templates to support the
following goals:
Create bugs for specific product areas

Provide guidance to complete the work item
Create work items with specific tags
Define a bug template for use with another application or extension, such as Bug
Bash Pro .
Review this article for examples of defining specific values of work item templates. For
guidance on adding, managing, and applying work item templates, see Use templates to
add and update work items.
７ Note
Work item templates are distinct from process templates. For more information, see
About processes and process templates or these specific articles for the process
templates: Basic, Agile, Scrum, or CMMI.
Specify the Area Path

As an organization grows, the number of product or feature areas and number of teams
can grow in number. To support work items to appear on a team's backlog or board,
templates should specify the Area Path that the team owns.
In this example, the Voice team sets the Area Path= Fabrikam Fiber/Voice .
To learn more about area paths, see About area and iteration (sprint) paths.
Add guidance in a rich-text field

To provide guidance, enter HTML syntax into a rich-text field's value.
For example, here we add the following syntax into the Repos Steps field
HTML
Steps to reproduce: 1. Expected Behavior:

 1. Affected Branch: Affected Build: 
The work item form renders this example as shown.

Add work item tags
Work item tags are useful to quickly filter backlogs, boards, or queries. You can add tags
to track anything of interest, for example: Customer issue, Release, Milestone.
To add two or more tags, add them all within a single Tags (Add) field, entering a
comma between tags.
For example, here we add Web and Sept Release.
To learn more about tags, see Add work item tags to categorize and filter lists and
boards.
You can also use the Tags (Remove) template field to remove tags from work items. For
example, if many work items were tagged with Milestone 1, and that no longer applies,
you could query for all those work items and remove the tag by doing a bulk apply of a
template that removed the Milestone 1 tag.
Define and pre-populate custom fields

You can pre-populate a custom field that has been added to the work item type. Before
adding it to a template, you must first add it to the work item type. For inherited process
models, see Add and manage fields for an inherited process. For On-premises XML
process models, see Add or modify a field to track work.
For example, the Triage custom field can be set to False , indicating the bug needs to be
triaged.
Access other features through extensions
An often requested feature is to allow the creation of a work item that automatically
links to one or more work items. For example, a user story that links to five tasks. Work
item templates don't support this capability. However, you may find a Marketplace
extension supports this feature. For example, see the following extensions:
Work item form one click actions

1-Click Tasks
1-Click Child-Links
Extensibility
You can programmatically interact with work item templates to create, get, list, and
delete using the Templates REST APIs.
Related articles
View and update work items via mobile
browser
Article • 07/13/2023
2018
With the mobile browser and work item form, you gain on-the-go features to stay on
top of the latest updates made to work tracking. When you select any work item link on
your mobile device, it opens a mobile-friendly version of the work item. From there, you
can update the work item or access all work items assigned to you or that you're
following.
７ Note
The mobile browser supports Azure DevOps work tracking. To sign up for free, go
to Azure DevOps Services . The mobile browser is not an app, but a mobile view
into select features. There is nothing to download. You access the mobile browser
by selecting a link from a work item you receive in your mobile email application.
Open the mobile work item form
The mobile work item form opens when you select View work item from an email you
receive from your mobile device. You receive this type of email under the following
circumstances:
Changes were made to a work item you're following.

You were @mentioned in a discussion.
A notification email gets sent based on the work item alerts you've set using
Manage personal notifications.
Update a work item

Within the mobile form, you can do almost everything you can do from the web portal
form. Here are the actions you can take in the order they appear in the mobile form:
Add and remove tags

View and add to the discussion, select on the comment to add to the discussion
View and update any field within the form (Assign to, State, Area, Iteration,
Description, and more)
View and open a link within the Development section
View History
View and open a link from the Links tab
Open and add an attachment from the Attachments tab
Actions not available to you within the mobile work item form:
You can't create or add new work items

You can't initiate a development operation
You can't add a link
Interact with mobile form controls

Mobile form controls operate as follows:
Select any field to edit it and the form changes to a full-screen experience. Some
of the most common actions include changing the state of an item, moving to a
different area path, adding an attachment, and creating/removing tags are all
supported.
Select the save icon to save your changes.
Update status (change State)

To update the state, select the state you want.
Add or remove tags

To add a tag, enter the text you want.
View history
Select History to view the work item's history.
View and open work items in your activity lists

From within the mobile work item form, you can access your work items. The mobile
browser allows you to view and open work items that fall into these categories:
Assigned to me: lists all work items assigned to you

Following: lists all work items that you have elected to follow
My activity: lists all work items that you have recently viewed or updated.
The lists available from each page span all team projects that you work in.
1. Select the list control from the work item form you opened.
2. Select Work items.
The browser opens to the Assigned to me page. From there, you can choose Following
or My activity to access the other pages. For more information, see View and add work
items.
Related articles
More experiences are in the works to improve and expand on the mobile experience.
For more information, see the blog post, The mobile work item form (preview) .
Set personal notifications

Set team notifications
Follow a work item
Provide feedback for the mobile experience

Help us improve the mobile experience.
To provide feedback, select the list control from the work item form and then select
Make a suggestion. You can also Report a bug and Contact support.
Use backlogs to manage projects
Article • 08/17/2023
2018
With backlogs, you can quickly plan your project by adding user stories or requirements
to your product backlog. Once you have your plan in place, you can start driving code
development efforts.
If you're a project administrator, see Configure and customize Azure Boards, which
shows you how to define area and iteration paths and customize your work item types.
When you create a project or add a team, your backlog automatically gets created. Each
team has access to their own product, portfolio, and sprint backlogs as described in
About teams and Agile tools.
About backlogs
An Azure Boards backlog is a prioritized list of work items that guides your
developments team's effort, helps manage project scope, and facilitates effective
communication and collaboration through the software development lifecycle.
Use backlogs to do the following tasks:
Define user stories, product backlog items, or requirements

Reorder your backlog
Add details and estimates to your backlog items
Bulk update
Drag items to a sprint
Map backlog items within a hierarchy
Review the hierarchy or portfolio of work assigned to multiple teams
Forecast work
Display rollup progress, counts, or totals
７ Note
For more information, see Backlogs, boards, and plans. In case you're not seeing
the desired work items on your backlog or board, see Set up your backlogs and
boards to configure them according to your preferences.
Product and portfolio backlogs
Backlogs present work items as lists. A product backlog represents your project plan,
the roadmap for what your team plans to deliver. It also provides a repository of all the
information you need to track and share with your team.
In Agile methodologies, a portfolio backlog allows you to group and organize your
backlog into a hierarchy and displays high-level initiatives, epics, or projects that your
organization plans to work on over a longer period of time. These initiatives are often
too large or complex to fit within the scope of a single team's backlog, and they require
coordination and planning at a higher organizational level.
Backlog configuration
７ Note
How do I add a backlog or board? You don't add backlogs or boards. You add a
team which is automatically configured with it's own set of backlogs and boards as
described in About teams and Agile tools.
Each backlog is associated with a team and the team configuration settings determine
the work items that appear on the team backlog. The team administrator does the
following tasks for their team:
Select the Area Paths that are active for the team, only work items assigned to
these area paths appear on the team's backlog
Set the default Area Path and Iteration Path used when defining work items from
the team backlog
Select the Iteration Paths that are active for the team
Determine which backlog levels are active for the team
Define how bugs get treated, as requirements or as tasks
Define iteration (sprint) paths and configure team iterations

Define area paths and assign to a team
Select backlog levels
Show bugs on backlogs or boards
 Tip
Each team member has several tools to configure their backlog view:
Expand/Collapse one level, Column Options, Backlog level selector, View options,
and Filter toolbar. Options set for each backlog level are distinct and persist until
changed. For more information, see Configure your backlog view.
Common backlog configurations for multiple teams

Question: Can you define a backlog configuration that multiple teams can subscribe to?
Answer: No. Each team controls their own team settings and backlog configurations.
Because each user can configure their own Column Options and View Options, there's
no way to configure a common backlog view for all teams. Also, there's no default
column options that can be set for each team.
Define work items and create your backlog

You build your project plan by creating a backlog of work items. These items represent
the features, requirements, user stories, or other work to complete. Portfolio backlogs
provide support for organizing work in a hierarchical fashion. They help track major
product initiatives or scenarios that rely on many stories or requirements. Different types
of work items help you track different types of work, such as user stories, tasks, bugs,
issues, and more.
Backlog priority or stack rank order
The sequence of items on each backlog is determined according to where you've added
the items or moved the items on the page. As you drag items within the backlog list, a
background process updates the Stack Rank (Agile and CMMI processes) or Backlog
Priority (Scrum process) fields. These fields are used by the system to track the relative
ranking of items on the product, feature, epic, or other portfolio backlog. By default,
these fields don't appear on the work item form.
Don't use the bulk modify function to change the value of the backlog priority field.
While you can assign a value to these fields, you assign the same value to all items
you've selected for bulk edit.
The preferred method for bulk edit is to use multi-select to move items to the top,
bottom, or specific position within the page. If you must edit one of the backlog order
fields in bulk to get a large number of work items in the priority order you want, use
Excel. You can export a query containing the backlog items, update either the Backlog
Priority or Stack Rank fields, and then publish your changes.
In Progress items and work listed on the

backlog
Backlogs are designed to display work that corresponds to a Proposed, In Progress, or
Resolved category state. Once you've completed work and its state enters a Done, or
Closed state, then it falls off the backlog view. You can always create a query to view
completed work, or view the Recently completed pivot from the Work Items page.
In general, you display all items that are in the In Progress category state, which
corresponds to the Active and Committed states. To focus on work that is proposed but
not in progress, you can toggle the backlog view to turn off In Progress. This toggle is
useful when forecasting your product backlog.
If your backlog is missing items, check whether the In Progress view is turned off. For
more information, see Workflow states and state categories.
Organize your backlog by mapping and

reparenting backlog items
When you have many initiatives your teams are working on, you may want to group the
work according to these initiatives. By defining features and epics, you can group your
work into a three-tiered hierarchy consisting of epics, features, and backlog items.
For example, here the Customer Service team has organized several backlog items
under two features and one epic.
Velocity
When you assign your backlog items to sprints, you'll gain access to an in-context
velocity report for both product and portfolio backlogs. Velocity helps teams determine
how much work they can perform sprint-over-sprint.
You can quickly configure the Velocity report to count work items or sum Story Points,
Effort, Remaining Work or other numeric field.
For more information, see View or configure team velocity
Display rollup progress counts, or totals

Product and portfolio backlogs support rollup columns. You can add one or more rollup
columns to display progress bars, counts of descendant work items, or totals of select
numeric fields. Your settings persist for each page that you customize and are only valid
for your views.
Progress bars indicate the percentage of descendant items within a hierarchy that
are closed or completed.
Counts display the total number of descendant items.
Totals provide a sum of numeric fields, such as Effort, Story Points, Completed
Work, or Remaining Work of descendant items.
The following example shows progress bars for a portfolio backlog.

Work with multi-team ownership of backlog
items
When you have several teams, your hierarchical views may show items that belong to
other teams.
View backlog items and parent items owned by other

teams
Your team's product backlog lists only those items whose area path matches items
assigned to your team. But, if you show parents, you see the parent epic of the features
and backlog items, even if another team owns the epic or feature.
Other team-owned items appear with an information icon .

 Tip
Add the Node Name field as a column to identify the area path/team associated
with the work items.
For more information, see Define area paths and assign to a team.
View epics and child items owned by other teams

Here's another example that shows the Epics backlog for the Management team.
Drilling down, you can see all the backlog items and features, even though they belong
to one of three different teams: Customer Service, Phone, and Web.
From these views, you can reparent items that you own and items other teams own. But,
you can't reorder items that another team owns.
This organization enables management teams to focus on high-level features and epics,
and development teams to focus on just the backlog items they're responsible to
deliver. Add teams and set their area paths. For example, you can create a team
structure similar to this one with two management and three development teams.
For more information about hierarchical team and backlog structures, see Portfolio
management.
Reordering and reparenting work items

All backlogs and boards support dragging to reorder and reparent work items. Updates
made to one team's backlogs and boards are reflected in other team backlogs and
boards that share the same area path. You may need to refresh the page to view the
changes.
You can only use dragging to reorder or reparent work items assigned to area paths
selected for your team. When the Parents view option is enabled, work items may
information icon can't be reordered nor reparented as another team owns it.
Display leaf node work items

For TFS 2018 and earlier versions, the Kanban board only shows the leaf node with
nested items of a same-category hierarchy. For all versions, sprint backlogs and
Taskboards only show the last node in a same-category hierarchy, called the leaf node.
While you can create a hierarchy of backlog items, tasks, and bugs—we don't
recommend that you create same-category hierarchies. In other words, don't create
parent-child links among work items of the same type, such as story-story, bug-bug, or
task-task. The last node in a same-category hierarchy may only appear on Kanban
boards, sprint backlogs, and Taskboards. For example, if you link items within a same-
category hierarchy that is four levels deep, only the items at the fourth level appear on
the Kanban board, sprint backlog, and taskboard.
Rather than nest requirements, bugs, and tasks, we recommend that you maintain a flat
list. Only create parent-child links one level deep between items that belong to a
different category. For more information, see Fix re-ordering and nesting issues, How
backlogs and boards display hierarchical (nested) items.
Product backlog controls

You can use the following controls to change or filter your product backlog view.
） Important
If you turn the In Progress control off, then items that are in the Active, Committed,
or Resolved states or in the In Progress category workflow state won't appear in the
backlog. To learn more about category workflow states, see How to use workflow
states and state categories.
For more information about using each of these controls, see Configure your backlog
view.
Icon or Link
Control
Function
Backlog
Switch to backlog view
Analytics
Switch to Analytics in-context reports
Backlog selector
Switch backlog view
View options
Turn Parents on/off (not available for top-level portfolio backlog)
Turn Forecasting on/off (Only available on product backlog)
Turn In Progress items on/off
Turn Completed child items on/off
Show Mapping (not available for top-level portfolio backlog)
Show Planning
Filter
Turn filtering On/Off
Settings
Full screen
Enter or exit full screen mode
Expand/Collapse
Expand or collapse one level of the tree hierarchy
More commands
Set column options
Create Query
Email
７ Note
Even if you have show parents turned on, the Create Query and Email controls
only list items at the currently selected level.
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 more information, see
For more information 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.
Add portfolio backlogs and boards

To add a portfolio backlog or board, customize your process, add new work item types,
and then configuring your backlogs and boards. You can also add or modify the fields
defined for a work item type (WIT) or add a custom WIT. For more information, see
Customize an inheritance process and Customize your backlogs or boards (Inheritance
process).
Next steps
If you're just getting started, see Start using Azure Boards.
Related articles
About Kanban and Agile project management
About work items
What is Agile?
What is Agile development?
Agile culture
Create your product backlog in Azure
Boards
Article • 06/27/2023
2018
Your product backlog corresponds to your project plan, the roadmap for what your
team plans to deliver. You create your product backlog by adding user stories, backlog
items, or requirements. As shown in the following image, your backlog consists of a flat
list of work items.
７ Note
The following image illustrates the product backlog image for a Scrum process for
Azure DevOps Services. For the Agile, Basic, and CMMI process models, the
Backlog items selection appears as Stories, Issues, and Requirements.
After you define it, you have a prioritized list of features and requirements to build. Your
backlog also provides a repository of the information you need to track and share with
your team. And, you can interactively filter the backlog to focus on a subset of work
items.
７ Note

Your backlog consists of a list of work items. You use work items to share information,
assign work to team members, track dependencies, organize work, and more. Because
the most important work appears at the top of the list, your team always knows what to
work on next.
７ Note
Your product backlog is one of three classes of backlogs available to you, backlogs,
boards, and plans. If you don't see the work items you expect on your backlog, see
Set up your backlogs and boards.
Add a backlog
If you have a project, you have a backlog. Each project defines a default team and set of
backlogs for that team. You only need to add a backlog when you want to support a
new team. When you add a team, you add various team assets. A team admin can
configure the assets to support the way the team works. To add a set of backlogs to
support a new team, see Add a team.
Each team's set of backlogs are associated with one or more work item types. The work
item type associated with a backlog depends on the:
Process selected at project creation

Team configurations
Process customizations
The backlogs defined for each default process are:
Agile: Stories, Features, and Epics

Basic: Issues and Epics
Scrum: Backlog items, Features, and Epics
CMMI: Requirements, Features, and Epics
You choose the backlog level from the backlog selector as shown in the following
image.
To customize your backlogs with custom work item types, add portfolio backlogs or
other supported options. See the following articles, depending on the process your
project uses:
Inherited process model

On-premises XML process model.
Prerequisites
Backlogs are automatically created when you create a project or add a team. Each team
To use the Planning pane, the sprints that you want to assign work to must have
been selected for your team by a team administrator. For more information, see
Define iteration (sprint) paths and configure team iterations.
７ Note
Users with Stakeholder access for a public project have full access to backlog and
board features just like users with Basic access. For more information, see
Open your backlog

From your web browser, open your product backlog.
1. (1) Check that you've selected the right project, (2) choose Boards>Backlogs, and
To select another backlog, open the selector and then choose a different team or
 Tip
Choose the star icon to favorite a team backlog. Favorited artifacts (
2. Check that you have selected Stories (for Agile), Issues (for Basic), Backlog items
(for Scrum), or Requirements (for CMMI) as the backlog level.
3. (Optional) To choose which columns should display and in what order, choose the
actions icon and select Column options. For more information, see Change
column options.
 Tip
Each team member has several tools to configure their backlog view:
Expand/Collapse one level, Column Options, Backlog level selector, View options,
and Filter toolbar. Options set for each backlog level are distinct and persist until
changed. For more information, see Configure your backlog view.
Track bugs on your backlog

You can choose how you want to manage bugs. Some teams like to track bugs along
with requirements on the backlog. Other teams like to track bugs as tasks completed in
support of a requirement. The bugs then appear on their taskboard.
Before deciding, review Configure and customize, Treat bugs as requirements or tasks
for guidance. Or, go directly to Show bugs on backlogs and boards.
Convert ideas into backlog items

Your backlog shows work that you plan to do or have started to work on. As soon as the
State of a work item is set to Done or Completed, the work item no longer shows up on
your backlog. You can use the backlog controls to filter or change your view.
 Tip
If you already have defined a long list of items, you don't have to reenter them one
at a time. Instead, use Import or update work items in bulk by using CSV files or
Microsoft Excel to quickly import them to your backlog.
1. Before you add work items, select View options and turn the slider for Parents
and Forecasting to Off. Optionally, turn In Progress Items on or off.
2. To add a work item, select New Work Item and enter a title. Then press Enter or
select Add to top. Work items are automatically assigned the default Area Path
and Iteration Path selected for the team. For more information, see Configure
team settings.
７ Note
If you have Stakeholder access , you can only add work items to the bottom
of the backlog. For more information, see Stakeholder access quick reference.
3. Repeat this step to capture all your ideas as work items.
７ Note
Depending on whether you create your project with Basic, Agile, Scrum, or CMMI,
the items in your backlog might be called issues, user stories, PBIs, or requirements.
All three are similar. They describe the customer value to be delivered and the work
to be performed.
By default, user stories appear on Agile backlogs, issues on Basic backlogs, PBIs and
bugs appear on Scrum backlogs, and requirements appear on CMMI backlogs.
Reorder your backlog

After you have some items in your backlog, reorder them to create a prioritized list of
work. Review and prioritize your backlog frequently to help your team know what's most
important to deliver next.
 Tip
You can't sort your backlog on a column. To view a sorted listed, select Create
query. Save and open the query, and then sort the query results. To learn more
about queries, see Use the query editor to list and manage queries.
To reorder your backlog, drag the work items. Or, if you prefer to use the keyboard, hold
down the Alt key and use the up and down arrows.
７ Note
To reorder a backlog, you must have Basic or higher level access. If you have
Stakeholder access, you can't reorder backlog items. For more information, see
Backlogs that participate in portfolio management or that contain nested same-type

child items might not allow you to reorder the items. For more information, see these
articles:
Backlogs, portfolios, and Agile project management, Work with multi-team

ownership of backlog items
Fix reordering and nesting issues
Add details and estimates to backlog items

Building and prioritizing your backlog provides a high-level roadmap. Before your team
can start work on any item, however, they need more details. Capture the details within
the work item form.
To open each item, double-click or press Enter. Then add all the information you want to
track. Change one or more field values, add a description, or make a note in the
Discussion section. You can also choose the Attachments tab and drag a file onto it
to share the file with others.
Enter as much detail as the team needs to:
Understand the scope.

Estimate the work required.
Develop tests.
Ensure that the end product meets acceptance criteria.
７ Note
Agile process
For example, here we assign the story to Raisa Pokrovskaya and we add a
discussion note, at-mentioning Raisa.
 Tip
To plan a sprint, at a minimum, estimate the effort involved to implement each

backlog item. To capture effort in the work item form, use Effort for Basic or Scrum,
Story Points for Agile, or Size for CMMI.
Field
Usage
Effort, Story Points, Size
Provide a relative estimate of the amount of work required to complete a PBI. For user
stories and requirements, you capture estimates in Story Points and Size.
Most Agile methods recommend that you set estimates for backlog items based on
relative size of work. Such methods include powers of 2 (1, 2, 4, 8) and the Fibonacci
sequence (1, 2, 3, 5, 8, and so on). Use any numeric unit of measurement your team
prefers.
The estimates you set for Effort, Size, or Story Points are used to calculate velocity and
forecast sprints.
Business Value
Specify a priority that captures the relative value of a PBI compared to other PBIs. The
higher the number, the greater the business value.
Use this field when you want to capture a priority separate from the changeable backlog
stack ranking.
Description
Provide enough detail to create shared understanding of scope and support estimation
efforts. Focus on the user, what they want to accomplish, and why. Don't describe how
to develop the product. Do provide sufficient details so that your team can write tasks
and test cases to implement the item.
Acceptance Criteria
Define what "Done" means by describing the criteria for the team to use to verify
whether the PBI or the bug fix is fully implemented.
Before work begins on a PBI or bug, describe the criteria for customer acceptance as
clearly as possible. Have conversations between the team and customers to determine
the acceptance criteria. These criteria help ensure a common understanding within the
team to meet customers' expectations. Also, this information provides the basis for
acceptance testing.
Impact Assessment (CMMI only)
Describes the customer impact of not implementing the requirement. You might include
details from the Kano model about whether this requirement is in the surprise, required,
or obvious categories.
Show/hide items that are in progress

From the View options selector, you can choose to show or hide In Progress items. If
you turn the In Progress control off, then items that are in the Active, Committed, or
Resolved states or states that map to the In Progress category state won't appear in the
backlog.
You usually choose to hide In Progress items when you want to forecast work. For more
information, see Forecast your product backlog.
Show/hide child items that are complete

From the View options selector, you can choose to show or hide Completed Child
items.
You usually choose to show Completed child items when you want to view rollup
columns.
You usually choose to hide Completed child items when you want to forecast work. For
more information, see Forecast your product backlog.
７ Note
Next steps
Now that you have a working backlog in place, your team can begin work on the top-
priority items. From here, it's time to decide how you want to work as a team. Do you
want to use Scrum or Kanban? You can use these methods independently or together.
Scrum: Schedule sprints or Kanban

Teams that want the least overhead for tracking and estimating might prefer Kanban.
Teams that like to work at a steady cadence and plot the details of their sprint plan
might prefer Scrum and sprint planning.
Related articles
Bulk modify work items
Copy or clone work items
Refine your backlog
Display rollup progress bars or counts
Keyboard shortcuts
Define features and epics, organize your
backlog
Article • 08/10/2023
2018
While many teams can work with a flat list of work items, sometimes it helps to group
related items into a hierarchical structure. You can start with several major features or
scenarios and break them down into smaller deliverables. Or, if you have an existing
backlog, you can begin to organize it with features and epics.
Portfolio backlogs
The following image shows a features portfolio backlog that consists of a flat list of
feature work items.
You can use portfolio backlogs to do the following tasks:
Bring more order to your backlog

Manage a portfolio of features that different development and management teams
support
Group items into a release train
Minimize size variability of your deliverables by breaking down a large feature into
smaller backlog items
Portfolio backlogs let you quickly add and group items into a hierarchy. You can also
drill up or down within the hierarchy, reorder and reparent items, and filter hierarchical
views. Portfolio backlogs are one of three classes of backlogs available to you. For more
information, see Visibility across teams.
Agile process
Prerequisites
Backlogs automatically get created when you create a project or add a team. Each team

Contributors group has this permission set to Allow. For more information, see Set
To use the Planning pane, your team administrator must define iteration (sprint)
７ Note
Users with Stakeholder access for public projects have full access to backlog and
board features, like users with Basic access. For more information, see Stakeholder
What makes a feature or epic?

Epics and features are higher level containers. Typically user stories or backlog items roll
up into features, and features roll up into epics, so keep this information in mind when
you name your features and epics.
As you define your features and epics, consider the time required to complete them. In
general, you should complete backlog items, such as user stories or tasks, within a
sprint. Features and epics may take one or more sprints to complete.
View a backlog
To focus on one level of a backlog at a time, select the name of the backlog. If you don't
see all three backlog levels—Epics, Features, and Backlog items—enable the backlog
levels for your team.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ) and go

to your project.
2. Select Boards > Backlogs.

 Tip
Select the star icon to favorite a team backlog. Favorited artifacts (

3. Select either Stories (for Agile), Issues (for Basic), Backlog items (for Scrum), or
Requirements (for CMMI) as the backlog level.
4. (Optional) Choose which columns should display and in what order: select the
actions icon and select Column options.
 Tip
For more information, see Select backlog navigation levels for your team.
Add features and epics to your backlog

Just as you can add items to your product backlog, you can add items to your features
and epics backlogs.
1. Select the New Work Item, enter a title, and then select Enter or Add to top.
2. Repeat step #1 to capture all your ideas as work items.
In the following example, we added six features.
You can add epics in the same way. Open the Epics backlog from the backlogs
selector.
Add details to a feature or epic

Open each item by double-clicking, or highlight the item and select Enter. Then, add the
info that you want to track. Enter as much detail as possible, so your team can
understand the scope, estimate the work, develop tests, and ensure that the final
product meets acceptance criteria.
Field
Usage
Value Area
The area of customer value addressed by the epic, feature, or backlog item. Values
include:
**Architectural—technical services to implement business features that deliver
solution
Business (Default)—services that fulfill customers or stakeholder needs that
directly deliver customer value to support the business
Effort
Story Points
Size
Provide a relative estimate of the amount of work required to complete a Feature or

Epic. Use any numeric unit of measurement your team prefers. Some options are story
points, time, or other relative unit.
Business Value
Specify a priority that captures the relative value of an Epic, Feature, or backlog item
compared to other items of the same type. The higher the number, the greater the
business value. Use this field when you want to capture a priority separate from the
changeable backlog stack ranking.
Time Criticality
A subjective unit of measure that captures how the business value decreases over time.
Higher values indicate that the Epic or Feature is inherently more time critical than those
items with lower values.
Target Date
Specify the date by which to implement the feature.
Add child items

You can add child items to your features from any backlog. You can also add child user
stories (Agile), or product backlog items (Scrum) or requirements (CMMI) from the
Kanban board for features. And, you can add child features from the Epic board. For
more information, see Kanban board features and epics. To quickly parent or reparent
children from a backlog, see Organize your backlog, map child work items to parents.
Whenever you see the Add icon, you can add a child item. The work item always
corresponds to the hierarchy of work item types defined for your project.
For more information, see Configure your backlog view and About work items and work
item types.
For Scrum projects, your hierarchy looks like the following example.
Teams can set bugs as tasks

Enable bugs to show up on your team's backlog
Your project's process and resulting work item types view.
Add portfolio backlogs and boards

To add a portfolio backlog or board, customize your process, add new work item types,
and then configuring your backlogs and boards. You can also add or modify the fields
defined for a work item type (WIT) or add a custom WIT. For more information, see
Customize an inheritance process and Customize your backlogs or boards (Inheritance
process).
Display rollup progress counts, or totals

Product and portfolio backlogs support rollup columns. You can add one or more rollup
columns to display progress bars, counts of descendant work items, or totals of select
numeric fields. Your settings persist for each page that you customize and are only valid
for your views.
Progress bars indicate the percentage of descendant items within a hierarchy that
are closed or completed.
Counts display the total number of descendant items.
Totals provide a sum of numeric fields, such as Effort, Story Points, Completed
Work, or Remaining Work of descendant items.
The following example shows progress bars for a portfolio backlog.

Next steps
Related articles
Organize your backlog and map child
work items to parents in Azure Boards
Article • 06/27/2023
2018
After you've added features or epics to your portfolio backlog, organize your backlog by
mapping backlog items. You can quickly add and group items into a hierarchy. And also
drill up or down within the hierarchy, reorder and reparent items, and filter hierarchical
views.
In this article you'll learn how to:
＂ Open your product backlog or portfolio backlog

＂ View the tree hierarchy
＂ Group backlog items using the Mapping pane
＂ Reparent items through dragging or the Change parent option
７ Note
Prerequisites
７ Note
７ Note
Stakeholder access users for a private project can't drag items to map or reparent
them or to assign their sprint.
Open your backlog from the web portal

 Tip

column options.
７ Note
Show parent tasks and expand the tree

hierarchy
You can set various options to view backlog work items using the View options menu.
To learn which options to set based on the tasks you want to accomplish, see Configure
your backlog view.
1. To view Parents or a tree hierarchy, choose the view options icon and slide
Parents to On.
The hierarchical view displays. From this view, you can reparent items by dragging
a child item to a new parent.
2. Use the Expand and Collapse icons to expand or collapse one level of the
hierarchy.
Map items to group them under a feature or

epic
If you've already created your backlog, and now you want to organize it, you can do that
most easily by mapping child items to parents.
1. Choose View options and select Mapping.

The Mapping pane displays immediately.
2. Find Unparented backlog items that may appear at the end of the parented set of
backlog items. Parents must be turned on in view options.
3. To map features to epics, select the Features backlog from the backlog selector.
The Epics Mapping pane automatically displays.
You can multi-select backlog and sprint backlog items in the same way as you multi-
select items from query results.
It's the same process to map features to epics. From the Features backlog, drag features
to an epic listed under the mapping pane.
Change the parent task and reorder items

When you need to change the order or grouping, drag the item to its new location.
You can reparent an item using the mapping pane, or drag it within the hierarchy to
change its parent.
You can only reparent backlog items under other features, and features under other
epics.
Also, to change an item's priority within a group, drag the item up or down within its
hierarchical group. Reordering from a portfolio backlog works the same as when you
moved items into priority order on your product backlog.
Limitations on reordering backlog items owned by other
teams
If you find you can't reorder a backlog item, check whether the info icon appears in
the first column as shown in the following image.
You can reparent items owned by other teams, but you can't reorder items owned by
other teams. For more information, see Backlogs, portfolios, and Agile project
management, Work with multi-team ownership of backlog items.
Change a parent of multiple backlog items

From a product or portfolio backlog, you can multi-select several work items and
choose Change parent… to link the items to a parent work item.
Add portfolio backlog levels and boards
If you need more than two portfolio backlogs, you can add up to two more for a total of
five backlog levels.
You can add them by customizing your process, adding new work item types, and then
configuring your backlogs and boards. You can also add or modify the fields defined for
a work item type (WIT) or add a custom WIT. For more information, see Customize an
inheritance process and Customize your backlogs or boards (Inheritance process).
Display rollup progress, counts, or totals

Product and portfolio backlogs support the display of rollup columns. You can add one
or more rollup columns to display progress bars, counts of descendant work items, or
totals of select numeric fields. Your settings persist for each page you customize and are
only valid for your views.
Progress bars indicate the percentage of descendant items within a hierarchy that are
closed or completed. Counts display the total number of descendant items. And, Totals
provide a sum of numeric fields, such as Effort, Story Points, Completed Work, or
Remaining Work of descendant items.
For example, progress bars are shown here for a portfolio backlog.
Related articles
Filter product and portfolio backlogs
Keyboard shortcuts
Article • 02/24/2023
2018
specific sprint.
assigned work.
Path, or Tags.
Area Path or Tags.

✔️or is listed.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes

enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
Relevance.


７ Note
team.
Prerequisites

view
Features, or Epics
Work Items
team member.
want to filter on.
criteria.
Inactive functions


values.
board.

operator.



include 'web'.

Unassigned
７ Note

Epics).
AND | OR . AND
Item 2.

７ Note
you've defined.

features.

tags.
boards.

Related articles
About backlogs
Customize cards
Tags
Article • 05/19/2023
2018
Teams use the forecast tool to help in their sprint planning efforts. By plugging in a
value for the team velocity, the forecast tool shows which items in the backlog can be
completed within future sprints. Both tools are team-specific tools that rely on the
team's ability to estimate backlog items. Once your team has completed a sprint or two,
they can use the team velocity to forecast how much of the backlog they can finish
within the upcoming sprints.
Use this article to learn:
＂ How to forecast upcoming sprints

＂ Required and recommended team activities to support forecasting
７ Note
Prerequisites
You must be added to a project as a member of the Contributors security group. If
you're not on a project or team, get added now.
You must be granted Basic access or higher to use the forecast feature. For more
information, see About access levels.
７ Note
Required and recommended activities
Here's what you need to have in place before you attempt to forecast your team's
backlog.
Required:
Define iteration paths (sprints) and configure team iterations

Sprints should be of the same duration.
Select enough future sprints to forecast your entire product backlog.
Define and estimate backlog items. If you work from your team's backlog, the
items you create automatically get assigned to the current sprint (Iteration) and to
your team's default Area Path.
Update the status of backlog items once work starts and when completed. Only
backlog items whose State maps to a state category of Proposed or In Progress
show up on the velocity chart. (For more information, see Workflow states and
state categories).
Recommended:
Define and size backlog items to minimize variability.

Determine how your team wants to treat bugs. If your team chooses to treat bugs
like requirements, bugs appear on the backlog and be counted within the Velocity
chart and forecasting.
Set your team's area path. The forecast tool forecasts those items based on your
team's default settings. These settings can specify to include items in area paths
under the team's default or exclude them.
Don't create a hierarchy of backlog items and bugs. The display of the leaf node,
the last node in a same-category hierarchy, may only appear on Kanban boards,
sprint backlogs, and Taskboards. For more information, see Fix reordering and
nesting issues, How backlogs and boards display hierarchical (nested) items.
Instead of nesting requirements, bugs, and tasks, maintain a flat list—only creating
parent-child links one level deep between different-category items. Use Features
to group requirements or user stories. You can quickly map stories to features. The
map creates parent-child links in the background.
At the end of the sprint, update the status of those backlog items that the team
has fully completed. Incomplete items should be moved back to the product
backlog and considered in a future sprint planning meeting.
７ Note
If you work with several teams, and each team wants to work with their own
backlog, velocity chart, and forecast tool, you can create additional teams. Each
team then gets access to their own set of Agile tools. Each Agile tool filters work
items to only include those whose assigned area paths and iteration paths meet
those set for the team.
Forecast upcoming sprints

Use the forecast tool to get an idea of how many items you can complete within a
sprint. By plugging in a velocity, you can see which items are within scope for the set of
sprints the team has activated.
To forecast your product backlog, complete the following actions.
column options.
4. Choose the view options icon and slide Forecasting to On. To keep things
simple, turn the Mapping and Planning panes Off.
Set In Progress Items to Off to hide those items that won't be counted in the
forecast. The forecast tool ignores Scrum items set to Committed or Done and
Agile and CMMI items set to Active, Resolved, or Completed.
5. Enter your team's predicted velocity.
 Tip
If your team has been working for several sprints, you can gain an idea of your
team's velocity from the Velocity widget.
The tool draws lines for each future sprint selected by the team. The Forecast lines
show how much work your team can complete in future sprints. Typically, items
above the first line are already in progress for the current sprint. Items that fall
between the first and second forecast lines indicate what can be completed in the
named sprint.
Review the forecast results
Check the results manually to understand discrepancies in what you expect and
what the forecast tool displays.
Check the amount of effort (Effort, Story Points, or Size) forecasted per sprint.
Question forecast results where the effort of an item is near to, or greater than,
team velocity.
In this example, a Velocity of 20 is used. The forecast tool limits the number of items
that are shown between the forecast lines to those items that can be completed within
the sprint or using unused velocity points from the previous sprint.
The forecast tool shows between two and four items can be worked on during Iterations
2 through 6 based on the number of Story Points you assigned to each user story or
bug. The forecast logic carries over velocity points from one sprint to the next.
Iteration 2: 13 Story Points, items 1 and 2 can be completed; 7 velocity points are
carried over to the next sprint
Iteration 3: 24 Story Points, items 3 through 5 can be completed; 3 (=20+7-24)

velocity points are carried over to the next sprint
Iteration 4: 21 Story points, items 6 through 8 can be completed; 2 (=20+3-21)



Determine the velocity needed to complete all
items in the backlog
Another way to use the forecast tool is to enter different velocity values until all the
backlog items are completed within a given set of sprints. This forecast provides an
estimate of what velocity is required to complete your backlog of items.
You can then assess the delta between the current team's velocity and the required
velocity. The delta helps determine what other resources are required to meet
production demands within a required time.
Next steps
Assign work to a sprint
Related articles
Team velocity
Use the taskboard to track work during your sprint
Monitor the sprint burndown chart to determine if your team is on track to
complete the sprint plan
Configure your backlog view in Azure
Boards
Article • 06/27/2023
Your backlogs are designed to support many project management tasks. Chief among
them are:
Define work to be done

Prioritize work
Group work into a hierarchical view
Assign work to iterations
Forecast work
Each backlog—product or portfolio—is a tool you share with your team members. When
you add backlog items, prioritize items, or link work items using parent-child links, team
members see the changes when they refresh their backlog.
To effectively perform select tasks, it's good to know how to set your view options to
support those tasks.
 Tip
You can't sort your backlog on a column. To view a sorted listed, select Create
query from your backlog. Save and open the query. Modify the query if needed to
be a flat list query. You can then sort the query results. To learn more about queries,
see Use the query editor to list and manage queries.
Backlog configuration options

You have the following tools to configure your backlog view: Expand/Collapse one
level, Column Options, Backlog level selector, View options, and Filter toolbar. The
options you set for each backlog level—stories, features, epics (Agile process) or
product backlog items, features, epics (Scrum process)—are distinct. The options you set
persist until you change them.
Expand and collapse the hierarchy

The default view when you select a backlog level is to show the collapsed view. Only
those items associated with the backlog level selected are shown. You can expand and
collapse the hierarchy by using the and collapse icons to expand or collapse one
level of the hierarchy. Your selection doesn't persist once you switch to a different page
or view.
Backlog level selector

The number of backlog levels available to you are set by your team administrator and
may have been customized to add custom work item types or backlog levels. Each
backlog automatically applies the filters associated with the Area Paths and Iteration
Paths selected for the team.
７ Note
Prior to using the tools described in this article, we recommend that you review Set
up your project's backlogs and boards to ensure you have configured your
backlog to support your team's needs.
From the Backlogs page, you can select the product backlog or a portfolio backlog. You
select a backlog from the backlog level selector next to the View options icon. The
labels within this selector vary depending on the process selected for your project,
customization made to that process, and configurations made by your team
administrator as shown in the following images.
Agile process
Scrum process
Basic process
CMMI process
Customized process
For information on team configuration of backlog levels, see Select backlog navigation
levels for your team.
View options menu

The View options menu controls the following options.
Parents: Show the hierarchical grouping of parent-child work items. Useful when
adding child work items, reparenting a work item, or displaying rollup columns.
Forecasting: Show the Forecast tool and forecast lines. The Forecast option only
appears for the first-level backlog and depends on the assignment of Story Points,
Effort, or Size.
In Progress Items: Show items whose workflow State corresponds to an In Progress

workflow state category. If you turn the In Progress control off, then items that are
in the Active, Committed, or Resolved states or a custom workflow state defined in
the In Progress state category won't appear in the backlog. To learn more about
category workflow states, see How to use workflow states and state categories.
Completed Child Items: Show child items that have been completed. Typically you
turn this On when reviewing reviewing a rollup column.
Keep hierarchy with filters: Maintain the backlog hierarchy when filtering.
Mapping: Shows the Mapping pane to support drag-and-drop linking of work

items to parent items. The Mapping option doesn't appear when you've selected
the highest backlog level configured for your team.
Planning: Shows the Planning pane to support drag-and-drop of work items to

Iteration Paths.
Filter bar
Turn on filtering when you want to find one or more work items based on a keyword,
tag, assignment, or other field you display using Column Options. You enable the filter
feature by choosing Filter.
Filtering displays a flat list of all items in the hierarchy when you have selected to show
Parents. The hierarchical grouping is restored once you dismiss the filter toolbar. The
filter toolbar persists until you dismiss it.
For more information, see Filter backlogs, boards, and plans.

Parents and Keep hierarchy with filters from the View Options menu.
Use these options when you want to show work items assigned to one or more team
members, work item types, area or iteration paths, or combination of these and
keywords. The hierarchy is maintained and work items that match the filter criteria are
shown in bold text.
Define backlog items

It's useful to be able to add work items quickly and refine details later when more
information becomes available. Often you use a query to help triage work added to the
backlog to review, refine, and add details to work items that you entered through your
backlog.
To quickly define many items to a backlog, perform the following steps.
1. Select the backlog level that you want to add items to.
2. From the View options menu, turn the slider for Parents and Forecasting to Off.
3. (Optional) turn In Progress Items on or off.
4. (Optional) Minimize the number of columns displayed on your backlog, or select

those fields you want to view.
5. Choose New Work Item, enter a title, choose Add to top or Add to bottom, and
then press Enter. We recommend you add items to the bottom of the backlog if
your team has a process for prioritizing backlog items.
Work items are automatically assigned the default Area Path and Iteration Path
selected for the team.
７ Note
If you have Stakeholder access , you can only add work items to the bottom
of the backlog. For more information, see Stakeholder access quick reference.
6. Continue entering a Title and pressing the Enter key to define more backlog work
items.
For more information, see Create your product backlog and Define features and epics.
Prioritize your product backlog

If your team follows Agile or Scrum methods, they'll want to prioritize the backlog to
make sure that the most important work to complete is situated at the top of the
backlog. To prioritize a backlog, follow these steps.
1. Select the backlog level you want to prioritize.
2. Turn the Parents view option Off.

3. Drag the work items up or down within the backlog. Or, if you prefer to use the
keyboard, hold down the Alt key and use the up and down arrows.
７ Note
Changes you make to the priority impact all backlog items. When other team
members refresh their backlog, they'll see the new priorities. A background process
updates the Stack Rank (Agile, Basic, and CMMI processes) or Backlog Priority
(Scrum process) fields. These fields are used by the system to track the relative
ranking of items on the product, feature, epic, or other portfolio backlog. By
default, these fields don't appear on the work item form. The priority ranking is
assigned separately to each backlog level, which you can check by adding the field
to a backlog and viewing a hiearchical list.
Backlogs that participate in portfolio management or that contain nested same-type

child items might not allow you to reorder the items. For more information, see these
articles:
Backlogs, portfolios, and Agile project management, Work with multi-team

ownership of backlog items
Fix reordering and nesting issues
Prioritize a portfolio backlog

The method for prioritizing a portfolio backlog is similar to that described for a product
backlog. The main difference is that you prioritize child items within each portfolio item.
Each backlog level—Stories, Features, Epics—supports priority ordering distinct from
every other level.
Prioritize the portfolio items:
1. Select the portfolio backlog level you want to prioritize.

2. Turn the Parents view option Off.
3. Drag the work items up or down within the backlog.
4. Within each item, you can expand to see child items and drag these items into
priority order.
Prioritize child items:
1. Expand each portfolio item.

2. Drag each child item up or down within the expanded item.
７ Note
Link work items to a parent (mapping)

You can drag items to quickly link one or several work items to a parent portfolio item.
 Tip
Prior to opening mapping work items, add the portfolio backlog items you want to
link work items to and prioritize them. The Mapping pane lists the portfolio
backlog items in priority order.
1. Select the backlog level you want to link to parent items. For example, choose
Stories to link to Features.
2. Open View options and choose Mapping. The Mapping pane opens. By
default, the pane lists the next-level up portfolio items for the current team.
3. (Optional) To map items to parent items owned by a different team, choose it from
the team selector in the Mapping pane as shown in the following image.
4. Drag work items from the backlog to the portfolio item listed in the Mapping
pane. The system creates a parent-child link in the background. The backlog item
turns bold and then unbold as the system saves the changes.
Note, you can select multiple backlog items and drag them to a portfolio item. To
select several items in a sequence, hold down the shift key. To select several non-
sequential items, use the Ctrl key. Then, you can drag the selected items.
5. (Optional) You can also drag a backlog item within the expanded hierarchical view
to reparent a work item.
 Tip
To view the work items that are unparented, you can add the Parent field as a
column. The Title of the parent item is listed for those items that have been linked
to a parent.
For more information, see Organize your backlog and map child work items to parents.
Add child items to a portfolio backlog item

1. Select the portfolio backlog level, such as Features, that you want to add items to.
2. Choose Add User Story, Bug for the feature you want to add the child item to
as shown in the following image. Your labels may differ based on process and
customizations.
3. In the work item form that appears, enter a Title and any other required fields or
details. Save the work item to close it.
For more information, see Define features and epics, add child items.
View or find unparented work

To view or find unparented work:
1. Select the backlog level you want to inspect for unparented items.
2. Open View options and choose Parents.
3. Scroll to the bottom of the backlog and expand Unparented Stories, Unparented
Features, or similar entries. Unparented work items are listed under these entries.
Assign work to a sprint or iteration

Similar to using the Mapping pane, you can use the Planning pane to assign one or
more work items to an Iteration Path or sprint.
1. Make sure all Iteration Paths have been selected for your team that you want to
show in the Planning pane.
2. Choose the backlog level that contains the work items you want to assign.
3. Open View options, turn off Completed Child Items and choose Planning.
4. Drag work items from the backlog to the portfolio item listed in the Mapping
pane. The system creates a parent-child link in the background. The backlog item
turns bold and then unbold as the system saves the changes.
Note, you can select multiple backlog items and drag them to a portfolio item. To
select several items in a sequence, hold down the shift key. To select several non-
sequential items, use the Ctrl key. Then, you can drag the selected items.
Forecast a backlog
The Forecast tool is only available for the product backlog. Use these steps to forecast
your backlog. To use the Forecast tool, you must have Basic or higher level access. This
feature isn't available to users granted Stakeholder access.
1. Make sure that future Iteration Paths have been selected for your team.
2. Choose the backlog level for your team.
3. (Optional) Add the Story Points, Effort, or Size field as a column based on the
process your project uses.
4. Open View options and turn off Parents and In Progress items, and Completed
Child Items. Turn on Forecast.
5. Enter a velocity estimate in the Forecasting based on velocity of box.
6. Review the forecast lines that appear, similar to the ones shown in the following
image.
The forecast tool doesn't reference any iteration assignments made to the product
backlog items.
 Tip
You can drag items to reprioritize them with forecast lines shown. You can also use
the Planning pane with the Forecast tool turned on.
For more information, see Forecast your product backlog.
Review progress made to your backlog

You can add a rollup progress bar, count of work items, or sum of any integer or
numeric field as a column to the backlog. This option allows you to review progress
made to parent work items based on the completion of their child items. These child
items can be Tasks for User Stories, User Stories and Bugs for Features, or Features for
Epics.
1. Select the backlog level you want to view progress on
2. Open View options, show Completed Child Items

3. Open Column Options, choose Add a rollup column, and select the progress bar
or count to display.
It can take several moments for the progress bar or count to appear.
For more information, see Display rollup progress or totals.
Related articles
Set up your project's backlogs and boards
Create your product backlog
Organize your backlog and map child work items to parents
Configure team settings
Bulk modify tools

Bulk modify (web)
Bulk add or modify (Excel)
Import or update work items in bulk by using CSV files
Set up your project's backlogs and
boards in Azure Boards
Article • 06/27/2023
2018
In most cases, you can start using your product and portfolio backlogs once your
project is created. A default team is created along with associated backlogs and boards.
You can start adding work items to your product backlog using the Backlog or Board.
However, you may need to ensure you've configured your backlogs and boards
correctly. Ensure the configuration if you've added a team and want to start using the
team backlogs and boards. Changes may be made to a project or team configuration
over time. These changes can influence the work items that appear on your backlog and
boards.
For an overview of the tools associated with your team, see Manage and configure team
tools.
Default backlog and board work items

The first thing you need to understand is that your product Backlog and Board display
work items that meet the following criteria:
Work item type belongs to the Requirements category. The types differ depending
on the process selected for your project:
Basic : Issue, Backlog name=Issues
Agile: User Story, Backlog name=Stories
Scrum: Product Backlog Item, Backlog name=Backlog items
CMMI: Requirement, Backlog name=Requirements
Work item Area Path matches one of the selected team's Area Paths
Work item Iteration Path is under the team's Default Iteration Path
You can determine the work item types that belong to your Requirements category.
Determine the items by opening your product Backlog and checking the product
backlog name.
Look up your team's Area Path(s) and Iteration Paths. For more information, see Define
area paths and assign to a team and Define sprint paths and configure team iterations.
Default sprint backlog and Taskboard work

items
Your sprint backlog and Taskboard apply the filters associated with your team's default
backlog and board work items along with the Iteration Path you select.
You can only select Iteration Paths that have been preselected by your team.
Your sprint backlog displays only those work items assigned to the selected sprint. Child
tasks assigned to other sprints aren't displayed.
Review checklist for work items, backlogs, and

boards
If you don't see the work items you expect on your product Backlog or Kanban board,
complete the following checks:
1. Make sure you've selected the team backlog or board of interest. To learn how, see
Use breadcrumbs and selectors to go to and open artifacts.
2. Create a query of your backlog items, specifying the work item types that belong
to your Requirements category and the Area Path associated with your team, for
example:
3. Add the State, Area Path, and Iteration Path fields to the column options.
4. Check the query results and that the values of the work items you expect to show
up on your backlog meet these criteria:
Area Path belongs to your team's area path(s)

Iteration Path belongs under your team's default iteration path
State isn't Closed, Completed, Done, or Removed.
７ Note
You can also filter your product backlog to show or hide work items that are in an
In Progress state category, corresponding to an Active, Resolved, Committed,
Doing workflow state.
Add bugs to your backlogs and boards

For all processes except the Basic process, each team manages the way bugs are
tracked. Track bugs in the Requirements category because they show up on the Backlog
and Kanban board or the Tasks category. They can also show up on the Taskboard or the
Bugs category where they don't appear on either backlogs or boards.
７ Note
If you want bugs to show up on your Backlog and Board, choose Bugs are managed
with requirements.
For more information, see Show bugs on backlogs and boards.

Correct your Kanban board configuration
If you see the following error when you open your Kanban board, you need to correct
the configuration. The main reason for this error is that the workflow states of work item
types that have been added to the Requirements category aren't mapped to the
column.
Choose Correct this now to open the Settings dialog. To map the workflow states, refer
to Add columns to your Kanban board, Update Kanban column-to-State mappings.
Customize your Kanban board checklist items

Checklists are a great way to create work items that are automatically linked with a
parent-child link to another work item on a Kanban board. You can customize the work
item types that you can add as a checklist by opening the Board Settings, choose
Annotations, and enable the work item types you want to appear on the board. For
more information, see Customize cards.
For example, here we've chosen to track bugs along with tasks, and enable Task, Bug,
GitHub objects, and Tests to appear within checklists.
To learn more about checklists, see the following articles:

Link GitHub commits, pull requests, and issues to work items
Add other work item types to your Kanban

board checklist
If you added work item types to the Task Category as described in Add custom work
item types to your Taskboard later in this article, you can choose if these types appear
within a checklist on your product Kanban board. You make this choice by opening
Board Settings, choose Annotations, and enable the work item types you want to
appear on the board. You can enable up to five annotations. For details see Customize
cards.
For example, here we've chosen to track bugs along with tasks, and we enable Issue and
Ticket and Task and Bug. To learn more about checklists, see Add tasks or child items as
checklists and Add, run, and update inline tests.
Hide or show backlog levels
Your team can also choose to hide or show one or more backlog levels. Feature teams
often manage backlog items, while management teams manage features and epics. In
this situation, you can enable or disable a backlog level.
Add custom work item types to your backlogs

and portfolio backlog levels
If you want to track different work item types on your product backlog, you can do that
by adding custom work item types and adding them to a specific backlog level.
You can also add custom work item types and add them to portfolio backlogs. You can
add up to five portfolio backlogs.
For example, here we've added Initiatives, fourth level, and fifth level work item types to
support five levels of portfolio backlogs. We've also added a custom work item type
named Ticket and added that to the product backlog.
For more information, see the following resources:
Add and manage work item types (Inherited process)

Customize your backlogs or boards (Inherited process)
Customize an inheritance process
Add custom work item types to your Taskboard

To add custom work item types to appear on your sprint Taskboard, follow the steps
outlined next based on the process model your project uses.
７ Note
You can enable work item types that you add to your Iteration backlog to appear as
a checklist on your product Kanban board. To learn how, see Customize your
Kanban board checklist items provided earlier in this article.
Track custom work items with the Inherited process

model
For example, if you want to track a custom work item type, Tickets, along with Tasks and
Bugs, you do the following tasks:
1. Define the Ticket custom work item type. See Add and manage work item types.
2. Add the Ticket work item types to the Iteration backlog. For more information, see
Other factors that can affect work items in your

backlogs and boards
The following settings can influence the type and number of work items that appear in
your backlogs and boards.
In your Kanban board, newly added work items may not appear if they're stack
ranked lower within the product backlog. By choosing Show more items, you can
cause the board to refresh and display more work items.
If you have nested work items that belong to the same category, only leaf nodes
may appear on the Kanban board (for TFS 2018.1 and earlier versions). For this
reason, we recommend that you don't nest work items of the same work item type
or belonging to the same category. For more information, see Fix reordering and
If you've turned off the In Progress view, then those work items where work has
started won't appear in the backlog list.
Work items appear in the priority order in which they're added or moved to. This
order or sequence is managed by the Stack Rank (Basic, Agile, and CMMI
processes) or Backlog Priority (Scrum) field. For more information, see the Stack
rank section in Backlogs, portfolios, and Agile project management.
Each backlog can display up to 999 work items. If your backlog exceeds this limit,
then you may want to consider adding a team and moving some of the work items
to the other team's backlog.
Sprint backlogs show only those work items that meet the team's area path and
the Iteration Path defined for the sprint.
Inheritance process model: If an administrator disables or deletes a work item type,
it doesn't appear on backlogs and boards.
On-premises XML process model: If an administrator deletes or destroys a work

item type, it doesn't appear on backlogs and boards.
Related articles
Create your backlog
Use categories to group work item types
Workflow states & state categories
Manage columns in a work item list in
Azure Boards
Article • 02/24/2023
2018
Each column corresponds to a work item field. You can add and remove columns within
work item lists to show the fields of interest to you. Or, you can drag a column to a new
position. Your settings persist for each page you customize and are only valid for your
views.
Specifically, you can do the following actions from the following list views:
Action
Backlogs
Sprint backlogs
Queries
Work items
Add or remove a column field
Yes
Yes
Yes
Yes
Add or remove the Parent field
Yes
Yes
Yes
Yes
Add or remove a rollup column
Yes
No
No
No
Sort on a column
No
No
Yes
Yes
 Tip
Unlike a query result, you can't sort a backlog by a column. However, you can use
the Create Query link on each backlog to create a query that you can sort on any
field column you choose from the Sorting tab of the Column options dialog. While
you may be able to add a field to sort on, not all fields are supported. For example,
selection of the Parent, History, Description, or other rich-text field results in the
display of an error message as you can't sort on these fields.
You can add most fields listed in the Work item field index. All fields defined within the
project collection or organization are available for selection, even those fields that aren't
used for your particular project. You can view the list of fields defined for your collection
from Organization Settings>Process>Fields
About persistence of column options

Once you set the column options for a specific view, your settings persist until you
change them. The following notes apply to specific views.
Column options you set for a backlog apply only to the active team and backlog.
Options you set for the product backlog differ from the options you set for a
portfolio backlog.
Column options you set for a Sprint backlog persist for all sprints you select until
you change them.
Column options you set for a query persist when you save the query.
Column options you set for one of the supported Work items views persists for a
specific view only, such as Assigned to me, Following, Mentioned, and so on.
７ Note
You can't set column options for other members of your team, nor can you set
default column options.
Open the Column options dialog

Start by opening the Column Options dialog. If you don't see the option, choose the …
and choose from the options provided.
Add or remove columns

Browser
In the Column options dialog, choose Add a column to add a field that isn't shown.
To change the order of the fields, drag-and-drop the field where you want it within
the set of selected fields. And, to remove a field, choose the .
Add or remove rollup columns
Rollup columns can display progress bars or the sum of numeric fields of child items.
You can add them to any product or portfolio backlog. For more information, see
Display rollup progress or totals.
Sort on a column
You can sort query results and Work items views. From the Column options dialog,
choose Sorting. Add or remove a column field and drag and drop it into the order you
want. Choose the up or down arrows to choose whether it sorts in ascending or
descending order.
Use keyboard shortcuts to change the column
order, column width, or sort options
You can change the column order, column size, or sort options by using the following
keyboard commands:
To change the column order, choose the field and drag it to a new location
To resize a column, choose the column divider to the right of the field and drag to
a new location
For query results:
Add the field as a column to sort by that field
To sort by a column, hold down the SHIFT key and select on the field
To reverse the sort order, SHIFT+click on the field
To sort by multiple columns, SHIFT+click on each column in the order you want
to sort
For other keyboard shortcuts, enter ? to display available shortcuts based on the page
you're on.
Related articles
Display rollup progress or totals in
Azure Boards
Article • 06/27/2023
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020
Rollup columns allow you to view progress bars or totals of numeric fields for
within a hierarchy. You can add one or more rollup columns to a product or portfolio
backlog. Support for sprint backlogs isn't supported. For information on linking work
items in a hierarchy, see Linking, traceability, and managing dependencies, Parent-child
work item links.
For example, here we show Progress by Work Items which displays progress bars for
ascendant work items based on the percentage of descendant items that have been
closed. Descendant items for Epics include all child Features and their child or grand-
child work items. Descendant items for Features include all child User Stories and their
child work items.
） Important
Rollup data supports progress bars, counts of work items, or sums of numeric fields
within a project. Child items that link to a different project aren't counted within the
parent rollup calculations. Also, links to test cases or test artifacts are also not
included in rollup calculation. These items are linked using a test-specific link types.
７ Note
You can also view rollup progress from the new version of Delivery Plans that is
available in public preview for Azure Boards. This feature is now part of Azure
Boards and not an extension. To enable it, see Manage or enable features and turn
on New Delivery Plans Experience. For more information, see Review team
Delivery Plans.
Prerequisites
Rollup column data is calculated from the Analytics service.
Rollup and hierarchical work items

The default set of backlog work items that supports a natural hierarchical grouping
varies depending on the process chosen for your project. The easiest way to group work
items into a hierarchy is by mapping them, or adding them to the parent item on a
Kanban board. For more information, see Organize your backlog, map child work items
to parents and Kanban board features and epics.
Agile process
The following image shows the Agile process backlog work item hierarchy. Each
team can configure how they manage bugs—at the same level as User Stories or
Tasks—by configuring the Working with bugs setting.
Open a product or portfolio backlog

Each user can set their own column options that persist for each backlog across the
user's sessions.
1. Open a product or portfolio backlog. Optionally, enable Show parents from your
view options. Even if child items aren't listed, rollup for them displays.
 Tip
Consider opening a portfolio backlog and choose to view In Progress Items

and Completed Child Items. That way, you can check the State value of items
against the rollup value.
2. Choose Column options, or choose the actions icon and then select Column
options.
 Tip
Remember that the Column options you choose are for the selected backlog
level. They persist across your sessions until you change them.
Add a rollup column

1. In the Column options dialog, choose Add a rollup column, select From quick list,
and then choose from one of the options listed.
７ Note
The menu options vary depending on the process chosen for your project, the
backlog level you've selected, and whether or not you have the Show parents
view option enabled.
2. Choose from the menu provided.
Progress bar displays progress bars based on the percentage of associated

descendant work items that have been completed or closed.
Total number displays the sum of descendant items or the associated fields
of descendant items. Totals provide a measure of the size of a Feature or Epic
based on the number of its child items. For example, Count of Tasks shows
the sum of all tasks that are linked to parent items. The active or closed state
is ignored.
For example, the following image shows the Count of Tasks for the parent user
stories is 2 and 4, respectively. The Count of Tasks is 6 for the parent Feature and
Epic.
3. Remaining Work of Tasks shows the sum of Remaining Work of tasks that are
linked to the parent item.
 Tip
Reminder that when a task is closed, the Remaining Work field is set to zero.
Analytics, latency, and error states

Rollup data is calculated from the Analytics service. When there's a large amount of
data, it's possible to experience some latency in displaying rollup. If you hover over the
rollup icon, you can determine the state of the data.
If an error occurs in retrieving rollup data, you'll see an info icon and empty rows.
Errors indicate when the Analytics data was last updated. This means that the Analytics
services are still processing changes made which may affect rollup calculations. Once the
Analytics data is up to date, the rollup columns refresh with the latest data.
To learn more about the service, see What is Analytics?.
Change the column order or remove a rollup

column
To change the order of the fields, drag-and-drop the field where you want it within the
set of selected fields. And, to remove a field, choose the .
Rollup of custom work item types or custom

fields
If you add a custom work item type or field to a backlog level, you can view rollup based
on those options. For example, the Customer Request type is added to the
Requirements category, and a Count of Customer Requests is shown in the following
image.
1. From the Column options dialog, choose Add a rollup column, select Configure
custom rollup option.
2. Choose the options you want from the Custom Rollup column dialog.
3. Choose OK. and then OK to complete your operations.
 Tip
If you add custom fields or custom work item types, you must refresh the
backlog page to reflect your changes.
keyboard commands:
To change the column order, select the field and drag it to a new location
a new location
Related articles
Select backlog navigation levels for your
team
Article • 04/24/2023
2018
Each team has the flexibility to choose their preferred backlog levels. Feature teams may
focus on their product backlog, while management teams may only display feature and
epic backlogs (the default portfolio backlogs). You can configure backlog levels through
team settings.
If you need more portfolio backlogs, see the following articles based on the process
model you use:
Inheritance: Customize your backlogs or boards for a process

On-premises XML: Add portfolio backlogs.
Prerequisites
Set your team's preferences for backlog levels

This setting impacts the backlog and board views for all team members. You can modify
the setting from either the backlog or board view. In this article, we show you from the
board view.
2. Choose Boards, and then open your Kanban board.
3. Select Configure team settings .

4. Choose Backlogs and check the boxes of those backlog levels you want your team
to manage.
5. When you're done with your changes, choose Save and close.
6. To see the changes, open or refresh your team's backlog.
Related articles
Get started with Agile tools to plan and track work
Backlogs, boards, and plans
Create your backlog
Article • 03/03/2023
2018
As your team identifies code defects or bugs, they can add them to the backlog and
track them similar to tracking requirements. Or, they can schedule bugs to be fixed
within a sprint along with other tasks.
When you track bugs as requirements, they appear on the product Backlogs and Kanban
boards. When you track bugs as tasks, the bugs appear on Sprint Backlogs and
Taskboards. For more information about other work item types, see Add other work item
types to backlogs or boards.
You can define your team's tracking setting for the Agile, Scrum, and CMMI processes.
The Bug work item type isn't defined for the Basic process, so there isn't a team setting
for Basic. Instead, you should track bugs and code defects using the Issue work item
type.
７ Note

Prerequisites
Choose from options for bug tracking

The following table summarizes the options teams have for tracking bugs. Before you
make your choice, we recommend you review the information provided in Define,
capture, triage, and manage bugs, which provides an overview of the Bug work item
type and supported tools for managing bugs.
Option

７ Note
Track bugs as Tasks

７ Note

７ Note
backlogs or boards
Delivery Plans
Set your team's preference for bug tracking

You can change settings from a backlog or board view, or from Project settings > Team
configuration.
In the following steps, we show how to change it from the board view.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ) and

select your project.
3. Choose Board settings to configure the board and set general team settings.
4. Choose Working with bugs and then choose the option that best meets your
team's way of working.
6. To see the changes, open or refresh the team's backlog or Kanban board.
Nest items
When you manage bugs with requirements or tasks, they appear on one or more of
your Agile tool backlogs and boards. However, if you nest items—create parent-child
links of items that belong in either the Requirements or Task categories—not all items
may appear on your backlogs and boards. To learn more about how nested items are
treated, see How backlogs and boards display hierarchical (nested) items.
 Tip
If, after refreshing a backlog or board, you don't see bugs where you expect to see
leaf nodes of nested items appear on the Kanban or task boards.
Add other work item types to your backlogs or

boards
Bugs are a common item that teams want to track, and choose how they track them. For
more information, see Manage bugs.
However, what if you want to track other work item types on your backlogs and boards?
You can add other work item types—such as change requests, issues, or impediments—
by customizing your process or project, based on the process model you use. For
details,
For the Inheritance process model, see Customize your backlogs or boards for a
process.
For Hosted XML and On-premises XML process models, see Add a work item type
to a backlog and board.
Create, list, and manage bugs

Bugs that are managed with requirements can be added through the product backlog
or Kanban board. When bugs are managed along with tasks, you can add them to a
sprint backlog or task board. Or, capture them using other tools. For more information,
see Define, triage, and manage bugs.
 Tip
Effort should automatically be part of a bug, but if you don't see it, customize the
bug work item type for it to appear.
You can review bugs defined for your project by creating a query and specifying the
Work Item Type=Bug. Or, open a predefined query, Active Bugs (Agile and CMMI), or
Work in Progress (Scrum).
Related articles
Define, capture, triage, and manage bugs
Enable backlog levels of interest to your team
Triage work items
Article • 06/27/2023
2018
boards.
tools.

backlog name.

items

boards
example:

７ Note

７ Note
with requirements.

column.



board checklist
cards.



７ Note

model

backlogs and boards

Related articles
Create your backlog
Rollup of work and other fields
Article • 02/21/2023
2018
Rollup provides summed values of select fields for all child work items of a parent.
Because Azure DevOps Services and Team Foundation Server (TFS) support multiple
levels of nesting, when you perform rollup, you want to make sure you don't double-
count values. Most project managers are interested in getting rollup of estimated or
completed work, effort, size, or story points.
７ Note
The system doesn't support rollup of the Effort, Story Points, or Size fields across
product backlogs and portfolio backlogs.
Native support of rollup within the web portal

Azure Boards supports rollup columns on product and portfolio backlogs, rollup within
the sprint Planning pane, as well as rollup on sprint backlogs and taskboards.
Display rollup progress bars, counts, or totals

From any product or portfolio backlog, you can add rollup progress bars, counts of
descendant work items within a hierarchy, or sum of select fields, such as Story Points or
Remaining Work.
For example, progress bars are shown here for a portfolio backlog.
To learn more, see Display rollup progress or totals.
View rollup within sprint Planning pane

As you assign backlog items to a sprint using the Planning pane, the sprint window
updates with a running tally of the number of backlog items and tasks, as well as the
Planned Effort.
Planned Effort provides a sum of all Story Points or Effort defined for backlog items
assigned to the sprint. To learn more, see Assign backlog items to a sprint.
View rollup of sprint backlogs and taskboards

In addition, you can view rollup of Remaining Work from a sprint backlog or taskboard.
From the sprint backlog, the sum of all Remaining Work defined for all tasks is
displayed for the parent work item. This value also displays on the parent work item card
when you view the task board.
From a sprint task board, there are three types of rollup:
The rollup of Remaining Work displays on the card for the parent work item
The sum of all Remaining Work defined for all tasks within a column displays at the
top of each column
The sum of all Remaining Work defined for all tasks for a backlog item displays
within each row, grouped by column.
When you update the status of a task as Completed, the system automatically zeros out
the Remaining Work for that task. To learn more, see Task board.
Other tools that support rollup

You can obtain rollup of additional data fields in Azure DevOps work tracking data by
using one of the following methods:
Method Azure DevOps Services On-premises Azure DevOps
Work item query charts
Microsoft Excel
Analytics
SQL Server Reporting Services report
Work item query charts and rollup

You can create a flat list query that sums the values of a field you specify. To learn more,
see Track progress by creating status and trend query-based charts. Charts support a
count of work items or a sum of a field.
For example, here we show a pivot table that sums the story points for user stories by
area path and work item state.
Microsoft Excel and rollup of work tracking
data
You can export a query to Excel that contains the work items you want to provide rollup.
You can then write an Excel macro to get the sums and publish data back to TFS. To
learn more about Excel integration, see Bulk add or modify work items with Excel.
To learn more about Excel macros, see Automate tasks with the Macro Recorder .
 Tip
To provide support for opening work items and query results in Excel from the web
portal, add the VSTS Open in Excel Marketplace extension to your organization
or collection.
Marketplace extensions and custom controls

There are several extensions available from the Marketplace that provide rollup. Here
are a few that may support your needs:
VSTS Rollup , supports Azure DevOps Services only

TFS Aggregator , supports Azure DevOps Services and TFS
Or, you can write an extension using the REST API for work tracking to get rollup. A code
sample available on github that can get you started is TFS Aggregator .
Analytics service
You can use the Analytics Service to answer quantitative questions about your projects.
With this service, you can add Analytics widgets to your dashboard. Or, you can create
additional reports using Power BI.
Rollup requirements
To support rollup, structure your work items according to the following
recommendations:
Use parent-child links to link work items that contain values that you want to
rollup.
Add required fields to the WITs that will capture the rollup values. Default fields
used to schedule work are only present on the task work item. These fields are:
Original Estimate (Microsoft.VSTS.Scheduling.OriginalEstimate): The amount of

work required to complete a task. (Agile and CMMI)
Completed Work (Microsoft.VSTS.Scheduling.CompletedWork): The amount of

work that has been spent implementing a task. (Agile and CMMI)
Remaining Work (Microsoft.VSTS.Scheduling.RemainingWork): This field is used

to support burndown charts.
If your project was created using the Visual Studio Scrum process template, only
Remaining Work is defined in the task.
To learn more about adding fields, see Modify a field or add a custom field.
Determine the unit of time used to track work and make sure it is used consistently
across your team or organization. For example, you can track tasks using hours or
days.
Determine if you want to make rollup values read-only on the work item form. By
making them read-only you prevent users from entering inaccurate data. You make
fields read-only using the Control field Readonly attribute.
Q&A
Q: Can I get rollup of team capacity?

A: No. The data entered for team capacity isn't stored in the regular data stores.
View and configure team velocity
Article • 07/19/2023
2018
Velocity metrics provide useful information, so teams can plan and forecast sprints and
determine how well they estimate and meet planned commitments. You can get an
indication of how much work a team can complete during a sprint based on either a
count of work items completed or the sum of estimates made for effort (product
backlog items), story points (user stories), or size (requirements). Use velocity as an aid
to determine team capacity and don't confuse it with key performance indicators.
Prerequisites
Be aware of the required and recommended tasks, listed later in this article.
 Tip
Velocity chart types

You have a choice of Velocity charts: the in-context Velocity chart you access from a
Backlogs page and the Velocity widget you add to a dashboard. With both these charts,
you can quickly determine the information in the following table, which describes the
available workflow state categories and their descriptions.
Items assigned to a Proposed or Resolved aren't included in any of the calculations for
Completed, Completed Late, or Incomplete. For more information, see How workflow
category states are used in Azure Boards. The selections you make are only set for you,
and persist across sessions until you change them.
Workflow Description
state
Planned Calculated based on the number of work items assigned to the sprint before the
start of the sprint. If a work item gets assigned to the sprint before it begins, but
gets assigned to another sprint after the start of the original sprint, it shows as
Planned in the original sprint. Then, the work item shows as Late or Incomplete in
the new sprint that it's assigned to.
Completed Calculated based on the number of work items assigned to the sprint before or
after the start of the sprint and completed before the end of the sprint.
Completed Calculated based on the number of work items assigned to the sprint before or
Late after the start of the sprint but completed after the end of the sprint.
Incomplete Calculated based on the number of work items assigned to the sprint before or
after the start of the sprint and not yet completed.
Later in this article, learn how to open the Velocity in-context report or configure the
Velocity widget.
In-context Velocity chart

You can configure each chart in the following ways:
Sum of Effort, Story Points, or Size fields or other supported numeric field assigned
to backlog items
Count of work items that appear on the backlog
Number of iterations
The widget supports some more configuration options. To configure or view Velocity
charts, see Configure and view Velocity charts.
View the Velocity in-context report

Velocity reports are available for each backlog level, both product and portfolio
backlogs. Each report provides interactive controls to provide each user the view of
interest to them.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ) and go
to your project.
2. From the Boards > Backlogs screen, select Analytics to open the Velocity report
for your product or portfolio backlog.
3. To change to a different backlog, choose from the backlog selector, and then
select View full report for Velocity.
4. Use the interactive controls to select the count or sum field and number of
iterations. Select Custom iterations to specify any number of iterations between 1
and 15.
If your team hasn't completed a sprint or if you're working on items before a sprint
start date, there's no data to analyze and forecast. You might see this message: Set
iteration dates to use this widget. To resolve this situation, set an iteration date
range to include present date or wait for the sprint to start.
Hover over a column area to show a summary of planned and completed work
items. For example, for the 07_2019 sprint, 131 items are planned.
For more information, see the workflow state descriptions mentioned earlier in this
article.
Dashboard.
6. Select the dashboard and select OK.
7. To return to the Analytics summary, select the back arrow.
Configure the Velocity widget

You can only configure your Velocity widget for a single team. If you want to view the
velocity for several teams, then you must configure a portfolio management team that
rolls up from several teams. For more information, see Add teams.
If you haven't yet, Add the Velocity widget to your dashboard. For Azure DevOps Server
2019, Enable or install Analytics.
Complete the following steps to configure the Velocity widget.
1. Select the actions icon and select the Configure option to open the
configuration dialog.
Modify the title, select the team, and then select either the backlog level or work
item type to track. Select whether you want to track a count of work items or a
sum of a numeric field. The most common summed field is that of Effort, Story
Points, or Size.
2. Specify the number of sprints you want to view. The default is 6 and the maximum
is 15.
3. (Optional) Select the check boxes to show additional information for work
completed later than planned for each sprint.
Display planned work for iterations: Check this box to display the amount of
work planned for an iteration at the start of the iteration, which is useful for
comparing your planned work to actual deliverables. By default, the count of
planned work begins on the start date of the iteration.
Days past start date of iteration when planned work is final: Specify the
number of days past the start date to count planned work. For example, if the
first two days of an iteration are for planning, then you can enter 3 , and
planned work gets counted on the third day. For example, if the iteration
starts on 01/01/2018 , and three backlog items are assigned to the iteration
on 01/01/2018 end-of-day, then those three backlog items are considered as
Planned. If your team doesn't complete planning until a few days into the
iteration, then you can update the Days past start date of iteration when
planned work is final.
７ Note
Work is considered Planned if it's assigned to the iteration as of the Iteration

Start Date.
Highlight work completed late: Check this box to display work items marked
complete after the iteration end date, which is considered to be completed
late and show as light green. Highlighting work completed late is useful for
spotting a trend where work items are marked complete after the iteration is
complete.
Days past end date of iteration after which work is late: Specify the number
of days past which you consider a work item late if its status is still new or is
in progress. For example, entering three days gives the team 3 days after the
end of an iteration to mark work items complete or done, before they're
considered late.
７ Note
A work item is considered late when the work item's Completed Date is
later than End Date of the Iteration the work item is currently assigned
to. It takes into account the value you enter for Days past end date of
iteration after which work is late.
4. Select Save when you're done. The following image shows Velocity based on Story
Points and eight sprints of data.
For more information about Planned, Completed, Completed Late, and Incomplete
states, see the State descriptions mentioned earlier in this article.
Required and recommended tasks

For your team to gain the greatest utility from the Velocity charts, follow these required
and recommended tasks.
Required:
Define iteration paths (sprints) and configure team iterations. Sprints should be of
the same duration.
Update the status of backlog items once work starts and when it's completed. Only
backlog items with State of In Progress or Done show up on the Velocity chart or
widget.
Recommended:

like requirements, bugs show up on the backlog and be counted within the
Velocity chart and forecasting.
Don't create a hierarchy of backlog items and bugs. The Kanban and task boards
and sprint backlog only show the last node in a hierarchy, called the leaf node. For
example, if you link items within a hierarchy that is four levels deep, only the items
at the fourth level appear on the Kanban board, sprint backlog, and task board.
Instead of nesting requirements, bugs, and tasks, we recommend that you
maintain a flat list-only creating parent-child links one level deep between items.
Use Features to group requirements or user stories. You can quickly map stories to
features, which create parent-child links in the background.
Minimize the size variability of your backlog items to help strengthen the team's
ability to create truer estimates. Variability increases uncertainty, but minimizing
the variability of your estimates, increases the likelihood of more reliable velocity
metrics and forecast results. Estimates, by their nature, don't reflect reality. They
represent a best guess by the team as to the effort required to complete an item,
as it relates to the effort to complete other items on the backlog.
） Important
Deleting Area Paths or reconfiguring Iteration Paths can cause a loss of data and
can't be reverted. For example, burndown or burnup widget charts, sprint
burndown, and velocity charts for teams whose Area Paths are changed won't
reflect correct data. Historical trend charts reference the Area Path and Iteration
Path as defined at a point in the past for each work item. When an Area Path or
Iteration Path is deleted, then the historical data for it can't be retrieved.
Add other teams

If each team wants to work with their own backlog view, Velocity chart, and forecast
tool, you can add a new team. Each team gets access to their own set of Agile tools.
Each Agile tool filters work items to only include assigned area paths and iteration paths
that are set for the team.
Next steps
Plan your sprint
Related articles
Forecast your sprints
Set dashboard permissions
Configure a burndown or burnup widget
Implement Scrum practices for your
team in Azure Boards
Article • 04/24/2023
2018
Your Sprints tools include a filtered backlog based on an Iteration Path and a similarly
filtered taskboard. These tools are useful for implementing Scrum practices. With Scrum,
you can schedule and plan sprints, update your taskboard, and monitor your sprint
burndown.
Scrum methods use Iteration Paths, also referred to as sprints, to plan work to be
performed by a team within a specific time period and cadence. To get started, several
sprints are predefined for your team. If you're new to Scrum, get an overview from What
is Scrum?.
７ Note
Use Azure Boards to implement Scrum

The general sequence of steps for implementing Scrum using Azure Boards is as follows:
Configure teams and sprints

1. Define project-level Iteration Paths and set dates
2. (Optional) Add project-level Area Paths (Or, add an area path when you configure
each team)
3. Add teams
4. Select team-level Iteration Paths.
Create team backlog

1. Create and organize your team backlog.
2. (Optional) Forecast your team backlog.
Implement a sprint
You can quickly assign work items to a sprint by dragging and dropping them from the
product backlog to the sprint.
1. Assign backlog items to a sprint

2. Add tasks to backlog items
3. Set sprint capacity
4. Adjust work to fit sprint capacity
5. (Optional) Share your sprint plan
6. Update the Taskboard
7. Monitor your sprint burndown
Close out a sprint

1. End of sprint activities
2. Sprint retrospective meetings
Sprint backlogs and Taskboards overview

Sprint backlogs and Taskboards provide a filtered view of work items a team has
assigned to a specific iteration path, or sprint. Sprints are defined for a project and then
selected by teams. From your backlog, you can map work to an iteration path using
drag-and-drop, and then view that work in a separate sprint backlog.
How selected sprints show up on the backlog
Each sprint that you select for your team provides access to a sprint backlog, taskboard,
and other Agile tools for planning and tracking work.
1. You can gain an overview of your sprint planning by turning on the Planning view
option. From the product backlog or any sprint backlog, choose the view
options icon and select Planning.
７ Note
The Planning pane will only show the current sprint and the next 10 future
sprints in the list, even if more have been selected for the team.
2. To select a sprint backlog, you can choose one of the sprint links from the
Planning pane, or from a Sprint backlog, choose a sprint from the sprint selector.
Track team capacity
Once you've defined iteration (sprint) paths and configured team iterations, you can
start using the following tools to plan your sprint.
At the start of each sprint, you'll want to plan the work that your team can commit to.
The three Agile tools that support this work include the sprint backlog, capacity
planning, and capacity bars. The sprint backlog contains a filtered subset of backlog
items whose iteration path corresponds to the current sprint.
Team capacity planning tool

By setting team capacity, the team knows exactly the total number of work hours or
days the team has for each sprint. With this tool, you set individual team member
capacity and days off. And, conveniently, you can set holidays or shared days off taken
by the entire team.
Setting capacity for each team member working during a sprint causes the capacity bar
for that individual to appear.
You set recurring days off, such as weekends, through team settings.
Individual and team capacity bars
With capacity bars, you can quickly see who is over, at, or under capacity. Capacity bars
update with each of these activities:
Tasks are assigned with non-zero remaining work

Change in remaining work
Date change within the sprint cycle. Individual and team capacity always reflects
their capacity from the current day until the end of the sprint.
Here's how to interpret the capacity colors:

Update tasks and monitor burndown
During a sprint, use the taskboard and sprint burndown chart to track their progress.
Your sprint burndown chart provides you with an at-a-glance visual to determine if your
team is on track to meet their sprint plan.
Taskboard
Your Taskboard provides an interactive progress board for work required to complete
the sprint backlog. During your sprint, you'll want to update the status of tasks and the
remaining work for each task.
Updating tasks daily or several times a week yields a smoother burndown chart.
You use the sprint burndown chart to mitigate risk and check for scope creep
throughout your sprint cycle. The burndown chart reflects the progress made by your
team in completing all the work they estimated during their sprint planning meeting.
The ideal trend line always indicates a steady burndown. The blue area, however,
represents what's actually going on. It shows the buildup of work as team members add
tasks and the reduction of work as team members complete those tasks.
Use velocity and forecast tools to predict work

effort
Use sprint planning and tracking tools for each sprint. Also, use the velocity and forecast
tools to estimate work that can be completed in future sprints.
Velocity provides a useful metric for gaining insight into how much work your team can
complete during a sprint cycle. And, the forecast tool provides a means for determining
how much work your team can complete within a sprint. This amount is based on a
specified team velocity.
After several sprints, use the Velocity chart and Forecast tool tool to estimate work that
can be accomplished in future sprints.
Velocity chart
Each team is associated with one and only one velocity chart. The green bar within the
chart indicates the total estimated effort (story points or size) of backlog items (user
stories or requirements) completed within the sprint. (Blue corresponds to the estimated
effort of items not yet completed.)
Velocity will vary depending on team capacity, sprint over sprint. However, over time,
the velocity should indicate a reliable average that can be used to forecast the full
backlog.
By minimizing the variability of backlog item size—effort or story points—you gain more
reliable velocity metrics.
Forecast tool
You can use the forecast tool to get an idea of how many and which items you can
complete within a sprint.
By plugging in a velocity, you can see which items are within scope for the set of sprints
the team has selected. As shown here, a velocity of 15 indicates that it will take three
sprints to complete the work shown.*
Query sprint scope changes
There isn't a sprint scope change chart or widget. However, you can query for work
items added to a sprint or moved out of a sprint after the start of the sprint. Use the
steps provided next.
List work items added after the start of the

sprint
1. Open the velocity chart for the team and choose the Planned bar for the sprint of
interest. You can use the Planned bar for a velocity chart widget or the team
backlog velocity chart.
2. The Query Results page opens with a list of work items defined for the sprint at the
start of the sprint, the first day of the sprint. This list is an itemized list of work item
IDs.
3. Choose the Editor page to edit the query.
4. List the items that were added to the sprint after the sprint's start. To do so, change
the query to add and change the following clauses:
Add a clause at the top to specify the Work Item Types of interest
Change the Operator for the ID Field to Not In.
Add the Iteration Path for the sprint of interest.
Add the Area Path for the team.
The updated query should look similar to the following image.
5. Add Created Date as a column option, and sort by that field. You can then view the
existing work items that were added to the sprint and what newly created work
items were added.
List work items moved out of the sprint

1. Open the velocity chart for the team and choose the Planned bar for the sprint of
interest. You can use the Planned bar for a velocity chart widget or the team
backlog velocity chart.
2. The Query Results page opens with a work item list defined for the sprint at the
sprint's start, the first day of the sprint. This list is an itemized list of work item IDs.
3. Choose the Editor page to edit the query.
4. List the items that were moved out of the sprint after the sprint's start. To do so,
change the query to add and change the following clauses:
Add a clause at the top to specify the Work Item Types of interest
Add the Iteration Path for the sprint of interest, specify Not Under operator
Add the Area Path for the team.
The updated query should look similar to the following image.
For other options to determine changes to the sprint scope, see Query by date or
current iteration, List work items moved out of a sprint.
Next step
Schedule sprints
Related articles
If you work with several teams, and each team wants their own backlog view, you can
create more teams. Each team then gets access to their own set of Agile tools. Each
Agile tool filters work items to only include those assigned values under the team's
default area path and iteration path.
Scrum concepts
End of sprint activities
About work items
What is Scrum?
Manage sprint timelines
Article • 02/24/2023
2018
With Scrum, teams plan and track work at regular time intervals, referred to as a sprint
cadence. You define Iteration Paths, also referred to as sprints, to support the
assignment of work items to time-box intervals. Iteration paths are a shared resource
used by all teams that select them. Many teams choose a two or three week cadence.
You can, however, specify shorter or longer sprint cycles. Or, you can create a release
schedule that encompasses several sprints.
 Tip
If all you need is to change the iteration dates, you can do that by following the
guidance provided in this article. However, if you need to define the iteration paths
and tree structure, or assign team sprints, then follow the guidance provided in
Define iteration paths (sprints) and configure team iterations.
Prerequisites
To change sprint dates, you must be a member of the Project Administrators
security group, or have the Edit this node permission for the iteration child node
you want to change. By default, the user who created the project has these
permissions set. For more information, see Change project-level permissions or Set
Start scheduling sprints

To quickly get started, you can use the default sprints. Default sprints are also referred to
as iterations and were added when your project was created. Note, you must be a
member of the Project Administrators group to add sprints and schedule sprint dates. If
you created the project, you're a member.
1. From your web browser, open your team's sprint backlog. (1) Check that you've
selected the right project, (2) choose Boards>Sprints, (3) select the correct team
from the team selector menu, and lastly (4), choose Backlog.
2. To choose another team, open the selector and select a different team or choose
the Browse all sprints option. Or, you can enter a keyword in the search box to
3. Choose Set sprint dates.

4. Choose the calendar icon to select the start date, and then the end date of the
sprint.
5. Choose Save and close. You'll see the date listed.
That's it! You can now start planning your first sprint.
If you have several teams, more complex release and sprint cadences to schedule, or
want to create child iterations, then read further. You define these items through the
settings context for the project. See Define iteration (sprint) paths and configure team
iterations.
７ Note
Terminology note: Your set of Agile tools uses the Iteration Path field to track
sprints and releases. When you define sprints, you define the picklist of values
available for the Iteration Path field. You use iterations to group work into sprints,
milestones, or releases in which they'll be worked on or shipped.
Schedule new sprints for different teams and

release cadences
７ Note
Your sprint backlog and taskboard are designed to support your Scrum processes.
In addition, you have access to product and portfolio backlogs and Kanban boards.
For an overview of the features supported on each backlog and board, see
Backlogs, boards, and plans.
Your project comes with several sprints predefined. However, they aren't associated with
any dates. For Scrum and sprint planning, assign start and end dates for your team's
sprints.
Defining other sprints is a two-step process. You first define the sprints for your project
and then you select the sprints for each team to use—Define iteration (sprint) paths and
configure team iterations. In this way, the system supports teams that work on different
sprint cadences.
Each sprint that you select for your team provides access to a sprint backlog, taskboard,
and other sprint planning tools for planning and tracking work.
For example, by selecting Sprints 1 through 6, the Fabrikam Fiber team gets access to six
sprint backlogs. They also get access to capacity planning tools and a taskboard for each
sprint.
Next step
Assign work to a sprint or
Related articles
If you work with several teams, and each team wants their own backlog view, you can
create more teams. Each team then gets access to their own set of Agile tools. Each
Agile tool filters work items. These items only include those assigned values under the
team's default area path and iteration path.
Article • 05/19/2023
2018
Teams use the forecast tool to help in their sprint planning efforts. By plugging in a
value for the team velocity, the forecast tool shows which items in the backlog can be
completed within future sprints. Both tools are team-specific tools that rely on the
team's ability to estimate backlog items. Once your team has completed a sprint or two,
they can use the team velocity to forecast how much of the backlog they can finish
within the upcoming sprints.
Use this article to learn:
＂ How to forecast upcoming sprints

＂ Required and recommended team activities to support forecasting
７ Note
Prerequisites
You must be added to a project as a member of the Contributors security group. If
you're not on a project or team, get added now.
You must be granted Basic access or higher to use the forecast feature. For more
information, see About access levels.
７ Note
Required and recommended activities
Here's what you need to have in place before you attempt to forecast your team's
backlog.
Required:

Sprints should be of the same duration.
Select enough future sprints to forecast your entire product backlog.
Update the status of backlog items once work starts and when completed. Only
backlog items whose State maps to a state category of Proposed or In Progress
show up on the velocity chart. (For more information, see Workflow states and
state categories).
Recommended:

like requirements, bugs appear on the backlog and be counted within the Velocity
chart and forecasting.
Don't create a hierarchy of backlog items and bugs. The display of the leaf node,
the last node in a same-category hierarchy, may only appear on Kanban boards,
sprint backlogs, and Taskboards. For more information, see Fix reordering and
Instead of nesting requirements, bugs, and tasks, maintain a flat list—only creating
parent-child links one level deep between different-category items. Use Features
to group requirements or user stories. You can quickly map stories to features. The
map creates parent-child links in the background.
７ Note
If you work with several teams, and each team wants to work with their own
backlog, velocity chart, and forecast tool, you can create additional teams. Each
team then gets access to their own set of Agile tools. Each Agile tool filters work
items to only include those whose assigned area paths and iteration paths meet
those set for the team.
Forecast upcoming sprints

Use the forecast tool to get an idea of how many items you can complete within a
sprint. By plugging in a velocity, you can see which items are within scope for the set of
sprints the team has activated.
To forecast your product backlog, complete the following actions.
column options.
4. Choose the view options icon and slide Forecasting to On. To keep things
simple, turn the Mapping and Planning panes Off.
Set In Progress Items to Off to hide those items that won't be counted in the
forecast. The forecast tool ignores Scrum items set to Committed or Done and
Agile and CMMI items set to Active, Resolved, or Completed.
5. Enter your team's predicted velocity.
 Tip
If your team has been working for several sprints, you can gain an idea of your
team's velocity from the Velocity widget.
The tool draws lines for each future sprint selected by the team. The Forecast lines
show how much work your team can complete in future sprints. Typically, items
above the first line are already in progress for the current sprint. Items that fall
between the first and second forecast lines indicate what can be completed in the
named sprint.
Review the forecast results
Check the results manually to understand discrepancies in what you expect and
what the forecast tool displays.
Check the amount of effort (Effort, Story Points, or Size) forecasted per sprint.
Question forecast results where the effort of an item is near to, or greater than,
team velocity.
In this example, a Velocity of 20 is used. The forecast tool limits the number of items
that are shown between the forecast lines to those items that can be completed within
the sprint or using unused velocity points from the previous sprint.
The forecast tool shows between two and four items can be worked on during Iterations
2 through 6 based on the number of Story Points you assigned to each user story or
bug. The forecast logic carries over velocity points from one sprint to the next.
Iteration 2: 13 Story Points, items 1 and 2 can be completed; 7 velocity points are
carried over to the next sprint
Iteration 3: 24 Story Points, items 3 through 5 can be completed; 3 (=20+7-24)




Determine the velocity needed to complete all
items in the backlog
Another way to use the forecast tool is to enter different velocity values until all the
backlog items are completed within a given set of sprints. This forecast provides an
estimate of what velocity is required to complete your backlog of items.
You can then assess the delta between the current team's velocity and the required
velocity. The delta helps determine what other resources are required to meet
production demands within a required time.
Next steps
Assign work to a sprint
Related articles
Team velocity
Use the taskboard to track work during your sprint
Monitor the sprint burndown chart to determine if your team is on track to
complete the sprint plan
1. Assign backlog items to a sprint in
Azure Boards
Article • 06/27/2023
2018
The first step in planning your sprint is to assign work from your backlog to a sprint.
Your team builds the sprint backlog during the sprint planning meeting, typically held
on the first day of the sprint. Each sprint corresponds to a time-boxed interval that
supports your team's ability to work using Agile processes and tools. During the
planning meeting, your product owner works with your team to identify those stories or
backlog items to complete in the sprint.
７ Note
Your project comes with several predefined sprints. You can quickly add more
sprints from your backlog as needed. Or, change the dates of the predefined
sprints. To learn more about sprints, also referred to as iterations, see About areas
and iterations.
Here's an example of a sprint plan that consists of backlog items and the tasks required
to complete each item. By setting team capacity and estimating tasks, the team can see
when the team or a team member is at, under, or over capacity.
＂ Open your product backlog

＂ Assign backlog items to a sprint
＂ Use multi-select to bulk update work items
Planning meetings typically consist of two parts. In the first part, the team and product
owner identify the backlog items that the team feels it can commit to completing in the
sprint, based on experience with previous sprints. These items get added to the sprint
backlog. In the second part, your team determines how it develops and tests each item.
They then define and estimate the tasks required to complete each item. Finally, your
team commits to implementing some or all of the items based on these estimates.
７ Note
Sprint planning doesn't need to be challenging. It can be fun and a time for the
entire Scrum team to build camaraderie by working together to answer the
question of "What can we commit to?" For examples and strategies to keep your
sprint planning focused and effective, check out the What is Scrum?.
When you've completed your sprint plan, your sprint backlog should contain all the
information your team needs to successfully complete work within the time allotted
without having to rush at the end.
Prerequisites
７ Note
Open your team's product backlog
７ Note
Your sprint backlogs are one of three classes of backlogs available to you. For an
overview of the features supported on each backlog and the two types of boards,
see Backlogs, boards, and plans.
For a beginner's guide to planning and tracking work, see Get started with Agile
tools.
 Tip

column options.
Assign work from your backlog to a sprint
Before you start planning your sprint, you'll want to have created, organized, and
estimated your backlog.
Also, you'll want to have set the start and end dates for your sprint.
You can quickly assign work items to a sprint through drag-and-drop from the product
backlog to the sprint.
1. The next step is to open the Planning pane. Choose the view options icon and
select Planning. While you're at it, make sure Parents and Forecasting are Off. You
can choose to set In Progress items to On or Off.
2. You can drag and drop items from the Backlog onto a sprint.
７ Note
The Planning pane only shows the current sprint and the next 10 future
sprints in the list, even if more have been selected for the team. Only a team
administrator or member of the Project Administrators group can select
iterations for a team.
3. Select one or more items from the backlog and drag them to the sprint you're
planning. This action updates the Iteration Path of the backlog items and any of its
child tasks to the sprint you selected.
4. Check the level of effort displayed in the sprint window. As you assign backlog
items to a sprint, the sprint window updates with a running tally of the number of
backlog items and tasks and the Planned Effort.
Planned Effort provides a sum of all Story Points or Effort defined for backlog items
assigned to the sprint. This sum represents your initial guess at the amount of
work your team completes in the sprint. Next, you'll define tasks, estimate that
work, and use your team's capacity to make sure it fits in the sprint.
Use the multi-select feature to modify items in
bulk
Multi-select of work items on the product and sprint backlogs works in the same way as
multi-select works within query results.
With multi-select, you can complete several actions on several work items at once, such
as:
Move to a sprint
Change the backlog priority
Assign to a team member
Change one or more field values
Add links
Map items or change the parent an item is linked to
To select several items in a sequence, hold down the shift key. To select several non-
sequential items, use the Ctrl key. Then, you can either drag the selected items to a new
position within the backlog, to a different sprint, or select an option from the context ( )
or action ( ) menu of one of the items.
For more information, see Bulk modify work items.
Next step
Now that you've defined your sprint plan, your team's ready to begin work on the sprint
tasks.
2. Add tasks
Related articles
To add or rename the sprints your team uses, see Define iteration (sprint) paths and
configure team iterations.
If your backlog doesn't show the work items you expect, see Setup your Backlogs &
Boards.
Add tasks to backlog items to support
sprint planning
Article • 06/27/2023
2018
Add tasks to backlog items when you want to track the work required to implement
those tasks. You can also use tasks to estimate work that is assigned to individual team
members and the team. The capacity tool tells you how much work your team can
commit to. However, to compare capacity with planned work, you need to define and
estimate tasks for each backlog item.
＂ Select a sprint backlog for a team

＂ Add tasks to backlog items from the sprint backlog or taskboard
＂ Estimate work, set Remaining Work
Add as many tasks as needed to capture the work required to complete each item. Tasks
can represent different work to be completed, such as design, code, test, content, or
sign out. Usually, each team member adds their own tasks and sets estimates for the
work. However, a development lead could define the initial tasks for a story or
requirement.
Prerequisites
７ Note
Open a sprint backlog for a team

To choose another team, open the selector and select a different team or choose
2. To choose a different sprint than the one shown, open the sprint selector and
choose the sprint you want.
The system lists only those sprints that have been selected for the current team
focus. If you don't see the sprints you want listed, then choose New Sprint from
the menu, and then choose Select existing iteration. For more information, see
Define iteration (sprint) paths.
Add existing work items to a sprint

If you haven't yet assigned work items to a sprint, see 1. Assign backlog items to a
sprint.
If you have added work items and they don't appear in your sprint backlog, check their
area and iteration paths.
The Area Path must match one of the areas assigned to the team
The Iteration Path must match the iteration of the sprint that you've selected.
For details on assigning iteration paths to teams, see Define Iteration Paths and
configure team iterations.
If you have added task work items, but they don't appear as a child of a product backlog
item, you can parent them from the sprint backlog.
Unparented tasks assigned to the selected sprint appear at the top of the backlog under
the Unparented group. Drag and drop the task on top of the work item you want to
parent it to.
Add tasks to backlog items

If you haven't yet assigned backlog items to your sprint, do that now. Also, you'll want
to have set the start and end dates for your sprint.
For each sprint backlog item, add a task. Adding tasks from the sprint backlog or board
automatically links the task to its parent backlog item.
 Tip
You can quickly add several tasks on the taskboard by simply entering a title. You
can then later bulk edit items to assign them or add additional details. You can also
enter Remaining Work onto the card by making sure you add that field to display
on the taskboard.
You can add tasks from the sprint Backlog or Taskboard. ALl items you add are
automatically assigned the Iteration Path of the selected sprint.
From the Backlog view, choose the plus sign to open the work item form for a task.
Complete the form as described in the next section.
Another option, is to open the Taskboard, and add tasks as cards. Select the plus
icon, enter a title for the item, and then press Enter on your keyboard.
 Tip
You can quickly add tasks through the Taskboard by just specifying the title of the
work item. To show fields on the card, see Customize a sprint Taskboard.
To interactively filter sprint views, choose Filter , and then specify a keyword or select
a value for a field or tag. For more information, see Interactively filter backlogs, boards,
queries, and plans.
Complete the task form

Name the task and enter an estimate for Remaining Work. Also, if you know who's doing
the work, assign the task to that team member.
At the planning stage, Remaining Work corresponds to an estimate of how long it takes
to complete the task.
A good rule of thumb is to size tasks to take no more than a day to complete. If a task is
too large, the team should break it down. In some cases, you might not estimate some
tasks effectively until other tasks have been completed. Create the task now, but
estimate it when you have enough information.
During the sprint, team members update remaining work to continually reflect the time
required to complete the task. This value can actually increase after work begins. For
example, after working 4 hours on a task that was estimated to take 8 hours, you realize
you need 16 hours over what you estimated. You would update the Remaining Work
field with 20 (8-4+16). As you complete a task, you might find that more time is
required. Always update the task with your best estimate of remaining work. That way,
you help accurately reflect the total amount of work remaining in the sprint.
Field
Usage
Original Estimate
The amount of approximate work required to complete a task. Typically, this field
doesn't change after it's assigned.
You can specify work in hours or in days. There are no inherent time units associated
with this field.
Remaining Work
It's used to calculate capacity charts and the sprint burndown chart. You can specify
work in any unit of measurement your team chooses.
Completed Work
The amount of work spent implementing a task.
Activity
Select the type of activity this task represents when your team plans sprint capacity by
activity.
Unparented tasks
Tasks without links to parent backlog items or user stories appear at the top of the
taskboard. You can track unparented tasks in similar ways to other tasks. You can also
drag them to an existing backlog item to parent them. The unparented card tracks the
total of remaining work defined for all unparented tasks. However, it isn't associated
with any work item.
Next step
3. Set sprint capacity
Related articles
Setup your Backlogs & Boards
3. Determine and set sprint capacity in
Azure Boards
Article • 08/24/2023
2018
As a next step, you'll want to determine your team's actual capacity. While velocity
correlates to how your team estimates requirements, capacity correlates to actual task
time. Time is calculated in either hours or days. Capacity takes into consideration the
variation in work hours by team members. It also considers holidays, vacation days, and
non-working days.
Because days off and time available for each team member may vary from sprint to
sprint, set capacity for each sprint. The capacity tool helps you make sure your team isn't
over or undercommitted for the sprint. Also, as you work day-to-day, you'll see if your
team is on track.
＂ Set team capacity for a sprint

＂ Copy capacity from the previous sprint to the current sprint
＂ Track capacity when performing multiple activities
＂ Add or remove user accounts from capacity planning for a sprint
＂ Track capacity when working on more than one team
If you haven't set up sprints yet for your team, see the Manage sprint timelines while
working in Scrum article.
Prerequisites
To view or set capacity, you must be granted Basic access or higher. Users with
Stakeholder access can't view or set capacity. For more information, see
To set capacity, you must be a member of the team. For more information, see Add
About the Activity or Discipline pick-list items

The values displayed for Activity (Agile, Basic, or Scrum) or Discipline (CMMI) reflect a
union of all values defined for the Activity or Discipline fields in all projects within the
organization.
To change the Activity or Discipline menu selections, see Add and manage fields.
Capacity per day entries

Most teams specify capacity in hours. You can also specify it in days or any other units
your team chooses. For example, 0.5 days would correspond to 4 hours for a typical 8
hour day. Choose the same unit your team uses to estimate and track their time. For
example, the entries they'll make to the Original Estimate or Remaining Work fields.

1. From your web browser, open your product backlog. (1) Check that you've selected
the right project, (2) choose Boards>Sprints, (3) select the correct team from the
team selector menu, and lastly (4), choose Capacity.
Set capacity for the team and team members

From the Capacity page, you can add team members, enter the team time off, and set
capacity and days off for each team member.
1. If you don't see your team members listed, add them. Choose the action icon
and select Add all team members. For this feature to work, team members will
have been added to the team.
７ Note
The Add all team members action retrieved a maximum of 100 team
members. If you have more team members to add, then you can add them
one by one by choosing Add user.
2. If you need to add other contributors to your project, choose the Add user.
3. Next, set any time off that a team member will take. For the entire team days off,
choose the 0 days link as shown.
In the Days off for dialog, select the start and end days during the sprint that the
team member or team will take off.
７ Note
Your sprint planning and tracking tools automatically consider days off when
calculating capacity and sprint burndown. You only have to indicate planned
days off for the team. For more information, see Set capacity for the team
and team members.
4. Now, set the Activity/Discipline and Capacity per day for each team member. If
you track capacity simply by team member, you can leave the Activity or Discipline
selection unassigned.
For example, Christie Church's capacity is 6 hours/day for design work.
Copy capacity planning from the previous

sprint
By copying the capacity from the previous sprint, you save time. With the basics defined,
all you have to do is adjust the capacity based on individual and team days off and
capacity allocation per activity.
Notice that only the capacity-per-day value and activity value are copied over. Individual
and team days off remain unset. The copy operation always copies the latest updates
made to the previous sprint. So you can repeat the copy operation if you've made
changes to the previous sprint that you want to copy to the latest sprint.
Remove a user from capacity
To remove a user, choose the option from the users action menu. This action won't
remove the user from the team.
Review capacity charts

As you define tasks and estimate the work, you'll see capacity charts start to fill in for
each team member. Capacity bars track the remaining work against the capacity for
each team member and the entire team.
You'll also see a roll-up of the remaining work required to complete each requirement or
bug.
From this view, you can easily see which individuals are at or near capacity. Teams can
determine if work needs to be moved out of the sprint or to reassign tasks.
 Tip
Define tasks that take a day or less to complete. This helps mitigate the risks that
come from poor estimates.
Also, don't divide tasks into subtasks. If you do divide a task into subtasks, specify
Remaining Work only for the subtasks, as the system rolls up summary values to
the parent task.
Track capacity when completing multiple

activities
Because individual team members have different sets of skills and duties, you can track
their activity and capacity for each activity and for each sprint.
Here, Jamal divides time between Deployment and Development.
Track capacity when working on more than one

team
If you work on more than one team, you'll want to specify your sprint capacity for each
team. For example, both Christie and Raisa split their time between the Web and Phone
teams. As such, give 3 hours a day to the Web team, and 3 hours a day to the Phone
team.
If your name isn't listed in the capacity view, you need to be added as a team member.
Next step
4. Adjust work
Related articles
Setting capacity and estimating remaining work for each task provides you with the
tools you need to track the amount of work and resources you have given sprint over
sprint.
Sprint burndown
Velocity
Forecasting
Adjust work to fit sprint capacity
Article • 06/27/2023
2018
Check your team's capacity after you've defined all the tasks for all the sprint backlog
items. You can consider adding more items onto the sprint if your team is under
capacity. If over capacity, you'll want to remove items out of the backlog.
Next, check whether any team member is under, at, or over capacity. Or, if someone
hasn't even been assigned any work. Use the capacity bars to make these
determinations. If you haven't yet set capacity for your team, do that now.
Use this article to learn how to:
＂ Adjust your sprint plan if your team is over or under capacity

＂ Load balance work across your team
＂ Quickly reassign tasks to another team member
Prerequisites
７ Note
Open a Sprint backlog for a team

Check your team capacity

To view capacity charts, you'll want to turn Work details on for a sprint.
Move items out of a sprint

Move items from the sprint backlog back to the product backlog if your team is over
capacity. This action resets the Iteration Path to the default set for your team. Or, you
can move the item into the next sprint your team works in. All the tasks that you've
defined for that item move with the backlog items.
Here we select two items at the bottom of the sprint backlog, open the action icon
for one of the items, choose Move to iteration, and then select Backlog.
 Tip
Optionally, you can open the Planning pane and drag a work item to the backlog
or another sprint which reassigns all child tasks to the same iteration path. See
Assign work to a sprint. Also, you can multi-select several items and drag them to
the backlog or another sprint. Users with Stakeholder access can't drag-and-drop
work items.
Balance work across the team

To quickly reassign tasks, drag the task onto the new assignee's capacity bar.
For example, here we reassign work from Raisa Pokrovskaya to Christie Church.
As you reassign tasks, capacity bars automatically update.
Next step
5. Share your sprint plan
5. Share your sprint plan
Article • 08/22/2023
2018
Once you've completed your sprint plan, you can easily share it with other members of
your team or organization. This article shows you how to:
＂ Create a query from your sprint plan

＂ Email your sprint plan
Any stakeholder on your team (someone with permissions to connect to your project)
can view your sprint plan. Send them the URL of your sprint backlog page. But also, you
can share it with them through email or print a version.

team selector menu, and lastly (4), choose Backlog.
Create query for your sprint plan

column options.
2. To email your sprint plan, create and save the query for the sprint backlog.
3. Then, open the query and choose the email icon.
4. In the form that appears, enter the name(s) of valid users (ones who have access to
the project).
） Important
You can only send the email to individual address for a project member that is
recognized by the system. Adding a team group or security group to the to
line isn't supported. If you add an email account that the system doesn't
recognize, you receive a message that one or more recipients of your email
don't have permissions to read the mailed work items.
Or, you can select all the items in the list, choose Copy as HTML, and paste the
formatted list into an email form or Word document. See Copy a list of work items.
Next step
6. Update the taskboard
Related articles
Send email with work items
6. Update and monitor your Taskboard
Article • 02/24/2023
2018
Once you have your sprint plan in place, you'll execute that plan during the sprint. In
your daily Scrum meetings, your team can view progress made to backlog items and
tasks from the sprint Taskboard.
Your Taskboard provides a visualization of flow and status of each sprint task. With it,
you can focus on the status of backlog items and work assigned to each team member.
It also summarizes the total amount of Remaining Work to complete for a task and
within a column.
＂ Open the sprint Taskboard for your team

＂ Customize your Taskboard
＂ Use your Taskboard to review progress during daily scrum meetings
＂ Filter and group work items on your Taskboard
＂ Update the status of tasks through drag-and-drop
＂ Update remaining work
＂ Close out a sprint
If you haven't yet added tasks to your sprint backlog, do that now.
７ Note
Your Taskboard is one of two types of boards available to you. For an overview of
the features supported on each backlog and board, see Backlogs, boards, and
plans.
Prerequisites
Get added to a project as a member of the Contributors or Project Administrators
security group. To get added, Add users to a project or team.
access or higher. Users granted Stakeholder accesses have limited access to
features. For more information, see Stakeholder access quick reference.
７ Note
Users assigned Stakeholder access can't exercise these Taskboard features: update
fields displayed on cards or use the Planning pane to change the sprint
assignment.
Open the sprint Taskboard for your team

1. From your web browser, open the sprint backlog for your team.
a. Check that you've selected the right Project
b. Choose Boards>Sprints
c. Select the correct Team from the team selector menu
d. Choose Taskboard
the View sprints directory or Browse all sprints option. Or, you can enter a
keyword in the search box to filter the list of team backlogs for the project.
Customize the Taskboard

Each team can customize their Taskboard in the following ways:
Add or rename columns.

Customize cards to show another fields or change card color based on specified
field criteria.
Show bugs on the Taskboard. Your team can choose to manage bugs similar to
product backlog items, as shown in this article, or manage them similar to tasks.
When you track bugs similar to tasks, they'll show up on your sprint backlogs and
Taskboards at the same level as tasks.
An administrator can customize the Taskboard for all teams in the following ways:
Add a custom workflow state to the task WIT for a process

Add a custom work item type to the Taskboard for a process
Taskboard controls
Control Function
Backlog Switch to sprint backlog view
Board Switch to taskboard view
Capacity Switch to Capacity planning
Group by Stories/People Switch grouping of cards based on backlog items or team members
Person Filter tasks to show items assigned to All or a selected team member
Open board settings
See also Backlog keyboard shortcuts.
Review progress in daily scrum meetings

During your daily Scrum, you can filter your Taskboard to help focus on items of
interest.
Group by Backlog items or Group by stories to monitor progress of your product

backlog items, stories, requirements, or bugs.
Group by People when you want to monitor progress of individual team members.
７ Note
Your Taskboard automatically refreshes when changes occur. There isn't any live
updates control, it simply happens in the background. As other team members
move or reorder cards on the taskboard, the Taskboard automatically updates with
these changes. You don't need to press F5 to see the latest changes.
Use the Person filter when you want to focus on work assigned to individual team
members.
 Tip
If you're seeing tasks that don't belong to your team, check that you've selected
the correct team.
Show progress on items

With this view, you can quickly see which items are nearing completion and which have
yet to be started.
1. To show cards based on their backlog-to-task groupings, choose View options

and select Stories (for Agile), Issues (for Basic), Backlog items (for Scrum),and
Requirements (for CMMI).
2. You can Collapse All or Expand All rows, and selectively expand and collapse
a row to focus on a particular item and its tasks.
Show a team member's progress

With this view, you can focus on the work completed and the work remaining for each
individual team member. You can quickly see who may need help with completing their
sprint tasks. This view shows items and tasks assigned to the selected team member.
To filter on the tasks for a specific team member, choose the filter icon, and then
select their name from the Assigned to filter box.
Group tasks by team members
With this view, you can quickly see all the tasks associated with each team member.
Backlog items don't appear in this view, only the tasks associated with each individual.
1. Choose the view options icon and select People.
Only those team members with tasks assigned to them are listed. All their tasks are
shown as cards under their column state.
2. To filter on the tasks for a specific team member, choose Filter , and then select
their name from the Assigned to filter box. For more information, see Interactively
filter backlogs, boards, queries, and plans.
Update tasks during the sprint cycle

The Taskboard makes quick work of updating both task status and remaining work.
Update a task's status

Drag tasks to a downstream column to reflect if they are in progress or completed.
When you move a task to the Done or Completed column, the system automatically
updates the Remaining Work field to 0 in all processes, except CMMI. If you discover
more work is remaining, change the State back to In progress or To do, and enter a
value for the Remaining Work.
Update Remaining Work

Updating Remaining Work, preferably before the daily Scrum meeting, helps the team
stay informed of the progress being made. It also ensures a smoother burndown chart.
Each team member can review the tasks they've worked on and estimate the work
remaining. If they've discovered that it's taking longer than expected to complete, they
should increase the Remaining Work for the task. Remaining Work should always
reflect exactly how much work the team member estimates is remaining to complete the
task.
Close out a sprint and update your Taskboard
At the end of the sprint, you'll want to complete these final tasks:
Zero out Remaining Work of all completed tasks

Update the status of all completed backlog items
Drag incomplete backlog items and tasks to the next sprint or back to the product
backlog.
Drag an incomplete item to the product backlog or to a future sprint updates the
Iteration Path of all unfinished child tasks to correspond to the product-backlog
iteration path or future sprint.
See also End of sprint activities.
Reduce the number of items on the taskboard

If you exceed the number of items allowed on your taskboard, you'll receive a message
indicating that you need to reduce the number of items. The maximum number of items
includes work item types included in the Requirement and Task categories.
You can reduce the number of items on the taskboard by moving them to the backlog
or another sprint. When you move a parent PBI or user story, all active child tasks (State
not equal to Done or Closed) automatically move with the parent item.
From the taskboard, drag the PBI or user story from the first column onto the
backlog or future sprint. All child tasks automatically move with the parent item.
From the sprint backlog, multi-select the items to move and then select the
context menu for an item. Then, select the iteration to move them to.
Next step
Related articles
As you can see, the Taskboard provides support for your Scrum activities. For related
articles, see:

Scrum best practices
Sprint planning
Schedule sprints
Sprint burndown
Capacity planning
End-of-sprint activities
Article • 02/24/2023
2018
At the end of a sprint, teams may want to attend to several tasks to maintain backlog
hygiene. In general, incomplete work should never be assigned to a past sprint. Teams
need to determine how they want to handle work that isn't completed in a sprint and
take appropriate action.
７ Note
There is no automatic way to move incomplete work items assigned to one sprint
to another. Nor, an automatic method for zeroing out Remaining Work.
At the end of each sprint, each team should determine and take action to address the
following questions:
How should we address user stories and their tasks that are only partially completed
at the end of the sprint?
What is the correct way to manage partially done work at the end so that sprint
metrics and velocity are correctly accounted for?
What should we review and in what order?
In general, end-of-sprint activities should be done before or after a sprint review

meeting and before a sprint retrospective. The main item to consider is to maintain
views and metrics to support the team in their sprint reviews, retrospectives, and sprint
planning.
Goals for end-of-sprint activities

Each sprint represents a time-boxed period of development to which work is assigned.
Review the following checklist for the goals to keep in mind when performing end-of-
sprint activities.
Maintain backlog hygiene where no incompleted work is assigned to a sprint

whose end date is in the past
Manage work item states and sprint assignments to support monitoring of team
progress and velocity
Support team's continuous improvement activities
Support team's focus on shipping software and meeting sprint goals
Minimize work tracking efforts that have no value
 Tip
Team velocity is not a measure of team productivity and should only be used as a
metric for planning future sprints. Work is either complete at the end of a sprint or
it isn't. If it's done it counts. If it's not, then it gets reconsidered for a future sprint
and not the current sprint. Velocity tends to level itself out no matter what choices
you make. However, by considering only done work, you work toward a more
realistic value and a much better source of historical data to make future forecasts.
Decide team preferences

The following suggestions walk through the main end-of-sprint activities teams should
consider performing. Typically, these activities should be done on the last day of the
sprint or after the sprint review meeting.
Review the sprint backlog for incomplete user stories, backlog items, and tasks.
You can perform the review by reviewing the sprint backlog or sprint taskboard.
Reassign user stories, backlog items, and tasks not started to the product
backlog or next sprint. Using the Planning pane, you can reassign to the team
backlog or a future sprint. Reassigned work items can be re-estimated and
prioritized.
Determine how to handle incomplete user stories, backlog items, or tasks. Keep
in mind the goal is to ship working software. The two choices here are:
Split the story into two to represent the work completed in the current sprint
and work yet to do. For more information, see Copy or clone stories, issues and
other work items.
Reassign the story to the next sprint where work can be completed. All
unfinished stories in the current sprint account for zero to the sprint's velocity.
Determine how to handle Remaining Work for completed tasks. If tasks are
complete, then having a non-zero value for Remaining Work doesn't make a lot of
sense. Teams should decide how they want to handle these cases and consider
setting the value of Remaining Work to zero for completed tasks.
Review sprint backlog for incomplete work

To determine incomplete work, review the Sprint backlog for work that is still in a
committed, active, in progress state.
Reassign incomplete user stories and tasks to future

sprint
From the Sprint backlog, choose View options and select Planning. Drag and drop
the work items that are incomplete to either the next sprint or back to the team backlog.
As shown in the following image, the Fabrikam Team backlog corresponds to the
default Iteration Path set for the team. Note that if the default is set to the
@CurrentIteration macro, then that selection wouldn't change the Iteration Path until
the start of the next sprint.
Archive past sprints
Over time, the number of sprints defined for a project or assigned to a team can grow.
To minimize the drop-down menu for Iteration paths, Project Administrators can choose
to move past sprints to an archive area. By maintaining the sprint assignment, but
moving it under a different sprint node, all work item data is retained. All sprint charts
and widgets continue to work.
As shown in the following image, sprints from 2012 and 2013 have been moved under
the Previous Sprints node.
 Tip
All data stored in work items is maintained by Azure DevOps until work items are
permanently deleted.
Sprint hygiene tips

The Sprint backlog automatically points to the current sprint as the active sprint based
on the start and end dates. If the current date falls within the sprint period, then the
corresponding sprint is the current sprint. No further action is required to make the next
sprint the active current sprint.
As a project or team administrator, make sure to meet the following guidance for
managing sprints.
Start and end dates defined for your project's sprints shouldn't overlap.
All sprints of interest to a team should be selected for that team's configuration.
Several future sprints should be defined for your project and selected for your
teams.
For more information, see Define iteration paths (sprints) and configure team iterations.
Related articles
Implement Scrum practices for your team in Azure Boards
Sprint planning
Sprint burndown
Customize cards on a sprint taskboard
in Azure Boards
Article • 06/27/2023
2018
Sprint Taskboards are similar to Kanban boards because they show work items as cards
instead of as lists. They're different in the ways summarized in Backlogs, Boards, and
Plans. Similar to the Kanban boards, you can customize cards and add columns.
７ Note
This article addresses customization of a sprint Taskboard. For information on

customizing a Kanban board, see Manage and configure team tools.
Prerequisites
You must have a sprint Taskboard you want to configure. When you add a team,
you add a Taskboard for every sprint that you select for your team. For more
To add or rename columns, or customize cards, you must be added to the team
administrator role for the team's settings you want to modify, or be a member of
the Project Administrators security group. To get added, see Add a team
Taskboard customization options

To add or remove columns, choose Column Options. You customize all other options
through the Settings dialog for the Taskboard.
） Important
To view the content available for your platform, make sure that you select the
correct version of this article from the version selector which is located above the
table of contents. Feature support differs depending on whether you are working
from Azure DevOps Services or an on-premises version of Azure DevOps Server.
To learn which on-premises version you are using, see Look up your Azure DevOps
platform and version
Option
Use to...
Show bugs
Manage bugs on Taskboard similar to tasks.
Customize columns
Add or remove columns shown on Taskboard.
Fields
Add or remove fields from cards.

Includes adding the Parent field to cards.
Styles
Add styling rules to change card color and title style based on field criteria.
７ Note
Each team can customize their Taskboard columns and cards. Taskboard settings
are not inherited from other teams that they may share portions of area paths.
Understand the Taskboard customization

sequence
Before you configure your Taskboard, you'll want to make sure the following tasks are as
complete as possible. Otherwise, you'll find yourself revisiting your configuration.
Process Administrator:
1. Add custom work item types that you want to appear on your Taskboard. For more
information, see Add and manage work item types.
2. Customize your iteration backlog to ensure all of your wanted work item types
appear on the Taskboards. For more information, see Customize backlogs &
boards.
3. Customize each work item type to have any custom fields you want to show. For
more information, see Customize a workflow.
７ Note
You can customize a work item type which is different then customizing the card
displayed on the Taskboard. You customize a WIT by adding fields, changing the
workflow, adding custom rules and more. You can also add custom work item types
and custom backlog levels. For more information, see Customize an inheritance
process.
Team Administrator:
1. Meet with your team and determine how the team wants to manage bugs, similar
to requirements or tasks.
2. Add any tags to work items that you want to use to support styling rules.
Show bugs on your taskboard

If you want bugs to appear on your taskboard, change your team settings for show bugs
on the backlogs and boards.
Add columns
You can add columns or rename columns that appear in your Taskboard. You'll see
different column titles and choices based on the process used to create your project and
whether your team has chosen to treat bugs like requirements or like tasks.
７ Note
Columns you add to a Taskboard aren't supported with corresponding fields such
as the Kanban board columns you add which is supported with Board Column field.
The changes made apply to all sprint Taskboards for the selected team.
1. From your web browser, open your team's sprint Taskboard as described in Update
and monitor your Taskboard. Remember, only team or project administrators can
customize the taskboard.
2. Choose Column Options.
3. In the Customize Columns dialog, choose the column you want to rename, or
choose Add Column.
In this example, we add a column named Review and set the Task to In Progress.
Similar to the Kanban board, each column must map to a category state. There are
four category states: Proposed, Committed, In Progress, and Completed. At least one
column must map to Proposed and one column must map to Completed. To learn
more about each state, see Workflow states and state categories.
4. To change the column order, hover over the column and choose the grabber
icon and drag it up or down within the list of columns.
5. To delete a column, first make sure that the column doesn't contain any work
items. If it does, move the items to another column. Then, hover over the column
and choose the delete icon.
Add fields to cards on a sprint taskboard

Scrum teams use the Taskboard to burn down work and report on progress during daily
stand ups. Each sprint Taskboard shows cards that correspond to both requirements and
tasks.
Provide information-rich cards

Information rich cards not only provide at-a-glance information of interest to you and
your team. They also provide a way for you to update a field without opening the work
item. And, with style rules, you can highlight those work items with select colors based
on the criteria you set.
Each card corresponds to a work item that you use to share information, track status,
and assign work.
７ Note
In this example, the bug work item type (WIT) shows all the core fields. It also shows
three other fields and tags. To make severity 1 bugs stand out, a styling rule has been
added to cause the card to display as yellow.
In the card shown below, the following customizations have been set for the task work
item type (WIT):
Show all core fields: ID, Assigned To, Remaining Work, Tags
Show three additional fields: Priority
Apply styling rule to display tasks with Priority=1 as green
You can either increase or simplify the information that displays on your cards. It all
depends on what's of interest to your team. Does your team like to refer to work items
by their ID? Do they want to see estimates? Do they want to highlight work items
according to set criteria? Or, do just the bare bones of title and assignment suffice?
Your best bet is to show fields on cards based on what your team frequently refers to.
Or, you can show fields based on updates when using the Taskboards. Also, add fields
with information that you can use to filter the board. If you're new to working with these
tools, see Sprint planning.
Add or remove fields from cards on the Taskboard

You change the way cards appear on the Taskboard in the same way you change the
appearance of cards on Kanban boards. Only here, you start from the Taskboard.
1. Open the taskboard for the sprint you want to customize. Remember, only team or
project administrators can customize the taskboard.
2. Choose the gear icon to open the Settings dialog.
3. Choose Fields and then a work item type to see all the settings you can modify.
4. Place a check mark in the check box for those fields you want to have appear on
the board.
Repeat this step for each work item type you want to change. Don't be surprised if
the options change when you choose a different work item type. For example,
Show Remaining Work only applies to tasks and perhaps bugs, but not to user
stories or product backlog items.
5. To add a field, choose the plus icon and enter the name of a field you want to
add.
6. To remove a field, choose the delete icon next to the field.
Update fields from cards

Using the board views provides you with quick and easy ways to update work items as
work progresses. Making daily or frequent updates helps everyone on your team stay in
sync with what's been done and what needs doing next.
To update status of a work item, you simply drag-and-drop cards to a different column.
To change the order or stack ranking of a work item, you drag a card up or down within
a column.
Moving the card from In Progress to the Done column on the Task board, for example,
updates the corresponding State field. In this case, the State field updates from Doing to
Done.
Another handy feature is to update a field without having to open the work item. You
can update most fields shown on the card. Here we reassign a task.
This quick update feature is useful when you need to update many work items at once.
For example, you can add estimates or update Remaining Work.
To change the title, choose the actions icon, and then choose Edit title.
To add tags, double-click the work item to open it. And, just a reminder, you can't
change the IDs for a work item, not from the card and not from within the form.
Define style rules, highlight cards

items meet criteria that you set. Here, we highlight Priority 1 tasks by having the cards
display as green.
Example styling rules

What rules should you apply to highlight work items? Here are a few examples and their
associated criteria.
Work items Criteria
High priority items Priority = 1
High effort items Remaining Work>=12
Stale items unchanged in the last 5 days Changed Date @Today-5

Work items Criteria
Title contains a key word Title Contains Yes
Severity 1 bugs Severity = 1 - Critical AND Work Item Type = Bug
High value business items Business Value 50
Items assigned to specific feature area Area Path Under Fabrikam Fiber\Phone
Contains specific tag Tags Contain RTM
Blocked tasks (Scrum process only) Blocked = Yes
Add or remove a style rule

You can apply style rules to change the color of Taskboard cards based on specified field
criteria.
1. Open the Taskboard that you want to customize.
2. Choose the gear icon to open the Settings dialog.
3. Choose Styles to specify a style rule. Choose the plus icon to add a style. Select
the color to apply to the card and define the criteria for the style rule.
In this example, we show the Styles dialog for the taskboard.

Follow these rules when creating and ordering your style rules:
The criteria you specify works in a similar fashion as when constructing a

query.
All clauses are considered AND clauses, grouping clauses isn't supported.
Card rules apply to all work items that meet the rule criteria
Rule color applies to work items based on the order in which rules are listed.
If you add more than one style rule, make sure that you move them in the
order of most importance. Drag them into the order you want them applied.
You can quickly enable and disable a style rule.
Here we add a Stale tasks rule that highlights tasks that haven't changed in
the last five days.
4. To copy or delete a style rule, choose the actions icon and select Clone or
Delete, respectively.
Changes cause automatic taskboard updates

Your Taskboard automatically refreshes when changes occur. There isn't any live updates
control, it simply happens in the background. As other team members move or reorder
cards on the taskboard, the Taskboard automatically updates with these changes. You
don't need to press F5 to see the latest changes.
Related articles
Setup your backlogs and boards
Set working days
Azure Boards
Article • 02/24/2023
2018
views.
Action
Backlogs
Sprint backlogs
Queries
Work items
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
No
Sort on a column
No
No
Yes
Yes
 Tip

portfolio backlog.
you change them.
７ Note


Browser
Sort on a column
descending order.
keyboard commands:
a new location
For query results:
to sort
you're on.
Related articles
Article • 02/24/2023
2018
specific sprint.
assigned work.
Path, or Tags.
Area Path or Tags.

✔️or is listed.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes

enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
Relevance.


７ Note
team.
Prerequisites

view
Features, or Epics
Work Items
team member.
want to filter on.
criteria.
Inactive functions


values.
board.

operator.



include 'web'.

Unassigned
７ Note

Epics).
AND | OR . AND
Item 2.

７ Note
you've defined.

features.

tags.
boards.

Related articles
About backlogs
Customize cards
Tags
3. Determine and set sprint capacity in
Azure Boards
Article • 08/24/2023
2018
As a next step, you'll want to determine your team's actual capacity. While velocity
correlates to how your team estimates requirements, capacity correlates to actual task
time. Time is calculated in either hours or days. Capacity takes into consideration the
variation in work hours by team members. It also considers holidays, vacation days, and
non-working days.
Because days off and time available for each team member may vary from sprint to
sprint, set capacity for each sprint. The capacity tool helps you make sure your team isn't
over or undercommitted for the sprint. Also, as you work day-to-day, you'll see if your
team is on track.
＂ Set team capacity for a sprint

＂ Copy capacity from the previous sprint to the current sprint
＂ Track capacity when performing multiple activities
＂ Add or remove user accounts from capacity planning for a sprint
＂ Track capacity when working on more than one team
If you haven't set up sprints yet for your team, see the Manage sprint timelines while
working in Scrum article.
Prerequisites
To view or set capacity, you must be granted Basic access or higher. Users with
Stakeholder access can't view or set capacity. For more information, see
To set capacity, you must be a member of the team. For more information, see Add
About the Activity or Discipline pick-list items

The values displayed for Activity (Agile, Basic, or Scrum) or Discipline (CMMI) reflect a
union of all values defined for the Activity or Discipline fields in all projects within the
organization.
To change the Activity or Discipline menu selections, see Add and manage fields.
Capacity per day entries

Most teams specify capacity in hours. You can also specify it in days or any other units
your team chooses. For example, 0.5 days would correspond to 4 hours for a typical 8
hour day. Choose the same unit your team uses to estimate and track their time. For
example, the entries they'll make to the Original Estimate or Remaining Work fields.

team selector menu, and lastly (4), choose Capacity.
Set capacity for the team and team members

From the Capacity page, you can add team members, enter the team time off, and set
capacity and days off for each team member.
1. If you don't see your team members listed, add them. Choose the action icon
and select Add all team members. For this feature to work, team members will
have been added to the team.
７ Note
The Add all team members action retrieved a maximum of 100 team
members. If you have more team members to add, then you can add them
one by one by choosing Add user.
2. If you need to add other contributors to your project, choose the Add user.
3. Next, set any time off that a team member will take. For the entire team days off,
choose the 0 days link as shown.
In the Days off for dialog, select the start and end days during the sprint that the
team member or team will take off.
７ Note
Your sprint planning and tracking tools automatically consider days off when
calculating capacity and sprint burndown. You only have to indicate planned
days off for the team. For more information, see Set capacity for the team
and team members.
4. Now, set the Activity/Discipline and Capacity per day for each team member. If
you track capacity simply by team member, you can leave the Activity or Discipline
selection unassigned.
For example, Christie Church's capacity is 6 hours/day for design work.
Copy capacity planning from the previous

sprint
By copying the capacity from the previous sprint, you save time. With the basics defined,
all you have to do is adjust the capacity based on individual and team days off and
capacity allocation per activity.
Notice that only the capacity-per-day value and activity value are copied over. Individual
and team days off remain unset. The copy operation always copies the latest updates
made to the previous sprint. So you can repeat the copy operation if you've made
changes to the previous sprint that you want to copy to the latest sprint.
Remove a user from capacity
To remove a user, choose the option from the users action menu. This action won't
remove the user from the team.
Review capacity charts

As you define tasks and estimate the work, you'll see capacity charts start to fill in for
each team member. Capacity bars track the remaining work against the capacity for
each team member and the entire team.
You'll also see a roll-up of the remaining work required to complete each requirement or
bug.
From this view, you can easily see which individuals are at or near capacity. Teams can
determine if work needs to be moved out of the sprint or to reassign tasks.
 Tip
Define tasks that take a day or less to complete. This helps mitigate the risks that
come from poor estimates.
Also, don't divide tasks into subtasks. If you do divide a task into subtasks, specify
Remaining Work only for the subtasks, as the system rolls up summary values to
the parent task.
Track capacity when completing multiple

activities
Because individual team members have different sets of skills and duties, you can track
their activity and capacity for each activity and for each sprint.
Here, Jamal divides time between Deployment and Development.

team
If you work on more than one team, you'll want to specify your sprint capacity for each
team. For example, both Christie and Raisa split their time between the Web and Phone
teams. As such, give 3 hours a day to the Web team, and 3 hours a day to the Phone
team.
If your name isn't listed in the capacity view, you need to be added as a team member.
Next step
4. Adjust work
Related articles
Setting capacity and estimating remaining work for each task provides you with the
tools you need to track the amount of work and resources you have given sprint over
sprint.
Sprint burndown
Velocity
Forecasting
Article • 02/24/2023
2018
Sprint planning meetings

Much of sprint planning involves a negotiation between the product owner and the
team to determine the focus and work to tackle in the upcoming sprint. It's useful to
time-box the planning meeting, restricting it to 4 hours or less.
In the first part of the meeting, your product owner meets with your team to discuss the
user stories that might be included in the sprint. Your product owner shares information
and answers any questions that your team has about those stories. This conversation
might reveal details such as data sources and user interface layout. Or it might reveal
response time expectations, and considerations for security and usability. Your team
should capture these details within the backlog items form. During this part of the
meeting, your team learns what it must build.
As you plan your sprints, you may discover other requirements to capture and add to
your backlog. Before your sprint planning meeting, you'll want to refine your backlog to
make sure it's well defined and in priority order.
Also, setting a sprint goal as part of your planning efforts can help the team stay
focused on what's most important for each sprint.
After you've planned your sprint, you may want to share the plan with key stakeholders.
You can learn more from these resources:
What is Scrum?
Sprint planning white paper
The Scrum Guide
Build and manage the product backlog white paper
Set sprint goals

Scrum teams use sprint goals to focus their sprint activities. They often set this goal
during their sprint planning meeting. The goal summarizes what the team wants to
accomplish by the end of the sprint. By explicitly stating the goal, you create shared
understanding within the team of the core purpose. The sprint goal can also help guide
the team when conflicts arise around priorities.
Tips from the trenches: Define sprint goals

The sprint goal defines what the product owner and the team consider as the ultimate
target to accomplish that sprint. It's not a random selection of backlog items that don't
really have a relationship, but a short piece of text that captures what the team should
try to accomplish. Normally the product owner comes up with the sprint goal before
selecting many items for the next sprint. The items for that sprint should all fit that
common goal.
Sprint goals can be feature oriented, but might also have a large process component
such as deployment automation or test automation.
For example:
This sprint we'll focus on a simple user story. We'll use it to prove that the
proposed solution works.
This sprint revolves around implementing the security features that properly secure
the administration section of the website.
This sprint is about integrating the most important payment gateways so that we
can start collecting money.
Setting the sprint goals helps the team to stay focused. It makes it easier to define
priority of tasks within a sprint and it probably helps limit the number of stakeholders
and end users that are involved.
During the sprint review, the most important question you should ask yourself is
whether you managed to achieve the sprint goal. How many stories you completed
comes second. If the goal is accomplished, the sprint succeeds, even if not all stories
were finished.
Contributed by Jesse Houwing , Visual Studio devops Ranger and a senior consultant
working for Avanade Netherlands.
Tips for successful triage meetings

Fixing bugs represents a trade-off with other work. Use your triage meeting to
determine how important fixing each bug is against other priorities related to meeting
the project scope, budget, and schedule.
Establish the team's criteria for evaluating which bugs to fix and how to assign
priority and severity. Bugs associated with features of significant value (or
significant opportunity cost of delay), or other project risks, should be assigned
higher priority and severity. Store your triage criteria with other team documents
and update as needed.
Use your triage criteria to determine which bugs to fix and how to set their State,
Priority, Severity, and other fields.
Adjust your triage criteria based on where you are in your development cycle. Early
on, you may decide to fix most of the bugs that you triage. However, later in the
cycle, you may raise the triage criteria to reduce the number of bugs that you need
to fix.
Once you've triaged a bug, assign it to a developer. The developer can then
investigate and determine how to implement a fix.
Manage your technical debt

Consider managing your bug bar and technical debt as part of your team's overall set of
continuous improvement activities. You may find these resources of interest:
Good and Bad Technical Debt (and how TDD helps) by Henrik Kniberg
Managing Technical Debt posted by Sven Johann & Eberhard Wolff
Tips from the trenches: Bug management

Agile Bug Management: Not an Oxymoron
by Gregg Boer, Principal Program Manager, Visual Studio Cloud Services at Microsoft
Address any known bug debt every sprint

Every sprint, the team looks at any bugs remaining in the bug backlog and dedicates
capacity to get that known set of bugs down to zero, or near-zero. Whether this is one
day, one week, or the entire sprint, they fix the bugs first. Bugs found later, within the
sprint, aren't considered part of that initial commitment. Unless they're high priority,
they're put on the bug backlog for the next sprint.
Many teams work in a commitment-based organization. Often, management places a

high value on a team's ability to meet their commitments. Doing capacity planning
against a known set of bugs makes sprint planning more deterministic, increasing their
chance to meet commitments. Any new bugs discovered during the sprint aren't a part
of the initial commitment, and can be addressed next sprint.
Manage bug debt across an enterprise
An organization transitioning to a culture where debt is continually eliminated likely is
dealing with the following question: How do you get teams to reduce their bug count
without telling them exactly what to do? Leadership wants the team to change, yet gives
the team autonomy to determine how they change. One option is to use a bug cap.
For example, consider a bug cap of three bugs per engineer. As such, a team of 10
people shouldn't have more than 30 bugs in its bug backlog. If the team is over its cap,
it's expected to stop work on new features and get under the bug cap. A team is
expected to be under its cap always, but the team decides how it wants to do that. The
bug cap ensures that teams don't carry bug debt for too long. The team can learn from
the mistakes that causes the bugs to be injected in the first place.
Remember that the bug cap represents the bugs in the bug backlog. It doesn't include
bugs found and fixed within the sprint in which a feature is developed. Those bugs are
considered undone work, not debt.
While bugs contribute to technical debt, they may not represent all debt.
Poor software design, poorly written code, or short-term fixes can all contribute to
technical debt. Technical debt reflects extra development work that arises from all these
problems.
Track work to address technical debt as PBIs, user stories, or bugs. To track a team's
progress in incurring and addressing technical debt, you'll want to consider how to
categorize the work item and the details you want to track. You can add tags to any
work item to group it into a category of your choosing.
Role of the Scrum Master

Scrum Masters help build and maintain healthy teams by employing Scrum processes.
They guide, coach, teach, and assist Scrum teams in the proper employment of Scrum
methods. Scrum Masters also act as change agents to help teams overcome
impediments and to drive the team toward significant productivity increases.
Core responsibilities of Scrum Masters include:
Support the team to adopt and follow Scrum processes. For example, you
shouldn't let the daily Scrum meeting become an open discussion that lasts 45
minutes.
Guard against the product owner or team members from adding work after the
sprint begins.
Clear blocking issues that prevent the team from making forward progress. This
work might require you to complete small tasks, such as approving a purchase
order for a new build computer or resolving a conflict within your team.
Help the team work to resolve conflicts and issues that arise and learn from the
process.
Ask questions that reveal hidden issues and confirm that what people are
communicating is well understood by the entire team.
Identify and safeguard the team from potential issues becoming major issues. Just
as it's cheaper to fix a bug soon after it's discovered, it's also easier and less
disruptive to fix a team issue when it's small and manageable.
Prevent the team from presenting incomplete user stories during a sprint review
meeting.
Gather, analyze, and present data to business stakeholders to demonstrate how

the team is improving and growing. For example, if your team has increased the
amount of value that it has delivered while generating fewer bugs, make the value
visible through regular communications to business stakeholders.
Good Scrum Masters have or develop excellent communication, negotiation, and

conflict resolution skills. They actively listen to the words that people say and write. They
also listen to how they deliver their messages, for example their body language, facial
expressions, vocal pace, and other nonverbal communication.
Just as it's cheaper to fix a bug soon after it's discovered, it's also easier and less
disruptive to fix a team issue when it's small and manageable before it grows into a
major issue.
Daily Scrum meetings

Daily Scrum meetings help keep a team focused on what it needs to do the next day.
Staying focused helps the team maximize their ability to meet sprint commitments. Your
Scrum Master should enforce the structure of the meeting and ensure that it starts on
time and finishes in 15 minutes or less.
Three aspects of successful Scrum meetings are:
Everyone stands up. Standing up helps to keep the meetings focused and short.
They start and end on time and occur at the same time in the same location each
day
Everyone participates, each team member answers the three Scrum questions:
What have I accomplished since the most recent Scrum?
What can I accomplish before the next Scrum?
What blocking issues or impediments might affect my work?
７ Note
The focus for scrum meetings is on the status of work that needs to be passed from
one team member to another team member.
Team members should strive to answer their questions quickly and concisely. For
example:
"Yesterday, I updated the class to reflect the new data element that we pull from the
database, and I got it to appear in the interface. This task is complete. Today, I ensure
that the new data element is correctly calculating with the stored procedure and the
other data elements in the table. I believe I can accomplish this task today. I need
someone to review my calculations. I have no impediments or blocking issues."
This response conveys what the team member accomplished, what the team member
plans to accomplish, and that the team member would like some help looking at the
code.
Contrast with this next example:
"Yesterday, I worked on the class, and it works. Today, I work on the interface. No
blocking issues."
The team member doesn't provide enough detail about what class they worked on nor
about the interface components they'll complete. In fact, the word accomplished never
came up.
It's important that no one interrupts during report outs. Each person must have
sufficient time to answer the three questions.
More in-depth and follow-up discussions should take place after the meeting, as people
return to their desks or, if a significant amount of conversation is necessary, in a follow-
up meeting.
Many teams delay discussions by using the "virtual parking lot" method. As subjects
come up that a team member thinks needs further discussion, they can quietly walk to a
whiteboard or flipchart and list the subject in the parking lot. At the end of the meeting,
the team determines how they'll handle the listed items.
Sprint review meetings

Conduct your sprint review meetings on the last day of the sprint. Your team
demonstrates each product backlog item that it completed in the sprint. The product
owner, customers, and stakeholders accept the user stories that meet their expectations
and identify any new requirements. Customers often understand their needs more fully
after seeing the demonstrations and may identify changes that they want to see.
Based on this meeting, some user stories get accepted as complete. Incomplete user
stories remain in the product backlog. New user stories get added to the backlog. Both
sets of stories get ranked and either estimated or re-estimated in the next sprint
planning meeting.
After this meeting and the retrospective meeting, your team plans the next sprint.
Because business needs change quickly, you can take advantage of this meeting with
your product owner, customers, and stakeholders to review the priorities of the product
backlog again.
Sprint retrospective meetings

Retrospectives, when conducted well and at regular intervals, support continuous
improvement.
The sprint retrospective meeting typically occurs on the last day of the sprint, after the
sprint review meeting. In this meeting, your team explores its execution of Scrum and
what might need tweaking.
Based on discussions, your team might change one or more processes to improve its
own effectiveness, productivity, quality, and satisfaction. This meeting and the resulting
improvements are critical to the agile principle of self-organization.
７ Note
To support your team's retrospective, consider installing the Marketplace

Retrospectives extension. This extension supports collecting feedback on your
project milestones, organizing and prioritizing the feedback, and creating and
tracking actionable tasks to help your team improve over time.
Look to address these areas during your team sprint retrospectives:
Issues that affected your team's general effectiveness, productivity, and quality.
Elements that affected your team's overall satisfaction and project flow.
What happened to cause incomplete backlog items? What actions can the team
take to prevent these issues in the future?
For example, consider a team that had several tasks that only one individual on the
team could do. The isolated expertise created a critical path that threatened the
sprint's success. The individual team member put in extra hours while other team
members were frustrated they couldn't do more to help. Going forward, the team
decided to practice eXtreme Programming to help correct this problem over
time.
As a team, work to determine whether to adapt one or more processes to minimize the
occurrence of problems during the sprint.
Your team may need to do some work to implement an improvement. For example, a
team that found themselves negatively affected by too many failed builds decided to
implement continuous integration. Because they didn't want to disrupt process, they
took a few hours to set up a trial build before turning it on in their production build. To
represent this work, they created a spike and organized that work against the rest of the
product backlog.
Related articles
What is Scrum?
Agile Retrospectives: Making Good Teams Great
Sprints and Scrum key concepts in
Azure Boards
Article • 02/24/2023
2018
This article provides a short dictionary of terms and available tools used in tracking work
using Sprints and Scrum methods. Other resources to review are Agile glossary and
Project management and navigation glossary.
Agile tools
A suite of web-based tools used to track work and support Agile methodologies. Agile
tools support the core Agile methods—Scrum and Kanban—used by software
development teams today. Learn more: About Agile tools and Agile project
management.
Bugs
A type of work item that records a potential source of dissatisfaction with the product.
The common name of a work item type for tracking code defects. Each team can choose
how they want to manage bugs. Some teams like to track bugs along with requirements
on the backlog. Other teams like to track bugs as tasks performed in support of a
requirement. The bugs then appear on their Taskboard. Learn more: Manage bugs.
Burndown or burnup charts

Burndown and burnup charts support project management to visually track work
completed over time. Burndown charts begin with the total amount of planned work. As
work is completed, the burndown graphs the remaining work. With the progression of
time, the amount of to-do work decreases. Burnup charts track work as it is completed
over time. They are useful to show the rate at which work is getting completed.
For more information, see Burndown and burnup guidance
Team and individual capacity

Capacity correlates to actual task time, either hours or days, that an individual or a team
has to work. Azure DevOps provides a Capacity tool for each team's sprint to set
capacity. Teams typically set capacity when they plan to create tasks and estimate the
time it takes to complete a task.
By setting team capacity, the team knows exactly the total number of work hours or
days the team has for each sprint. With this tool, you set individual team member
capacity and days off. Setting capacity for each team member working during a sprint
causes the capacity bar for that individual to appear. Learn more: Set sprint capacity.
Capacity bars
With capacity bars, you can quickly see who is over, at, or under capacity. Capacity bars
update with each of these activities:
Tasks are assigned with non-zero remaining work

Change in remaining work
Date change within the sprint cycle. Individual and team capacity always reflects
their capacity from the current day until the end of the sprint.
Capacity colors Capacity bars

Capacity colors Capacity bars
For more information, see Adjust work to fit sprint capacity.
Daily scrum meetings

Daily Scrum meetings help teams stay focused on what they need to do to maximize
their ability to meet their sprint commitments. The team's Scrum Master should enforce
the structure of the meeting and ensure that it starts on time and finishes in 15 minutes
or less. Learn more: Scrum best practices, Daily scrum meeting.
Forecast
The forecast tool helps teams plan their sprints. The tool shows teams the backlog items
that can be completed in future sprints based on work item estimates and a set velocity.
As shown here, a velocity of 20 indicates that it will take five sprints to complete the
work shown. Learn more: Forecast your product backlog.
Iteration paths (aka sprints)
A time period, usually two to three weeks, used to group work items to be completed
during that time period. Sprints are used in Scrum methods to support sprint planning,
sprint burndown, and other Scrum processes. Iteration paths allow you to group work
into sprints, milestones, or other event-specific or time-related period. Learn more:
About area and iteration paths.
Product backlog
An interactive list of work items that corresponds to a team's project plan or roadmap
for what the team plans to deliver. The product backlog supports prioritizing work,
forecasting work by sprints, and quickly linking work to portfolio backlog items. You can
define your backlog items and then manage their status using the Kanban board.
Each product backlog can be customized by a team. Learn more: Create your backlog.
Product backlog item (PBI)

A type of work item that defines the applications, requirements, and elements that
teams plan to create. Product owners typically define and stack rank product backlog
items which are defined with the Scrum process. Learn more: Scrum process work item
types and workflow.
Product owner role

The role of product owners is to act as the interface between customers and the team. A
product owner can reduce the need for detailed specifications. They reduce the need by
being more responsive to the team's questions about implementation details. Also, they
clearly define acceptance criteria within each requirement. Learn more: Refine your
backlog, Role of the product owner.
Scrum Master role

Scrum Masters help build and maintain healthy teams by employing Scrum processes.
They guide, coach, teach, and assist Scrum teams in the proper employment of Scrum
methods. Scrum Masters also act as change agents to help teams overcome
impediments and to drive the team toward significant productivity increases. Learn
more: Scrum best practices, Role of the Scrum Master.
Sprints (also known as iterations)

A sprint is a time period of usually two to three weeks that's used to group work items
to be completed during that time period. Sprints are used in Scrum methods to support
sprint planning, sprint burndown, and other Scrum processes. Sprints are defined via
iteration paths. To learn more, see About area and iteration paths (aka sprints).
Sprint backlog
An interactive list of work items that have been assigned to the same sprint or iteration
path for a team. The sprint backlog supports teams that use Scrum methodologies.
Learn more: Sprint planning.

The sprint burndown chart reflects the progress made by a team in completing all the
work they estimated during their sprint planning meeting. Team's monitor it to mitigate
risk and check for scope creep throughout their sprint cycle. The ideal trend line always
indicates a steady burndown. The blue area, as shown in the following chart, represents
what's actually going on. It shows the buildup of work as team members add tasks and
the reduction of work as team members complete those tasks. Learn more: Monitor
sprint burndown.
Sprint goals
Sprint goals are used to focus sprint activities. The goal summarizes what the team
wants to accomplish by the end of the sprint. Learn more: Scrum best practices, Set
sprint goals.
Sprint planning
The Sprint planning meeting occurs at the start of a sprint and is when the product
owner and team agree on a set of sprint goals and work. Learn more: Scrum best
practices, Sprint planning meetings.
Sprint retrospective meetings

The Sprint review or retrospective meeting occurs at the end of a sprint. This meeting is
when the team demonstrates the work that they completed during the sprint. The
product owner, customers, and stakeholders accept the user stories that meet their
expectations and identify any new requirements. Customers often understand their
needs more fully after seeing the demonstrations and may identify changes that they
want to see. Learn more: Scrum best practices, Sprint retrospective meeting.
Task
A task is a type of work item used to track estimated and remaining work. In Scrum, a
task is defined to range between four and twelve hours. Defining tasks are essential for
monitoring sprint burndown, working with team capacity, and using the Taskboard.
Tasks are linked to their parent product backlog items or user stories. Learn more: Add
tasks to backlog items.
Taskboard
A taskboard provides an interactive progress board for work required to complete a
team's sprint backlog. During your sprint, you'll want to update the status of tasks and
the remaining work for each task. Updating tasks daily or several times a week yields a
smoother sprint burndown chart. Learn more: Taskboard.
Teams
A team corresponds to a selected set of project members. With teams, organizations
can subcategorize work to better focus on all the work they track within a project. Each
team gets access to a suite of Agile tools. Teams can use these tools to work
autonomously and collaborate with other teams across the enterprise. Each team can
configure and customize each tool to meet their work requirements. To learn more, see
Team member
A member who has been added to a project or organization who has been added to a
specific team. Project members can be added to several teams. Several Agile tools, such
as capacity planning, team alerts, and dashboard widgets are team-scoped. That is, they
automatically reference the users that have been added as members of a team to
support planning activities or sending alerts.
To add users to a team, see Add users to a project or specific team.
Technical debt
Technical debt includes anything the team must do to deploy production quality code
and keep it running in production. Examples are bugs, performance issues, operational
issues, accessibility, and others. Learn more about how to minimize technical debt: What
is Agile Development?.
Triage meetings
Triage meetings are used to review and organize the backlog and bugs assigned to a
team. Other details, such as estimates, acceptance criteria, and more may be added to
the work items. Typically, a product owner runs triage meetings, and team leads,
business analysts, and other stakeholders who can speak about specific project risks
attend them. Learn more: Triage work items.
User story
teams plan to create. Product owners typically define and stack rank user stories. User
story is defined with the Agile process. Learn more: Agile process work item types and
workflow.
Velocity and velocity chart

Velocity provides a useful metric for gaining insight into how much work your team can
complete during a sprint cycle. After your team has worked several sprints, they can use
the velocity chart and forecast tool to estimate work that can be accomplished in future
sprints.
Velocity is a measure of how much work a team can complete based on their sprint
cadence. The built-in velocity chart measures velocity by summing the Story Points
(Agile), Effort (Scrum), or Size (CMMI) defined for a sprint.
For example, in the chart shown below the green bar indicates the total estimated effort
(story points) of the user stories completed within each sprint. Blue corresponds to the
estimated effort of items not yet completed. Learn more: View and work with the built-
in team velocity chart.
Along with the built-in Velocity chart, you can add a Velocity widget to your team
dashboard. You can configure this widget to sum a count of work items or the sum of
effort. Learn more: Configure the Velocity widget.
Each team is associated with one and only one velocity chart. Velocity varies depending
on team capacity, sprint over sprint. However, over time, the velocity should indicate a
reliable average that can be used to forecast the full backlog. By minimizing the
variability of backlog item size—effort or story points—you gain more reliable velocity
metrics. Learn more: Add tasks to backlog items.
Related articles
About Sprints and Scrum
Scrum best practices.
Agile glossary
What is Scrum?
Article • 02/24/2023
2018
Throughout your sprint, you can monitor the sprint burndown report to determine if
your team is on track to complete its sprint plan. There are two sprint accessible
burndown charts: the in-context Burndown Trend report viewable from a team sprint
backlog and the Sprint Burndown widget you can add to a dashboard.
Both the report and the widget derive data from Analytics. They support monitoring
burndown based on a count of work items or a sum of Story Points/Size/Effort,
Remaining Work, or other numeric field.
You can add either the report or widget to a dashboard. Also, you can monitor progress
using the Analytics-based burndown or burnup widgets. They provide more
configuration options.
） Important
Use this article to learn about:
＂ Metrics tracked in the sprint burndown report and widget

＂ Team activities required to track tasks and Remaining Work
＂ How to set interactive controls to personalize your view of the sprint burndown
report
＂ How to add the in-context Burndown Trend report to a dashboard
＂ How to configure the Sprint Burndown widgets
＂ How to view current and past sprint burndowns
For an overview of all burndown/burnup charts available to you, see Burndown and
burnup guidance.
７ Note
Sprint burndown reports are derived from data tracked by a team during a sprint or
iteration. To learn more, see About teams and Agile tools.
The in-context Burndown Trend report

The Burndown Trend report is based on either a count of tasks or remaining work
estimates, or other numeric fields that you define and update throughout the sprint
cycle. For details, see Sprint planning. To open this report, jump to the section Open a
Sprint backlog.
A healthy sprint burndown report looks something like the image shown below.
Typically, there will be a stair-case burndown as individual team members may only
update their work items once a week or every few days. The Total Scope line indicates
the number of work items added after the sprint starts. The Ideal Trend line is calculated
based on the number of work items, days in the sprint, and number of working days.
The blue area indicates the number of work items active or in progress each day of the
sprint. As shown in this example, one work item is still active at the end of the sprint.
７ Note
The Show non-working days shades those days set through the team's Working
days setting as well as the team's days off set through the Capacity page.
７ Note
The Total Scope line reflects the number of work items added to the sprint. If the
team's default iteration is the @CurrentIteration, then new work items are added
to the current iteration. The scope decreases as the Iteration Path is modified to
another sprint, or work items are completed.
The Sprint Burndown widget

In the widget catalog, you'll find two versions of the Sprint Burndown widget: the
Analytics-based Sprint Burndown and Sprint Burndown (Legacy) which is built from the
work tracking data store.
Sprint Burndown widget

The Analytics-based Sprint Burndown widget provides an easy way to monitor progress
for a team by showing work remaining for a given sprint. Work remaining is the vertical
axis and time is the horizontal axis. You can define remaining work based on Stories or
Tasks, and by counting the work items or summing a field.
The charts provide useful metrics to help you answer the question: Are we on track to
complete this set of work by the end a sprint?
Percentage work complete

Number of work items not estimated (if using a field other than Remaining Work)
Average burndown
Total scope increase
Sprint Burndown (Legacy) widget

The Sprint Burndown (Legacy) widget adds a chart based on Remaining Work defined
for tasks in a team's current sprint. Select this version when you don't have access to
Analytics. Configuration options include team selection, and widget size.
If your dashboard already has a legacy version available, you can easily upgrade the
widget by editing the widget's configuration, and checking Try the new version now.
You can always go back to the legacy version by unchecking the box.
Prerequisites
Team activities to track tasks and Remaining

Work
To monitor sprint burndown, your team must schedule sprints and assign work to those
sprints.
If you want to monitor sprint burndown based on tasks and Remaining Work, your team
must carry out these extra actions.
Required activities:
Define and estimate tasks for each product backlog item you're working on in the
sprint. If you work from your team's backlog and taskboard, the items you create
will automatically be assigned to the current sprint (Iteration) and to your team's
default Area Path.
Update Remaining Work for each sprint task as work progresses.
Recommended activities:
Define tasks that take a day or less to complete to lessen the effect of poor
estimates.
Don't divide tasks into subtasks. If you divide a task into subtasks, specify hours
only for the subtasks. These hours are rolled up as summary values for the parent
task.
Update Remaining Work daily or several times within a week to support
monitoring and achieve a smoother burndown chart.
At the end of the sprint, update the task status of completed tasks and determine
how to handle incomplete tasks.
Empty sprint burndown chart

If your sprint burndown chart appears empty, check these points:
Have you assigned tasks to the sprint associated with the chart?
Have you assigned Remaining Work to the tasks assigned to the sprint?
Are the parent work items of the tasks assigned to the same sprint? If not, the
tasks may appear in another sprint associated with the parent item.
Open a Sprint backlog

You view the in-context sprint burndown report from a team's Sprint backlog.
1. From your web portal, open your team's sprint backlog. (1) Check that you've
selected the right project, (2) select Boards>Sprints, (3) select the correct team
from the team selector menu, and lastly (4), select Backlog.
To select another team, open the selector and select a different team or select the
View Sprint directory option. Or, you can enter a keyword in the search box to
2. To select a different sprint than the one shown, open the sprint selector and select
the sprint you want.
focus. If you don't see the sprints you want listed, then select New Sprint from the
menu, and then select Select existing iteration. For details, see Define iteration
paths.
View the in-context Burndown Trend report

1. To open the Sprint burndown report, select Analytics.
2. Use the interactive controls to select from the following options:
a. The Start Date and End Date of the sprint. These dates will default to the team's
current iteration sprint dates.
b. The Backlogs/Work Items to burn down on, either the product backlog—
Stories, Issues, Product Backlog Items, or Requirements—or Tasks backlog to
use. Your selection impacts the options available for the Burndown on menu.
c. The Burndown on field to use to calculate burndown, either a Count of Work

Items or a sum of a field, such as Story Points, Effort, or Size.
d. Check or uncheck Show non-working days. Non-working days appear as gray

bars in the background when enabled. Default non-working days are set for a
team and for a team's sprint through the capacity page. See Set working days
and Set sprint capacity.
Select Reset to reset the controls to the default options. By default, the dates
are set to the selected sprint. Changes to the start and end dates don't change
any sprint date definitions.
3. If you don't track Remaining Work in tasks, you can view burndown based on a
count of work items/tasks. Hover over any point on the chart to show a summary
of the data for a specific day.
Sum of Remaining Work
When you choose to view the Tasks backlog and Sum of Remaining Work, the blue
area shows the sum of Remaining Work per day for those tasks that are still active
or in progress. As the Remaining Work is updated, the chart indicates the rate of
burndown. The Scope trend line indicates the addition of Remaining Work after the
start of the sprint. The Ideal trend line indicates the ideal burndown rate for the
sprint. Capacity lines are only shown when the team has configured capacity.
７ Note
The options for the sum fields depend on the numeric fields defined for task and
requirement category work item types. The most common fields used to show the
burndown trend are:
Count of work items
Sum of Story Points, Effort, or Size
Sum of Remaining Work.
The selections you make are only set for you, and persist across sessions until you
change them.
Add the report to a dashboard

Dashboard.
2. Select the dashboard and select OK.
Add the Sprint Burndown widget to a

dashboard
You can add the Sprint Burndown widget to a dashboard and select the team whose
progress you want to monitor. You configure these widgets for one or more teams.
1. If you haven't yet added the Sprint Burndown widget to your dashboard, do that
now.
You can filter the Add widget dialog with "sprint burndown" to quickly locate the
two widgets available to you.
2. To configure the widget, select the actions icon and select the Configure
option.
Configure the Analytics-based Sprint Burndown

widget
option.
2. Modify the Title of the widget and select your preferred Size. The Sprint Burndown
widget can scale up to 10x10.
3. Make the following selections:

Team - Select the Team you want to track.
Backlogs and work items - Select the work items to include in your
burndown. You can select to any backlog or a specific work item type.
Burndown on - Choose how you want to burndown. You may burndown by

count of work items or a sum based on a selected field.
Select iteration - You may select @CurrentIteration, or a specific iteration.
Time period - If you selected @CurrentIteration, these dates aren't editable,

as they'll be automatically to the start/end date of the current iteration. If you
selected a specific iteration, you may customize the start/end date for the
burndown chart.
4. Advanced features: Check the boxes of the following options that you want to add
to your chart.
Show total scope: Displays both the historical and projected scope increase.
Show non working days: Displays non working days on the burndown. When
displayed, non working days are shaded.
Plot remaining using work item type color: Displays remaining work based
on the work item type color, rather than the default blue color. If multiple
work items are included, then it stacks colors by work item type.
７ Note
The Show non-working days shades those days set through the team's Working
days setting as well as the team's days off set through the Capacity page.
Configure the Sprint Burndown (Legacy)

widget
option.
If your dashboard already has a legacy version available, you can easily upgrade
the widget by editing the widget's configuration, and checking Try the new
version now. You can always go back to the legacy version by unchecking the box.
Current and past sprint burndown charts

As you complete each sprint, the system maintains a history of your activity.
To view a past sprint and its burndown chart, select the sprint from the Sprint selector.
You can review sprint burndown in-context reports to show the team patterns in
execution. The burndown charts maintain a record of the team's ability to plan and
estimate.
May
Teams may find it useful to review these reports periodically during their sprint
retrospectives. It may spark useful discussions and lead to setting one or more sprint
goals, such as:
How does our projected velocity match up to our actual velocity?

How can we more accurately determine how much we can accomplish in a sprint?
How can we complete work at a more regular pace throughout the sprint?
Next steps
Burndown and burnup guidance
In addition to the sprint burndown chart, teams can review the velocity at which they
work sprint over sprint. The velocity chart tracks how many backlog items your team
works on in a sprint. You can use your team velocity as input into the forecast tool to
help plan your sprints.
Related articles
You can learn more about defining, planning, and executing your sprints from these
articles:
Define iteration paths and configure team iterations
Sprint planning
Add tasks to backlog items
Update and monitor your Taskboard
And, from these industry resources:
Understanding the Scrum Burndown Chart

Configure a burndown or burnup
widget
Article • 06/13/2023
The burndown and burnup widgets give you flexibility to create charts for any type of
scope or number of teams within specified time periods. Burndown charts focus on
remaining work, while burnup charts focus on completed work. Both chart types help
your team determine whether you're on track to complete the set of work by the end
date. For an overview of all burndown/burnup charts available to you, see Burndown
and burnup guidance.
Burndown widget configured to display a release burndown
Prerequisites
Add the widget to your dashboard

2. Go to your project, and then select Dashboards, and then Edit.
3. Select a widget, and then Add.

Configure burndown or burnup widget
Do the following steps to configure both widget types. The only difference between the
burndown and burnup widgets is that the burnup widget plots work completed and the
burndown widget plots work remaining. For more information, see how to interpret a
burndown or burnup chart, later in this article.
1. On the widget, select Configure.

2. Complete configuration information, described in the following table, and then
select Save.
Configuration Guidance
category
Teams To track progress across teams, add more teams. You can select teams from
other projects, but the lists of selectable backlogs, work item types, and fields
are based on your current project. Tracking across multiple projects only works if
the process for those projects is the same, or at least similar.
category
Work items Backlog includes all the work item types configured for that backlog. If your
project is customized using a Hosted XML process and has a customized bug
work item category name, then the burndown/burnup widgets can't query for
work items within that category. To query for bugs, the customized bug work
item type must belong to the default Bug category, reference name
Microsoft.BugCategory .
Field criteria Select field criteria to limit the work items that appear in the chart. Filtering is
based on values assigned to fields as defined for each work item on the date
within the tracking period. For more information, see Filters that apply to
historical data.
Analytics-based charts are built based on the WorkItemsSnapshot EntitySet.
Snapshot entity types are modeled as daily snapshots. Data aggregates based
on assignments made as of the date they're assigned. So, if you want to filter a
burndown/burnup widget based on field or tag assignments, assign them prior
to the period you want to monitor. Otherwise, the widget doesn't recognize
them until the date on which they're applied. You can filter on a null value for
the Field criteria, which is consistent with a query using the same field criteria.
Burndown on Choose how you want to calculate burndown by Count of work items or by Sum
based on a selected field. You can select from standard or custom fields of
integer or decimal data type, such as Story Points, Effort, or Remaining Work.
Burndown works best when you aggregate size fields like Story Points. If you
choose to burndown on fields that change during the sprint, like Remaining
Work for Tasks, the calculation of "Items not Estimated" grows as items get
closed.
Time period - Start Date: Determines the original scope baseline. The chart burns down from
the original scope.
- % Complete and Total Scope Increase: Calculated based on your original
scope.
- End Date: Specifies the target date of completion. Your goal is to burndown
the original scope of work by the End Date.
Plot interval Select the intervals to plot between the Start Date and End Date. Average
burndown is based on the selected interval. After you select the Start Date, set
Plot burndown by to Iteration. The Average Burndown assumes that every
interval is the same length and that the interval between the Start Date and the
first month is a full month, even if the length of time between Start Date and the
first month's end date doesn't match your typical length of a month. For best
results, enter a Start Date that is the same as the first month's start date, which is
also true when plotting by weekly intervals.
category
Advanced - Show burndown: Displays both the historical and projected future burndown.
features - Show total scope: Displays both the historical and projected scope increase.
- Show completed work: It displays remaining work and completed work as
stack bar.
- Plot remaining using work item type color: Displays remaining work based on
the work item type color, rather than the default blue color. If multiple work
items are included, then it stacks colors by work item type.
Interpret a burndown or burnup chart

Your team can get immediate insight as to their progress and learn about their rhythm
and behavior. Most burndown lines aren't straight lines. The team never moves at
exactly one fixed velocity. Scope increases occur over time. For example, if your
projected completion date moves, you may want to ask one of these questions:
Are we adding too much scope?

Is the average burn rate changing, and if so, why?
Burndown charts also help teams understand risks to their release. If the projected end
date exceeds the release target date, teams may need to reduce scope or lengthen the
project. Burndown can also indicate that progress is greater than expected, providing
the uncommon, but wonderful option of adding scope.
As the following diagram shows, charts based on the burndown/burnup widgets provide
many calculated elements.
Element Description
Date range The start and end date of the burndown. When burndown gets plotted
by iterations, the end date is the end of the last iteration.
Main metric Current remaining work based on the selected burndown method.
% Completed The percentage of work completed based on original scope. Select %

Completed to see the full list of completed work items.
Average burndown Average work completed per interval or iteration.
Items not estimated Shows only when burning down on the Sum of a field. It represents the
current number of items that don't have a value in the selected
Burndown on field. Select the number to see a full list of work items
without estimates.
Total Scope Increase Shows how much work was added to the original scope since the
burndown started.
Projected completion Calculates the projected completion date based on the remaining work
and historical burndown and scope increase rates. If the projected
completion date is before the specified End Date, it draws a vertical line
on the interval when the work should complete. If the projected
completion date is after the specified End Date, it displays the number of
other intervals/iterations needed to complete the work.
Original Scope Original scope is all remaining work since the specified Start Date. The
chart burns down from the original scope. % Complete and Total Scope
Increase are calculated based on your original scope.
Element Description
Total Scope Represents to the total scope of the burndown. The plotted points
include both completed and remaining work. The total scope line
indicates the scope change of your project. For past data points, the
plotted total scope represents actual total scope as of the end of each
interval/iteration. For future data points, the plotted total scope
represents a projected scope change, based on past scope changes.
Burndown Represents the burndown. The burndown line tells you how fast you're
burning down the work. For past data points, the plotted burndown
represents actual burndown as of the end of each interval/iteration. For
future data points, the plotted burndown represents a projected
burndown, based on past burndown.
） Important
Next steps
Burndown and burnup guidance
Related articles
Define iteration paths or sprints) and configure team iterations
Add a custom field to a work item type
Apply filters to historical data
Track your work by using managed
queries in Azure Boards
Article • 06/27/2023
2018
List bugs, user stories, or other work items based on field criteria you specify using
queries. You can then review these lists with your team, triage work, or bulk update work
items. Along with managed queries, the semantic search tool provides some
overlapping and different functionality worth exploring.
Use managed queries to support these operations:
Bulk update of work items using the web portal

Triage and update work items
Review a hierarchy of work items
Share a list of work items with a team member
You can create queries and query folders from the web portal or from Visual Studio
Team Explorer. Changes you make in one client are reflected in other clients as all
changes are stored in the work tracking data store.
Get started using queries

If you're just getting started, read View, run, or email a work item query. For a quick
reference to query editor tasks and sample queries, see Query quick reference.
To find work items that are assigned to you, add the @Me macros as the value for
the Assigned To field in one of the query clauses.
have the Contribute permission set. For more information, see Set permissions on
queries.
You can modify any query by adding criteria to focus on a product area, an
iteration, or another field. To modify a query, open the query editor.
You can open any query in Excel. You can also update the fields of one or more
work items and publish your changes to the database for tracking work items.
You can visualize status or progress by creating a pie-chart, column chart, or trend
chart for flat-list queries.
Query capabilities
The following sections provide an overview of the functions supported to define and
manage work item queries.
Query filters are defined through the Query Editor.

Query macros can be selected for specific fields to create a query clause.
Query results and query management features are capabilities available through
the Query Results page.
Query filters
The following table summarizes the query filter functions supported by each Azure
DevOps version.
７ Note
Managed queries don't support proximity searches, however semantic searches do.
In addition, semantic searches support both * and ? as wildcard characters and
you can use more than one wildcard character to match more than one character.
For more information, see Functional work items search.
Filter function
Query support
Supported versions
Text string searches (single text, multi-line text, rich text)
Searches are not case sensitive.
All versions
Wildcard searches
Wild card = *
All versions
Linked work item searches

Find work items based on direct links or topological/hierarchical link types.
Filter linked work items based on MODE (WIQL syntax)
All versions
Logical clause groupings
Group and nest clauses using AND and OR Boolean operators.
All versions
Historical String and DateTime field queries
Find work items based on a field match with a previous value. Supported operator: Was
Ever Find work items based on a value defined on a specific date. Supported operator:
ASOF (WIQL syntax)
All versions
Query using macros or variables
Use macros to create queries relative to a date, other tools, such as team area path,
team iteration, and more.
All versions
Search across projects
Find work items in one or more projects in an organization or collection. Default is the
current project. Use the Team Project field to query on two or more projects.
All versions
Field comparison searches
Find work items based on how two fields compare with one another.
Supported operators: =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]
All versions
Query on tags
Find work items based on whether they contain or don't contain a tag. Supported
operators: Contains, Does Not Contain
All versions
Query on blank or empty fields
Find work items based on empty or not empty HTML/rich text fields.
Supported operators: Is Empty, Is Not Empty
Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services
In and Not In Group searches
Find work whose field value matches any value in a delimited set, such as a set of work
item types, workflow states, or picklist values. Separate values with the list separator that
corresponds to the regional settings that are defined for your client computer. For
example, you might use a comma(,).
All versions
Boolean searches
Find work items based on boolean field value.
All versions
Query History and Discussion
Find work items based on key words or phrases added through the Discussion.
All versions
Query on Kanban board fields
Find work items based on their Kanban column, swimlane, or Doing/Done status.
Interactive query filters
Filter query results based on a key word or select fields.
To bulk move, copy, or paste query clauses, install and use the WIQL editor. For more
information, see Cross-service and enhanced query operations
Supported macros
The following table summarizes the query macros or variables supported by the Azure
DevOps versions. You can use some of these macros to filter notifications.
７ Note
You can use certain macros from the web portal only. These include the
@CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity,
@RecentMentions, @RecentProjectActivity, and @TeamAreas macros. These
macros aren't supported when exporting a query to Excel, notification filters, or
exercised from Team Explorer, or REST APIs.
For more detailed descriptions and links to examples, see Query fields, operators, and
macros.
Macro
Query support
Supported versions
[Any]
Find any work item type, Work Item Type=[Any] , or any State, State=[Any] .
All versions
@Me
Find work where Identity field=logged in user .
All versions
@Today
Find work where Date-Time field=today .
All versions
@Project
Find work defined in one or more projects.

All versions
@CurrentIteration
Find work defined in current iteration for a team.
All versions
@CurrentIteration +/-n
Find work defined in +/- n of current iteration for a team.
@Follows
Find work current logged in user is following, ID In @Follows .
All versions
@MyRecentActivity, @RecentMentions, @RecentProjectActivity
Find work items recently changed, ID In @MyRecentActivity See also View and add work
items, Work Items page.
All versions
@StartOfDay, @StartOfMonth, @StartOfWeek, @StartOfYear
Find work where the selected date-time field is within the current day, month, week, or
year with a plus/minus offset, example: Closed Date>=@StartOfDay-7 .
@TeamAreas
Find work assigned to an Area Path or Iteration Path of specified team, for examples, see
Query by area or iteration path.
Query results and query management features

The following features provide support for working with query results, saving and
sharing queries, and more.
- Add a query chart to a dashboard

- Apply interactive filters
- Choose column sort
- Choose query column options
- Copy query results
- Copy Query URL
- Create a query from a backlog
- Create query charts
- Create query folders
- Define a query hyperlink

- Define and edit a query
- Define WIQL syntax
- Email query results
- Favorite a query
- Filter a query
- Import/export a query (csv)

- Import/export a query (.wiq)
- Open and run a query
- Publish/refresh a query (Excel)
- Run REST API queries
- Save queries
- Set query permissions
- Triage query results
Unsupported features
Work item queries only support querying of work items and work items linked to other
work items. Here are a few of the tasks that managed queries don't support:
Hierarchical views of Test Plans, Test Suites, and Test Cases. These items aren't
linked together using parent-child link types. Instead, you can view the hierarchy
through the Test>Test Plans page.
Views showing linked objects such as builds, releases, code, or other non-work
item objects.
List work items linked from one project to another.
Export a cross-project query to Excel. Direct links queries export to Excel as a flat-
list.
Query types (flat, direct links, tree)

query type. Use the following guidance to choose the query type based on what you
want to accomplish with the query.
Query type
Usage guidance
Flat list of work items

List items to do bulk updates to fields
Triage a list of work items
Create a query chart and add it to a dashboard
Create a chart to get a count of items or sum a field
Export a list of items to Excel to update fields
Work items and direct links

List items that are dependent on other work items
Find items related or dependent on other work items
List linked work items to do bulk updates to fields
Triage a list of linked work items
List test-related linked work items
Find orphaned backlog items, work items that have no parent
７ Note
Work items and direct links queries export to Excel as a flat list. Direct links queries
are imported as a flat list as modifying multiple types of links isn't a supported
feature in Excel.
Tree of work items

List a tree of Parent-Child related work items, or other tree-topology link type
Triage a hierarchical list of work items
Export a hierarchical list of items to Excel to update fields or modify the hierarchy
To learn more about link types, see Link type reference.
My Queries, Shared Queries, and Favorites

Only you can view and run queries that you save under My Queries with the queries
directory. Also, you can favorite one of these queries to have it appear within your query
selector.
Queries you and others save under Shared Queries can be viewed by everyone with
access to the project. Shared queries can be organized within folders and favorited by
you or for a team. Also, you can set permissions on the folders and queries to prevent
others from moving or editing them.
For more information, see:
Manage queries & query folders

Set query permissions
Favorite a query and Set personal or team favorites
Query directory, query folders, and

breadcrumbs
The Queries page contains a directory-focused view that you can filter to find specific
queries of interest. When working in the Queries pages, you can go to a subfolder,
folder, or page.
Also, you can choose a query that you've favorited from the selector menu. Or, you can
choose to browse all queries that return you to the All Queries page.
For more information, see Query FAQs, Navigate, and Folders.
Query charts and widgets

You can quickly create pie, bar, pivot, and trend charts from a flat-list query. Queries
must be flat-list and return 1000 or less work items. You can add your query charts to a
dashboard, retitle, and reconfigure them.
Query-based widgets provide support for presenting query information on a dashboard.
For example, the number of active bugs or a list of work items that you can interact with.
To learn about query charts and widgets, see these articles:
Chart a flat-list query

Query results widget
Query tile widget
Add a custom field to support queries

To add a custom field to support your query needs, see Customize your work tracking
experience.
Taskboard versus query list items
You may notice and wonder why the contents of the taskboard differ from the contents
listed with its created query? For more information, see taskboard items versus query list
items.
REST API
To programmatically interact with queries, see one of these REST API resources:
Azure DevOps Services REST API Reference

Queries
Work item query language
Fetch work items with queries programmatically
Related articles
Query FAQs
Cross-service and enhanced query operations
Query fields, operators, and macros
Use an index to query quick reference
data in Azure Boards and Azure DevOps
Article • 02/24/2023
2018
Use this index to quickly access example queries and information on opening, defining,
and working with queries. To learn how to use the Query Editor, see Define a query. If
you find that your queries take too long to return results, review the Guidance to create
high-performing queries.
Example queries
You can list work items based on the following criteria...
Keywords, wildcard queries

Keyword or phrase query with wildcards
Undefined field value queries
Empty or not empty HTML field queries
Category based queries
Items you're following
Recent activity work items
Tag based queries

Items containing a specific tag
Items that don't contain a specific tag
Items that contain two or more tags
Items that have no tag assignments
State, reason, or workflow change queries

Resolved user stories
Items I resolved in the last week
Items failing acceptance tests
Items closed within the last 15 days
Items removed as they're duplicate
Items closed and then reactivated
Stories in the Code/Doing column
Items in the Expedite swimlane
Items in a swimlane containing "Test"
Date and iteration-based queries

Items created in the last 30 days
Items modified on a specific date
Items resolved today
Items closed within a specific time period
Items whose updated status
Items closed in the current sprint
Link and attachment count queries

All child items of a single epic
All related items
Items with one or more attachments
Items with 2 or more hyperlinks
Items containing external links
Identity-based queries
Active items assigned to me
Closed items that were assigned to me
Active items assigned to my team
Items I've modified in the last 30 days
Items I closed
Team or group membership queries
My recent activity work items
Work item count and numeric field queries

Count of active bugs per developer
Count of bugs by area and states
Sum of story points and their status
Burnup chart of user stories for a sprint
Sum of remaining work per developer
History, Discussion, and revision-change queries

History contains a specific word
History doesn't contain a specific word
Reactivated items
Items closed within a time period
Items you've been associated with
Team focus queries

Assigned to a member of a team
Assigned to a team's area path
Assigned to a team's current sprint
Assigned to a team's sprint window
Build and test field queries

List bugs and linked test cases
List automated test cases
List requirement-based test suites
List query-based test suites
Other
List deleted work items (Recycle bin)
Query by field value comparisons
Query tasks
Add a query
Add a query chart
Add a query chart to a dashboard
Add a query tile to a dashboard
Add query results to a dashboard
Add a query folder
Add columns to query results
Bulk modify query items
Bulk update existing work items (csv)
Copy query URL
Define a clause
Delete a query or query folder
Direct-links query
Edit a query
Email a query
Export a query to Excel
Export a query (csv)
Favorite a query
Favorite a query as a team favorite
Filter a query
Flat-list query
Group a clause
Group a chart by tags
Import new work items (csv)
Open a query
Query across projects
Query based on tags
Rename a query or query folder
Run a query
Save a query
Tree query
Triage query results
View a query
View query results with Parent field
Understand link types
Ungroup a clause
Work Item Query Language (WIQL)
Operators and macros supported for each data

type
The following table indicates the operators and macros available for the different field
data types. Each field is associated with a data type. You can find the data type listed in
the descriptions of each field, which you can look up using the Work item field index.
Operators available for defining a query clause depend on the data type of the field that
you select. For more detailed descriptions of data types, operators, and macros, see
Query fields, operators, and macros.
７ Note
The following macros are only supported from the web portal: @CurrentIteration,
@CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions,
@RecentProjectActivity, and @TeamAreas. Queries that contain these macros
won't work when opened in Visual Studio/Team Explorer, Microsoft Excel, or
Microsoft Project.
Data type
Description
Supported operators and macros
Boolean
Supports a True/False value. Query samples: Query by assignment or workflow changes.
= , <> , =[Field] , <>[Field]
DateTime
A date field in which you can specify a variable, such as @Today or @Today-1 , or a value,
such as 1/1/2012. Enter dates in the Date Pattern you set for your personal profile. See
Set personal preferences for details.
For query examples, see Query by date or@CurrentIteration.
= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=
[Field], In, Not In, Was Ever

Macros: @Today , valid with any DateTime field
Additional macros supported on Azure DevOps 2019 Update 1 and later versions::
@StartOfDay , @StartOfWeek , @StartOfMonth , and @StartOfYear , valid with any DateTime
field
Double
Also referred to as Decimal and includes picklistDouble1. A real number, such as 0.2 or
3.5.
Query examples: Query by numeric fields.
GUID
A character string that represents a unique ID.
History
Custom formatted field used to track historical information and only assigned to the
History field.
Query examples: History and auditing.
Contains Words, Does Not Contain Words

Contains Words, Does Not Contain Words
HTML
Text strings that support formatted descriptions, such as the Description or Repro Steps
fields. These fields are automatically indexed for full-text search when full-text search is
available. Query samples: Query by titles, IDs, and rich-text fields.
Contains Words , Does Not Contain Words , Is Empty 2, Is Not Empty 2
Identity
A String field that is used to hold a user identity. Query samples: Query by assignment
or workflow changes.
[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever
Macros: @me valid for all Identity fields.
Integer
Also includes picklistInteger1. A 32-bit integer that is signed, such as 0, 1, 2, 34.
Query samples: Query by numeric fields
Macros: @Follows , @MyRecentActivity , @RecentMentions , and @RecentProjectActivity ,

valid when used with the ID field.
PlainText
Multi-line text strings that support long descriptions and are automatically indexed for
full-text search, when full-text search is available.
Query examples: Query by titles, IDs, and rich-text fields.
Contains Words , Does Not Contain Words , Is Empty , Is Not Empty
String
Also includes picklistString1. Short single-line text that can contain up to 255 Unicode
characters. String fields support the Title field, picklists (drop-down menus), user
accounts, Tags, and other fields.
Query examples: Query by titles, IDs, and rich-text fields and Query by picklist value.
Macros: [Any] , valid with the Work Item Type field @Project , valid with the Team
Project field.
TreePath
Field type that supports the Area Path and Iteration Path fields. You define the tree
structure for a project—area paths and iteration paths.
Query examples: Query by area or iteration path and Query by date or current iteration.
Under , Not Under , = , <> , In , Not In
Macros: @TeamAreas 3, valid with Area Path field

@CurrentIteration and @CurrentIteration+/- n 4 valid with the Iteration Path field
７ Note
1. The picklist... data types are only assigned to custom fields defined for an
inherited process. The Inherited process model is only supported for Azure
DevOps Server 2019 and later versions.
2. The Is Empty and Is Not Empty operators are supported for Azure DevOps
Server 2019 RC2 and later versions.
3. The @TeamAreas macro is supported for Azure Boards and Azure DevOps
4. The @CurrentIteration +/- n macro is supported for Azure DevOps Server
2019 and later versions, and only when run from the web portal.
Date and time pattern

The date and time pattern you enter for DateTime fields should match that which you
select through your profile. To view or change your selection, see Set user preferences,
Time and Locale.
Example queries for select fields
The following table lists common query fields and their data type for which sample
queries are provided. To determine the data type of a field, see Work item fields and
attributes, List field attributes.
A
Acceptance Criteria (HTML)
Activated By (Identity)
Activated Date (DateTime)
Activity (String)
Area Path (TreePath)
Assigned To (Identity)
Attached File Count (Integer)
Automated Test Name (String)
Automated Test Type (String)
B
Blocked (String)
Board Column (String)
Board Column Done (Boolean)
Board Lane (String)
Business Value (String)
C
Changed By (Identity)
Changed Date (DateTime)
Closed By (Identity)
Closed Date (DateTime)
Comment Count (Integer)
Committed (String)
Completed Work (Decimal)
Created By (Identity)
Created Date (DateTime)
D-E-F
Discipline (String)
Description (HTML)
Due Date (DateTime)
Effort (Decimal)
External Link Count (Integer)
Finish Date (DateTime)
Found In Build (String)
H-P
History (History)
Hyperlink Count (Integer)
ID (Integer)
Integrated in Build (String)
Iteration Path (TreePath)
Link Comment (Integer)
Node Name (String)
Original Estimate (Decimal)
Parameters (HTML)
Priority (Integer)
R
Reason (String)
Related Link Count (Integer)
Remaining Work (Decimal)
Repro Steps (HTML)
Resolved By (Identity)
Resolved Date (DateTime)
Resolved Reason (String)
Rev (Integer)
Revised Date (DateTime)
S
Severity (String)
Size (Decimal)
Stack Rank (Decimal)
Start Date (DateTime)
State (String)
State Change Date (DateTime)
Steps (HTML)
Steps to Reproduce (HTML)
Story Points (Decimal)
System Info (HTML)
T
Tags (String)
Target Date (DateTime)
Task Type (String)
Team Project (String)
Test Suite Type (String)
Title (System)
Triage (String)
V-W
Value Area (String)
Work Item Type (String)
Related articles
Query by field value comparisons
Guidance to create high-performing queries
Define a managed query
Run a semantic work item search in
Article • 04/03/2023
2018
You can find work items by using shortcut filters or by specifying keywords or phrases.
You can also use specific fields/field values, assignment or date modifications, or using
Equals, Contains, and Not operators. Searching isn't case-sensitive. Use semantic
searches when you want to do the following tasks:
Find a specific work item using its ID or a keyword

Find one or more work items across all projects in a fast, flexible manner
Run a full text search across all work item fields
Review work items assigned to a specific team member
Search against specific work item fields to quickly narrow down a list of work items
Determine what key words support a managed search
You can run a powerful semantic search from the web portal for Azure DevOps Services
or for on-premises deployments when the server instance has been configured with the
work item search extension.
Start a semantic search for work items

With semantic search you can search:
Across one or more projects

Across all work item fields using free text
Against specific work item fields
Free text search easily searches across all work item fields, including custom fields, which
enables more natural searches. Search results are displayed in a snippet view where the
search matches found are highlighted. Semantic search also integrates with work item
tracking, providing familiar controls to view, edit, comment, and share information
within a work item form.
1. Choose any Boards page, enter a keyword or phrase in the search box, and press
Enter or choose the start search icon.
2. Search results are displayed in a snippet view where the matches found are shown
in bold.
This search is a full text search that uses simple search strings for words or phrases.
Work item search matches derived forms of your search terms; for example, a
search for "updating" also finds instances of the word "updated" and "update".
Searches aren't case-sensitive.
3. Select a snippet of a work item to display it in the right window.
Open the search results in a new browser tab from a search box by pressing Ctrl +
Enter or by holding Ctrl and clicking the icon. In Google Chrome, press Ctrl +
Shift + Enter to switch the focus to the new browser tab.
Fine-tune semantic search results

1. Fine-tune your search by specifying the fields to search. Enter a: and a user name
to search for all items assigned to that user.
The quick filters you can use are:
a: for Assigned to:
c: for Created by:

s: for State
t: for Work item type
2. Start entering the name of a field in your work items; for example, type ta .
The dropdown list shows work item field name suggestions that match user input
and help the user to complete the search faster. For example, a search such as
tags:Critical finds all work items tagged "Critical".
3. Add more filters to further narrow your search, and use Boolean operators to
combine terms if necessary. For example, a: Chris t: Bug s: Active finds all
active bugs assigned to a user named "Chris".
4. Narrow your search to specific types and states, by using the drop-down selector
lists at the top of the results page.
### From the web portal
Improvised search isn't available from Azure DevOps Services. Only semantic search.
From Visual Studio Team Explorer

Open the context menu and select an option.
Finding work items using the search box (Team Explorer)
You can combine shortcuts and use search operators within the search box.
Use the Clear button to remove content from the search box. To switch your context
to the search box from within Visual Studio, enter Ctrl+'.
Find items based on keywords or phrases

Keywords or phrases that you type into the search box return a list of work items that
contain those keywords or phrases in the Description, Repro Steps, or Title fields.
Enclose each phrase in quotation marks.
In the Search work items box, type a keyword or phrase that appears in the Title,
Description, or Repro Steps fields for the work items of interest.
Enclose multiple words in quotation marks.
For example, to find work items with the specified keywords in the Title or Description
fields:
For the keyword "duplication", enter duplication.

For the phrase "Getting Started", enter "Getting Started".
For the phrase "Getting Started" or the keyword "feature", enter feature "Getting
Started".
Filter for items that contain these keywords or phrases: Enter the following string:
Duplication duplication
Getting Started "Getting Started"
Feature and Getting Started feature "Getting Started"
You can run partial or exact match queries on a keyword or a phrase contained within
any text field. Or, you can run a full-text search query by filtering on keywords and
phrases contained within the full-text search index. Team Foundation automatically
indexes all long-text fields with a data type of PlainText and HTML and the Title field for
full-text search.
Find items based on specific fields and field

values
To find work items based on a keyword or phrase contained within other text string
fields, specify either the friendly name or the reference name of the field. Enclose each
phrase in quotation marks. You can determine the friendly name of a field by hovering
over the field within a work item form. To determine the reference name of commonly
used fields or to find a field that isn't listed on the form, see Work item field index.
Filter for items that meet this criteria: Enter the following string:
Contains one attached file. System.AttachedFileCount=1
Cut user stories. T:Story Reason=Cut

Or
T="User Story" System.Reason=Cut
Resolved by Peter. "Resolved By":Peter

Or
Microsoft.VSTS.Common.ResolvedBy:Peter
Modified today. "Changed Date"=@Today
Created yesterday as a test activity. "Created Date"=@Today-1 Activity=Test
７ Note
Some fields, such as History and Description, do not support partial word text
searches. For example, if the History field contains the phrase reproducible
behavior and you search for History:repro the work item isn't found. However, if
you search for the complete string History:reproducible the work item is found.
Use @Me or @Today macros

The @Me macro expands to the full name of the current user in any work item search.
The @Me macro is especially useful for creating a search that you can share with other
users, and it can simplify your work by reducing the number of characters you must type
to specify your own user name. For a description of all macros, see Query fields,
operators, and macros, Query macros or variables.
Filter for
Enter the following string
Currently assigned to you
A=@Me
Created by you
C=@Me
Resolved yesterday
Resolved Date=@Today-1
Modified seven days ago
System.ChangedDate=@Today-7
Created yesterday under the Phone Saver team
Created Date=@Today-1 And Area Path=FabrikamFiber\Phone Saver
Use Equals, Contains, and Not operators

Use the following search operators to specify search criteria:
= (EQUALS) to search for exact matches of text.

: (CONTAINS) to search for partial matches of text.
- (NOT) to exclude work items that contain certain text. The NOT operator can only be
used with field names.
The following examples show how to use operators when you create a search string.
Filter for items that meet this criteria: Enter the following
string:
Assigned to Peter and not Active. A:Peter -S=Active
In which the Activity field wasn't Development . - Activity=Development
Resolved by Peter. "Resolved By":Peter
Contain the keyword triage in the title or description, aren't triage -A=@me -S=Closed
assigned to you, and aren't closed.
Active bugs that are assigned to you that don't contain the keyword S=Active T=bug A=@Me -
bugbash in the title. Title:bugbash
Related articles
About managed queries
Define a query
Q&A
Q: Does the search box support less than/greater than

operators?
A: No. The search box doesn't recognize comparison operators such as greater than (>)
or less than (<). It translates queries with these operators into a search phrase.
Article • 06/27/2023
2018
To find work items assigned to you or your team, run a query. Many work item queries
are predefined with your process. Members of your team may have created shared
queries that you can view and run. Often, it's easier to define a new query by building on
the query definition that's already available to you.
Prerequisites
By default, all project members and users with Stakeholder access can view and
run all shared queries. You can change the permissions set for a shared query
folder or shared query. For more information, see Set query permissions.
To add and save a query under Shared queries, you must be granted Basic access
or higher. Also, you must have your Contribute permission set to Allow for the
folder you want to add the query to. By default, the Contributors group doesn't
have this permission.
７ Note
Users with Stakeholder access for a public project have full access to query features
just like users with Basic access. For more information, see Stakeholder access
quick reference.
Open Queries
Browser
From your web browser, (1) check that you have selected the right project, (2)
choose Boards>Queries, and then (3) choose All.
If it is your first time opening Queries, the page opens to Favorites. This page lists
those queries that you have indicated are a favorite. Otherwise, you can choose All
to view all queries you've defined and shared queries defined for the project.
 Tip
Queries you or your team have chosen as favorites show up on the Favorites
page. Favorite queries along with other objects also appear on your Project
page. For more information, see Set personal or team favorites.
Run a query in Azure Boards

To run any query, expand a folder and choose the title of the query. The view opens to
display the query Results.
You can also run a query by using the Azure DevOps command line interface.
Browser
 Tip
The Queries page, as with other web portal pages, remembers the view you
last went to and returns you to that view.
1. Choose All to open the page where you can view all queries you've defined or
that are shared within your project.
2. Choose My Queries as needed.
To view all work items assigned to you, choose Assigned to me. This
query uses the @Me macro to list all work items assigned to you.
To view all work items you're following, choose Followed work items.
This query uses the @Follows macro (ID in @Follows) to list all work
items you've chosen to follow. For more information, see Follow a work
item or pull request.
3. Choose Shared Queries to expand the folder and access queries saved as
shared queries.
4. Choose a folder within a breadcrumb to open a query folder.
Run a query from the command line

You can run a query in the CLI with the az boards query command. To get started, see
Get started with Azure DevOps CLI.
Azure CLI
az boards query [--id]

[--org]
[--path]
[--project]
[--wiql]
Parameters
id: The ID of an existing query. Required unless--path or--wiql is specified.
wiql: The query in Work Item Query Language format. Ignored if--id or--path is
specified.
path: The path of an existing query. Ignored if--id is specified.
org: Azure DevOps organization URL. You can configure the default organization
using az devops configure -d organization=ORG_URL . Required if not configured as
default or picked up using git config . Example: --org
https://dev.azure.com/MyOrganizationName/ .
project: Name or ID of the project. You can configure the default project using az
devops configure -d project=NAME_OR_ID . Required if not configured as default or
picked up using git config .
Example
The following command runs a query with the specified ID and shows the result in table
format.
Azure CLI
az boards query --id 6c286d74-26a5-4cce-bfcf-bf9123495bfe --output table
Priority Node Name Work Item Type Title

Remaining Work
---------- ---------------- ---------------- ----------------------------
---- ----------------
1 Voice Bug Apply fix elsewhere as
needed
2 CMMI Bug Slow response on form
1 Fiber Bug Check issues with
permissions 0
2 Fiber Bug Voicemail hang issue
0
2 FabrikamBB Bug Research slow response time
1 FabrikamBB Bug Fix performance issues
0
The following command runs a query with the specified WIQL and shows the result in
table format.
Azure CLI
az boards query --wiql "SELECT [Microsoft.VSTS.Common.Priority],

[System.NodeName], [System.WorkItemType], [System.Title],
[Microsoft.VSTS.Scheduling.RemainingWork], [System.AssignedTo],
[System.State], [System.Tags], [System.AreaPath] FROM workitems WHERE
[System.WorkItemType] = 'Bug' AND [System.AreaPath] = 'Fabrikam Fiber' ORDER
BY [System.WorkItemType]" --output table
Priority Node Name Work Item Type Title

Remaining Work
---------- -------------- ---------------- ---------------- -------
---------
2 Fabrikam Fiber Bug Slow response on form
2 Fabrikam Fiber Bug Check permissions
2 Fabrikam Fiber Bug Fix performance issue
2 Fabrikam Fiber Bug Secure Sign-in
Query directory, query folders, and

breadcrumbs
７ Note
You can't add folders to My Favorites or Team Favorites.
Browser
The Queries page contains a directory-focused view that you can filter to find
specific queries of interest. When you're working in the Queries pages, you can go
to a subfolder, folder, or page.
Also, you can choose a query that you've favorited from the selector menu, Or, you
can choose to browse all queries, which returns you to the All Queries page.
All and Favorites supported tasks

You can do most tasks for viewing and running queries from each of the queries list
pages as indicated in the following table. Only queries you save under My Queries and
have favorited show up under My Favorites. Only queries saved under Shared Queries
can be favorited by a team.
Favorites All Work Items

Task (Browser) (Browser) (Team
Explorer)
View all favorited queries, yours or a team you belong ✔️ ✔️

to
View all your queries or shared queries for the current ✔️ ✔️

project
Run a query, open the context menu for a query ✔️ ✔️ ✔️
Expand or collapse container folders or query folders ✔️ ✔️ ✔️
Filter the list of queries ✔️ ✔️
Favorite a query (for web portal, choose ) ✔️
Unfavorite a query (for web portal, choose ) ✔️ ✔️ ✔️
Add a new query: Choose ✔️ ✔️ ✔️
Filter the list of queries

Enter a keyword into the filter box to filter the set of queries displayed on either the
Favorites or All pages. To learn more about filtering, see Filter backlogs, boards, queries,
and plans.
Email query items or share a query URL

Browser
From the Query Editor or Results view, you can email a formatted list of query
items or copy the query URL.
Choose the actions icon to open the menu and select from the options listed,
Email query or Copy query URL.
You can only send the email to individual address for a project member that is
recognized by the system. Adding a team group or security group to the to line
isn't supported. If you add an email account that the system doesn't recognize, you
receive a message that one or more recipients of your email don't have permissions
to read the mailed work items.
７ Note
To email a formatted list to people who aren't project members, you'll need to
use the Copy as HTML option described in Copy a list of work items. For on-
premises Azure DevOps, all email actions require an SMTP server to be
configured. If you don't have an SMTP server configured, you can work around
this by using Copy as HTML.
Next steps
Define a query
Related articles
Manage queries and query folders
Set personal or team favorites
Keyboard shortcuts
Define a work item query in Azure
Boards
Article • 09/29/2023
2018
Work item queries generate lists of work items based on the filter criteria provided by
you. You can save and share these managed queries with others.
You can create queries from the web portal or from a supported client, such as Visual
Studio Team Explorer. To support bulk updates or additions, import or export queries
using Excel or .csv files.
Check out our recommended best practices, later in this article.
Prerequisites
You must have Stakeholder access to view and run shared queries. All project
members have Stakeholder access by default. For more information, see Change
the permissions for a shared query or folder.
You must have Basic access or higher to add and save a shared query.
You must have your Contribute permission set to Allow for the folder that you
want to add a query to. By default, the Contributors group doesn't have this
permission.
７ Note
quick reference.
Choose a query filter

From the Query Editor, you can select the filter to jump to an article with sample
queries. Along with the query filters, you can interactively apply filters to query results.
７ Note
In addition, semantic searches supports both * and ? as wildcard characters and
For more information, see Functional work item search.
Filter features
Macros
Compare fields
Key words
Linked work items
Logical groupings
Query macros
Tags
Was Ever
Was Ever (Board Column)
Wildcard
Blank or empty fields
Boolean searches
Identity searches
History and Discussion
Kanban board fields
[Any]
@Me
@Today
@CurrentIteration, @CurrentIteration +/-n
@Follows
@TeamAreas
You can also interactively filter a query using the Filter function.
Open Queries
Browser
choose Boards > Queries, and then (3) choose All.
 Tip
Define a flat-list query

Start a new query from the Queries tab in the web portal or the Work Items tab in Team
Explorer.
Browser
Select New query.

The Query Editor displays with the following default settings: Flat list of work items,
Work Item Type=[Any], and State=[Any].
Modify the Values and add or remove clauses, or change the Type of query to
Work items and direct links or to a Tree of work items.
Query across or within projects

New queries scope to the current project by default. But, you can create queries to find
work items defined within the organization or project collection. All queries that you
save, however, get saved under a specific project.
Browser
To list work items defined in two or more projects, checkmark Query across
projects. For example, the following query finds all features created in all projects
within the last 30 days.
With the Query across projects checked, you can add the Team Project field to
filter to a select number of projects.
７ Note
Separate multiple project names with the list separator that corresponds to the
regional settings defined for your client computer, for example, a comma , .
The Team Project field is available only after you check Query across projects.
When Query across projects is checked, all fields from all work item types
defined in all projects in the collection appear in the Field drop-down menu.
When Query across projects is unchecked, only those fields from those work
item types, as defined in the current project, appear in the Field drop-down
menu.
Define a clause
To create a query, define one or more clauses. Each clause defines a filter criteria for a
single field.
Sample query clause
And/Or Field Operator Value
And Assigned To = @Me
For a list of available operators based on the field data type, see Query index quick
reference.
All clauses get added as an And statement. Select Or to change the grouping. Group
clauses to ensure that the clause statements are run in the sequence required.
Browser
Select Add new clause to add another clause at the end of the query, and then
select the Field, Operator, and Value for that clause.
For example, search for all work items assigned to you by specifying the Assigned
To field, the equals (=) operator, and the @Me macro, which represents your user
identity.
 Tip
To view the WIQL syntax for a query, and how parenthesis are used to group
clauses, install the Marketplace Wiql Editor . This extension supports viewing the
WIQL syntax and exporting it to a WIQL file for use in REST API calls. For more
information, see Syntax for the Work Item Query Language (WIQL).
Checklist for defining a query clause

1. In the first empty row, under the Field column heading, choose the down arrow to
display the list of available fields, and choose an item in the list. For more
information, see Query Fields and Values.
2. In the same row, under the Operator column heading, select the down arrow to
display the list of available operators, and then choose an item in the list. For more
information, see Operators.
3. In the same row, under the Value column heading, either enter a value, or select
the down arrow, and then choose an item in the list. For more information about
how to use a macro or variable to specify the current project, user, date, or other
selection, see Variables.
4. To add a clause, choose Add new clause.
You can add a clause to the end of the query, or perform the following tasks with
the corresponding icons:
Insert new filter line

Remove this filter line
Group selected clauses
Ungroup clauses
Use a work item tree to view hierarchies

Use the Tree of Work Items query to view a multi-tiered, nested list of work items.
For example, you can view all backlog items and their linked tasks. To focus on different
parts of the tree, choose Expand all or Collapse all.
７ Note
You can't construct a query that shows a hierarchical view of Test Plans, Test Suites,
and Test Cases. These items aren't linked together using parent-child link types.
However, you can create a direct links query that lists test-related work items. Also,
you can, view the hierarchy through the Test Plans page.
Browser
Define the filter criteria for both parent and child work items. To find linked
children, select Match top-level work items first. To find linked parents, select
Match linked work items first.
Use direct links to view dependencies
Use the Work items and Direct links query to track work items that depend on other
tracked work, such as tasks, bugs, issues, or features. For example, you can view backlog
items that depend on other items being implemented or a bug being fixed.
Use the direct links query to track dependencies across teams. The query also helps you
manage commitments your team makes. Choose the filter criteria for the top and linked
work items. And, select the types of links to filter the dependencies.
Browser
Filter your first-tier list of work items by choosing one of these options:
Only return items that have matching links: First-tier work items return, but
only if they have links to work items specified by the linked work items filter
criteria.
Return all top level items: All first-tier work items return despite the linked
work items filter criteria. Second-tier work items that are linked to the first tier
return if they match the linked work items filter criteria.
Only return items that do not have matching links: First-tier work items are
returned, but only if they don't have links to work items specified by the linked
work items filter criteria.
For more information about each link type, see Linking, traceability, and managing
dependencies.
Use and/or logical expression

Specify And or Or to create logical expressions of your query clauses. Use And to find
work items that meet the criteria in both the current clause and the previous clause. Use
Or to find work items that meet the criterion in either the current clause or the previous
clause.
Add one new clause for each work item field to refine your search criteria. Add clauses
to return only the set of work items you want. If you don't receive the results you expect
from your query, refine it. You can add, remove, group, or ungroup query clauses to
improve your query results.
Group query clauses to operate as a single unit separate from the rest of the query.
Grouping clauses is similar to putting parentheses around an expression in a
mathematical equation or logic statement. When you group clauses, the And or Or for
the first clause in the group applies to the whole group.
Group clauses
Grouped clauses operate as a single unit separate from the rest of the query. Grouping
clauses is similar to putting parentheses around a mathematical equation or logic
expression. The And or Or operator for the first clause in the group applies to the whole
group.
As the following examples show, the grouped clauses are translated to the
corresponding logical expression.
Query Grouped clauses Logical expression
These queries return work items that are type Bug and meet the following logical
expressions:
Query 1: AND State=Active OR Assigned to @Me

Query 2: AND (State=Active OR Assigned to @Me)
Query 3: OR (State=Active AND Assigned to @Me)
To group one or more clauses, select them and then select the group clauses icon.
You can also group several grouped clauses. Check the boxes of each clause that's
already been grouped. Then, choose the group clauses icon.
If your query results don't return expected results, do the following steps:
Make sure that each clause is defined as you intended.

Verify And / Or assignments to each clause. If your results contain more work items
than expected, often an Or clause is present instead of an And clause.
Determine if you need to group or change the grouping of the query clauses and
the And / Or assignments of each grouped clause.
Add more query clauses to refine your query filter criteria.
Review the options available to specify fields, operators, and values.
See best practices, later in this article.
Ungroup a clause
To ungroup a clause, select the ungroup clauses icon for the grouped clause.
View query results in a dashboard

The following two widgets display query results. You can open work items directly from
these widgets.
Work assigned to me: Lists all proposed or active work items assigned to the
signed-in user. Lists the ID, State, and Title fields.
Query results widget: Displays the results of a flat, tree, or direct-links query. You
can configure the fields displayed through the widget, resize the column fields, and
expand and collapse tree and direct-links query.
For more information, see Add widgets to a dashboard.
View query results widget with Parent titles

You can view the results of a query with the Parent title displayed. To do so, perform
these steps:
1. Create the query that filters the work items of interest. The query can be a flat-list,
tree, or direct-links query.
2. Add the Parent field as a column.
3. Save the query as a Shared query or Team favorite.
4. Add the Query results widget to your dashboard and configure the query. Make
sure the Parent field is set to display.
The following image illustrates a query results widget that displays the Parent field.
Define a query as a hyperlink

A query hyperlink uses the Work Item Query Language (WIQL), which resembles
Transact-SQL. For more information, see Syntax for the Work Item Query Language
(WIQL).
７ Note
Most browsers enforce a limit of between 2000 and 2083 characters for a URL
string.
Query hyperlink syntax for Azure DevOps Services
Encode the WIQL portion of the URL syntax. You can use any URL encoder tool to
encode your URL.
https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql=
{Encoded WorkItemQueryLanguage}
For example, the following hyperlink lists the ID and title of all active bugs defined under
the FabrikamFiber/Web area path for the Fabrikam organization.
https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?
_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20Work
Items%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem
.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSy
stem.AreaPath%5D%3D'FabrikamFiber%5CWeb'
The decoded WIQL conforms to:
wiql
SELECT [System.ID], [System.Title]

FROM WorkItems
WHERE [System.TeamProject]='FabrikamFiber'
AND [System.WorkItemType]='Bug'
AND [System.State]='Active'
AND [System.AreaPath]='FabrikamFiber\Web'
７ Note
The WIQL length must not exceed 32K characters for Azure Boards queries.
Best practices
The following best practices apply to the following queries you can create:
Web portal queries

Work Item Query Language (WIQL) queries
az boards query command line
REST API queries
Create focused, selective queries

Define a highly selective query by applying all filters that are necessary for your query.
The more selective the query is, the smaller the set of results. The smaller the result set
is, the more targeted and selective your query is.
Use tags to categorize work items

Use work item tags to categorize your work items instead of a custom field. Queries that
filter on tags usually perform faster over those queries that filter on string matches.
Unlike custom field matches or partial matches, a query with a Tags Contains operation
doesn't require a complete scan of all work item tables.
Use Contains words for string matches

To filter on a string match, use the Contains Words instead of the Contains operator.
The Contains Words operator runs a full-text search on the specified field, which tends
to complete more quickly.
The Contains operator runs a table scan, which is a slower operation than the Contains
Words operator. It also consumes more CPU cycles. These CPU cycles can cause you to
encounter rate limitations. For more information, see Service limits and rate limits and
Rate limits.
Specify small groups with the In Group operator

The In Group operator filters work items based on matches within a group of values.
The group of values correspond to the values contained within a team, security group,
or work tracking category. For example, you can create a query to find all work items
that are assigned to any member of a team. Or, find all work items that belong to the
requirements category ( Microsoft.RequirementCategory ).
When you filter on a group that contains a large number of members, your result set
tends to be larger and nonselective. Also, if a group corresponds to a large Azure Active
Directory (Azure AD) group, the query generates a fairly large cost to resolve that group
from Azure AD.
Avoid use of negated operators
Negated operators—such as <>, Not In, Not Under, Not In Group —tend to generate
nonselective queries and large result sets.
Only use negated operators when necessary. Always try to find alternatives first. For
example, if Field1 has values A, B, C, D; specify the Field1 In A, B, C clause, instead of
the negated Field1 <> D clause.
Avoid string comparisons

Queries that contain string comparisons generate table scans that are inherently
inefficient. Instead, we recommend you use tags or a specific custom field as
alternatives, particularly when a query performs poorly.
Limit Or operators
Limit the number of Or operators defined in your query. Queries run better when fewer
Or operators are used. Too many Or operators can make your query nonselective. If
your query runs slowly, reorder the Or operator clause towards the top of the query
clauses.
Save your query

Due to internal optimizations, saved queries tend to perform better over unsaved
queries. Always save your query when you plan to reuse it. Even for WIQL queries run
through a REST API, save the WIQL through the web portal to make your REST API calls,
so they're less prone to future performance regressions.
Run your query

Sometimes you need to run your query a few times to reach the right optimization plan.
Make sure to save your query and run it up to 10 times over a 30-minute period. This
way, the system can examine and seek out the optimization plan that's most appropriate
for your query.
Related articles
Query quick reference.
Query FAQs
Chart a flat-list query
Keyboard shortcuts
Manage and organize queries in Azure
Boards and Azure DevOps
Article • 02/24/2023
2018
Organize your personal or shared queries by adding a query folder. You can then add
queries to or move existing queries into those folders. You can create queries and query
folders from the web portal or from a supported client, such as Visual Studio Team
Explorer.
７ Note
To create and manage queries in Visual Studio 2019, you need to Set the Work
Items experience to the legacy option. Also, you can perform bulk drag-and-drop
of queries into query folders from Visual Studio but not from the web portal.
Prerequisites
By default, all project members and users with Stakeholder access can view and
run all shared queries. You can change the permissions set for a shared query
folder or shared query. For more information, see Set query permissions.
To add and save a query under Shared queries, you must be granted Basic access
or higher. Also, you must have your Contribute permission set to Allow for the
folder you want to add the query to. By default, the Contributors group doesn't
have this permission.
７ Note
quick reference.
Open a query
Browser
 Tip
Run, edit, and save a query

The easiest way to define a query is to start with an existing shared query. The following
example shows how to find all closed bugs by modifying the Active Bugs shared query
provided with the Agile process template. Examples are based on the user interface
provided through the web portal.
Browser
1. Open a shared query. For example, from the web portal, open the Active Bugs
or similar flat list query.
 Tip
If you're working in Visual Studio Team Explorer, open the Work page to
access your queries and shared queries. If Team Explorer isn't visible,
choose View>Team Explorer from the top level menu.
2. Edit the query to find closed bugs and then run the query. Use to insert a
clause above the current clause. Use to delete a clause. Queries are
automatically scoped to the current project. To find work items defined in
several projects, see Query across projects.
3. Save the query to your My Queries folder.

To save a query to the Shared Queries folder, you need to be a member of the
Project Administrators group, or have your Contribute permissions on the
folder set to Allow. For more information, see Set query permissions.
Rename or delete a query

Browser
From either the Favorites or All page, choose the actions icon of a query to run,
edit, rename, or delete the query.
For shared queries, you can also choose to do one of these tasks:
Add to team queries: Select the team to add the query as a team favorite
Security...: to set permissions for the query. For more information, see Set
query permissions.
Add to dashboard: Adds a Query tile widget to the team dashboard you
select. For more information, see Add widgets to a dashboard.
Add a query folder and move items into a

folder
 Tip
You need Delete permissions to rename or move a shared query or folder, and
Contribute permissions for the folder where you move the query to. To view or set
permissions, see Set permissions on queries and query folders.
Browser
You add query folders from the Boards>Queries>All page.
1. Choose All. Expand My Queries or Shared Queries depending on where you

want to add a query folder.
2. To add a folder, choose the actions icon for an existing folder or the top
container folder, and choose New folder.
3. Enter the name for the folder in the New folder dialog. If you want to change
the location of the folder, select it from the Folder drop down menu.
4. To move items into a folder, drag-and-drop a query onto the folder. From the
web portal, you can only drag a single query from outside a folder into a
folder.
Optionally, you can choose More commands for an existing query, choose
Edit, and then choose Save As. In the Save query as dialog, choose the folder
you want to save the query in.
Save a query as a team favorite
To save a shared query as a team favorite, you must be a member of the team.
To add a query to a dashboard, open the actions icon (or context icon) menu for
the query and add it to a specific dashboard or as a team favorite.
Share queries with your team by adding them to a folder under the Shared Queries
container. To save a query to a Shared Queries folder, get added to the Project
Collection Administrators group or have your permissions set for a folder under Shared
Queries.
You can only add shared queries to dashboards or as team favorites, and only if you
have team administrator or project administrator permissions.
1. To save a query as a team favorite, open More actions or the context menu
for the query from the Queries page.
2. Choose Add to team favorites, and then select from the teams listed. Only teams
for which you're a member are listed.
Add a query tile to a dashboard
A query tile displays a count of the work items in a query. You can also quickly open the
query from the dashboard. You can add a query tile to a dashboard from the Queries
page using the following steps, or by following the steps outlined in Add widgets to a
dashboard.
７ Note
You can only add a shared query to a dashboard. And, to add or edit a widget of a
team dashboard, you must be a member of the team or be granted permissions to
edit the dashboard.
1. To add a query to a dashboard from the Queries page, open the actions icon
(or context icon) menu for the query.
2. From the Select a dashboard dialog, choose the dashboard you want to add the
query to.
3. Open the dashboard, and verify the query tile was added. You can configure the
query tile to change the default color and to specify the color for the tile based on
a conditional rule you specify.
Related articles
Query FAQs
Keyboard shortcuts
Track progress with status and trend
query-based charts
Article • 02/24/2023
2018
You can quickly view the status of work in progress by charting the results of a flat-list
query. Different chart views such as pie, column, pivot, or trend are supported. Charts
support viewing a count of work items or a sum of values for select numeric fields, such
as Story Points, Effort, or Remaining Work. Group work by State, Assigned To, or other
system defined or custom field.
In this article you'll learn how to perform the following tasks:
＂ Construct a flat-list query to support your chart

＂ Create and share your query-based chart
＂ Create a status pie, column, bar, or pivot chart
＂ Create a trend chart
＂ Add a chart to a dashboard
７ Note
This article describes how to configure work tracking query charts. To add existing
query charts to dashboards, see Add charts to a dashboard. For information on
configuring a Chart for Work Items widget, see Configure a chart for work items
widget.
For an overview of all work tracking charts and in-context reports, see About
dashboards, charts, reports, & widgets.
For example, the following image illustrates two different charts created from the same
flat-list query. The pie chart groups the 19 bugs by state, and the bar chart groups the
bugs by assignment and their current status.
Prerequisites
Prerequisites to meet include having Basic access or higher and to have created a flat-
list query. Only flat-list queries support charts.
If you want to add the chart to a dashboard, then you need to save the query under the
Shared Queries folder, and create the dashboard where you want to add the chart.
To create a query chart, you must have Basic access or higher. Users with
Stakeholder access can't view or create charts from the Queries page, however,
they can view charts added to a team dashboard. For details, see Stakeholder
To add a chart to a dashboard, you must save the query to a Shared Queries
folder. To do that, you must be granted permissions to save queries under a folder.
To get permissions granted, see Set permissions on queries and query folders.
To add a query chart to a team dashboard, you must be a member of the team or
be a member of the Project Administrators security group.
To add a query chart to a project dashboard, you must have created the dashboard
or be granted permissions to edit the dashboard, or be a member of the Project
To view a query chart added to a dashboard, you must have Read permissions to
the underlying query. If that permission has been denied, then the widget will
display with a Widget failed to load message.
７ Note
Users with Stakeholder access for a public project have full access to query chart
features just like users with Basic access. For details, see Stakeholder access quick
reference.
To learn more about dashboard permissions, see Set dashboard permissions.
Create a flat-list query

When creating a query to support your chart, follow these guidelines.
Always select the Flat list of work items query type. Other query types aren't
supported for charting. For more information, see Define a query, Define a flat-list
query.
Add those fields to either a query clause or the column options that you want to
use within your chart. You can group charts by any field except date-time, free-
form text, and tag fields. For example:
To group by Status, include the State field
To group by work assignments, include the Assigned To field
To group by sprints or iterations, include the Iteration Path
To group by team, include the Node Name field that displays the leaf node of
the Area Path
To group by a custom field, include it.
To sum a numeric column, include the corresponding field in your query clause or
column options. For more examples of charts created from numeric fields, see
Query by a numeric field.
If you plan to add your query to a dashboard, save your query as a Shared query.
You can't group charts by the following field data types:

ID
Date-time, such as Created Date, Changed Date
Plain text, such as Title
Rich-text, such as Description, Repro Steps
Tags (You can filter a query using tags, however you can't use tags to configure
your chart).
７ Note
Work Items widget by tags that you add to a dashboard as described in Configure
a chart for work items widget.
Display of areas and iterations
When you select Area Path or Iteration Path, only the leaf node appears in the chart.
The leaf node is the last node of the full path. For example, Phone is the leaf node of
FabrikamFiber/Fabrikam Website/Phone . If your query contains a mixed level of leaf
nodes, your chart might not reflect expected results.
Select the Node Name field, the area path leaf node, to see if that improves your results.
Charts display in browsers that support Scalable Vector Graphics (SVG). Supported
browsers include Microsoft Edge, Internet Explorer 9 and later versions, Chrome, Firefox
and Safari on Mac. Charts aren't optimized for mobile or touch displays.
７ Note
Internet Explorer is no longer supported for Azure DevOps Services, nor for Azure
DevOps Server 2020.1.
Sort by Value or Label

Most charts allow you to choose how you want to sort the data. You can sort by Value
or Label and select Ascending or Descending.
Value: Sorts data by the numeric value

Label: Sorts by the label selected for grouping the data.
Limited display of series

When a chart contains more than eight or 12 items within the data series, values in the 9
or 13-plus items are consolidated into a set labeled "other"? However, if you increase
the chart size through the configurable widget on a dashboard you may increase the
series limit.
Chart availability
Charts saved under Shared Queries are viewable by all team members, except
members with Stakeholder access, and can be added to dashboards.
Charts that you create for queries under your My Queries folder are visible only to
you.
You can copy and email the URL of any chart page to share it with a project
member.
To create similar charts for tests, see Track test status.
Create a query-based chart

1. From Queries, open the chart editor for a flat list query. You must belong to the
Contributors group to create charts.
If you have Stakeholder access, the Charts and New Chart links won't appear.
2. Select the chart type and field for grouping values. When you use pie, bar, and
column charts, select a single field to view a count of work items.
If you don't see the field you want in the Group by drop-down list, add the field as
a column to the query and save the query. Also, the Aggregation options depend
on the fields used in the query or those selected from the Column Options.
If you receive an error message when you close the chart editor, you need to
request Basic access.
3. To sort the results, select Value or Label as the sort option and then Ascending or
Descending.
To change a color, select a color from the Series set of color pickers.
Charts automatically update when you edit the query or refresh the query results.
Add a Pie chart

Use a pie chart to show group percentages with six or fewer categories. Good examples
of pie charts are:
Active Bugs Status, group by State

User Story Status, group by State
User Story Progress, group by Completed, In Progress, or Cut
For example, the following query filters User Stories based on the State for Cut, In
Progress, and Completed since the start of the year.
The pie chart configuration is as shown in the following image.
The combined query and chart configuration yield the following pie chart.
Add a Stacked bar chart
A stacked bar chart lets you track progress against two field values. Node Name will
display the last leaf within an area path. Use this when you want to show data across
teams, and each node corresponds to a team.
Add a Pivot table
The Pivot table displays a table of configurable rows and columns, with columns
showing a count of work items or sum of a numeric field. Choose a Pivot table when you
want to compare across areas the work being performed.
The following image shows an example of active bugs assigned to developers and their
current state.
Add a Trend chart

Trend charts let you view progress over time. You can select a rolling period ranging
from the last week to the last year.
Trend data is extracted from the work tracking data store. Like most data stores, the
schema of the relational database is designed and optimized for the online transactional
processing of data. As the tool or plug-in performs an activity, it writes the latest
information to the operational store. Therefore, data in the operational store is
constantly changing and being updated, and all data is current.
Add a Burndown chart

Burndown charts are useful for determining how quickly work is progressing based on a
numeric field value, such as Story Points, Effort, or Remaining Work, or on a count of
work items.
To create a burndown chart, make sure to add the numeric field you want to your query.
To view a burndown chart of tasks, select the Sum operator for Remaining Work.
In addition to query-based burndown charts, you can Configure a burndown or burnup
widget.
Add chart to a dashboard

A chart added to a dashboard is added through the addition of a Chart for Work Items
widget. You can add the chart to a dashboard as shown in the following procedure, or
by adding the Chart for Work Items widget directly. To learn more, see Configure a
chart for work items widget.
 Tip
All query charts are limited in size. However, charts added to a dashboard can be
re-sized and re-configured by opening the Chart for Work Items widget used to
display them.
Select the actions icon for the chart you want to add, and select Add to
dashboard.
The Add to dashboard menu option is only available for queries that have been saved
to a Shared Queries folder.
In the dialog that opens, select the dashboard to add the chart to.
To add other types of charts, such as test results and build summary charts, see Add
widgets and chart to a dashboard.
Related articles
Example query charts
Configure a chart for work items widget
FAQs on Azure DevOps dashboards, charts, and reports
Team velocity
View/configure sprint burndown
Track test status
Add widgets and chart to a dashboard
Widget catalog
Article • 02/24/2023
2018
specific sprint.
assigned work.
Path, or Tags.
Area Path or Tags.

✔️or is listed.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes

enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
Relevance.


７ Note
team.
Prerequisites

view
Features, or Epics
Work Items
team member.
want to filter on.
criteria.
Inactive functions


values.
board.

operator.



include 'web'.

Unassigned
７ Note

Epics).
AND | OR . AND
Item 2.

７ Note
you've defined.

features.

tags.
boards.

Related articles
About backlogs
Customize cards
Tags
FAQs about queries in Azure
Boards and Azure DevOps
FAQ
2018
The Query Editor supports finding work items by specifying query clauses based on
fields, operators, and values. You can save and share these queries with others in your
team. Here are some answers to frequently asked questions about work item queries.
General
Can I use a wildcard in my query?
Yes. The wildcard character is an asterisk (*). For samples, see Query by titles, IDs, and
rich-text fields.
What's the difference between a query and a

semantic search?
While both query and semantic searches find and list work items, the filter features and
results presentation are different. For more information, see Functional work item
search, Semantic search vs. managed work item queries.
Can I export a query and import to another

project?
Yes. You can save a query as a .wiq file, update the syntax, and then import it to another
project, organization, or collection.
What are all the query filter functions?

From the Query Editor, you can exercise the following filter functions. Choose the filter
to jump to an article with sample queries. In addition to the query filters, you can
interactively apply filters to query results.
７ Note
In addition, semantic searches support both * and ? as wildcard characters and
For more information, see Advanced work items search.
Filter features
Macros
Compare fields
Key words
Linked work items
Logical groupings
Query macros
Tags
Was Ever
Wildcard
Blank or empty fields
Boolean searches
History and Discussion
Kanban board fields
[Any]
@Me
@Today
@CurrentIteration, @CurrentIteration +/-n
@Follows
@TeamAreas
Can I filter the Query Results?

Yes. See Interactively filter backlogs, boards, queries, and plans.
Can I run several queries at the same time?

Yes. Open a query in a new browser tab to run several queries at the same time.
What query macros are only supported from the

web portal?
@RecentProjectActivity, @TeamAreas. Queries that contain these macros won't work
when opened in Visual Studio/Team Explorer, Microsoft Excel, or Microsoft Project.
Navigate
How do I quickly navigate to queries I view
frequently?
Favorite those queries and other artifacts that you view frequently. Choose the
star icon to favorite a query.
Favorited queries ( favorited icon) are listed in the Queries>Favorites page.
Also, you can select one from the queries selector, as shown in the following
image.
Or, you can select from any of your favorited items by choosing the inbox icon and
choose Favorites.
How do I quickly navigate to queries within the
same query folder?
When viewing a query, you can use the queries breadcrumb selector ( the
breadcrumb icon changes to a context menu selector) to view the queries defined
within the folder. To open the queries folder, choose the folder name.
Find work items
Where can I find work assigned to me or work
that I'm following?
Open Queries>All. Under the My Queries section are two fully customizable queries:
Assigned to me and Followed work items.
Where can I find recent work item activity?

Open Boards>Work Items and select the Recently updated view. See View and
add work items.
You can also use the macros — @Me, @Follows, MyRecentActivity,

@RecentMentions, @RecentProjectActivity — to create custom queries. These
queries can filter for work items assigned to you, that you're following, and so on.
To learn more about these macros, see Query macros and variables.
How do I sort on the Parent field?

You can't. Sorting a query on the Parent field isn't a supported feature.
Linked work item queries

How do I query for a list of related work items?
You can't query for work items that contain links solely based on the Related link type.
You can query for work items that have links by specifying Related Link Count > 0 .
However, the results contain all work items containing links to other work items,
including Parent-Child, Predecesor-Successor, and other link types.
Can I query for work items linked across
projects?
No. There's a prohibitive performance cost for trying to execute such a query, so it isn't
supported.
Can I link work items across organizations or

collections?
Yes across organizations. See Link user stories, issues, bugs, and other work items; Link
to a remote work item. However, you can't run a search for work items linked from other
projects than the current project you're connected to.
Bulk add and update work items using

queries
Can I export a cross-project query to Excel?
No. Cross-project queries won't open in Excel. However, you can export a cross-project
query to a .csv file, open it in Excel, and import it to Azure Boards. For more information,
see Bulk import or update work items using CSV files.
How do I manage dependencies across projects?

To manage dependencies in Azure Boards, you can link work items using the
Predecessor/Successor link type. To learn how, see Link user stories, issues, bugs, and
other work items.
Query folders
Can I change the owner of a query or folder?
No. You can only enable permissions for users and groups from the permissions window
for the query or folder.
Can I move a query or a folder?

Yes. In the web portal, choose Rename from the context menu. In Team Explorer for
Visual Studio, drag the folder to the new location. In Team Explorer Everywhere or
Eclipse, choose Move from the context menu and select the folder to which you want to
move the item.
Can I add folders to My Favorites or Team

Favorites?
No. This feature isn't supported.
Are the queries and folders I create from the

web portal the same as in Team Explorer?
Yes. You may have to refresh your browser or client to see changes you make in another
client. For Visual Studio 2019, you must choose the legacy experience to see work item
queries and folders.
Monitor progress with queries

How can I best use queries to monitor progress
on a project or team?
Define a chart for a query and add it to a dashboard, or add the Query Results
widget to a dashboard. Each time you open the dashboard, the query
automatically runs and refreshes.
Related articles
Azure Boards FAQs
Excel FAQs
Set permissions on queries and query
folders in Azure Boards and Azure
DevOps
Article • 02/24/2023
2018
As with most project objects, you can control access by setting permissions. With
queries, you can configure users and groups to create, delete, view, and manage
permissions of shared queries and shared query folders.
All users, except those users assigned to the Readers group, can create and edit their
own queries and save them under My Queries. Only the signed in user can view queries
saved under their My Queries space.
By default, only members of the Project Administrators group can create and edit
queries and folders under Shared Queries, or change the permissions for a query or
folder.
By creating folders under Shared Queries, you can grant permissions to users for each
folder. For example, if you have several teams contributing to a project, then you might
want to create a folder under Shared Queries for each team to manage their own set of
shared queries.
Prerequisites
To create or edit a shared query or manage permissions, you must be a member of
the Project Administrators groups with Basic or higher access level. Or, you must
have your Contribute permission set to Allow for the shared query folder. To get
added to this group, see Change project-level permissions
Or, to create a query or folder under a shared query folder, you must have the
Contribute permission set explicitly to Allow for the query folder and be granted
Basic or higher access level.
Or, to change permissions of a query or query folder, you must have the Manage
Permissions permission set explicitly to Allow for the query folder and be granted
Basic or higher access level.
Users with Stakeholder access can't create or save queries in a Shared folder. To learn
more about access levels, see Stakeholder access quick reference.
 Tip
Consider creating a query folder for each team and give the team administrators or
the team group query permissions to manage their folder.
Default query permissions

A ✔️(checkmark) in the following table indicates that the corresponding security group
has permission to exercise the task by default.
Task
Readers
Contributors
Project admins
✔️
✔️
✔️
✔️
✔️
✔️
Set permissions on a new query folder

You set permissions from the web portal. To open Queries, see View, run, or email a
query.
 Tip
You need Delete permissions to rename or move a shared query or folder, and
Contribute permissions for the folder where you move the query to.
1. Choose All. Expand Shared Queries.
2. To add a folder, choose More actions for an existing folder or the top container
folder, and choose New folder.
3. Enter the name for the folder. If you want to change the location of the folder,
select Rename from the folder drop-down menu.
Here we name the folder Service Delivery with the intention that it gets used by the
Service Delivery team.
4. To set permissions for the folder you just added, choose the actions icon and
select Security.
5. Change the permissions so that the team member or group can contribute and
manage permissions for the folder. Enter the name of a user or group within the
search box.
Here we add the Service Delivery team and grant them permissions to create and
manage permissions to all queries and folders under the Service Delivery folder.
Contribute allows team members to create and edit queries and folders under the
folder where the permissions were granted. And, Manage Permissions allows team
members to manage the permission settings on queries and subfolders.
6. (Optional) Turn off inheritance. Default is On. By turning off inheritance for a
folder, you disallow inheritance of permissions that exist up the chain of query
folders. For more information, see Permissions, Inheritance.
7. Close the dialog when you're done.
8. Reopen the Security dialog and choose Service Delivery to verify that the
permissions are set.
Set permissions on a shared query
To keep anyone else from modifying a shared query that you create, you may want to
set permissions on a specific query. You can set permissions by opening the permissions
dialog for the specific query.
1. Choose the actions icon and select Security.

2. Change the permissions so that a team member or group can't edit, delete, or
change permissions for the query.
Here we deny permissions for the Disallow access group.
Related articles
With queries, you cannot only list work items, you can create status and trend charts and
add them to dashboards. You can learn more about permissions and working with
queries from these resources:
Manage queries and query folders

Permissions and access for work tracking
Add a chart to a dashboard
Dashboards
Azure Boards
Article • 02/24/2023
2018
views.
Action
Backlogs
Sprint backlogs
Queries
Work items
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
No
Sort on a column
No
No
Yes
Yes
 Tip

portfolio backlog.
you change them.
７ Note


Browser
Sort on a column
descending order.
keyboard commands:
a new location
For query results:
to sort
you're on.
Related articles
Import & update bulk work items with
CSV files
Article • 06/06/2023
Import and export work items in bulk using a CSV formatted file in Azure DevOps. While
you can continue to use Excel for bulk import and updates, you can use the native
import/export feature that doesn't require Excel. For more information, see Bulk add or
modify work items with Excel.
７ Note
The export feature is available with Azure DevOps Server 2019 Update 1 and
later versions. The import feature is available with Azure DevOps Server 2020 and
Import new work items

All work items that you import get created in a New state. This rule means that you can't
specify field values that don't meet the field rules for the new state. For example, when
you create a new user story with the Agile process, the State = New and the Reason =
New. You can't specify any other values.
1. Create a local import.csv file and open it in Visual Studio Code or Excel.
2. The file must contain the Work Item Type and the Title fields. You can include
other fields as needed. For a list of default fields, see Work item field index.
In the following example, we include the Priority field.
CSV
Work Item Type,Title,Priority

Issue,Fix issues with code,1
Issue,Merge testing modules,3
Issue,Open private preview for select customers,2
Issue,Enable feature for customer champs,2
Issue,Remove old test code,2
3. From the web portal for your project, open Boards > Queries, and then select the
Import Work Items option.
4. Select your CSV file and then choose Import.
The import process loads the imported work items into the queries view in an
unsaved state. No IDs get assigned.
5. Verify the results and then select Save items to save the work items.
７ Note
Don't assign IDs to new work items that you're adding, otherwise you receive
an error message similar to the following if you do so.
6. The system highlights those work items with data issues. Resolve the data issues
before you save the work items. In this example, an invalid value has been entered
into the Priority field. Fix the data by opening the work item directly. Instead, use
bulk edit to fix several work items with the same issue.
 Tip
You can add parent-child links between work items you import by indenting the
title columns as shown in the example later in this article, Can I import a CSV file
that have parent-child links?. However, you can't specify any other link types when
importing or updating work items.
Update existing work items
1. To update work items, create a query that contains all the columns you want to
export and possibly edit. Save your query and select Export to CSV to save the
data.csv file to your local machine.
The exported file should look similar to the following syntax:
CSV
ID,Work Item Type,State,Assigned To,Title,Tags

"1043","Issue","To Do",,"Fix issues with code",
"1044","Issue","To Do",,"Merge testing modules",
"1045","Issue","To Do",,"Open private preview for select customers",
"1046","Issue","To Do",,"Enable feature for customer champs",
"1047","Issue","To Do",,"Remove old test code",
2. Make the edits to your work items. Your CSV file must contain the ID, Work Item
Type, Title, and State fields. Any other fields you want to include are optional.
７ Note
When you import identity fields, enter the name and email in the following
format "Display Name <email>" . For example, to assign work to Jamal
Hartnett, specify "Jamal Hartnett <fabrikamfiber4@hotmail.com>" . If you
specify a value that isn't recognized as a valid user to the system, you may
encounter problems with the import.
In the following example, we change several values on existing working items.

ID,Work

<fabrikamfiber4@hotmail.com>","Fix issues with code",architecture
<fabrikamfiber4@hotmail.com>","Merge testing modules",testing
<fabrikamfiber5@hotmail.com>","Open private preview for select
customers","customer focus"
<fabrikamfiber5@hotmail.com>","Enable feature for customer
champs","customer focus"
"1047","Issue","To Do","Christie Church
<fabrikamfiber1@hotmail.com>","Remove old test code",architecture```
3. Save the file and import (see steps 4-6 from the previous import section.)
4. The results list with work items that contain value changes appear highlighted in
bold. Select Save Items to apply the changes.
5. Work items with data issues get highlighted in red and must be resolved before
you can save them. In this example, an invalid value appears in the Assigned To
field. Fix the data by opening the work item directly. You can use bulk edit if you
have many work items with the same issue.
Export list as a CSV file
query, select the actions icon, and then select Export to CSV.
Export and import work items to a different

project
You can use this feature to export work items from one project and import them to
another project. However, before you import them to another project, you must remove
the work item ID. You get an error if you attempt to import new work items to a project
with an ID specified.
Import or update rich-text fields

You can update or import rich-text fields such as the Description or Acceptance Criteria
fields. Rich-text fields are HTML formatted fields. Replace lines ending in CRLF by
surrounding sentences with ... .
For example, you can import the following work item, which includes three lines of text
in the Description field.
CSV
Work Item Type,Title,Description

"Product Backlog Item","Hello World Web Site - 8"," You can
include bold text And italic text
 Underline text"
FAQs
Q: Can I import new items and update existing items in

the same CSV file?
A: Absolutely! Leave the ID field empty for any new work items. In the following
example, the last entry for an Epic doesn't specify an ID.
CSV
ID,Work Item Type,Title,Assigned To,State,Priority,Tags

"16504","Issue","Fix issues with code",,"To Do","1",
"16505","Issue","Merge testing modules",,"To Do","3",
"16506","Issue","Open private preview for select customers",,"To Do","2",
"16507","Issue","Enable feature for customer champs",,"To Do","2",
"16508","Issue","Remove old test code",,"To Do","2",
,"Epic","Track Telemetry for data imports",,"To Do","2",
Q: How do I add multiple tags?

A: You can add multiple tags separated by a semicolon. For more information, see Tasks
you can and can't do with Excel.
Q: Can I import a CSV file that has parent-child links?

A: Yes, you can add child work items by indenting title columns. The following example
adds three child issues under the already defined Epic.
CSV
ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags

"165","Epic","Track Telemetry for data imports",,,"To Do","2",
,"Issue",,"Fix issues with code",,"To Do","1",
,"Issue",,"Open private preview for select customers",,"To Do","2",
,"Issue",,"Enable feature for customer champs",,"To Do","2",
Q: How do I know if my imported file has errors?
A: You can test by adding tags with spaces and hyphens, for example, and include it in
the export. The import should match the same format. Any problems with the
formatting of your CSV file appear in the Results page of the import view. You can't
import the work items until the formatting and syntax is correct.
The work item results always list the data errors found for individual work items. Fix each
error either from the web portal, or in the CSV file and import again.
Q: Why am I getting errors for some identity values?

A: When you use the Web UI, the identity picker goes through extra steps to validate the
user. First it checks to see if the person is a valid user in the org. If not, it searches on the
identity in Azure Active Directory (Azure AD). If the user's in Azure AD but not in the org,
that user gets added to the valid identities. When you import via CSV, for performance
reasons, the identity picker doesn't go through these extra steps. It only checks to see if
there's a matching UPN already in the org. If it doesn't find a matching UPN, it reports
that the identity is unknown.
Q: Does CSV import support all work item types?

A: No, the CSV import doesn't support the following work item types:
Code Review Request

Feedback Request
Feedback Response
Test Case
Test Plan
Test Suite
Shared Parameter
For more information, see Bulk import or export test cases.
Related articles
Article • 02/24/2023
2018

７ Note
Prerequisites
７ Note
７ Note

Server.

Editor.
Query types:
List types:
Query types
feature in Excel.
Tree lists

Agile process
this article.


no hierarchy
items, no hierarchy
Use Excel features


Fill down cells
Filter
Sort work items


reconnect.


７ Note
the project.

list.
 Tip

topology link type.
） Important
relationships.
restrictions.
type.
was imported.
created.

Remove a tree level
removed.

work items:
item tasks.

 Tip
Choose Columns.
periodically.
the drop-down menu.

or query.


７ Note
search.
3. Choose Find.

interest.
up and down arrows.

this feature.
 Tip
Team ribbon.

Link work items

Delete links
other work items.
View and add links


following dialog.




Add attachments
Create a report
） Important

articles:

Related articles
Basic Excel tasks
Example query charts
Article • 02/24/2023
2018
Query charts are a great way to visualize status and trends. Also, by adding several
charts to a dashboard, you can quickly review all the important data you want to
monitor for your team or project. With that in mind, consider addressing the following
questions with your team:
What are the most useful query charts for us to create and monitor?
What charts help to maintain backlog hygiene?
What time frame should we monitor when creating trend charts?
Not all teams have the same goals or tracking needs. However, teams that adopt Agile
methods tend to routinely perform the following tasks. So consider the status and trend
charts that can help your team perform these tasks.
Triage incoming work, ensure new work is well defined

Refine the backlog as described in Backlog management
Plan sprints and set sprint goals as described in Scrum and best practices
Conduct daily stand-ups.
Prerequisites
To create a query chart or view query charts from the Queries page, you must have
Basic access or higher. Users with Stakeholder access can't view or create charts
from the Queries page, however, they can view charts added to a team dashboard.
To add a query chart to a dashboard:
You need to save the query under the Shared Queries folder. To do that, you
must be granted permissions to save queries under a folder. To get permissions
granted, see Set permissions on queries and query folders.
You must have created the dashboard or be granted permissions to edit the
dashboard. To learn more about dashboard permissions, see Set dashboard
permissions.
To view a query chart added to a dashboard, you must have Read permissions to
the underlying query. If that permission is denied, then the widget displays a
Widget failed to load message.
７ Note
Users with Stakeholder access for a public project have full access to query chart
features just like users with Basic access. For more information, see Stakeholder
Tips for creating query charts

For details on creating query charts, see Track progress with status and trend query-
based charts. Make sure your queries meet the following guidelines.
Only choose Flat list of work items for the query type. Only flat-list queries
support query charts.
Always save a query after modifying the clauses or column options before
switching to the Charts page.
Use the In and Not In operators to specify more than one work item type,
workflow state, or other groupings of interest
When creating a trend chart, make sure that your query returns no more than 1000
work items. You'll receive a widget error if that number is exceeded.
Add the fields to either a query clause or the column options that you want to use
within your chart. You can group charts by any field except date-time, free-form
text, and tag fields. For example:
To group by status, include the State field
To group by work assignments, include the Assigned To field
To group by sprints or iterations, include the Iteration Path
To group by team, include the Node Name field that displays the leaf node of
the Area Path
To group by a custom field, include it.
To sum a numeric column, include the corresponding field in your query clause or
column options. For more examples of charts created from numeric fields, see
Query by a numeric field.
You can't group charts by the following field data types:
Work item ID or Parent fields
Date-time fields, such as Created Date, Changed Date
Plain text fields, such as Title
Rich-text fields, such as Description, Acceptance Criteria, Repro Steps
Tags (You can filter a query using tags, however you can't use tags to configure
your query chart).
７ Note
While you can't group a query-based chart by tags, you can group a Chart for
Work Items widget by tags that you add to a dashboard as described in
Configure a chart for work items widget.
If you plan to add a query chart to a dashboard, first create the dashboard. Then,
you can add it to the dashboard from the Queries>Charts page.
If you add a query and then want to add it to a dashboard from the dashboard,
you must first refresh your browser for the dashboard to register the newly added
query.
To optimize performance of complex queries, see Best integration practices,
Optimize queries.
Maintain backlog hygiene

The following queries can help your team maintain a healthy backlog by ensuring that
work is assigned. The following table provides some example queries to review
periodically, usually at the beginning or end of a sprint. Review this list for what makes
sense for your team and organization goals. Substitute the Fabrikam Team for your team
and add other filters as needed.
７ Note
Work item types and workflow states applicable to your project may differ from
those shown in the following examples depending on the process used by your
project.
Query focus
Query clauses
Unassigned work: Work assigned to the current sprint but not assigned to a team
member
Active work not assigned to the current sprint
Active work assigned to a past sprint
Stale work: Work items with no changes made in the last two to three months (query by
Changed Date)
Ill-defined work: For example, ones with no Description, Acceptance Criteria, Story
Points, or Effort defined
In the following image, all five query charts appear on a team dashboard. To add query
charts to a dashboard, see Add charts to a dashboard
Alternatively, you can add query tiles that reference the same query and show the total
count of work items as shown in the following image.
７ Note
The query tile widget is a 1x1 tile, whereas the smallest query chart dashboard
widget is 2x2. To add query tiles to a dashboard, see Add widgets to a dashboard.
Example status charts

The following table provides some examples of status charts you can create and the
queries behind them.
Query focus
Query clauses
Planned work: How much work is represented in the backlog. A query that looks at work
in the New or Proposed category state provides a snapshot of work in the backlog.
Active bugs: Agile teams monitor their bug or technical debt and set goals to maintain
the total number under a specific number.
From this one query, you can create a chart based on assignment or state.
Tagged work items: Monitor tagged work to ensure the team is meeting specific goals,
milestones, or categories of work.
Blocked work: How much work is currently blocked? You can query blocked work using
a tag or custom field.
Example trend charts
The following table provides some examples of trend charts you can create.
Query focus
Query clauses and chart
Bug trends over time by state (last 30 days)
Active work trends by state (last 30 days)

Useful work tracking widgets and charts
In addition to the query charts provided earlier in this article, the following built-in
widgets provide a wealth of information for teams working to monitor progress and
continuous improvement goals. Each of these charts can be added to a team dashboard.
Velocity
Cumulative flow
Sprint burndown
Lead time and Cycle time
Related articles
Query editor
FAQs about queries
Query by date or current iteration
Query by titles, IDs, and rich-text fields
in Azure Boards and Azure DevOps
Article • 09/28/2023
2018
When you want to find work items based on a keyword or phrase or a null text field, you
can do so by filtering on single-line text (String), multi-line text (PlainText), and rich-text
(HTML) fields. If you find that your queries take too long to return results, see Create a
query/Best practices.

Query clauses that specify a text or rich-text field can use the operators and macros
listed in the following table.
Data type
Rich-text (HTML)
Multi-line text strings (PlainText)
Contains Words , Does Not Contain Words , Is Empty 1, Is Not Empty 1
Single text (String)
Macros: [Any] , valid with the Work Item Type field and @Project 2, valid with the Team
Project field.
ID
[Field], In, Not In, Was Ever Macros: @Follows , @MyRecentActivity , @RecentMentions ,
@RecentProjectActivity valid with the ID field and In and Not In operators @Project 2,
valid with the Team Project field.

State and Work Item Type fields
[Field], Contains , Does Not Contain , In , Not In , In Group , Not In Group , Was
Ever **Macros**: [Any]` valid with both fields.
７ Note
1. The Is Empty and Is Not Empty operators are supported for Azure DevOps
Server 2019 RC2 and later versions
2. The system automatically defaults to filtering based on the current project. For
more information, see Query across projects.
Use Contains words for string matches

When you want to filter on a string match, try using the Contains Words operator
instead of Contains . The Contains Words operator runs a full-text search on the
specified field, which is faster in most cases. Text string is limited to 100 characters.
While the Contains operator runs a table scan, which isn't only slower, but also
consumes more CPU cycles. These CPU cycles contribute towards your resource
consuming rate limit.
７ Note
The Contains Words operator makes use of SQL's full-text search indexing. When a
new value is saved to a long-text field, SQL Server will:
Split the phrase into individual words

Remove any common words that don't really add value to a search (like "a" or
"is" in English)
Convert words to their common stem (e.g. running, ran, and runner would get
converted into "run", as they are all variations on that word)
Store these unique keywords in an index.
When a user then runs a query on this field using the Contains Words operator, the
search will be run against the unique keywords stored in the index. For long-text
fields, this makes searching much more efficient and quicker than doing a substring
search. By default, SQL defines a "word" as a set of characters between
punctuation. For example, periods signify the end of a word, but the period is not
considered to be part of the word. Because the full-text search index contains
keywords instead of exact phrases, you'll end up getting all the results that contain
the same keywords, as determined by the indexing.
Keyword or phrase query with wildcards

Use Contains or Contains Words to list items that partially or exactly match the words
or phrase that you enter.
Choose Contains or Does Not Contain to search against exact or partial matches of a
word or phrase. Choose Contains Words or Does Not Contain Words to search against
an exact phrase or to use the wildcard character, *. These operators use the full-text
search index.
For example, specify Contains Words and inform* to filter on a text field that contains
inform or information or informational.
 Tip
editor entry.
Query for specific words and not others

Use Contains Words and Does Not Contain Words operators to list items that exactly
match the words or phrase that you enter, and exclude other words or phrases. You can
use these operators in combination and with the wildcard character (*).
In the following example, these operators filter work items for those items that contain
the work Phase but not the word Phasor.

You can find work items that have an undefined field value by using the equals operator
(=) and leaving the Value for the field blank. For example, the following filters list all
work items of type Task whose Activity field is blank.
To list work items based on a field that isn't blank, use the not operator (<>) and leave
the Value blank.
Empty or not empty HTML field queries

You can find work items where no Description has been entered. Using the Is Empty or
Is Not Empty with an HTML field supports listing work items with empty or not empty
rich text fields. You don't specify a value with this operator.
For example, the following query filters list all work items where some entries have been
made into the Description field.
７ Note
Category-based queries
To filter work items based on the category they belong to, use the In Group operator.
For example, the following filter criteria returns all work items that are in the current
project, assigned to the team member, and defined as belonging to the Bug Category.
What items appear in the Requirement or Task
categories?
The default assignments of work item types to each category are listed below for each
process.
Process Requirement category Task category
Basic Issue Task
Agile User Story Task
Scrum Product Backlog Item, Bug Task
CMMI Requirement Task
Each team can determine if the Bug work item type appears in either the Requirement
or Task category. See Show bugs on backlogs and boards. You can add custom work
item types to a backlog. For more information, see Add or modify a work item type, Add
a custom WIT to a backlog or board.
Query for work items that you're following

You can use the @Follows macro to filter a list based on work items you're following
along with other query filters.
For example, the following query shows how to query across all projects for active work
items that you're following. You use the ID field and the In operator with the @Follows
macro.
Query for recent work item activity

You can use the following macros to list work items based on recent activity:
@MyRecentActivity: List items you've recently viewed or modified.

@RecentMentions: List items you were added to via an @mention in the last 30
days.
@RecentProjectActivity: List items that have been recently created or modified in
your project.
Specify the ID field and either the In or Not In operators.
For example, the following query shows how to query for work items that you've
recently viewed or modified.
Common fields for most work item types

The following table describes common fields used to filter queries. The ID fields
uniquely identify work items in a list. Use the Title field to distinguish the work item
from all others of the same type. The Description and other rich-text (data type=HTML)
fields provide additional information that is needed to implement work and track
changes. After a work item is created, you can modify all fields except for the ID. When
you add and save a work item, the ID is assigned by the system and cannot be changed.
７ Note
The system automatically indexes all long-text fields with a data type of PlainText
and HTML fields for full-text search. This includes the Title, Description, and Steps
to Repro fields. For more information and server and collation requirements
applicable to on-premises Azure DevOps, see Query fields, operators, values, and
variables - Full-text and partial word searches.
Field name
Description
Work item type
Acceptance Criteria 1
A description of the criteria to be met before the bug or product backlog item can be
closed.
Before work begins on a bug or product backlog item, the criteria for customer
acceptance should be described as clearly as possible. Conversations between the team
and customers to define the acceptance criteria helps ensure that your team
understands your customers' expectations. The acceptance criteria can be used as the
basis for acceptance tests so that you can more effectively evaluate whether an item has
been satisfactorily completed.
Reference name=Microsoft.VSTS.Common.AcceptanceCriteria, Data type=HTML
Bug, Epic, Feature, Product backlog item (Scrum)
Description 1, 2
Use this field to provide in-depth information about a work item.
Reference name=System.Description, Data type=HTML
All
ID
The unique identifier that is assigned to a work item. Work item IDs are unique across all
projects and within a project collection.
Reference name=System.Id, Data type=Integer
All
Repro Steps (or Steps to reproduce) 1
The steps that are required to reproduce unexpected behavior. Capture enough
information so that other team members can understand the full impact of the problem
as well as whether they have fixed the bug. This includes actions taken to find or
reproduce the bug and expected behavior.
Reference name=Microsoft.VSTS.TCM.ReproSteps, Data type=HTML
Bug
Resolution
Describes how an impediment was resolved.
Reference name=Microsoft.VSTS.Common.Resolution, Data type=HTML
Impediment (Scrum)
System Info1
Information about the software and system configuration that is relevant to the bug,
code review, or feedback.
Reference name=Microsoft.VSTS.TCM.SystemInfo, Data type=HTML
Bug, Code Review Request, Feedback Request
Team Project
The project to which a work item belongs. Add this field to a query when you want to
filter your list to items in one or more projects. For more information, see Example
queries, query across projects.
Reference name=System.TeamProject, Data type=String
All
Title
A short description that summarizes what the work item is and helps team members
distinguish it from other work items in a list.
Reference name=System.Title, Data type=String
All
Work Item Type
The name of the work item type. Work item types are defined based on the process
used when you created your project. For more information, see About processes and
process templates and Add or modify a work item type.
To filter work items based on their category assignment, you can use the In Group and
Not In Group operators and select a category from the drop-down list.
Reference name=System.WorkItemType, Data type=String
All
７ Note
Upon upgrade to Team Foundation Server 2012, the Description field was changed
from a field type of PlainText to HTML. Using the witadmin changefield command
you can revert the data type for this field. See Manage work item fields
(witadmin).
Related articles
Query editor
Add work items
REST API

Queries
Query by assignment or workflow
changes in Azure Boards
Article • 02/24/2023
2018
The states in the workflow support tracking work status as it moves from a new state to
a closed or done state. Kanban query fields support tracking the status of work as it
moves from one column or swimlane to another on the Kanban board.
Each workflow consists of a set of states, valid transitions between states, and reasons
for transitioning the work item to the selected state. Workflow states and reasons differ
among the work item types and default processes used to create your project.
Most work items move from a New, Active, or Proposed state to a Done or Closed state.
As each work item moves from one state to another, the item might also be reassigned
to various members of the team. For example, a tester might create a bug that is
assigned to another team member during triage. When the other team member resolves
the bug, it's reassigned to the tester who created it.
For example, you can find all work items that were closed but then reactivated. By
specifying the Changed Date field, you can focus on reactivations that occurred today,
yesterday, or in the last week.
You can also use the Activated By and Activated Date fields, or other workflow fields.
 Tip
Not all fields are valid for all work item types. Jump to Workflow and Kanban
query fields for the set of fields you can include in queries and which work item
types they apply to.
If you're new to creating queries, see Use the query editor to list and manage queries.

Query clauses that specify an identity or workflow-associated field can use the operators
and macros listed in the following table. To learn about the field data type, see Workflow
and Kanban board fields provided later in this article.
Data type
Boolean 1
= , <> , =[Field] , <>[Field]
DateTime
Macros: @Today , @Today +/- n valid with any DateTime field
Identity
Macros: @Me valid for all Identity fields
Single text (String) 2
Use the In and Not In operators to filter for or exclude two or more pick list entries or
a delimited set of items. Use the In Group or Not In Group operators to filter for items
that belong or don't belong within a category group or security group. For more
information, see Query fields, operators, and macros.

Time and Locale.
Identity-based queries
Use the search box or query editor to quickly find work items based on an assignment
made to an Identity field. Also, you can filter for work items based on who changed,
resolved, or closed a work item. By specifying a time period, you can scope your query
even further, which can help with performance.
Use = to find current assignments, Was Ever to list items based on past assignments,
and @Me to scope to your user identity.
Filter for
Include these query clauses
Active items assigned to me
Assigned To @Me
And State = Active

Closed items that at some point was assigned to me
Assigned To Was Ever @Me

And State = Closed
Active user stories assigned to the Web team
Work Item Type = User Story
And State = Active
And Assigned To In Group [FabrikamFiber]\Web
Items I've modified in the last 30 days
Changed By = @Me And Changed Date >= @Today-30
Unassigned items (leave the Value blank)
Assigned To = _
Team or group membership queries

To filter on items assigned to someone who belongs to a team or security group, use
the In Group operator.
You can use the In Group or Not In Group operators to filter a query based on several
values that are members of a group, or that aren't members of a group. Examples of
groups you can specify include the following items:
Teams
Built-in and custom security groups
Azure Active Directory and Active Directory security groups
Work item categories
Queries based on workflow changes

You use the State, Reason, and Resolved Reason fields to query for items based on
workflow changes.
Filter for
Resolved stories
And State = Resolved
Stories, bugs, and tasks that are new or active
Work Item Type In User Story,Bug,Task

And State In New,Active
Items removed as they're duplicate
State= Removed
And Reason = Duplicate
Items failing acceptance tests
Resolved Reason = Acceptance tests fail
Items closed within the last 15 days
State = Closed
And Closed Date > @Today-15
Workflow changes and identity-based queries

You can quickly find items that you changed, resolved, or closed. You can also find items
that were changed by other team members. Several fields—such as the Created By,
Changed By, Resolved By, and Closed By—are populated based on changes to the
workflow.
Filter for

User Stories that I closed

And Closed By = @Me
Resolved By = @Me
And Resolved Date >= Today-7
Query changes in work item state

To list work items that have changed state within a specific date range, you can use the
State Change Date field to narrow the search and then add clauses for changes to the
State field. An example is shown in the following image.
Query changes to a Kanban board

Using the Kanban query fields—Board Column, Board Column Done, and Board Lane—
you can list work items according to their flow status on the Kanban board. And, you
can create a status or trend chart based on these queries.
You can list items based on the team area path, and if they are in a specific custom
Kanban column and swimlane. If you rename a column or swimlane, you'll need to
update the query filters to reflect the new name. For more ideas, see this blog post: New
fields bring Kanban goodness to queries, and more
７ Note
Queries are now scoped to the current project by default. Check the Query across
projects to find work items defined in other projects within the collection.
Filter for
User Stories in the Code/Doing column

And Board Column = Code
And Board Column Done = False
Items in the Expedite swimlane
Board Lane = Expedite
Items in any swimlane whose label contains "Test"
Board Lane Contains Test
Items that were ever in the "In Review" column
Board Column Was Ever In Review
） Important
Workflow and Kanban board fields

The following fields are useful to filter queries. Some of these fields get updated as a
work item progresses from one state to another. Or they're updated as you move a work
item in the Kanban board to a different column or swimlane. Several of these fields
don't appear on the work item form, but they're tracked for those work item types listed
in the following table.
For more information about field attributes, see Work item fields and attributes.
Field name
Description
Work item type
Activated By 1, 2, 3
The name of the team member who changed the status of a work item to an In Progress
category state.
Reference name= Microsoft.VSTS.Common.ActivatedBy

Data type=String (Identity)
Bug, Change Request, Epic, Feature, Issue, Product Backlog Item, Requirement, Review,
Risk, Shared Step, Task, Test Case, User Story
Activated Date 1, 3
The date and time when the work item was changed to an In Progress category state.
Reference name= Microsoft.VSTS.Common.ActivatedDate

Data type=DateTime
All
2
Assigned To
The name of the team member who currently owns the work item. For more
information, see Note 1 on synchronization and person-name fields.
Reference name= System.AssignedTo

All
Board Column
The current Kanban board column assignment of the work item, for example: Active,
Closed, Committed, Done, or other custom column assignment.
Reference name= System.BoardColumn

Data type=String
Requirement Category 4
Board Column Done
The current assignment of the work item to Doing (False) or Done (True) Kanban
column. Only assigned when split-columns is enabled for a Kanban board column.
Reference name= System.BoardColumnDone

Data type=Boolean
Board Lane
The current Kanban board swimlane assignment of the work item, for example: Default,
Expedite, Blocked, or other custom swimlane assignment. Reference
name= System.BoardLane
Data type=String
Closed By 1, 2
The name of the team member who set the state to closed, completed, or done.
Reference name= Microsoft.VSTS.Common.ClosedBy

All
Closed Date
The date and time when a work item was closed.
Reference name= Microsoft.VSTS.Common.ClosedDate

Data type=DateTime
All
Created By 1, 2
The name of the team member who created the work item.
Reference name=`System.CreatedBy
All
Created Date
The date and time when a work item was created.
Reference name= System.CreatedDate

Data type=DateTime
All
Reason
The reason why the work item is in the current state. Each transition from one workflow
state to another is associated with a corresponding reason.
Reference name= System.Reason

Data type=String
All (except Test Case and Shared Steps)
Resolved By 1, 2
The name of the team member who changed the status of a work item to a Resolved
category state.
Reference name= Microsoft.VSTS.Common.ResolvedBy , Data type=String (Identity)
All
Resolved Date
The date and time when the work item was changed to an In Resolved category state.
Reference name= Microsoft.VSTS.Common.ResolvedDate , Data type=DateTime
All
Resolved Reason
The reason why a work item was resolved. For example, the user story is code complete
or the bug is fixed. This field is read-only and only valid for Agile and CMMI work item
types.
Reference name= Microsoft.VSTS.Common.ResolvedReason

Data type=String
All (Agile, CMMI)
Reviewed By
The name of the team member who responded to a code review request and is
cataloged in the code review response.
Reference name= Microsoft.VSTS.Common.ReviewedBy

State
The current state of the work item. This field allows you to update the status of a work
item as it progresses from new or active to a done or closed state.
To modify the workflow states, see Customize the workflow for a process.
Reference name= System.State

Data type=String
All
State Changed Date
The date and time when the value of the State field changed.
Reference name= Microsoft.VSTS.Common.StateChangeDate
Data type=DateTime
All
７ Note
1. See Date and Identity fields.

2. By default, the server synchronizes system-defined person-name or Identity-
based fields with Active Directory or Azure Active Directory. These 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 AD or Azure AD or by adding accounts to existing or custom groups
defined from the collection setting Security page. See set up Active Directory
or Azure Active Directory.
3. See Activated By/Date and Resolved By/Date fields.
4. The Requirement Category applies to all work item types that appear on the
product backlog and Kanban board, and may include those added to the Bug
Category based on the team setting for Show bugs on boards and backlogs.
For more information on work item type categories, see Use categories to
group work item types.
７ Note
Even if you add a board-related field, such as Board Column or Board Lane, to a
work item form, you can't modify the field from the form.
People picker
The Assigned To field is supported by the people picker feature. For example, when you
choose the Assigned To field from within a work item form, the people picker is
activated. As shown in the following image, you simply start entering the name of the
user you want to select, and search until you find a match. Users that you've previously
selected appear in the list automatically. To select users that you haven't selected
previously, enter their entire name or search against the full directory.
@mention tool in Discussion showing people picker." />
(Azure AD) or Active Directory, people pickers provide support for searching all users
and groups added to the AD, not just those users and groups added to the project.
To limit the scope of identities available for selection to just those users added to the
project, you can do so using the Project-Scoped Users group. For more information, see
Manage your organization, Limit identity search and selection.
Date and identity fields

Several date and identity fields are set based on workflow states or transitions. Some
fields, such as Created By and Created Date, are set by the system when a work item is
added. Other fields, such as Closed Date and Closed By, are set through the workflow
definition of the work item type. Additionally, customized work item types may have
other rules defined that influence the date and identity field assignments.

Time and Locale.
Activated By/Date and Resolved By/Date fields
The system updates these fields—Activated By, Activated Date, Resolved By, and
Resolved Date—when a change occurs based on corresponding workflow category
states. When the workflow state changes to an In Progress state category, Activated By
and Activated Date are updated. When the workflow state changes to a Resolved state
category, Resolved By and Resolved Date are updated.
To learn more how workflow states map to state categories, see How workflow states
and state categories are used in Backlogs and Boards.
７ Note
The logic governing the fields described here applies to Azure DevOps Services,
Azure DevOps Server 2020.1 update, and later versions.
Because these fields reference the workflow state categories, custom workflow states
that you add are referenced when updating the fields. To learn more about
customization, see Customize the workflow for a process.
Additional notes:
The fields get updated anytime a work item moves from any category state other
than that being set. For example, if you update a work item from New to Fixed, the
Resolved By/Resolved Date fields are updated. However, if you update from Fixed
and Ready for Testing—which are in the same category state—the Resolved
By/Resolved Date fields aren't updated.
When you transition backwards, such as going from a Resolved to an Active state,
the system clears the values for Resolved By/Resolved Date fields. If you got from
Active to New, the system clears the values for Activated By/Activated Date fields.
Don't manually change the values for these fields. They are system fields that are
governed by system rules. Any value you attempt to set gets over written.
Related articles
How workflow states and state categories are used in Backlogs and Boards
Work item fields and attributes
Query permissions
REST API

Queries
Query by area or iteration path
Article • 02/24/2023
2018
The Area Path and Iteration Path are two fields that appear on the work tracking form
for all work item types. You define them for a project—area paths and iteration paths—
and then select the ones you want to associate with a team.
To better understand how to work with area and iteration paths, see About teams and
Agile tools.
７ Note
Microsoft Project.

When creating queries and specifying the Area Path and Iteration Path fields, you can
use the following operators:
Operator Use when you want to...
= Specify one specific area or iteration path
<> Filter out one, specific area or iteration path.
In Filter for a set of area or iteration paths.
Not In Exclude items that are assigned to a set of area or iteration paths.
Under Specify all paths under a select area or iteration path.
Not Under Exclude items assigned under a specific area or iteration path.
Along with these operators, you can use the following macros when you select the
Iteration Path. For examples, see Query by date or current iteration.
Macro Use when you want to...
@CurrentIteration Specify the current iteration associated with the selected team context.
@CurrentIteration Filter items based on assignment to a sliding window of sprints associated

+/- n with the selected team context.
@TeamAreas Filter items based on area path(s) assigned to a specific team.
７ Note
The @CurrentIteration +/- n and @TeamAreas macros are supported for Azure
DevOps Server 2019 and later versions. These macros are only supported from the
web portal. Queries that contain these macros won't work when opened in Visual
Studio/Team Explorer, Microsoft Excel, or Microsoft Project.
Area path queries

You can specify to filter for work items assigned to several area paths by using the In
operator as shown in the following example.
Node Name and keyword-based queries

Use the Node Name field to filter on work items assigned to area paths based on a
keyword using the Contains operator. The Node Name specifies the last node of an
Area Path, which corresponds to the last node in the tree hierarchy.
The following query yields the same result as the previous example.
In this example, the filter returns any work items assigned to an area path whose last
node contains the word "Azure".
Here's another example that uses the Node Name and the In operator.
Team area path queries

Use the @TeamAreas macro to quickly find items assigned to the area paths assigned to
a specific team. Specify the = operator. The Query Editor automatically prompts for you
to enter the name of the team. You can add it by entering the name of the team and
choosing the team value that appears in the search filter criteria.
Classification field reference
Field Description Reference name
name
Area Groups work items into product feature or team areas. The System.AreaPath
Path area must be a valid node in the project hierarchy.
Iteration Groups work items by named sprints or time periods. The System.IterationPath
Path iteration must be a valid node in the project hierarchy.
For each field, data path= TreePath , reportable type= Dimension , index attribute= True .
If you define a path name that is longer than 256 characters, you can't specify it in
Microsoft Project. To avoid this problem, define path names of no more than 10
characters, and don't nest nodes more than 14 levels deep.
You can't apply most field rules to system fields, such as System.AreaPath and
System.IterationPath fields. For more information, see Rules and rule evaluation.
The following fields don't appear on work item forms but are tracked for each work item
type. These fields provide a numeric value for each classification value that is defined for
a project. You can use these fields to filter queries and create reports.
Field Description Reference name Data

name type
Area ID The unique ID of the area to which this work item is System.AreaId Integer
assigned.
Iteration The unique ID of the iteration to which this work item System.IterationId Integer
ID is assigned.
Node The name of the last node of an area path. For System.NodeName String
Name example, if the area path is Project\A1\B2\C3, the node
name is C3.
The default reportable type is none. Area ID and Iteration ID are indexed, Node Name
isn't. To learn more about field attributes, see Work item fields and attributes.
Related articles
REST API

Queries
Query by date or current iteration in
Azure Boards
Article • 02/24/2023
2018
To list work items based on when they were created, closed, resolved, or changed—you
can specify a date or use a supported macro. Use the @Today macro and specify a plus
or minus number of days for relative dates. For queries that list work items based on
their assignment to a team's current sprint, use @CurrentIteration .
For example, you can find work items that were modified in the last three days with the
following query.
Also, you can use the CurrentIteration +/- _n_ macro to create queries based on a
sliding window of team iterations.

Query clauses that specify a DateTime field or the Iteration Path can use the operators
and macros listed in the following table.
Data type
DateTime

Macros: @StartOfDay , @StartOfWeek , @StartOfMonth , @StartOfYear , and @Today .
You can use +/- n with each of the supported macros.
TreePath
= , <> , Under, Not Under

Macros: @CurrentIteration 2 and @CurrentIteration +/- n 3 valid with the Iteration Path
field.
Notes:
1. The @StartOfDay , @StartOfWeek , @StartOfMonth , @StartOfYear macros are
supported for Azure DevOps Server 2019.1 and later versions, and only when run
from the web portal.
2. The @CurrentIteration +/- n macro is supported for Azure DevOps Server 2019
and later versions, and only when run from the web portal.
 Tip
The WasEver operator can be used with the Iteration Path field but only when
defined through the WIQL syntax. For an example, see Work Item Query Language
(WIQL) syntax reference.

Time and Locale.
Client restrictions on the use of the
@CurrentIteration macros
You can use the @CurrentIteration macro in a query from the following clients:
Web portal that connects to Azure Boards

Visual Studio 2019 or later versions connected to Azure Boards
Using the REST API.
You can use the @CurrentIteration +/- n macro in a query against Azure Boards, Azure
DevOps Server 2019, and later versions, and with a REST API that includes the team as a
parameter, for example, @CurrentIteration('[Project]/Team') .
An error occurs if you open a query that contains the @CurrentIteration macro in earlier
versions of Visual Studio, or from Excel or Project. Also, you can't use the macro when
copying or cloning test suites and test cases, defining alerts, or with REST APIs.
Date-based queries
You can filter for work items by the date on which they were changed or for a specific
time period. Limiting the scope of your query can help with performance by only
returning results that fit the date range that you include. If you're new to creating
queries, see Use the query editor to list and manage queries.
Not all fields are valid for all work item types. Jump to date fields for the set of fields you
can include in queries and which work item types they apply to.
 Tip
Remember to enter dates in the Date Pattern you set for your personal profile.
Filter for
Items created in the last 30 days
Items modified on a specific date
Items resolved today
Items closed within a specified time period
Items that haven't been closed (Closed Date is null)
Items whose status was updated within the last week

Items closed during the current sprint (the @CurrentIteration macro references the
sprint defined for the current team context)
 Tip
editor entry.
Create start of day, week, month, or year date-

based queries
The following examples show how to use the StartOf... macros to filter for work items
with various offsets. For more examples of using these macros, see WIQL syntax.
Filter for
Bugs closed in the last two weeks
Items modified in the last 10 days

Features scheduled to be completed in the next three months
Not all fields are valid for all work item types. Jump to date fields for the set of fields you
can include in queries and which work item types they apply to.
Create queries for your team's current iteration

If your team follows Scrum processes, you schedule work to be completed in sprints.
You can track the progress of requirements, bugs, and other work to be completed in
the current sprint using the @CurrentIteration macro.
Any item assigned to a sprint that corresponds to the current iteration path for the team
is found. For example, if a team is on Sprint 5, the query returns items assigned to Sprint
5. Later, when the team is working in Sprint 6, the same query returns items assigned to
Sprint 6.
７ Note
For the @CurrentIteration macro to work, the team must have selected an
Iteration Path whose date range encompasses the current date. For more
information, see Define iteration paths (also referred to as sprints) and configure
team iterations. Also, queries that contain this macro are only valid when run from
the web portal.
See also Client restrictions on the use of the @CurrentIteration macros later in
this article.
Azure Boards adds a team parameter when you select the @CurrentIteration or
@CurrentIteration +/- n macros. The team parameter is derived from your current team
context.
 Tip
If the @CurrentIteration macro isn't working, check that the expected iteration is
selected for your team and that dates have been set for it.
To change the team parameter the system automatically sets, you choose it by entering
the name of the team into the parameter field added below the @CurrentIteration
macro.
Create a sliding window of your team's

iterations query
Use the @CurrentIteration +/- n macro when you want to track the work a team has
planned for upcoming sprints and for understanding work that wasn't completed in
previous sprints.
７ Note
For the @CurrentIteration +/- n macro to work, the team must have selected
Iteration Paths that meet the +/- n criteria and date ranges encompass the current
date for the @CurrentIteration. For details about team selection of Iteration Paths,
see Define iteration (sprint) paths and configure team iterations.
See also Client restrictions on the use of the @CurrentIteration macros later in
this article.
Here we show how to list all User Stories and Bugs that are assigned to the sliding
window that spans the last two, the current, and the next two sprints selected for the
Cloud Admin and Tools team.
To use this macro, the specified team must have selected a set of sprints that span the
+/- n value entered for the macro.
List work items moved out of a sprint

You can list work items that were defined for a sprint but later moved out using a query
with a clause that contains the Was Ever operator for the Iteration Path. You can only
construct this query using the WIQL syntax. You can edit the WIQL syntax in the Query
Editor by installing the Wiql Editor Marketplace extension .
For example, the following syntax queries for work items that meet the following criteria:
1. Defined in the current project

2. Work item type equals User Story or Bug
3. Work items are under the Fabrikam Fiber Web team Area Path
4. Work items aren't in a Closed, Completed, Cut, or Resolved state
5. Not in the current iteration path for the Fabrikam Fiber Web team
6. But were assigned to the current iteration path for the Fabrikam Fiber Web team
7. Are now assigned to the Current iteration +1 for the Fabrikam Fiber Web team
8. And were changed within the last 30 days (the length of the sprint)
WIQL
SELECT
[System.Id],
[System.WorkItemType],
[System.AssignedTo],
[System.Title],
[System.State],
[System.Tags],
[System.IterationPath],
[System.AreaPath]
FROM workitems
WHERE
[System.TeamProject] = @project
AND [System.WorkItemType] IN ('User Story', 'Bug')
AND [System.AreaPath] UNDER 'FabrikamFiber\Web'
AND NOT [System.State] IN ('Completed', 'Closed', 'Cut', 'Resolved')
AND NOT [System.IterationPath] = @currentIteration('[FabrikamFiber]\Web
<id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>')
AND (
EVER (
[System.IterationPath] = @currentIteration('[FabrikamFiber]\Web
<id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>')
)
AND [System.IterationPath] = @currentIteration('[FabrikamFiber]\Web
<id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>') + 1
AND [System.ChangedDate] >= @today - 30
)
ORDER BY [System.Id]
The Query Editor view of the syntax appears as shown.
７ Note
The Query Editor displays a information icon next to the Was Ever operator,
indicating an issue with the clause. However, the query still runs and you can create
query charts. However, to modify the query, you need to use the WIQL editor .
List work items added to a sprint after the start
date
To list newly created work items added to a sprint after its start date, use a query similar
to the one shown in the following image. This query works by filtering for work items
assigned to the current sprint but were created after the start of the sprint date. In this
example, this is achieved with the clause created Date = @Today - 28.
For other options for querying changes to sprint scope, see About Sprints, Scrum and
project management, Sprint scope change.
Date and Iteration Path fields

You can use date fields to filter your queries. Some of these fields are populated with
information as a work item progresses from one state to another. Several of these fields
don't appear on the work item form, but are tracked for those work item types listed in
the following table.
Field name
Description
Work item types
Activated Date (Notes 1, and 2)
The date and time when the work item was created or when its status was changed from
closed, completed, or done to a new or active state.
Reference name=Microsoft.VSTS.Common.ActivatedDate, Data type=DateTime
Change Date
The date and time when a work item was modified.

Reference name=System.ChangedDate, Data type=DateTime
All
Closed Date (Note 2)

Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime
All
Created Date

Reference name=System.CreatedDate, Data type=DateTime
All
Due Date
The forecasted due date for an issue to be resolved.

Reference name=Microsoft.VSTS.Scheduling.DueDate, Data type=DateTime
Issue (Agile)
Finish Date (Note 3)
The date and time when the schedule indicates that the task is completed.
Reference name=Microsoft.VSTS.Scheduling.FinishDate, Data type=DateTime
Requirement, Task, Test Plan, User Story
Iteration Path
Groups work items by named sprints or time periods. The iteration must be a valid node
in the project hierarchy. You define iteration paths for a project and select iteration
paths for a team define iteration paths for a project and select iteration paths for a
team.
Reference name=System.IterationPath, Data type=TreePath
All
Resolved Date (Notes 1 and 2)
The date and time when the work item was moved into a Resolved state.
Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime
Start Date (Note 3)
The date and time when the schedule indicates that the task starts.
７ Note
Delivery Plans uses the Start Date and Target Date to show the span of Features,
Epics, and other portfolio backlog items.
Reference name=Microsoft.VSTS.Scheduling.StartDate, Data type=DateTime
Epic, Feature, Requirement, Task, Test Plan, User Story
State Change Date

Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime
All
Target Date
The date by which a feature, work item, or issue is to be completed or resolved.
７ Note
Delivery Plans uses the Start Date and Target Date to show the span of Features,
Epics, and other portfolio backlog items.
Reference name=Microsoft.VSTS.Scheduling.TargetDate, Data type=DateTime
Epic, Feature
Notes:
1. See also Query by assignment or workflow changes, Date, and Identity fields.
2. For these fields to be defined for a WIT, they must be included in the WORKFLOW
section of the WIT definition. For example, this syntax is included within the FIELDS
definition when transitioning to a Resolved state:
XML
<FIELD refname="Microsoft.VSTS.Common.ResolvedDate" />

<SERVERDEFAULT from="clock" />
</FIELD >
3. Start Date and Finish Date fields are calculated if you create a project plan in
Microsoft Project and then synchronize that plan with tasks that are stored in
Azure Boards. These fields might not appear on the work item form, but are
calculated for the backlog items and tasks that are linked to backlog items. You can
view their read-only values in results from a query or from Microsoft Excel.
） Important

supported for:
Services.
However, full support for Microsoft Excel integration is maintained and

supports bulk import and update of work items. Alternatives to using
Microsoft Project include the following:
Delivery plans
Related articles
To query for items based on text entered in the History field, see History and auditing.

Create managed queries with the query editor
Query operators & macros
Query permissions
Work item query language (WIQL) syntax
REST API

Queries
Add work item tags to categorize and
filter lists and boards
Article • 06/27/2023
2018
Tagging work items helps you quickly filter the product backlog or a work item query by
categories that you define. A tag corresponds to a one or two keyword phrase that you
define and that supports your needs to filter a backlog or query, or define a query.
Tags are a better choice to filter work items than using text strings as described in
Guidance to create high-performing queries.
You can add and modify tags from the web portal, from Team Explorer plug-in for Visual
Studio. Also, you can open a query in Excel to modify tags in bulk.
７ Note
Tags are a shared resource, they're associated with a project and not a team. If your
project contains multiple teams, all teams add to and work from the same set of
tags.
Prerequisites
items.
７ Note
Users with Stakeholder access for public projects are allowed to add new tags.
Add tags to a work item

Tags should be 400 characters or less and not contain separators such as a , (comma),
; (semicolon), or other formatting character.
 Tip
We recommend that you don't use the @ character in a tag. Tags that start with the
@ character can't be used in a work item query. The @ character signifies a macro
within a query and therefore the tag isn't recognized as a tag.
From the web portal, open a work item and add a tag. Choose Add tag and type your
keyword. Or, select from the list of previously assigned tags.
To add several tags at one time, type a comma between tags. Tags are case sensitive.
Tags that appear in the tag bar are already assigned to the work item. To unassign a tag,
choose the x on the tag, .
７ Note
By default, all Contributors and Stakeholders of public projects are granted

permissions to add new and existing tags. Stakeholders in private projects can add
tags that are already defined, but not add new tags. To grant or restrict permissions
to create new tags, you set the permission Create tag definition at the project-
level. To learn more, see Change project-level permissions.
You can bulk update work items to add or remove tags from the web portal. You bulk
modify tags in the same way as you bulk modify other fields using the web portal. Or,
you can use Excel to bulk add or remove tags.
７ Note
Bulk modify of tags from the Visual Studio or other supported clients isn't
supported.
Query for work items based on tags

To query work items based on tags, add a clause for each tag you want to use to
support your query.
 Tip
You can use the Contains or Does Not Contain operators. Tags that start with the @
character can't be used in a work item query as the query editor interprets the @
character as a macro. To learn more about queries, see Create managed queries.
For example, here we query for all work items that are tagged either Web or Service .
 Tip
editor entry.
７ Note
Show tags in your backlog or query results

Choose Column Options to add the Tags field to the product backlog or a work item
query. If the option doesn't appear, choose More commands to select it from the
menu of options.
All tags that have been added to the listed work items appear.
Filter lists using tags
From the web portal, you can filter backlogs, boards, and query results using tags.
Begin by choosing Filter .
Check the boxes of those tags that you want to filter on. Keep the OR selection to run a
logical OR for all the tags you selected. Or, choose the AND option to run a logical AND
Delete, remove, or manage tags
You can't delete a tag itself. However, if you delete a tag from all work items to which it's
currently assigned, the system deletes the tag. The system automatically deletes
unassigned tags after three days of disuse.
If you misspell a tag, don't assign the misspelled tag to any work item and the system
automatically deletes it within three days.
Another option is to install the Marketplace Tags Manager , which adds a Tags page
under Boards or Work to manage tags.
Color-code tags on boards

You can highlight tags on Kanban board cards by color-coding them. These colors only
appear on the Kanban board that you configure. They don't appear on backlogs or
Taskboards. For more information, see Customize cards, color-code tags.
７ Note
Work Items widget by tags that you add to a dashboard. This feature is in public
preview. To enable it, see Manage or enable features and turn on Enable group by
tags for work item chart widget on dashboard.
To group a Chart for Work Items widget by tags, complete the same steps provided in
Track progress with status and trend query-based charts, Add a chart widget to a
dashboard. Make sure that your flat-list query contains Tags in the query clause or as a
column option. Then, choose Tags for the Group by selection. To filter the chart to show
only some tags, choose the Selected tags radio button and then choose the tags you
want the chart to display.
Related articles
Use the query editor to list and manage queries
Show tags on cards
Bulk modify work items from the web portal
Bulk modify work items from Excel
Marketplace extension
Marketplace Tags Manager
Limits on the number of tags

While no hard limit exists, creating more than 100,000 tags for a project collection can
negatively impact performance. Also, the autocomplete dropdown menu for the tag
control displays a maximum of 200 tags. When more than 200 tags are defined, begin
entering to cause the tag control to display relevant tags.
You can't assign more than 100 tags to a work item or you'll receive the following
message:
TF401243: Failed to save work item because too many new tags were added to
the work item.
Save the work item with the tags (100 or less) that you've added, and then you can add
more tags.
Limit queries to fewer than 25 tags. More than that amount and the query likely times
out.
Query work item history and discussion
fields in Azure Boards
Article • 02/24/2023
2018
The history of a work item tells you who opened the item, what changed, and why. This
information helps you track how an item changes over time. When you enter
information in the history field, provide as much information as possible to help the next
work item owner understand what has happened and what they have to do.
７ Note
There is no 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.

Query clauses that specify the History field can use the Contains Words and Does Not
Contain Words operators. Search against an exact phrase or to use the wildcard
character, *. You can only use the wildcard character at the end of a partial word or
phrase.
The History field is automatically indexed for full-text search when full-text search is
available. See Full-Text and partial word searches
Query a work item's history

You can use either the web portal or Team Explorer to view the history of a work item or
find work items based on the contents of the History field. When you run a search on
the contents of the History field, it returns only work items that have changes recorded
in that field. That is, it doesn't register changes that were made to text in other fields.
Browser
List items based on the contents of the History
field
You use the query editor to add the History field to a query clause. Comments entered
into the Discussion area are queryable. Change history entries, such as which fields were
changed, aren't queryable. To quickly find items based on words entered into the
Discussion area, or Description or other rich-text fields, consider using work item search.
You can filter for work items by the date on which they were changed or for a specific
time period. If you limit the scope of your query, it can help with performance by only
returning those results that fit the date range that you want to include.
Filter for
Items whose History field contains the word "reproducible"
History Contains Words reproducible
Items whose History field doesn't contain the word "beta"
History Does Not Contain Words beta
Items that contain the phrase "stack traces" and were closed but reactivated
History Contains Words stack traces And State Was Ever Closed
And State <> Closed
Items closed within a specified time period
State = Done
And Closed Date > 7/1/2015

And Closed Date <= 7/21/2015
Items I've been associated with
History Contains Words MyName
Or Assigned To Was Ever _ @Me
Tips for using the query editor

Enter the complete word or phrase that is specified in the History field of those
work items that you want to find.
Enter the full text for the word that you want to search. The History field is indexed
for full-text search. If you enter only a partial word, the query won't return work
items that contain the full word. For example, if the History field contains the
phrase reproducible behavior and you search for repro, the work item won't be
found. However, if you search for the complete word reproducible, the work item
can be found. You can also search for the string with a wild card, such as repro* .
The query editor ignores common words or stop words as defined in Configure
and Manage Stopwords and Stoplists for Full-Text Search.
On the query editor toolbar, choose or icon and confirm that your query
returns expected results.
If you don't receive the results you expect, adjust the word or phrase that you
entered, and run the query again.
View the history of work items

An entry is made to the History field each time a work item is saved. To view the history
of changes, open an existing work item, and then choose the or History tab, or for
some work item types, choose the Details tab.
The history details shown depend on the platform, version, and client.
Browser
The state change history diagram appears first. To see the entire history of state
changes, choose Show all.
Choose an entry in the left pane to view the details of changes made.
Filter the history view

The History tab is designed to track all changes made to a work item to support full
traceability. The long revision history that results can make it difficult to understand
when changes happen to specific fields. To quickly find revisions made to a specific field
or by specific people, filter the history view.
７ Note
The Toggle filter feature requires you to enable the New Boards Hub preview
feature. To enable this feature, see Manage or enable features.
You enable the filter feature by choosing Toggle filter.
To review updates by specific people, select their names from the Updated by menu.
To review updates made to one or more fields, select the fields from the Fields menu.
Fields that support history, auditing, and

revision tracking
You can use the following fields to filter queries and create reports. Several of these
fields are populated with information as a work item progresses from one state to
another. Other fields update when the work item is modified. Some fields don't appear
on the work item form, but they're tracked for the WITs listed.
Field name
Description
Work item type
Changed By
The name of the team member who modified the work item most recently.
Reference name=System.ChangedBy, Data type=String
All
Change Date
The date and time when a work item was modified.
Reference name=System.ChangedDate, Data type=DateTime
All
Closed Date 1

Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime
All
Created Date
Reference name=System.CreatedDate, Data type=DateTime
All
History
The record of changes that were made to the work item after it was created. Every time
that the work item is updated, information is appended to the history, which specifies
the date of the change, who made the changes, and which fields were changed.
７ Note
History field queries return work items whose Discussion comments or Description
fields contain words that match the keywords entered. You can't use the History
field to query on changes made to other fields.
You can't add formatted text to the history field. Once you've saved the work item, you
can't alter the history.
The History field, along with the Description , Steps to Repro and Title fields are
automatically indexed for full-text search as described in Query fields, operators, and
macros.
Reference name=System.History, Data type=History
All
Resolved Date 1
The date and time when the work item was moved into a Resolved state.
Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime
Bug (Agile, CMMI)
Rev
A number that is assigned to the historical revision of a work item.
７ Note
A work item revision limit of 10,000 is in effect for updates made through the REST
API for Azure DevOps Services. This limit restricts updates from the REST API,
however, updates from the web portal are not affected.
Reference name=System.Rev, Data type=Integer
All
Revised Date
The date and time when a work item was revised or modified.
Reference name=System.RevisedDate, Data type=DateTime
Shared Parameter, Shared Step, Test Case
State Change Date

Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime
All
Test Suite Audit
Tracks other operations performed when modifying a test suite, for example: adding
tests to a test suite or changing configurations. This field can be viewed through the
History tab or through a separate query. There's a consolidated history view, including
changes performed to work items field and changes resulting from related artifacts such
as test points and configurations.
Reference name=Microsoft.VSTS.TCM.TestSuiteAudit, Data type=PlainText
Test Suite
Watermark
A system-managed field (not editable) that increments with changes made to a work
item.
Reference name=System.Watermark, Data type=Integer
All
７ Note
1. For these fields to be defined for a WIT, they must be included in the
WORKFLOW section of the WIT definition. For example, this syntax is included
within the FIELDS definition when transitioning to a Resolved state:
XML
<FIELD refname="Microsoft.VSTS.Common.ResolvedDate">
<SERVERDEFAULT from="clock" />
</FIELD>
Related articles
Query editor
REST API

Queries
Query by field value comparisons in
Article • 02/24/2023
2018
You can create queries based on how one field's value compares to another using the
comparison field operators. This query is useful to filter work items based on:
Is the person who created the work item the same as or different than the person
assigned to it? Or, who closed it
Which Tasks were closed before or after their Target Date.
Supported data types

You can use the comparison field operators— =[Field], <>[Field], >[Field], <[Field],
>=[Field], <=[Field] —with the following field data types. The data type you select for
the Field and the Value must match.
Boolean (supports =[Field], <>[Field]

Date/Time
Double, Integer
GUID
Identity
String (excluding Tags)
７ Note
Some combinations of data type and comparison field operator might not make
sense to use, such as Title >=[Field] or Assigned To <=[Field] .
Sample filters
Filter for

Work items closed by someone other than the person who created the work item
Created By <>[Field] Closed By

State = Closed
Tasks whose Original Estimate is less than Completed Work
Original Estimate <=[Field] Completed Work
Closed tasks completed before their target date
Target Date <=[Field] Closed Date

State = Closed
Fields that support field comparison

The following table provides an index to those fields that support field comparison
queries.
７ Note
Not all fields listed are supported for all projects or work item types. However, you
can customize a process or work item type by adding custom fields which you can
use for the purposes of queries and field comparisons. For more information, see
Add a custom field to a work item type (Inheritance process) or Add or modify a
field (Online XML process).
A
Acceptance Criteria (Scrum)
Accepted By
Accepted Date
Activated By
Activated Date
Activity
Actual Attendee 1-8 (CMMI)
Analysis (CMMI)
Application Launch Instructions
Application Start Information
Application Type
Iteration Id (System)
Assigned To
Associated Context
Associated Context Code
Associated Context Owner
Associated Context Type
Attached File Count
Automated Test Id (TCM)
Automated Test Name (TCM)
Automated Test Storage (TCM)
Automated Test Type (TCM)
AutomatedTestId (TCM)
AutomatedTestName (TCM)
Automation Status (TCM)
B
Backlog Priority (Scrum)
Blocked
Board Column
Board Column Done
Board Lane
Business Value
C
Called By (CMMI)
Called Date (CMMI)
Changed By (System)
Changed Date (System)
Closed By (System)
Closed Date (System)
Closed Status
Closed Status Code
Closing Comment
Comment Count
Comments (CMMI)
Committed (CMMI)
Completed Work
Contingency Plan (CMMI)
Corrective Action Actual Resolution (CMMI)
Corrective Action Plan (CMMI)
Created By (System)
Created Date (System)
D-E-F
Discipline (CMMI)
Due Date
Effort
Escalate (CMMI)
External Link Count
Finish Date
Found In Build (TCM)
Found In Environment (CMMI)
H
How Found (CMMI)
Hyperlink Count
I
ID (System)
Impact Assessment (CMMI)
Impact on Architecture (CMMI)
Impact on Development (CMMI)
Impact on Technical Publications (CMMI)
Impact on Test (CMMI)
Impact on User Experience (CMMI)
Integrated in Build (TCM)
Issue (TCM)
Iteration Id (System)
J-L-M-N
Justification (CMMI)
Link Comment (System)
Link Description (System)
Local Data Source (TCM)
Meeting Type (CMMI)
Minutes (CMMI)
Mitigation Plan (CMMI)
Mitigation Triggers (CMMI)
Node Name (System)
O-P-Q
Optional Attendee 1-8 (CMMI)
Original Estimate
Parameters (TCM)
Priority
Probability (CMMI)
Proposed Fix (CMMI)
Purpose (CMMI)
Query Text (TCM)
R
Rating
Reason (System)
Related Link Count (System)
Remaining Work
Remote Link Count (System)
Repro Steps
Required Attendee 1-8 (CMMI)
Requirement Type (CMMI)
Requires Review (CMMI)
Requires Test (CMMI)
Resolution (Scrum)
Resolved By
Resolved Date
Resolved Reason
Reviewed By
Reviewed Date
Rev (System)
Risk (Agile)
Root Cause (CMMI)
S
Severity
Size (CMMI)
Stack Rank
Start Date
State (System)
State Change Date
State Code
Steps (TCM)
Steps to Reproduce (TCM)
Story Points (Agile)
Subject Matter Expert (CMMI)
Symptom (CMMI)
System Info (TCM)
T
Target Date
Target Resolve Date (CMMI)
Task Type (CMMI)
Team Project (System)
Test Suite Audit (TCM)
Test Suite Type (TCM)
Test Suite Type ID (TCM)
Time Criticality
Title (System)
Triage (CMMI)
U-V-W
User Acceptance Test (CMMI)
Value Area
Watermark (System)
Work Item Type (System)
Related articles
Query index quick reference
Query by title, ID, or description
Query a numeric field
Query by picklist value
REST API

Queries
Query by numeric fields in Azure Boards
and Azure DevOps
Article • 02/24/2023
2018
How do I determine how much work each developer has completed on my team? Is
there a way to sum up the effort or story points for an iteration?
The most common numeric fields track effort for items in the Requirements category or
estimated, remaining, and completed work for items in the Task category. With queries
you can list the work items of interest, and then define a chart that shows either a count
of work items or a sum of a numeric field.

Query clauses that specify a numeric field can use the operators listed below.
= , <> , > , < , >= , <=

=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]
In, Not In
Was Ever
Tips for developing chart-based queries

You can only add charts for flat-list queries
Chart options reference either query filters or fields displayed through column
options
Save changes you make to your query prior to adding or modifying a chart.
To group one or more clauses, select them and then choose the group clauses
icon. To ungroup, select on the grouped clause.
For more details on creating queries and chart-based queries, see Use the query editor
to list and manage queries and Charts. If you want to add a custom field to track and
generate sums of other numeric values, see Add or modify a field.
Useful filters
Filter for
User stories or bugs
Work Item Type In User Story,Bug
Tasks or bugs
Work Item Type In Task,Bug
Items that are Active or Closed
State In Active,Closed
Items in the Requirements category
Work Item Type In Group Microsoft.RequirementCategory
Unestimated user stories
Story Points <> (leave Value field blank)
Work item count queries and charts

All queries show a count of items when you run the query. Here we define a flat-list
query that filters for bugs in any state.
Also, all charts contain a Values selection designed to display a count of work items
within the chart.
Count of bugs per developer
Create an active bugs query and modify the column options to show Assigned To and
State. Then, add a pivot chart that displays the assignments and state.
Count of bugs by state and area

Using the same flat-list query that filters for bugs shown in the previous section, you can
show a count based on area. Modify the column options to show the Area Path. Then,
add a pivot chart that displays the state and area path.
You can find work items that have an undefined field value by using the equals operator
(=) and leaving the Value for the field blank. For example, the following filters list all
work items of type User Stories whose Story Points field is blank.
To list work items based on a field that isn't blank, use the not operator (<>) and leave
the Value blank.
Effort or story point queries and charts

You can assign Story Points to user stories or bugs when you work in an Agile process.
Or, Effort to product backlog items and bugs when you work in a Scrum process. For
more information, see Basic, Agile, Scrum, or CMMI work item types and workflow
articles.
Sum of story points and their status

Create a query that filters for User Story as the work item type and modify the column
options to show Story Points and State.
Then, add a stacked bar chart that sums the Story Points.
For information on system-defined cumulative flow diagrams, see Cumulative flow.
Burn up chart of user stories for an iteration

Create a query that filters for User Story as the work item type and in the Active or
Closed state. Modify the column options to show Story Points.
Then, add a stacked area trend chart that sums the Story Points.
Remaining and completed work queries and

charts
Based on the process your project references, you can assign the following fields to
tasks or bugs.
Process Available fields
Agile Original Estimate, Remaining Work, Completed Work
Scrum Remaining Work

Process Available fields
CMMI Original Estimate, Remaining Work, Completed Work
Sum of remaining work per developer

If you follow Scrum practices and estimate Remaining Work for your tasks and bugs, you
can get a rollup of the amount of work remaining for each developer with the following
query and chart. By using the In operator and including both Task and Bug, you include
any bugs that are being tracked as tasks.
Add Remaining Work as a column option to the query and save. To view a sum of the
remaining work, add a pivot chart as shown.
For information on system-defined sprint burndown charts, see Sprint burndown.

Fields used to estimate and track work
The following table describes the activity-based and numeric fields that you can use to
track work. For information on date-related fields, such as Start Date, Finish Date, and
Target Date, see Query by date or current iteration.
Field name
Description
Work item type
Activity 1, 2
The type of activity that is required to complete a task.To learn more about how this
Deployment
Design
Development
Documentation
Requirements
Testing
The Activity field is assigned to Activity in the ProcessConfiguration file.3
Reference name=Microsoft.VSTS.Common.Activity, Data type=String
Task, Bug4 (Agile and Scrum)
Business Value
A subjective unit of measure that captures the relative business value of a product
backlog item or feature compared to other items of the same type. An item that is
assigned a higher number should be considered as having more business value than an
item that is assigned a lower number.
Reference name=Microsoft.VSTS.Common.BusinessValue, Data type=Integer
Epic, Feature
Completed Work
The amount of work that has been spent implementing a task. You can specify work in
hours or in days. There are no inherent time units associated with this field.
Reference name=Microsoft.VSTS.Scheduling.CompletedWork, Data type=Double
Task, Bug4
Discipline 1, 2
The type of activity or discipline that is assigned to a task. To learn more about how this
Analysis
Development
Test
User Education
User Experience
The Discipline field is assigned to Activity in the ProcessConfiguration file.3
Reference name=Microsoft.VSTS.Common.Discipline, Data type=String
Task, Bug 4 (CMMI)
Effort
A subjective unit of measure that captures the size of a bug or product backlog item. If
you assign more effort to an item, you indicate that more work is required to implement
it.
This field 3 is also used to calculate team velocity and forecasting. It's assigned to
Effort in the ProcessConfiguration file.
Reference name=Microsoft.VSTS.Scheduling.Effort, Data type=Double
Product Backlog Item, Bug 4 (Scrum)
Feature, Epic
Story Points
A subjective unit of measure that captures the size of a user story. If you assign more
points to a user story, you indicate that more work is required to implement it.
This field 3 is also used to calculate team velocity and forecasting. It's assigned to
Effort in the ProcessConfiguration file.
Reference name=Microsoft.VSTS. Scheduling.StoryPoints, Data type=Double

User Story, Bug 4 (Agile)
Size
A subjective unit of measure that captures the size of a requirement. The larger the size,
the more work is required to implement it.
This field3 is also used to calculate team velocity and forecasting. It's assigned to Effort
in the ProcessConfiguration file.
Reference name=Microsoft.VSTS. Scheduling.Size, Data type=Double
Requirement, Bug 4 (CMMI)
Original Estimate
The amount of work required to complete a task. You can specify work in hours or in
days. There are no inherent time units associated with this field.
Reference name=Microsoft.VSTS.Scheduling.OriginalEstimate, Data type=Double
Task, Bug 4 (Agile and CMMI)
Remaining Work
The amount of work that remains to finish a task. You can specify work in hours or in
days. There are no inherent time units associated with this field. This field 3 is also used
to calculate burn down. It is assigned to type="RemainingWork" in the
ProcessConfiguration file.
７ Note
For Azure Boards, the taskboard always shows "h" for hours in relationship to
Remaining Work. For TFS, you can modify the ProcessConfiguration file for the
Remaining Work type field to specify "d" for days, or other preferred label.
Reference name=Microsoft.VSTS.Scheduling.RemainingWork, Data type=Double
Task, Bug4
Requires Review
Indicates the task requires review. You can specify Yes or No (default).
Reference name=Microsoft.VSTS.CMMI.RequiresReview, Data type=String
Task (CMMI)
Requires Test
Indicates the task requires a test. You can specify Yes or No (default).
Reference name=Microsoft.VSTS.CMMI.RequiresTest, Data type=String
Task (CMMI)
Task Type1
Specifies the kind of task to implement. Allowed values are:

Corrective Action
Mitigation Action
Planned
Reference name=Microsoft.VSTS.CMMI.TaskType, Data type=String
Task, Bug4 (CMMI process)
７ Note
1. To change the menu selection: for cloud services or an Inherited process, see
Add and manage fields; and for On-premises XML process, see Add or
modify a field, customize a picklist.
2. The values displayed in the Capacity page for Activity (Agile or Scrum) or
Discipline (CMMI) reflect a union of all values defined for the field in all
projects within the project collection instance. Therefore, to restrict the values
that appear for Capacity on the sprint backlog pages, you must make the
values match in all the projects for the field assigned to type="Activity" .
3. To change the ProcessConfiguration field assignment (on-premises only), see
Process configuration XML element reference.
4. Each team can configure their Agile tools to determine if bugs are treated
similar to requirements or tasks. Since bugs can appear either with
requirements or tasks, fields used to estimate effort at the requirement-level
and the task-level are included in the work item form.
Related articles
For information on adding custom fields, see Customize your work tracking experience.
The main tools you use to plan and track work are described here:
Create your backlog

Sprint planning
Capacity planning
Taskboard
Kanban board
For more information on using work items and queries, see:
Query editor
Add work items
Rollup numeric values across work item types

Rollup provides summed values of select fields for all child work items of a parent.
Natively, Azure Boards provides rollup of Remaining Work for tasks on the taskboard.
For other rollup requirements, see the following articles:
Support rollup of work and other fields

Create rollup charts with Power BI
What items appear in the Requirement or Task

categories?
The default assignments of work item types to each category are listed below for each
process.
Process Requirement category Task category
Agile User Story Task
Scrum Product Backlog Item Task
CMMI Requirement Task

However, each team can determine if the Bug work item type appears in either the
Requirement or Task category. See Show bugs on backlogs and boards.
You can add custom work item types to a backlog. For more information, see Add or
modify a work item type, Add a custom WIT to a backlog or board.
REST API

Queries
Query by rank and picklist value in
Azure DevOps and Azure Boards
Article • 02/24/2023
2018
You use planning, ranking, and priority fields to specify which work the team should
complete first. By ranking and prioritizing work items, all team members gain an
understanding of the relative importance of the work that they must accomplish.
You rank and prioritize work items when you Create your backlog.

Query clauses that specify a string or integer field can use the operators listed below.
= , <> , > , < , >= , <=

=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]
In, Not In
Was Ever
Picklist query examples

Most of the planning fields described in the next section are either an integer or string
field. For example queries of numeric or rich-text fields, see Query by numeric fields and
Query by titles, IDs, and rich-text fields.
To use the In and Not In operators, enter the names or labels of items that correspond
to the selected field separated by a comma. For example, to filter for Work Item Types
that are either user stories or bugs, add the clause: Work Item Types In User Story,Bug .
Filter for
List blocked tasks (Scrum)

(Blocked field is type String)
Work Item Type In Task

And Blocked = Yes
Priority 1 bugs (Priority field is type Integer)
Work Item Type In Bug
And Priority = 1
Features and stories that address Architectural areas

(Value Area field is type String)
Work Item Type In Feature,User Story

And Value Area = _ Architectural
Fields used to plan and prioritize work

The following table describes the fields that you can use to plan and prioritize work.
Some fields are only valid for a specific process—Basic, Agile, Scrum, or Capability
Maturity Model Integration (CMMI).
Field name
Description
Work item type
Backlog Priority 1
A number assigned by a background process used to track the sequence of items on a

backlog or board. To learn more about how this field is used, see Use backlogs for
effective project management, Backlog priority or stack rank order.
Reference name=Microsoft.VSTS.Common.BacklogPriority, Data type=Double
Bug, Epic, Feature, Product backlog item, Task (Scrum)
Blocked
Indicates that no further work can be performed on the work item. If an issue has been
opened to track a blocking problem, a link should be made to the issue.
For the Scrum process, task work items: You can specify Yes or clear the field.
For the CMMI process work items: You can specify Yes or No.
Reference name=Microsoft.VSTS.CMMI.Blocked, Data type=String

Bug, Change Request, Requirement, Risk, Task (CMMI, Scrum)
Committed
Indicates if the requirement is committed in the project. You can specify Yes or No.
Reference name=Microsoft.VSTS.CMMI.Committed, Data type=String
Requirement (CMMI)
Escalate
Indicates if the issue is affecting the critical path of the project plan. You can specify Yes
or No.
Reference name=Microsoft.VSTS.CMMI.Escalate, Data type=String
Issue (CMMI)
Priority 1
A subjective rating of the bug, issue, task, or test case as it relates to the business. You
can specify the following values:
1: Highest priority, implement feature or fix as soon as possible. Product cannot
ship without successful resolution.
2: Medium priority. Product cannot ship without successful resolution, but it does
not need to be addressed immediately.
3: Low priority. Implementation or fix is optional based on resources, time, and risk.
If product ships without successful resolution, document the issue in release notes
as known issues.
4: Lowest priority. Tracks an issue that basically does not affect usage (such as a
small typo).
Reference name=Microsoft.VSTS.Common.Priority, Data type=Integer
Bug, Change Request, Epic, Feature, Impediment, Issue, Product backlog item,
Requirement, Risk, Shared Step, Task, Test Case, User Story
Risk
A subjective rating of the relative uncertainty around the successful completion of a user
story. Defined allowed values are:
1 - High
2 - Medium
3 - Low
Reference name=Microsoft.VSTS.Common.Risk, Data type=String
Epic, Feature, User Story (Agile)
Severity 1
A subjective rating of the impact of a bug on the project. You can specify the following
values:
1 - Critical
2 - High
3 - Medium
4 - Low
Reference name=Microsoft.VSTS.Common.Severity, Data type=String
Bug, Issue (CMMI), Risk (CMMI)
Stack Rank 2
A number, assigned by a background process, used to track the list order of items on a
backlog or board in the web portal. To learn more about how this field is used, see Use
backlogs for effective project management, Backlog priority or stack rank order.
Reference name=Microsoft.VSTS.Common.StackRank, Data type=Double
Bug, Epic, Feature, Requirement (CMMI), Risk (CMMI), Task, User Story (Agile)
Time Criticality
A subjective unit of measure that captures how the business value lessens over time.
Higher values indicate that the epic or feature is inherently more time critical than those
items with lower values.
Reference name=Microsoft.VSTS.Common.TimeCriticality, Data type=Double
Epic, Feature
Triage
Indicates the type of triage decision that is pending for the work item. You use this field
when the work item is in the Proposed state.
You can specify one of the following values:

Pending (default)
More Info
Info Received
Triaged
Reference name=Microsoft.VSTS.Common.Triage, Data type=String
CMMI only: Bug, Change Request, Epic, Feature, Issue, Requirement, Task
Value Area 1
The area of customer value addressed by the epic, feature, or backlog item. Values
include:
Architectural: technical services to implement business features that deliver
solution
Business: services that fulfill customers or stakeholder needs that directly deliver
Reference name=Microsoft.VSTS.Common.ValueArea, Data type=String
Bug, Epic, Feature, Product Backlog Item (Scrum) Requirement (CMMI), User Story (Agile)
Notes:
1. To change the menu selection, see Add and manage fields (Inherited process) or
Add or modify a field, customize a picklist (On-premises XML process).
2. The sequence of items on a product backlog page is determined according to
where you have added or dragged the items. As you drag items, a background
process updates either the Backlog Priority (Scrum) or Stack Rank (Agile, Basic,
CMMI) field. These fields determine the order in which backlog items appear on a
backlog page. They are assigned to type="Order" in the ProcessConfiguration file.
More about Backlog Priority or Stack Rank

fields
The Backlog Priority and Stack Rank fields don't appear on the work item forms. (To
learn why, see Where is the field on the work item form to order the backlog? .
To add the field to the form:
For an Inherited process, add the Stack Rank field to a work item type (for the
custom process that your project references).
For an On-premises XML process, add the field to the form, modify the WIT XML
definition to add the following control element:
XML
<Control FieldName="Microsoft.VSTS.Common.StackRank"
Type="FieldControl" Label="Stack Rank" LabelPosition="Left" />
or, for Scrum:
XML
<Control FieldName="Microsoft.VSTS.Common.BacklogPriority"
Type="FieldControl" Label="Stack Rank" LabelPosition="Left" />
Related articles
Query by a numeric field
Work item fields and attributes.
Query work items by link or attachment
count
Article • 02/24/2023
2018
You can link work items to track related work and dependencies and attach files to share
information with your team. You can then list work items based on one or more of the
following fields:
Attachment File Count

(Discussion) Comment Count
External Link count
Hyperlink Count
Link Comment
Related Link Count
Remote Link Count
For descriptions of each of these fields, see the table provided later in this article.

Query clauses that specify an integer field can use the operators listed below.
= , <> , > , < , >= , <= ,

=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field],
In, Not In,

Was Ever
Link or attachment count queries

You can filter for work items by the link type, link count, or attachment count.
::: moniker-end
List hierarchical items in a tree view

Add a query and select Tree of work items to begin your query. You should see
something similar to the following examples:
Browser
７ Note
and Test Cases. These items aren't linked together using parent-child link types.
However, you can create a Direct links query that lists test-related work items. Also,
you can, view the hierarchy through the Test>Test Plans page.
From there, you can add query clauses or change the filter options for linked work
items.
Filter for
View only child items of work item 645
Add to Filters for top-level work items:

ID = 645
Tasks or bugs
Add to Filters for linked work items:

Work Item Type In Task,Bug
Items assigned to my team (Web)
Add to both top and bottom filters:

Assigned to In Group [Fabrikam Fiber]\Web
Parent items of tasks assigned to me
Change Filter options to Match linked work items first

Add to Filters for linked work items:
Assigned To = @Me
List items based on linked dependents

The following example shows a dependent linked query that returns items with
dependencies on work managed by other teams and projects.
Browser
The following query finds work items in all projects that are linked to work items
under the Fabrikam area path and project using Predecessor and Successor link
types.
Why this works:
Checking the Query across projects checkbox enables all dependent linked
work items that match the filter criteria to be listed, no matter which project
they belong to.
Specifying the Area Path Under Fabrikam clause indicates to find only work
items that are linked to work items defined under the Fabrikam project.
Specifying Only return items that have matching links, and Return selected
link types causes the query to return only work items that are linked based on
the Predecessor and Successor link types.
List orphan user stories

If you typically organize your user stories under features, you can quickly find user
stories that are orphan by opening the product backlog, enable Parents On view option,
and scroll down to the section that lists Unparented Stories (Agile) or Unparented
Backlog items (Scrum).
Or, you can find unparented backlog items using a Work items and direct links query.
For example, the following query lists active user stories for the Azure DevOps team that
don't have a Parent link.
Link, attachment count, and comment fields
The following table describes fields associated with links and attachments. Most of these
fields don't appear within the work item form, but are tracked for all work item types.
Attachment File Count
The number of files attached to the work item and stored in the work item tracking
database.
Reference Name=System.AttachedFileCount, Data type=Integer
７ Note
For Azure Boards (cloud service), you can add up to 100 attachments to a work
item. Attempts to add more result in an error message upon saving the work item.
All
Comment Count
The number of comments added to the Discussion section of the work item.
Reference Name=System.CommentCount, Data type=Integer
All
External Link Count
The number of links from the work item to artifacts that are not work items. such as pull
requests, commits, changesets, or other link types.
Reference Name=System.ExternalLinkCount, Data type=Integer
All
Hyperlink Count
The number of hyperlinks that are defined for the work item.
Reference Name=System.HyperLinkCount, Data type=Integer
All
Link Comment
Contains comments from the team member who created the link. You can configure this
field to appear as a column in a list of links on a work item form. (Not supported in
query editor.)
Reference Name=System.Links.Comment, Data type=PlainText
All
Link Description
Contains the work item type, ID, and title of the work item that is the target of the link.
You can configure this field to appear as a column in a list of links on a work item form.
(Not supported in query editor.)
Reference Name=System.Links.Description, Data type=PlainText
All
Parent
When included as a column option in a backlog or query results list, the Title of the
parent work item is displayed. Internally, the system stores the ID of the work item
within an Integer field.
７ Note
You can add the Parent field as a column or specify it within a query clause by
specifying the parent work item ID.
Reference Name=System.Parent, Data type=Integer
All
Related Link Count
The number of links defined for a work item which use a work link type, such as Parent-
Child, Predecessor-Successor, and Related. For a full list, see Link type reference.
Reference Name=System.RelatedLinkCount, Data type=Integer
All
Remote Link Count
Available for Azure DevOps Services only. The number of links from a work item to work
items defined in another organization. Organizations must be managed by the same
Azure Active Directory. Supported link types include Consumes From, Produced For, and
Remote Related. For more information, see Add link to work items, Link to a remote
work item.
Reference Name=System.RemoteLinkCount, Data type=Integer
All
Related articles
Add a link to multiple work items
Track dependencies using Delivery Plans
Query editor
Add work items
Create a query based on build and test
integration fields
Article • 02/24/2023
2018
Work item fields that support build and test integration support the following actions:
Associate bugs with the builds where they were found or fixed
Query for bugs associated with a build
Mark test cases as either manual or automated, and store information to support
automated test cases
For test cases and shared steps, define the action and validation steps and the data
that are used to run tests.

Most build and test integration fields have a data type of String, PlainText, or HTML.
Query clauses that specify a text or rich-text field can use the operators and macros
listed in the following table.
Data type
Rich-text (HTML) and

Multi-line text strings (PlainText)
Contains Words , Does Not Contain Words , Is Empty , Is Not Empty .

The Is Empty and Is Not Empty operators are supported for Azure DevOps Server 2019
RC2 and later versions.
Single text (String)
[Field] , Contains , Does Not Contain , In , Not In , In Group , Not In Group , Was Ever
Macros: [Any] , valid with the Work Item Type field; and @Project , valid with the Team
Project field. The system automatically defaults to filtering based on the current project.
For more information, see Query across projects.
Useful filters
Filter for
Automated test cases
Work Item Type = Test Case And Automation Status = Automated
Query-based test suites
Work Item Type = Test Suite And Test Suite Type = Query Based
Requirement-based test suites
Work Item Type = Test Suite And Test Suite Type = Requirement Based
List bugs and the test cases that test them

Open a new query, set the query type to Work items and direct links. Filter for bugs in
the top level and add the filter for Test Cases in the linked work items filter.
７ Note
and Test Cases. These items aren't linked together using parent-child link types. You
can view the hierarchy through the Test>Test Plans page.
Build and test data fields

The following table describes the fields that are defined in one or more of the test WITs.
For information about data types and field attributes, see Work item fields and
attributes.
To customize a field or picklist, see Add or modify a field to support queries, reports,
and workflow.
Field name
Description
Work item type
Automation Status 1
The status of a test case. You can specify the following values:
Automated
Not Automated
Planned
To run automated tests, see Run automated tests from test plans.
Reference name=Microsoft.VSTS.TCM.AutomationStatus, Data type=String
Test Case
Found In 2
Product build number, also known as a revision, in which a bug was found.
Reference name=Microsoft.VSTS.Build.FoundIn, Data type=String
７ Note
You can also use the Found in build link type to link a work item to a build. This link
type is available from Azure DevOps and only works with the current build
processes (not XAML builds).
Bug
Integration Build 2
Product build number that incorporates the code or fixes a bug.

Reference name=Microsoft.VSTS.Build.IntegrationBuild, Data type=String
７ Note
You can also use the Integrated in build link type to link a work item to a build.
This link type is available from Azure DevOps and only works with the current build
processes (not XAML builds).
All
Issue
Indicates that the Shared Steps are associated with an expected result. Allowed values
are Yes and No. Reference name=Microsoft.VSTS.Common.Issue, Data type=String
Shared Steps
Parameters
Contains the parameters to use when running a manual test.

Microsoft.VSTS.TCM.Parameters, Data type=HTML
Shared Parameters, Shared Steps, Test Case
Steps
The action and validation steps that are required to run the test.
Microsoft.VSTS.TCM.Steps, Data type=HTML
Shared Steps, Test Case
System Info
Information about the software and system configuration that is relevant to the test.
Microsoft.VSTS.TCM.SystemInfo, Data type=HTML
Bug, Feedback Response

Repro Steps (or Steps to reproduce)
The steps that are required to reproduce unexpected behavior. Capture enough
information so that other team members can understand the full impact of the problem
and whether they've fixed the bug. This includes actions taken to find or reproduce the
bug and expected behavior. Reference name=Microsoft.VSTS.TCM.ReproSteps, Data
type=HTML
Bug
Test Suite Type 1
The test suite category. Allowed values are:

Query Based: Use to group together test cases that have a particular characteristic
- for example, all the tests that have Priority=1. The suite automatically includes
every test case that is returned by the query that you define.
Requirement Based: Use to group together test cases designed to track the test
status of backlog items. Each test case that you add to a requirement-based test
suite is automatically linked to the backlog item.
Static: Use to group together test cases with any characteristics or test suites.
For more information, see Create a test plan.
Reference name=Microsoft.VSTS.TCM.TestSuiteType, Data type=String
Test Suite
７ Note
1. Do not customize the pick list for these fields. The system accepts only those
values listed.
2. By adding a GLOBALLIST element to the FIELD definition, you can provide a
drop-down menu of builds that users can choose from. To learn how, see
Builds and global list auto-population later in this article.
Other fields
The following fields don't appear on work item forms, but these fields are tracked for
test cases or test suites. You can use some of these fields to filter queries and create
reports. (None of these fields are added to the data warehouse nor indexed.)
Field name
Description
Work item type
Automated Test Storage
The assembly that contains the test that automates the test case.
Reference name=Microsoft.VSTS.TCM.AutomatedTestStorage, Data type=String
Test Case
Automated Test Type
The type of test that automates the test case.
Reference name=Microsoft.VSTS.TCM.AutomatedTestType, Data type=String
Test Case
AutomatedTestId
The ID of the test that automates the test case.
Reference name=Microsoft.VSTS.TCM.AutomatedTestId, Data type=String
Test Case
AutomatedTestName
The name of the test that is used to automate the test case.
Reference name=Microsoft.VSTS.TCM.AutomatedTestName, Data type=String
Test Case
LocalDataSource
The local data source that supports the test.
Reference name=Microsoft.VSTS.TCM.LocalDataSource, Data type=HTML
Test Case
Query Text
Field used to capture the query defined for a Query-based suite type.
Reference name=Microsoft.VSTS.TCM.QueryText, Data type=PlainText
Test Suite
Test Suite Audit
Tracks other operations run when modifying a test suite, for example: adding tests to a
test suite or changing configurations. This field can be viewed through the History tab
or through a separate query. There's a combined history view, including changes done
to work items field and changes resulting from related artifacts such as test points and
configurations.
Reference name=Microsoft.VSTS.TCM.TestSuiteAudit, Data type=PlainText
Test Suite
Test Suite Type ID 1
A system assigned value that corresponds to the test suite category and only applicable
to test suites. Assigned values are:
1 (Static)
2 (Query-based)
3 (Requirement- based)
Reference name=Microsoft.VSTS.TCM.TestSuiteTypeId, Data type=Integer
Test Suite
７ Note
1. Do not customize the pick list for these fields. The system accepts only those
values listed.
Fields that integrate with Team Foundation Build

Team Foundation Build is the on-premise build system you can use with Azure DevOps
Server and TFS. You can configure your build process by using Team Foundation Build,
and Team Foundation Build can generate work items when a build fails. It can also add
build information to work items that were resolved in a particular build. For this to work,
Team Foundation Build requires that the following two fields be added to the work item
type definition: Found In and Integration Build.
Found In and Integrated in Build fields are defined for Bugs in the default processes.
These fields associate bugs with the builds where they were found or fixed.
You can use the following code snippet to add these fields to a WIT definition.
<FIELD name="Found In" refname="Microsoft.VSTS.Build.FoundIn" type="String"

reportable="dimension">
<HELPTEXT>Product build number (revision) in which this item was
found</HELPTEXT>
<SUGGESTEDVALUES>
<LISTITEM value="<None>" />
</SUGGESTEDVALUES>
</FIELD>
<FIELD name="Integration Build"
refname="Microsoft.VSTS.Build.IntegrationBuild" type="String"
reportable="dimension">
<HELPTEXT>Product build number this bug was fixed in</HELPTEXT>
<SUGGESTEDVALUES>
<LISTITEM value="<None>" />
</SUGGESTEDVALUES>
</FIELD>
When the Found In field is present in a WIT definition, Team Foundation Build creates a
work item when a build fails, and sets the Found In field to the build number of the
build that failed. If the Found In field is missing, Team Foundation Build doesn't create a
work item for the failed build, and everything else works as expected.
When the Integration Build field is present in the WIT definition, Team Foundation Build
identifies work items that were resolved with each build and then updates those work
items to set the build number in which they were resolved in the Integration Build field.
If the Integration Build field is missing, Team Foundation Build doesn't store the build
number in the work items, and everything else works as expected.
Builds and global list autopopulation

The first time you queue a build for a project using Team Foundation Build, TFS
automatically adds a global list labeled Build - ProjectName. Each time a build is run, a
LISTITEM is added to this global list with the name of the build.
Fields that Integrate with Test Plans

With Test Plans, you can automate the creation of a bug or other type of work item
when a test fails. For more information, see Add findings to existing bugs with
exploratory testing.
When a work item has been created in this manner, information about the system and
the steps to reproduce the bug are captured in the System Info and Repro Steps fields.
Fields that integrate with Team Foundation Version

Control
One of the features available in Team Foundation version control (TFVC) enables you to
associate or resolve work items when you check in code. You might have worked on a
particular work item when you make a code change and you can set that association
from within the source-control check-in window when you're finished working on the
code.
The ability of Team Foundation version control to resolve a work item requires that work
items contain a particular action. The source control system then queries work item
tracking to determine whether the work item supports that action, and if it does support
that action, it also queries for the source and destination states of the transition. If the
action is found, the source control system can transition the work item according to the
set transition when it checks in the code.
７ Note
When you use the Checkin action, you must set appropriate from and to states to
reflect the state transition that you want.
For more information about Actions, see Automate field assignments based on State,
Transition, or Reason.
Related articles
Drive Git development from a work item
Link and attachment queries
Query fields, operators, and macros in
Azure Boards
Article • 09/22/2023
2018
Here you'll find detailed descriptions of each field data type, query operators, and query
macros. Some data types, operators, and macros are only valid for the indicated Azure
DevOps version.
For a quick reference of query tasks and operators and macros supported for each data
type, see Query quick reference. See also Create a query/Best practices.
Query field data types and values

The value you specify for a field must conform to the data type for that field. The
following table lists the supported data types:
７ Note
For Azure Boards cloud service, the data type corresponds to that listed for the field
on the Process>Fields page. For on-premises deployments, the data type
corresponds to the type attribute assigned to a FIELD definition. For more
information, see Work item fields and field attributes.
Data type
Description
Boolean
Specifies a field that takes on a True/False value.
DateTime or Date/Time
A date field in which you can specify a variable, such as @Today or @Today-1, or a
value, such as 1/1/2023. Enter dates in the Date Pattern you set for your personal profile.
(See Set personal preferences for details.) For query examples, see Query by date or
@CurrentIteration.
For WIQL queries, you can also specify the date in the Coordinated Universal Time (UTC)
pattern. For more information, see Syntax for the Work Item Query Language (WIQL).
Double or Decimal
A real number, such as 0.2 or 3.5. For query examples, see Query by numeric fields.
GUID
A character string that represents a unique ID.
History
Custom formatted field used to track historical information. This data type is only used
to support the History field. This field is automatically indexed for full-text search when
full-text search is available. See Full-Text and partial word searches described later in this
article. For query examples, see History and auditing.
HTML
Text strings that support formatted descriptions, such as the Description or Repro Steps
fields. These fields are automatically indexed for full-text search when full-text search is
available. See Full-Text and partial word searches described later in this article. To query
rich-text fields, see Query by titles, IDs, and rich-text fields.
Identity
Short text string that identifies a user identity.
Integer
A 32-bit integer that is signed, such as 0, 1, 2, 34.
PlainText or Text field (multi-line)
Text strings that support long descriptions, such as the Application Start Information
field. These fields are automatically indexed for full-text search, when full-text search is
available. See Full-Text and partial word searches described later in this article. To query
plain-text fields, see Query by titles, IDs, and rich-text fields.
picklistDouble1
Custom field defined to contain a pick list of Decimal values.
picklistInteger1
Custom field defined to contain a pick list of Integer values.
picklistString1
Custom field defined to contain a pick list of short text string (255 characters or less)
values.
String or Text field (single line)
Short text string that can contain up to 255 Unicode characters. String text fields are
often used to support picklists or drop-down menus.
TreePath
A branching tree structure, such as an Area Path or Iteration path. Choose an item from
a list of valid values. Find work items that equal, not equal, under or not under a tree
structure, or use the In or Not In operators to specify several values. You define the tree
structure for a project—area paths and iteration paths—and then select the ones you
want to associate with a team.
For more information on constructing queries, see Query by area or iteration path or
Query by date or current iteration.
７ Note
1. The picklist... data types are only assigned to custom fields defined for an
inherited process. The Inherited process model is only supported for Azure
DevOps Services and Azure DevOps Server 2019.

Time and Locale.
Query operators
You can use query operators in the following table to specify how each value in a clause
must relate to the corresponding value in a work item. For information about the data
type that is assigned to work item fields, see Work item field reference.
To learn about adding clauses and use of the And/Or operators, see Define a query,
And/Or logical expression.
Query operator
Returns work items if the value in the work item matches the criteria listed
Applicable data types
Matches the value in the clause.
Number—which includes Double, GUID, Integer—and String, DateTime, and TreePath
<>
Doesn't match the value in the clause.
Number, String, DateTime, and TreePath
>
Is larger than the value in the clause.
Number, String, and DateTime
<
Is less than the value in the clause.
>=
Is larger than or equal to the value in the clause.
<=
Is less than or equal to the value in the clause.
=[Field]
Matches the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
<>[Field]
Doesn't match the value that is contained in the specified field.
>[Field]
Is larger than the value that is contained in the specified field.
<[Field]
Is less than the value that is contained in the specified field.
>=[Field]
Is larger than or equal to the value that is contained in the specified field.
<=[Field]
Is less than or equal to the value that is contained in the specified field.
Contains
Contains an exact or partial match of the text string within the field you selected for
filtering.
String
Does Not Contain
Doesn't contain an exact or partial match of the text string within the field you selected
for filtering.
String
Contains Words
Contains the exact text string or words within the field you selected for filtering. You can
also enter partial words or phrases that contain the wildcard character, *. Text string is
limited to 100 characters. For restrictions, see Full-text searches for server and collation
requirements.
Long-text fields that are indexed for full-text search, which correspond to all PlainText
and HTML fields, and the History and Title fields.
Does Not Contain Words

Doesn't contain the exact text string or words within the field you selected for filtering.
Text string is limited to 100 characters.
Use this operator in combination with a clause with the Contains Words operator to
include and exclude specific keywords.
Text fields that are indexed for full text search.
In
Matches any value in a delimited set. For example, you can find work items whose IDs
are 100, 101, and 102 if you specify those values for the ID field. Separate values with
the list separator that corresponds to the regional settings that are defined for your
client computer. For example, you might use a comma(,).
Number, String, DateTime, TreePath
Is Empty
Lists work items that contain an empty HTML field. You don't specify a value with this
operator. This operator is supported for Azure Boards (cloud service), Azure DevOps
Server 2019, and later versions.
HTML
Is Not Empty
Lists work items that contain some content in the HTML field. You don't specify a value
with this operator. This operator is supported for Azure Boards (cloud service), Azure
DevOps Server 2019, and later versions.
HTML
Not In
Doesn't match any value in a delimited set. You can exclude work items whose states are
not Resolved, Completed, or Closed from query results if you specify those values for
the State field. Separate values with the list separator that corresponds to the regional
settings that are defined for your client computer. For example, you might use a
comma(,).
The Not In operator is available from Azure Boards and TFS 2018.2 and later
versions.
Number, String, DateTime, TreePath
In Group
Matches a value that is a member of the group in the clause. Groups correspond to the
name of a team, security group, or work tracking category. For example, you can create
a query to find all work items that are assigned to members of the Contributors group
or to a team. Team groups are created when you create a team. The name of team
groups follows the pattern [Team Project Name]\Team Name.
For example queries, see Query by assignment or workflow changes.
String that matches the name of a team, security group, or category defined in the
system.
７ Note
You can use the In Group operator only with fields that use the String data type or
the Work Item Type field. You can also use groups defined in Azure Active
Directory (Azure AD) when your Azure Boards account is backed by Azure AD, or
Active Directory when your on-premises server instance is backed by Active
Directory.
For information about category groups, see Use categories to group work item types.
Not in Group
Doesn't match a value that is a member of the group in the clause.
String that matches the name of a user group in Team Foundation Server or a category
group defined for a project.
７ Note
You can use the Not In Group operator only with fields that use the String data
type or the Work Item Type field. You can also use groups defined in Azure AD
when your Azure Boards account is backed by Azure AD, or Active Directory when
your on-premises server instance is backed by Active Directory.
Not Under
Doesn't match the value in the clause and isn't contained under the node in the clause.
TreePath
Under
Matches the value in the clause or is contained under the node in the clause.
TreePath
Was Ever
Matches the value in the clause at any previous point.
String , DateTime
７ Note
Was Ever on date fields is not currently supported when using the Query Editor.
They are only supported when doing a direct WIQL.
 Tip
It's possible to contsruct a query using WIQL syntax that uses an operator, such as
Was Ever, for other data type fields than those listed. For example, you can use Was
Ever within a clause using the Iteration Path. For an example, see Query by date or
current iteration, List work items moved out of a sprint.
Query macros or variables

You can use the macros described in the following table to filter your queries based on
specific fields.
７ Note
Microsoft Project.
Macro
Description
[Any]
Use with the Work Item Type or State fields to search across all work item types or
across all states. For example, Work Item Type=[Any] won't place any filters based on the
work item type.
@CurrentIteration
Use with the Iteration Path field to automatically filter for work items assigned to the
current sprint based on the current team focus or context. For specific examples, see
Query by date or current iteration.
The @CurrentIteration macro only works when run from the web portal. You can't use
the macro when copying or cloning test suites and test cases, defining alerts, or with
REST APIs.
@CurrentIteration +/- n
Use with the Iteration Path field to filter the set of work items assigned to the current
sprint +/- n sprints based on the current team focus or context. For specific examples,
see Query by date or current iteration.
The @CurrentIteration +/- n macro is supported for Azure Boards, Azure DevOps Server
2019 and later versions, and only when run from the web portal.
@Follows
Use with the ID field and In operator to list all work items that you're following in the
project. To learn more about the Follow feature, see Follow a work item or pull request.
You can view this same list from the Work Items page, Following pivot view.
The @Follows macro is supported only when run from the web portal.
@Me
Use with an identity or user account field to automatically search for items associated
with your user or account name. For example, you can find work items that you opened
with the clause Created By=@Me . For more examples, see Query by assignment, workflow,
or Kanban board changes.
@MyRecentActivity 1
Use with the ID field and In operator to list work items that you have viewed or updated
in the project within the last 30 days. You can view this same list from the Work Items
page, My activity pivot view.
@Project
Use with the Team Project field to filter for work items in other projects. For example,
you can find all the work items in the currently selected project with the clause Team
Project=@Project . The system automatically defaults to filtering based on the current
project. For more information, see Define a query, Query across projects.
@RecentMentions 1
Use with the ID field and In operator to list work items where you have been mentioned
in the Discussion section. You can view this same list from the Work Items page,
Mentioned pivot view.
@RecentProjectActivity 1
Use with the ID field and In operator to list work items that have been recently updated.
The number of work items listed depends on the work tracking activity of the project.
For highly active projects, the macro lists work items that have been updated in the
project within the last 30 days or so. For less active projects, however, this list could
include work items older than 30 days. You can view similar lists from the Work Items
page, Recently created, Recently updated and Recently completed pivot views. The
number of work items returned is capped at 5000.
@StartOfDay 2
Use with a DateTime field to filter for work items that relate to the current date or with a
plus/minus offset. For example, you can find all items closed in the last week with the
clause Closed Date>=@StartOfDay-7 . For more examples, see Query by date or current
iteration.
@StartOfMonth 2
Use with a DateTime field to filter for work items that relate to the current month or with
a plus/minus offset. For example, you can find all items created in the last three months
with the clause Created Date>=@StartOfMonth-3 . For more examples, see Query by
date or current iteration.
@StartOfWeek 2
Use with a DateTime field to filter for work items that relate to the current week or with a
plus/minus offset. For example, you can find all items changed in the last two weeks
with the clause Changed Date>=@StartOfWeek-2 . For more examples, see Query by
date or current iteration.
@StartOfYear 2
Use with a DateTime field to filter for work items that relate to the current year or with a
plus/minus offset. For example, you can find all features that have a Target Date
scheduled within the current year with the clause Target Date>=@StartOfYear . For
more examples, see Query by date or current iteration.
@TeamAreas
Only use with the Area Path field to filter for work items whose area path corresponds
to one assigned to a specific team. Requires you use the = operator. For example, you
can find all items assigned to the area paths assigned to the Web team with the clause
Area Path=@TeamAreas [Fabrikam Fiber]\Web . For more examples, see Query by area or
iteration path.
The @TeamAreas macro is supported for Azure DevOps Server 2019 and later versions,
and only when run from the web portal.
@Today
Use with a DateTime field to filter for work items that relate to the current date or to an
earlier date. You can also modify the @Today macro by subtracting days. For example,
you can find all items created in the last week with the clause Created Date>=@Today-
7 . For more examples, see Query by date or current iteration.
７ Note
1. The @MyRecentActivity, @RecentMentions, and @RecentProjectActivity

macros are supported for TFS 2018.2 and later versions.
2. The @StartOfDay, @StartOfWeek, @StartOfMonth, and @StartOfYear
macros are supported for Azure DevOps Server 2019 Update 1 and later
versions.
Full-text and partial word searches

Specify Contains or Does Not Contain to search against exact or partial matches of a
word or phrase. These operators filter items based on the full-text search index created
for long-text fields. Specify Contains Words or Does Not Contain Words to search
against an exact phrase or to use the wildcard character, *. These operators use the full-
text search index. You can only use the wildcard character at the end of a partial word or
phrase.
For examples, see Example work item queries and Query for work items using the
History field.
７ Note
Not all deployments support full-text searches. For example, SQL Express and SQL
Azure, which support the cloud service, do not support full-text search. In these
instances, you only see the Contains and Does not Contain operators.
Related articles
Syntax for the Work Item Query Language (WIQL)
REST API

Queries
Work Item Query Language (WIQL)
syntax reference
Article • 03/06/2023
2018
You can use the WIQL syntax to define a query as a hyperlink or when using the Work
Item Query Language (REST API).
The WIQL syntax supports all functions available through the web portal Query Editor
plus a few more. You can specify the fields to return and specify logical grouping of
query clauses. In addition, you can use an ASOF clause to filter based on assignments
based on a previous date.
） Important
The WIQL syntax is used to execute the Query By Wiql REST API. Currently, there is
no way to call the API to return the detailed work item information from a WIQL
query directly. No matter which fields you include in the SELECT statement, the API
only returns the work item IDs. To get the full information, you need to perform two
steps: (1) get the ID of the work items from a WIQL, and (2) get the work items via
Get a list of work items by ID and for specific fields.
Prerequisites
A query returns only those work items for which you have the View work items or View
work items in this node permission. Typically, these permissions are granted to
members of the Readers and Contributors groups for each team project. For more
information, see Permissions and groups.
Query language overview

The work item query language has five parts shown in the following syntax snippet and
described in the following table. WIQL syntax isn't case-sensitive.
WIQL
SELECT
[System.Id],
[System.State],
[System.Title],
[System.Tags]
FROM workitems
WHERE
[System.TeamProject] = 'Design Agile'
AND [System.WorkItemType] = 'User Story'
AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2020'
 Tip
By installing the Wiql Editor Marketplace extension , you can construct your
queries using the Query Editor and then view the WIQL syntax. You can then copy
and modify the WIQL syntax and run the query using the Wiql Playground hub
added to Boards.
Clause
Example
SELECT
Identifies the fields to return for each work item returned by the query. You can specify
either the friendly name or reference name. Use square brackets ([]) if the name contains
blanks or periods.
FROM
Indicates whether you want the query to find work items or links between work items.
Use FROM WorkItems to return work items.
Use FROM workItemLinks to return links between work items. For more information,
see Queries for links between work items later in this article.
WHERE
Specifies the filter criteria for the query. For more information, see Filter conditions
(WHERE) later in this article.
ORDER BY
Specifies the sort order of the work items returned. You can specify Ascending (Asc) or
Descending (Desc) for one or more fields. For example:
ORDER BY [State] Asc, [Changed Date] Desc
ASOF
Specifies a historical query by indicating a date for when the filter is to be applied. For
example, this query returns all user stories that were defined as Active on February 11,
2020. Specify the date according to the guidance provided in Date and time pattern.
ASOF '02-11-2020'
７ Note
The WIQL length of queries made against Azure Boards must not exceed 32K
characters. The system won't allow you to create or run queries that exceed that
length.

Time and Locale.
Quote (single or double quotes are supported) DateTime literals used in comparisons.
They must be in the .NET DateTime format of the local client computer running the
query. Unless a time zone is specified, DateTime literals are in the time zone of the local
computer.
WIQL
WHERE
AND [System.ChangedDate] >= '01-18-2019 GMT'
AND ([Closed Date] < '01-09-2022 GMT'
OR [Resolved Date] >= '01-18-2019 14:30:01')
When the time is omitted in a DateTime literal and the dayPrecision parameter equals
false, the time is assumed to be zero (midnight). The default setting for the dayPrecision
parameter is false.
Or, you can specify ISO 8601 format which is valid no matter the locale. ISO 8601
represents date and time by starting with the year, followed by the month, the day, the
hour, the minutes, seconds and milliseconds. For example, 2021-12-10 15:00:00.000,
represents the 10th of December 2021 at 3 p.m. in local time. An example of using ISO
8601 format is as follows.
WIQL
WHERE
AND [System.ChangedDate] >= '2019-01-18T00:00:00.0000000'
AND ([Closed Date] < '2022-01-09T00:00:00.0000000'
OR [Resolved Date] >= '2019-01-18T00:00:00.0000000')
Custom fields
You can add a custom field to a query clause. With WIQL, you must specify the reference
name for the custom field. For projects that use an Inherited process model, custom
fields are typically labeled with Custom. prepended to their name, and spaces removed.
For example:
Friendly name Reference name
Approver Custom.Approver
Request Type Custom.RequestType
Scope Estimate Custom.CustomEstimate
For projects that use the On-premises XML process model, the reference name is as
defined by the XML work item type definitions.
For more information, see Work item fields and attributes.
Specify filter clauses ( WHERE )

The WHERE clause specifies the filter criteria. The query returns only work items that
satisfy the specified criteria. For example, the following example WHERE clause returns
user stories that are active and that are assigned to you.
WIQL
WHERE [Work Item Type] = 'User Story'

AND [State] = 'Active'
AND [Assigned to] = @Me
You can control the order in which logical operators are evaluated by enclosing them
within parentheses to group the filter criteria. For example, to return work items that are
either assigned to you or that you closed, change the query filter to match the following
example.
WIQL
WHERE
AND (
[System.WorkItemType] = 'Product Backlog Item'
AND (
[System.AssignedTo] = @me
OR [Microsoft.VSTS.Common.ClosedBy] = @me
)
)
Filter conditions
Each filter condition is composed of three parts, each of which must conform to the
following rules:
Field: You can specify either the reference name or friendly name. The following
examples are valid WIQL syntax:
Reference name: SELECT [System.AssignedTo] ...
Friendly name with spaces: SELECT [Assigned To] ...
Names without spaces don't require square brackets: SELECT ID, Title ...
Operator: Valid values are specified in the Operators section later in this article.
Field value: You can specify one of the following three values depending on the
field specified.
A literal value must match the data type of the field value.
A *variable or macro that indicates a certain value. For example, @Me indicates
the person who is running the query. For more information, see Macros and
variables later in this article.
The name of another field. For example, you can use [Assigned to] = [Changed
by] to find work items that are assigned to the person who changed the work
item most recently.
For a description and reference names of all system-defined fields, see Work item field
index.
Operators
Queries use logical expressions to qualify result sets. These logical expressions are
formed by one or more conjoined operations.
Some simple query operations are listed below.
WIQL
WHERE
AND [System.WorkItemType] <> ''
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'
The table below summarizes all the supported operators for different field types. For
more information on each field type, see Work item fields and attributes.
The =, <>, >, <, >=, and <= operators work as expected. For instance, System.ID >
100 queries for all work items with an ID greater than 100. System.ChangedDate > '01-
01-19 12:00:00' queries for all work items changed after noon of January 1, 2019.
Beyond these basic operators, there are some behaviors and operators specific to
certain field types.
７ Note
The operators available to you depend on your platform and version. For more
information, see Query quick reference.
Field type
Supported operators
Boolean
= , <> , =[Field] , <>[Field]
DateTime
Double, GUID, Integer
Identity
[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
PlainText
Contains Words, Not Contains Words, Is Empty, Is Not Empty
String
[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
TreePath
=, <>, In, Not In, Under, Not Under
Logical groupings
You can use the terms AND and OR in the typical Boolean sense to evaluate two clauses.
You can use the terms AND EVER and OR EVER when specifying a WAS EVER operator. You
can group logical expressions and further conjoin them, as needed. Examples are shown
below.
WIQL
WHERE
AND (
[System.WorkItemType] <> ''
AND [System.State] IN ('Active', 'Approved', 'Committed', 'In
Progress')
AND (
[System.CreatedBy] = ''
OR [System.AssignedTo] = 'Jamal Hartnett
<fabrikamfiber4@hotmail.com>'
)
)
You can negate the contains, under, and in operators by using not . You can't negate
the ever operator. The example below queries for all work items that aren't assigned
under the subtree of Fabrikam Fiber\Account Management .
WIQL
WHERE
AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'
Example query, Was Ever Assigned To

The following Query Editor example finds all work items that were ever assigned to
Jamal Hartnett.
And, here is the corresponding WIQL syntax.
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
[System.IterationPath]
FROM workitems
WHERE
AND EVER [System.AssignedTo] = 'Jamal Hartnett
Macros or variables
The following table lists the macros or variables you can use within a WIQL query.
Macro Usage
@Me Use this variable to automatically search for the current user's alias in a field
that contains user aliases. For example, you can find work items that you
opened if you set the Field column to Activated By, the Operator column to
=, and the Value column to @Me.
Macro Usage
@CurrentIteration Use this variable to automatically filter for work items assigned to the
current sprint for the selected team based on the selected team context.
@Project Use this variable to search for work items in the current project. For example,
you can find all the work items in the current project if you set the Field
column to Team Project, the Operator column to =, and the Value column
to @Project.
@StartOfDay Use these macros to filter DateTime fields based on the start of the current
@StartOfWeek day, week, month, year, or an offset to one of these values. For example, you
@StartOfMonth can find all items created in the last 3 months if you set the Field column to
@StartOfYear Created Date, the Operator column to >=, and the Value column to
@StartOfMonth - 3.
@Today Use this variable to search for work items that relate to the current date or to
an earlier date. You can also modify the @Today variable by subtracting
days. For example, you can find all items activated in the last week if you set
the Field column to Activated Date, the Operator column to >=, and the
Value column to @Today - 7.
[Any] Use this variable to search for work items that relate to any value that is
defined for a particular field.
@me macro
The @me macro replaces the Windows Integrated account name of the user who runs the
query. The example below shows how to use the macro and the equivalent static
statement. The macro is intended for use with identity fields such as Assigned To .
WIQL
WHERE
[System.AssignedTo] = @Me
@today macro
You can use the @today macro with any DateTime field. This macro replaces midnight of
the current date on the local computer that runs the query. You can also specify
@today+x or @today-y using integer offsets for x days after @today and y days before
@today , respectively. A query that uses the @today macro can return different result sets
depending on the time zone in which it's run.
The examples below assumes that today is 1/3/19.

WIQL
WHERE
[System.CreatedDate] = @today
Is the equivalent of:
WIQL
WHERE
[System.CreatedDate] = '01-03-2019'
And
WIQL
WHERE
[System.CreatedDate] > @today-2
WIQL
WHERE
[System.CreatedDate] > '01-01-2019'
@StartOfDay, @StartOfWeek, @StartOfMonth,

@StartOfYear macros
You can use the @StartOf... macros with any DateTime field. This macro replaces
midnight of the current day, start of week, start of month, or start of year on the local
computer that runs the query.
These macros accept a modifier string that has a format of (+/-)nn(y|M|w|d|h|m) .

Similar to the @Today macro, you can specify plus or minus integer offsets. If the time
unit qualifier is omitted, it defaults to the natural period of the function. For example,
@StartOfWeek("+1") is the same as @StartOfWeek("+1w") . If the plus/minus (+/-) sign is
omitted, plus is assumed.
This syntax allows you to nest modifiers and offset your query twice. For example, the
clause Closed Date >= @StartOfYear - 1 , filters work items that have been closed since
last year. By modifying it to Closed Date >= @StartOfYear('+3M') - 1 , it excludes work
items closed within the first three months of the last year. The WIQL syntax is as shown
in the following example.
WIQL
WHERE
[Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1
The following examples assume that today is 4/5/19.
WIQL
WHERE
[Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3
WIQL
WHERE
[Microsoft.VSTS.Common.CreatedDate] >= '01-01-2019'
And
WIQL
WHERE
[Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear
WIQL
WHERE
[Microsoft.VSTS.Scheduling.TargetDate] > '01-01-2019'
Custom macros
WIQL also supports arbitrary custom macros. Any string prefixed by an @ is treated as a
custom macro and gets substituted. The replacement value for the custom macro is
retrieved from the context parameter of the query method in the object model. The
following method is the API used for macros:
C#
public WorkItemCollection Query(string wiql, IDictionary context)
The context parameter contains key-value pairs for macros. For example, if the context
contains a key-value pair of (project, MyProject), then @project gets replaced by
MyProject in the WIQL. This replacement is how the work item query builder handles
the @project macro in Visual Studio.
Specify historical queries ( ASOF )

You can use an ASOF clause in a query to filter for work items that satisfy the specified
filter conditions as they were defined on a specific date and time.
７ Note
You can’t create ASOF queries in the query builder in Visual Studio. If you create a
query file (.wiq) that includes an ASOF clause, and then load that in Visual Studio,
the ASOF clause is ignored.
Suppose a work item was classified under an Iteration Path of Fabrikam Fiber\Release
1 and assigned to 'Jamal Hartnett' prior to 5/05/2022. However, the work item was
recently assigned to 'Raisa Pokrovskaya' and moved to a new iteration path of Release 2.
The following example query returns work items assigned to Jamal Hartnett because the
query is based on the state of work items as of a past date and time.
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
FROM workitems
WHERE
AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>')
ASOF '01-05-2022 00:00:00.0000000'
７ Note
If no time is specified, WIQL uses midnight. If no time zone is specified, WIQL uses
the time zone of the local client computer.
Set the sort order ( ORDER BY )

You can use the ORDER BY clause to sort the results of a query by one or more fields in
ascending or descending order.
７ Note
The sorting preferences of the SQL server on the data tier determine the default
sort order. However, you can use the asc or desc parameters to choose an explicit
sort order.
The following example sorts work items first by Priority in ascending order (default), and
then by Created Date in descending order ( DESC ).
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
FROM workitems
WHERE
AND [System.State] = 'Active'
ORDER BY [Microsoft.VSTS.Common.Priority],
[System.CreatedDate] DESC
Query for links between work items

To return links between work items, you specify FROM WorkItemLinks . Filter conditions in
the WHERE clause may apply to the links or to any work item that is the source or the
target of a link. For example, the following query returns the links between Product
Backlog Items and their active child items.
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
FROM workitemLinks
WHERE
(
[Source].[System.TeamProject] = @project
AND [Source].[System.WorkItemType] = 'Product Backlog Item'
)
AND (
[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
)
AND (
[Target].[System.TeamProject] = @project
AND [Target].[System.WorkItemType] <> ''
AND [Target].[System.State] <> 'Closed'
)
ORDER BY [Microsoft.VSTS.Common.Priority],
[System.CreatedDate] DESC
MODE (Recursive)
The following table summarizes the differences between work item queries and queries
for links between work items.
Clause
Work items
Links between work items
FROM
FROM WorkItems
FROM WorkItemLinks
WHERE
[FieldName] = Value
Specify one or more of the following:

[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'
MODE
not applicable
Specify one of the following:

MODE (MustContain) : (Default) Returns only WorkItemLinkInfo records where the
source, target, and link criteria are all satisfied.
MODE (MayContain) : Returns WorkItemLinkInfo records for all work items that
satisfy the source and link criteria, even if no linked work item satisfies the target
criteria.
MODE (DoesNotContain) : Returns WorkItemLinkInfo records for all work items that
satisfy the source, only if no linked work item satisfies the link and target criteria.
MODE (Recursive) : Use for Tree queries( [System.Links.LinkType] =
'System.LinkTypes.Hierarchy-Forward' ). Link type must be Tree topology and

forward direction. Returns WorkItemLinkInfo records for all work items that satisfy
the source, recursively for target. ORDER BY and ASOF aren't compatible with tree
queries.
RETURNS
WorkItemQueryResult
WorkItemLink
You can specify one of the following system link type names.
System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward (CMMI process)
For more information, see Link type reference.
Tree type query example

The following query returns all work item types define in the current project. The query
as shown in the Query Editor appears as shown in the following image.
The equivalent WIQL syntax is shown below.
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
FROM workitemLinks
WHERE
(
AND [Source].[System.WorkItemType] <> ''
AND [Source].[System.State] <> ''
)
AND (
[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
)
AND (
)
MODE (Recursive)
Direct-link query example

The following query returns all work item types define in the current project. The query
as shown in the Query Editor appears as shown in the following image.
The equivalent WIQL syntax is as shown.
WIQL
SELECT
[System.Id],
[System.WorkItemType],
[System.Title],
[System.State]
FROM workitemLinks
WHERE
(
AND [Source].[System.WorkItemType] <> ''
AND [Source].[System.State] <> ''
)
AND (
[System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
)
AND (
AND [Target].[System.ChangedDate] >= @today - 60
)
MODE (MustContain)
More query examples

The following typical WIQL query example uses reference names for the fields. The
query selects work items (no work item type specified) with a Priority=1. The query
returns the ID and Title of the return set as columns. The results are sorted by ID in
ascending order.
WIQL
SELECT
[System.Id],
[System.Title],
[System.State],
FROM workitems
WHERE
AND [Microsoft.VSTS.Common.Priority] <> ''
Date-time pattern
You specify the date-time pattern according to one of two patterns:
The Date Pattern and Time Pattern format comes from your user preferences, Time
and Locale
The pattern specified by UTC, which follows this pattern (with Z appended to the
date-time).
AND [System.ChangedDate] >= '1/1/2019 00:00:00Z'
Example clauses
The following example statements show specific qualifying clauses.
Clause
Example
AND
SELECT [System.Id], [System.Title]

FROM WorkItems
WHERE [System.TeamProject] = @project
OR

FROM WorkItems
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )
NOT

FROM WorkItems
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya
EVER

FROM WorkItems
UNDER

FROM WorkItems
AND [System.AreaPath] UNDER 'Agile1\Area 0'
ORDER BY

FROM WorkItems
ORDER BY [System.Id] [asc | desc]
ASOF (Time filter)
SELECT [System.Title]
FROM workitems
WHERE [System.IterationPath] = 'MyProject\Beta'
ASOF '3/16/19 12:30'
String and PlainText

Quote string literals (single or double quotes are supported) in a comparison with a
string or plain text field. String literals support all Unicode characters.
WIQL
WHERE [Custom.Blocking] = 'Not Blocking'

WHERE [Custom.Blocking] <> 'Blocked'
You can use the contains operator to search for a substring anywhere in the field value.
WIQL
WHERE [System.Description] contains 'WIQL'
Area and Iteration (TreePath)

You can use the UNDER operator for the Area and Iteration Path fields. The UNDER
operator evaluates whether a value is within the subtree of a specific classification node.
For instance, the expression below would evaluate to true if the Area Path were
'MyProject\Server\Administration', 'MyProject\Server\Administration\Feature 1',
'MyProject\Server\Administration\Feature 2\SubFeature 5', or any other node within the
subtree.
WIQL
WHERE [System.AreaPath] UNDER 'MyProject\Server\Administration'
Modifiers and special operators

You can use some modifiers and special operators in a query expression.
Use the IN operator to evaluate whether a field value is equal to any of a set of values.
This operator is supported for the String, Integer, Double, and DateTime field types. See
the following example along with its semantic equivalent.
WIQL
WHERE
AND [System.CreatedBy] IN ('Jamal Hartnett
<fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya
<fabrikamfiber5@hotmail.com>', 'Christie Church
<fabrikamfiber1@hotmail.com>')
or
WHERE
AND (
[System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.CreatedBy] = 'Raisa Pokrovskaya
OR [System.CreatedBy] = 'Christie Church
)
The EVER operator is used to evaluate whether a field value equals or has ever equaled a
particular value throughout all past revisions of work items. The String, Integer, Double,
and DateTime field types support this operator. There are alternate syntaxes for the
EVER operator. For example, the snippets below query whether all work items were ever
assigned to Jamal, Raise, or Christie.
WIQL
WHERE
AND (
EVER [System.AssignedTo] = 'Jamal Hartnett
OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya
OR EVER [System.AssignedTo] = 'Christie Church
)
Related articles
Query fields, operators, values, and variables
Cross-service and enhanced query operations
Define a query
Plan for Agile at scale
Article • 06/27/2023
2018
As your organization grows, you want your tools to scale to support your growing
business needs. Azure Boards tools scale primarily by supporting the addition of teams.
Each team provides configurable tools that allow teams to focus on their set of work.
For guidance on adding teams, see About teams and Agile tools.
Video: Agile at Scale

https://www.microsoft.com/en-us/videoplayer/embed/RE3wM7v?postJsllMsg=true
Enterprise project managers often have a portfolio of projects that they manage. These
projects are typically developed by several teams. By creating a hierarchy of teams,
portfolio managers can gain insight into the tools being developed by their teams.
For more information, see Manage portfolios.
Delivery plans
Delivery plans provide visibility into features under development by several teams across
several sprints. With Delivery Plans, portfolio managers can review the schedule of
stories or features their teams plan to deliver. Delivery Plans show the scheduled work
items by sprint (iteration path) of selected teams against a calendar view.
For more information, see Review delivery plans.
Team dashboards
Each team can construct several dashboards to track and monitor their progress. Also,
portfolio managers can create dashboards to monitor progress across several teams.
For more information, see Add and manage dashboards.
Related articles
Agile culture and scale
Agile culture
Scale Agile to large teams
Creating productive teams
Use Azure Boards to manage your
product and portfolio backlogs
Article • 09/28/2023
2018
Portfolio backlogs provide product owners insight into the work done by several agile
feature teams. Product owners can define the high-level goals as Epics or Features.
Feature teams can break down these work items into the user stories they'll prioritize
and develop.
＂ How to support a management view of multiple team progress

＂ How feature teams can focus on their team backlog progress
＂ How to assign work from a common backlog
＂ How to set up a hierarchical set of teams and backlogs
７ Note

By setting up a team structure like the one shown, you provide each feature team with
their distinct backlog to plan, prioritize, and track their work. And, portfolio or product
owners can create their vision, roadmap, and goals for each release, monitor progress
across their portfolio of projects, and manage risks and dependencies.
Set up a hierarchical team and backlog structure when you want to support the
following elements:
Autonomous feature teams that can organize and manage their backlog of work
Portfolio management views for planning epics and features and monitoring
progress of subordinate feature teams
Assign backlog items to feature teams from a common backlog
７ Note
this article. These differences result from updates made to Azure DevOps Services.
However, the basic functionality available to you remains the same unless explicitly
mentioned.
Management view of team progress

In this example, we show the Epics portfolio backlog for the Management team. Drilling
down, you can see all the backlog items and features, even though they belong to one
of three different teams: Customer Service, Phone, and Web.
） Important
You have the flexibility to establish child links with work items from different
projects. However, if the processes differ between projects, the hierarchy won't be
visible on the backlog for those child items residing in the separate projects.
Nonetheless, you can view all of the associated child items directly on the work
item form.
Feature team backlog ownership and view of

progress
Each feature team has its own team home page or dashboards, product and portfolio
backlogs, Kanban boards, and Taskboards. These pages only show work relevant to each
team. The relevance is based on assignments made to the work item area and iteration
paths. For more information, see About teams and Agile tools.
 Tip
Add Node Name to the column options to show the team assigned to the work
item.
The Customer Service feature team's view of the backlog only includes those work items
assigned to their area path, Fabrikam Fiber/Customer Service. Here we show parents
that provide a few of the features and epics to which the backlog items belong. Items
that are owned by other teams appear with hollow-filled bars. For example, Mobile
feedback and Text alerts belong to the Account Management team.
Items that are owned by other teams appear with an information icon, .
Assign work from a common backlog

While the hierarchical team and backlog structure works well to support autonomous
teams to take ownership of their backlog, it also supports assigning work to teams from
a common backlog. During a sprint or product planning meeting, product owners and
development leads can review the backlog. Teams can also assign select items to various
teams by assigning them to the feature team Area Path.
In this view of the Account Management backlog, all items still assigned to Account
Management have yet to be assigned.
During the planning meeting, you can open each item, make notes, and assign the item
to the team to work on it.
 Tip
You can multi-select work items and perform a bulk edit of the area path. See Bulk
modify work items.
Here, all backlog items have been assigned to feature teams while all features and epics
remain owned by Account Management.
Add portfolio backlogs
If you need more than three backlog levels, you can add more. To learn how, see
Track dependencies across teams

The simplest way to track dependencies across teams is to link work items using the
Related link type. If they're dependent in time, then you can use the
Predecessor/Successor link types. You can then create queries that find work items
containing these relationships. See Manage dependencies, link work items to support
traceability to learn more.
Using Delivery Plans, you can track dependencies across projects within an organization.
For more information, see Track dependencies using Delivery Plans.
Portfolio feature progress

To view feature progress based on linked requirements, you can add a rollup column or
view a delivery plan. For more information, see Display rollup and Review delivery plans.
Next steps
Related articles
Create your backlog
Kanban quickstart
Assign work to sprints
Limitations of multi-team Kanban board views
Article • 02/24/2023
2018
In Portfolio management, we showed how management teams and feature teams can
use their backlogs to focus on the work that's most important to them. In this article, we
show how to configure teams that best support the different backlog views of
management and feature teams.
Specifically, we'll show you how to configure a team structure like the one shown in the
image below.
＂ Set up a hierarchical set of teams and backlogs

＂ Define a single sprint cadence for all teams
＂ Review which area paths are assigned to teams
Prerequisites
If you don't have a project yet, create one.
To add teams, you must be a member of the Project Administrators group. To get
added to this group, see Change project-level permissions.
Add a team for each management area

The first step is to add a team for each feature team and management area. You can
also rename teams that you've already added. When you finish, you'll have a set of
teams similar to the ones shown.
1. From the web portal, choose Project settings and open Teams.
2. Choose New team. Give the team a name, and optionally a description.
Repeat this step for all feature and management teams you want to create.
Move area paths into a hierarchical structure

In this step, you want to move the areas paths associated with feature teams from a flat
structure to a hierarchical structure.
Flat area structure Hierarchical area structure

Flat area structure Hierarchical area structure
You do this by opening each area path associated with a feature team and changing its
location to be under the management area path.
1. Choose (1) Project Settings, expand Work if needed, and choose (2) Project
configuration and then (3) Areas.
2. Next, choose the actions icon for one of the area paths associated with a
feature team and select Edit. Then change the Location to move it under its
corresponding management team area path.
For example, here we move the Customer Profile to under Account Management.
Repeat this step for all feature team area paths.
Include subarea paths for management teams

By including subarea paths for the management teams, you automatically include the
backlog items of their feature teams onto the management team's backlog. The default
setting for all teams is to exclude subarea paths.
７ Note
Sub-area paths may break a team's ability to reorder or reparent items on the
backlog. Also, it can introduce uncertainties with regards to assignments made to
the Kanban Board Column, Done, and Lane fields. For more information, see
Exercising select features with shared area paths later in this article.
You define both areas and iterations from Project Settings>Boards>Team

configuration. You can quickly go to it from Teams.
1. From Project Settings, choose Teams, and then choose the team whose settings
you want to modify.
Here we open the Account Management team.

2. Choose Iterations and areas and then Areas.
If you need to switch the team context, use the team selector within the
breadcrumbs.
3. Choose Select area(s), and select the area path for Account Management and
check the Include sub areas checkbox.
Verify that only this area path is selected for the team and is the default area path.
Remove any other area paths that may have been previously selected.
Repeat this step for all your management areas. If you want to enable rollup across
all feature teams and management areas to the top-level area, repeat this step for
the default team. In our example, that corresponds to Fabrikam Fiber.
Define a single sprint cadence for all teams

If your feature teams use Scrum or use sprints to assign their work, you'll want to set up
a series of sprints that all teams can use. By default, you'll see a set of predefined sprints.
Add more sprints and set their sprint dates from Project Settings as described in Add
iterations and set iteration dates. You can rename and edit the default sprints as needed.
７ Note
While maintaining a single sprint cadence simplifies project administration, you can
create different cadences as needed. For example, some teams may follow a
monthly cadence while others follow a 3-week cadence. Simply define a node
under the top project node for each cadence, and then define the sprints under
those nodes. For example:
Fabrikam Fiber/CY2019
Fabrikam Fiber/3Week Sprints
Here we define the start and end dates of the first 6 sprints corresponding to a 3-
week cadence.
Configure other team settings

For teams to be well defined, you'll want to add team administrator(s) and have them
verify or configure other team settings. For more information, see Manage and
configure team tools.
Review area paths assigned to teams

From Project Settings>Project configuration>Areas, you can review which Area Paths
have been assigned to which teams. To modify the assignments, choose the team and
change the team's area path assignments.
Exercising select features with shared area

paths
When you share area paths across two or more teams, you'll want to understand how
Azure Boards manages conflicts that can arise when exercising these features:
Reordering or reparenting work items on a backlog or board

Updates made to Kanban Board Column, Board Column Done, and Board Lane
fields when dragging items to a different column
Reordering and reparenting work items

All backlogs and boards support drag-and-drop to reorder and reparent work items.
Updates made to one team backlogs and boards are reflected in other team backlogs
and boards that share the same area path. You may need to refresh the page to view the
changes.
You can only use drag-and-drop to reorder or reparent work items assigned to area
paths selected for your team. When the Parents view option is enabled, work items may
information icon can't be reordered nor reparented as it's owned by another team.
Kanban board column updates

Because each team can customize the Kanban board columns and swimlanes, the values
assigned to Kanban board fields may differ from what you expect when another team
updates the work item from a different board. Even if the management team and the
feature teams configure their Feature Kanban board columns with identical workflow
mapping, updating work items on one team's Kanban board won't be reflected on
another team's Kanban board. Only when the work item moves to a column that maps
to a workflow state does the card column reflect the same on all boards.
By design, the team with the longest area path wins the conflict and determines the
values for the Kanban Board Column, Board Column Done, and Board Lane fields. If the
shared area paths are of equal depth, the results are non-deterministic.
The primary work-around for this issue is to maintain single ownership of work items by
Defining area paths and assign to a team. Another option is to add custom workflow
states that all teams can use. For more information, see Customize the workflow
(Inheritance process).
Next steps
Related articles
Create your backlog
Kanban quickstart
Fix display, reordering, and nesting issues
Review team delivery plans in Azure
Boards
Article • 07/12/2023
Azure DevOps Services | Azure DevOps Server 2022
Use the visualization options provided by the Delivery Plans feature of Azure Boards to
review the schedule of stories or features that your teams plan to deliver. A delivery plan
shows the scheduled work items by sprint (iteration path) of selected teams against a
calendar view.
７ Note
This article describes using Delivery Plans 2.0, which is available for Azure DevOps
Services and Azure DevOps Server 2022. For information on the Delivery Plans
Marketplace extension that supports Azure DevOps Server 2020 and earlier
versions, see Delivery Plans 1.0.
Use the Delivery Plans feature to ensure that your teams are aligned with your
organizational goals. You can view multiple backlogs and multiple teams across your
whole account. Interact with the plan by using simple drag-and-drop operations to
update or modify the schedule, open cards, expand and collapse teams, and more.
Delivery Plans supports the following tasks:
View up to 20 team backlogs, including a mix of backlogs and teams from different
projects.
Add custom portfolio backlogs and epics
View work items that span several iterations
Reset start date and target date through drag-and-drop borders
Add backlog items to a team from a plan
View rollup progress of features, epics, and other portfolio items
View dependencies that exist between work items
Enable stakeholders to view plans
Any plan that you created with the original Delivery Plans extension works with the
Delivery Plans feature. You don't have to migrate any data or reconfigure plan settings.
For more information, see Add or edit a delivery plan.
In this article, learn how to:
＂ Open a plan from the list of defined plans

＂ Review a plan with your teams
＂ Use the interactive elements of plans and change a plan view
＂ View rollups
For information on working with dependencies, see Track dependencies.
Prerequisites
To view a delivery plan, you must be a member of the Project Collection Valid
Users group. Users granted Stakeholder access for a private project can view plans.
Users granted Stakeholder access for a public project can add and view plans.
To open or modify a work item or add work items to a plan, you must have Edit
work items in this node set to Allow for the area paths assigned to the work item.
For more information, see Set permissions and access for work tracking.
For work items and dependency lines to appear on the plan:
Work items must belong to a team's product backlog or portfolio backlog. Only
work items that belong to a category selected for viewing on a team's backlog
appear on the plan.
Team product or portfolio backlog must be enabled.
Sprints must be selected for each team defined in the plan.
Start and end dates must be defined for each iteration.
Iteration paths must be assigned to each work item.
For dependency icons and lines to show, work items must be linked via the
Predecessor-Successor link type or other custom dependency link type. (Remote
link types aren't supported.) You can add custom link types only for on-premises
environments.
 Tip
If you edit a plan and the changes that you make don't seem to appear in the plan,
refresh your browser. A browser refresh is sometimes needed to trigger the
updates.
Review a plan with your teams

It takes multiple autonomous teams to develop large software projects. Autonomous
teams manage their own backlog and priority, which contributes to a unified direction
for that project. Review Agile culture for a discussion of autonomous teams and
organizational alignment.
Regular reviews of the project schedule with these teams help ensure that the teams are
working toward common goals. Delivery plans provide the needed multiple-team view
of your project schedule.
Questions that you might address during the review include:
How confident are the teams in meeting the deliverables scheduled for each sprint?
Are dependencies across teams adequately addressed via the planned deliverables?
Are there gaps in the schedule, where no deliverables are scheduled? What's the
cause? Can the issue be mitigated?
For example, you might use delivery plans internally to share the schedule of features.
By seeing the work that many teams have planned for the next three sprints, you can
easily see if a plan has the right priorities and spot dependencies.
In this way, a delivery plan is a driver of alignment while letting each team remain
autonomous. Individual teams can work to different sprint cadences, if needed, and
manage different work item types (stories, features, or epics). Their work is all visible
with the same plan view. Teams can even be part of different projects if they use
different processes. Customize the card fields so that you see only the data fields that
interest you and that apply for each work item type.
Best practices for using a delivery plan

Determine how you want to use the delivery plan. Some ideas are:
Review quarterly plans for features to be delivered
Sync up monthly with several teams that have dependencies
Review cross-project deliverables and identify dependencies
Use a consistent sprint schedule across your project teams and organization when
possible. Although the plan can accommodate various sprint schedules, it adds to
visual clutter. Use the same sprints for backlogs, features, and epics. Don't create
specific sprints for epics or other portfolio backlogs.
Use Start Date and Iteration to specify the time frame for a work item. Or, use
Start Date and Target Date. However, don't specify both Iteration and Target Date
for a work item. Target Date always overrides the Iteration end date on the plan.
Minimize the number of fields that you choose to display on your cards.
Eliminate cross-team ownership of area paths. Cross-team ownership of area paths
can lead to undesirable edge cases.
Keep your work items up to date. When changes occur, update the target dates or
iteration paths.
Know the following information:
Plan views display the set of months that correspond to the iteration paths
selected by the teams whose backlogs appear in the plan.
Plan views are limited to a maximum of 20 teams or backlogs.
Zooming out can cause fields and tags to disappear from the cards. The farther
you zoom out, the harder it is to fit items on a card. Certain items might be
hidden, depending on the zoom level.
Rollup isn't supported for child work items that belong to a different project
than that of the originating parent work item.
If Start Date or Target Date is missing from a work item, you can add it to the
custom process defined for the project, as discussed in Add and manage fields
(inheritance process).
Open a plan
After you define a few plans, they're listed on the Plans page under All. Or you can see
them under Favorites, showing the title, description, and most recent creator/editor.
Use Add to favorites to favorite a plan so you can quickly return to the plan. You can
also search for other plans in the project.
To open a plan, open Boards > Delivery Plans and then choose the plan name. You can
sort by any of the columns: Name, Created By, Description, Last configured, or
Favorites.
Interact with a plan
Each team's backlog specified in a delivery plan appears as a row within the plan view.
When a row is collapsed, a rollup of the backlog items appears. When a row is
expanded, a card for each backlog item appears, organized by its assigned iteration.
 Tip
Work items appear in the prioritized order listed for the sprint backlog, which
inherits the priority from the product backlog.
Use your plan in the following ways:
Filter the plan: Select Filter . You can filter on any field that you include in the
plan. Settings are based on the keyword or text filter. For more information, see
Interactively filter your backlogs, boards, and plans.
Scale the size of the cards and calendar: Select Zoom out or Zoom in .
View previous or future months: Select Scroll calendar left or Scroll calendar
right . You can also scroll through the plan by selecting the plan and dragging
your mouse horizontally.
View details for a team: Select Expand team row.
Expand and collapse all team rows: Select Expand all team rows or Collapse all
team rows next to Teams.
Scroll the view vertically to view teams that appear lower within the plan view.
View titles only: Select Collapsed card fields . To view all fields, select
Expand card fields .

Select a card title to open the backlog item and view details. Close the work item
to return to the plan.
Add a work item to a sprint: Select Add item within the sprint and team that
you want to add it to.
Change the fields displayed on the cards: Select More actions .
Collapse teams for summary information

A benefit of Delivery Plans is the ability to view multiple teams across the projects that
you care about. There are two main ways to view more teams within the plan view:
Collapse all teams to focus on summary data.

Minimize the number of fields displayed on cards.
To gain a summary view of work that's scheduled, collapse all teams. You can then more
easily look for gaps in the forecast.
Expand or collapse each team row by selecting Expand team row or Collapse team row
next to the team name.
Show work that spans one or more iterations
For work items that span one or more iterations, define Start Date and Target Date. The
plan displays cards that start and end according to the dates that you set, as shown in
the following image. You can also grab the left or right border of a work item and drag it
to a new start date or target date.
View titles only in the collapsed card view

The collapsed card view allows you to quickly switch back and forth between cards that
show titles only and cards that show all fields configured for the plan. To view titles only,
select Collapsed card fields . To view all fields, select Expand card fields
View the rollup of features and epics

A rollup displays a fuller picture of the underlying work directly on the cards in your
delivery plan. Rollup views are available for features, epics, or any portfolio backlog
you've added to your project. To enable rollups, open your plan settings, select Fields,
and then select Show child rollup data.
For example, here's a plan view of four scenarios with a rollup of the child features, user
stories, and bugs for a single team.
You can also view rollups from a backlog view, as described in Display rollup progress or
totals.
Update the iteration for a backlog item

As changes occur to the schedule, you can update the iteration for a backlog item.
Move a card to a different iteration. This change helps drive alignment across your
organization.
Print a delivery plan
You can print all or a portion of your delivery plan, depending on the view that you want
to capture and share. You can print only one page at a time by using your browser's
Print feature.
Here are some tips for printing portions of a plan:
Select Full screen mode .

Expand or collapse one or more teams and zoom in or out to get the view that you
want.
Take a screenshot of the plan view, or select the Print function of your browser.
Related articles
Add or edit a delivery plan
Track dependencies by using Delivery Plans
Interactively filter your backlogs, boards, and plans
Add teams
Track dependencies by using Delivery
Plans
Article • 02/24/2023
With Delivery Plans, you can track dependencies that have been added to work items.
Dependency tracking supports the Predecessor/Successor link type between work
items. The following image shows several work items that have dependencies. Those
cards with a green icon indicate there are no dependency issues. Those cards with
a red icon indicate there are issues with one or more dependencies. Dependency
issues arise when a predecessor work item is scheduled to finish after a successor work
item.
To view dependencies, you must first define the Delivery Plan and dependencies
between work items. To learn how, see Add or edit a Delivery Plans and Link user stories,
issues, bugs, and other work items.
 Tip
You can create dependencies between work items in different projects and different
teams within the same organization, but not in projects in different organizations.
You can open a work item and add a dependency through the links tab.
Prerequisites
To view a Delivery Plan, you must be a member of the Project Collection Valid
To open or modify a work item or add work items, you must have the Edit work
items in this node set to Allow for the Area Paths assigned to the work item.
For work items and dependency lines to appear on the plan
Team product or portfolio backlog must be enabled to select it for a plan.

Work items must belong to a team's product backlog or portfolio backlog. Only
work items belonging to a category selected for viewing on a team's backlog and
meet any field criteria defined for the plan appear on the plan.
Sprints must be selected for each team defined in the plan.
Start and end dates must be defined for each project iteration.
Iteration Paths or Start Date/Target Date must be assigned to each work item.
When defined, Start Date/Target Date overrides the sprint assigned to a work
item.
For dependency icons and lines to show, work items must be linked using
Predecessor-Successor link type.
Team or teams must be expanded to view dependency icons and dependency
lines.
 Tip
If you edit a plan and don't see the changes you made appear in the plan, refresh
your browser. A browser refresh is needed some times to trigger the updates.
Show dependency lines for a work item

1. Open the Delivery Plan from Boards>Delivery Plans.
2. To view dependency lines for a work item, select the top or bottom of its card. To
dismiss the lines, select the top or bottom of the card again, or anywhere else
within the plan.
Dependency lines that have no issues show up as black lines.

 Tip
To view dependency lines across team backlogs, make sure to expand both
teams.
Dependency lines that have issues, show up with red lines. The issues indicate that
the successor work item is scheduled to end before the predecessor work item is
completed.
3. To view the issue, choose the icon.

Open the dependency summary for a work
item
To drill down into specific dependencies, open the Dependencies dialog for the work
item. Choose the icon that indicates the work item has dependencies, either the
green or red icon.
For example, here we choose the link icon for a work item with dependencies to several
work items within the same project and another project.
The Dependencies dialog indicates that the work item has three predecessors and no
issues.
Identify dependency issues
When issues exist, they're highlighted in red. The issue always has to do with an end
date for a successor work item occurring before the end date of the predecessor work
item. Determine the end date by using either the Target Date for the work item or the
End Date of the work item's assigned Iteration Path.
For example, the following Dependencies dialog indicates that two predecessor work
items are scheduled to complete before the successor work item is scheduled to
complete. A red exclamation mark and red colored arrows indicate there's an issue with
the dependency.
When the dependency is to a work item in another project, the project information is
shown as are other link relationships.
Related articles
Add or edit a Delivery Plan
Interactively filter your backlogs, boards, and plans
Article • 02/24/2023
2018
specific sprint.
assigned work.
Path, or Tags.
Area Path or Tags.

✔️or is listed.
Tool
Keywords
or ID
Fields
Parent
Work Item
Tags
Work items
✔️
Assigned To
Work Item Type
States
Area Path
✔️
Boards
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
✔️
✔️
Backlogs
✔️
Assigned To
Work Item Type
States
Area Path
Iteration Path
Note 1
✔️
Sprints (Backlogs
& Taskboards)
✔️
Assigned To
Work Item Type
States
Area Path
✔️(Note 2)
✔️
Query Results
✔️
Work Item Types
Assigned To
States
Tags
Note 1
✔️
Delivery Plans
✔️
Work Item Types
Assigned To
States
Area Path
Iteration Path
Tags
✔️
✔️
✔️
Projects
Area Paths
Assigned To
Work Item Types
States
✔️
Notes

enabled.
Tool
Filter settings
Sort
Group
Reorder
Rollup
Work items
✔️(Note 1)
✔️
Boards
✔️(Note 1)
✔️
Backlogs
✔️(Note 1)
In Progress items
✔️(Note 2)
✔️(Note 3)
✔️
Sprints, Backlogs
✔️(Note 1)
✔️(Note 2)
✔️(Note 3)
Sprints, Taskboards
✔️(Note 1)
Person
✔️(Note 4)
✔️
Query Results
✔️
✔️(Note 2)
Delivery Plans
✔️(Note 6)
✔️
✔️(Note 7)
Notes
Relevance.


７ Note
team.
Prerequisites

view
Features, or Epics
Work Items
team member.
want to filter on.
criteria.
Inactive functions


values.
board.

operator.



include 'web'.

Unassigned
７ Note

Epics).
AND | OR . AND
Item 2.

７ Note
you've defined.

features.

tags.
boards.

Related articles
About backlogs
Customize cards
Tags
Add or edit a Delivery Plan
Article • 05/25/2023
Delivery Plans provide a highly interactive calendar view of multiple team backlogs. For
the use cases, benefits, and interactions you can do, see Review team Delivery Plans.
Use this article to learn how to complete these tasks:
Open a plan from the list of defined plans

Add and edit a plan
Add field criteria, customize cards, and add markers
７ Note
This article describes how to add or edit Delivery Plans 2.0 which is available for
Azure DevOps Services and Azure DevOps Server 2022 and later versions. For
information on the Delivery Plans Marketplace extension which supports Azure
DevOps Server 2020 and earlier versions, see Delivery Plans 1.0.
Prerequisites
To add or edit a Delivery Plan, you must be a member of the Contributors group
for the project where you add the plan.
To add team backlogs to a plan, you must have view permissions to those projects.
To view a Delivery Plan, you must be a member of the Project Collection Valid
To manage permissions for a Delivery Plan or edit or delete a plan, you must be
the creator of the plan. Or, you must be a member of the Project Administrators,
Project Collection Administrators group, or be granted explicit permission
through the plan's Security dialog. For more information, see Manage Delivery Plan
permissions.
Before you define a plan

To add and configure a Delivery Plan, the following elements must be configured:
Teams and team backlogs.

Team product or portfolio backlog must be enabled.
Area paths and team area paths assignments.
Iteration (sprint) paths and team iterations
Iteration Paths must be assigned Start and End Dates or they won't appear on
the plan.
Also, Iteration Paths must be selected for the team whose backlogs you select,
or work items associated with those Iteration Paths won't appear on the plan.
Each team must have defined product backlog items, or portfolio backlogs and
assigned those items to either a Start Date and End Date or an Iteration Path.
 Tip
If you edit a plan and don't see the changes you made appear in the plan, refresh
your browser. A browser refresh is needed some times to trigger the updates.
Plan customization options

Once you open the Plan settings dialog, choose one of the following tabs to set your
customization options.
Page Use to...
Overview Edit the plan Name or Description.
Teams Add or remove a team backlog. You can add up to 20 backlog levels for Azure
DevOps Services or 15 backlog levels for Azure DevOps Server 2022. You can add a
mix of backlog levels and teams from any project defined for the organization.
Field Specify field criteria to filter work item types displayed on the plan. All criteria are
criteria evaluated as an AND statement. If no fields are specified, then all work item types
that appear on the teams backlog level appear on the delivery plan.
Markers Add up to 30 milestone markers to the plan. Specify a label and select a color.
Fields Add or remove fields from cards to display on the plan, similar to how you customize
them for your Kanban board. You can't add rich-text (HTML) fields, such as the
Description field, to a card even if it appears in the list. These field types represent too
many challenges to format on a card.
Styles Add styling rules to change card color based on field criteria.
Tag Add tags and specify a tag color. Optionally enable or disable a tag color.
colors
Add a plan
1. Open Boards>Delivery Plans.
2. To add a plan, choose New Plan.
All users have permissions to create a plan and manage the plans they create.
3. Fill in the form to name, describe, and specify the team backlogs that you want to
appear within your plan. You can add up to 15 teams to a plan.
When defining a plan, note the following information:
Use the name and description field to clearly identify your plan within the project
You can choose one or more teams from any project defined in the organization or
collection. There can be up to a maximum of 15 teams
You can choose one or more active backlogs for a team
７ Note
If you aren't able to select a backlog level, check the Team Backlog settings to
ensure the backlog level is enabled for the team. For more information, see
Select backlog navigation levels for your team.
You can reorder the team backlogs by dragging and dropping them into the
sequence you want
To filter for specific work items, specify the field criteria. For example, to exclude
bugs from the view, add the following criteria: Work Item Type <> Bug .
Edit a plan
Once you've defined a plan, you can modify or further customize it.
1. Choose the Settings to open the Plans settings dialog.
2. Then, choose the page you want to edit based on the customizations you want to
make. Here, we add the Tags to the Field criteria. Only work items that contain the
Build 2021 tag appear in the Delivery Plan.
Choose fields to appear on cards

Show those fields that are useful for your review purposes or if they contain keywords
that you may want to use to filter your plan. Unlike the Kanban board, you can't change
the field displayed on the card. First, open the work item to make field changes.
 Tip
To add a custom field, you must first add it to the process used to customize the
project.
1. From the Plan settings dialog, choose the Fields tab. Place a check mark in the
check box for those fields you want to have appear on the board.
2. To add a field, choose the plus icon and enter the name of a field you want to
add. You can add both default and custom fields, including Boolean fields. The only
fields you can't add are rich-text or HTML fields.
Here we select all standard fields and add the Story Points and Priority fields to
display on cards.
 Tip
To show the Title of the parent work item, choose the Parent field. Choosing
the Parent title from a card opens the parent work item. To change the parent
work item, open the child work item and remove the link and add a different
parent work item. You can filter your plan based on parent work items,
whether the Parent field is added to cards or not.
3. To remove a field, choose the delete icon next to the field.
Add milestone markers

1. To set a marker, open Markers, specify a date and specify a hexadecimal color, or
choose the color palette icon to change to a new color selected by the system.
2. To add more markers, choose + Add marker. You can add up to 30 markers. The +
Add marker button becomes disabled after 30 markers have been added.
3. Choose Save when you're done.
Markers appear on the plan as shown.
Change card color

items meet the field criteria that you set. This feature is similar to the one you can define
for Kanban boards as described in Customize cards. Here we highlight the card based
on its Tags assignment.
1. To change the card color, open the Styles tab. You can specify up to 10 styles.
There are some limits to the fields you choose.
2. Choose +Add styling rule. Enter a name for the style and choose the color from
the color picker. Then specify the field criteria. You can add multiple field values.
For style purposes, they're all evaluated as a logical AND. Choose the field and the
value for the field.
For example, here we choose to highlight cards with a Priority=1.

７ Note
Some fields aren't supported for selection, such as the Title field, Description
and other rich-text fields, Assigned To and other identity fields. Also, you may
be able to select a field but not be able to specify a value or the value you
want. For example, you can't specify Tags that are Empty or Not Empty.
Set color for an Iteration Path

You can highlight work items for a team's current Iteration Path by specifying the
@CurrentIteration macro in the Styles tab as shown in the following image. For more
information on using the @CurrentIteration macros, see Query by date or current

iteration, Create queries for your team's current iteration.
Set tag colors

Before setting tag colors, first add tags to backlog items that you want to highlight with
color.
1. From the Plan settings dialog, choose Tag colors and then choose Add tag
color. Then, select the tag and the color you want to appear on the cards.
2. To enable or disable a tag color, select the Enabled checkbox.
 Tip
If tags don't display on the cards, choose Fields and make sure that you've
checked Show Tags.
Programmatically manage Delivery Plans

You can manage plans using the REST API, Plans.
Related articles
Review team plans
Add teams
Delivery Plans FAQs
FAQ
Azure Boards
Delivery Plans provides a calendar view of multiple backlogs, teams, and team backlogs
from different projects. It replaces the Delivery Plans marketplace extension and is
available for Azure DevOps Services and Azure DevOps Server 2022 and later versions.
Here are some answers to frequently asked questions about Delivery Plans.
What are the main differences between

Delivery Plans 2.0 and the Delivery
Plans extension?
Feature
Delivery Plans 2.0
Delivery Plans Extension
Teams, Backlogs
20 maximum
10 maximum
Cross-project team backlogs
Supported
Supported
Timeframes
Start Date/Target Date and Iterations
Iterations only
Varying iteration paths

Supported
Supported
Card data
Condensed and expanded views

Variable based on zoom-level
Full card/TItle only
Rollup
% done of child and linked work items
Not supported
Dependency tracking
Supported
Not supported
Card styles
Supported
Not supported
Keyboard shortcuts
Not supported at this time
Supported
Can I use Delivery Plans 2.0 with Azure

DevOps Server 2020?
No. Delivery Plans 2.0 is available with Azure DevOps Server 2022 RC1.
Why don't my work items show on the
plan?
Make sure your work items are assigned to an Iteration Path, or a Start Date and Target
Date. Also, verify that the Iteration Paths have been selected for the teams whose
backlog levels are chosen for the Delivery Plans. If the Iteration Paths aren't selected,
work items associated with those iterations won't display.
How do I get dependency lines to

show?
Select the bottom of the card to show the dependency lines of the work item. To turn
them off, select the bottom of the card or anywhere else in the plan. Clicking the
bottom of the card is a toggle for the display of the dependency lines.
Why can't I see all the fields and tags

I've configured?
In the settings under the Fields section, you can add fields display on the cards.
However, depending on the number of fields and the zoom level, not all fields are
displayed. Selective field display based on zoom level is a design decision that was
made to avoid card clutter. To see all the fields and tags on a card, continue to increase
(+) the zoom level until they fully display.
Can I view custom work item types on

Delivery Plans?
Yes. Add your custom work item type to a backlog level as described in Customize your
backlogs or boards (Inheritance process).
Related articles
Azure Boards FAQs
Implement Scaled Agile Framework® in
Azure Boards
Article • 02/24/2023
2018
Many enterprises benefit from individual Agile teams. Greater interest grows to scale
Agile practices as the organization grows. The need for enterprises to view progress of
many Agile teams and across a portfolio continues to increase. To address these needs,
many businesses have adopted the Scaled Agile Framework® (SAFe®).
If you're familiar with Scrum but not familiar with SAFe®, these videos at Scaled Agile
are a good way to orient yourself.
Azure Boards supports SAFe® practices through its autonomous teams, backlogs,
boards, reports, and metrics. This article introduces you to how Azure Boards artifacts
support SAFe practices and artifacts.
＂ The Scaled Agile Framework®

＂ Essential SAFe®
＂ Portfolio SAFe®
＂ Large Solution SAFe®
＂ Quick reference mapping
＂ Azure Boards implementation of SAFe®
７ Note
This article is one of a set of Scaled Agile Framework® tutorials that applies to
Azure Boards and Azure DevOps Services. Most of the guidance is valid for both
the cloud and on-premises versions. However, some of the features and procedures
are specific to the cloud or the latest version of Azure DevOps Server.
Scaled Agile Framework®

The SAFe® addresses how a portfolio vision is met by a hierarchy of teams, all
concerned with specific goals. This framework breaks down Epics into Features and
Stories. Teams work on these items in Sprints and deliver through Program Increments
(PIs) and Release Trains. Furthermore, the portfolio backlog can track deliverables that
map to value streams and associated budgets.
SAFe® architectural overview version 5.0
Reproduced with permission from © 2011-2020 Scaled Agile Inc. . All rights reserved.
SAFe® and Scaled Agile Framework are registered trademarks of Scaled Agile Inc.
SAFe® 5.0 Business Agility

Many SAFe® practices include growing a culture that supports agility, alignment, and
autonomy, all while being customer-centric.
Some of the ways Azure Boards supports business agility and agile culture are discussed
in the following articles:
Agile culture
Essential SAFe®
Essential SAFe® requires support for the artifacts and practices illustrated in the
following poster.
All of these artifacts and practices are supported by Azure Boards.
Stories, Features, and Enablers: Implemented as work items that capture

information and status of work. These work items automatically appear on team
backlogs and Kanban boards.
Team Backlogs and Program Backlogs: Implemented as team backlogs that filter
work items assigned to a team and support prioritizing and grouping of work.
Scrum and Kanban: Practices that are fully supported using Kanban boards, Sprint
backlogs and Taskboards, teams, and sprint cadences.
Iterations, Innovation and Planning (IP) Iteration, Program Increments (PI),
Milestones, and Release Trains: Implemented via a flat-list or a hierarchical
configuration of Iteration Paths.
Agile Release Train: Implemented by a set of Agile teams and Program teams
configured to support specific team and program views.
PI Objectives, Team Goals, and Solution context: Teams can use the built-in
project wiki to share objectives, goals, customer information, and solution
requirements.
For an overview of how Azure Boards implements Scrum and Kanban, see About Sprints,
Scrum, and project management and About Boards and Kanban.
Portfolio SAFe®
Portfolio SAFe® adds support for managing portfolios through epics, enablers, and
value streams.
Azure Boards provides supports for the following portfolio components:
Epics: Map to the Epic work item type and allow tracking, grouping, and rollup of
child items.
Portfolio backlogs: Implemented as a portfolio backlog that supports filtering of
work based on review of business needs.
Portfolio Vision and Strategic Themes: Business owners and portfolio managers
can use the built-in project wiki to share their vision, objectives, and goals.
Value Streams: Value streams can be tracked using tags or custom fields.
Lean budgets: Budget information can be captured in custom fields and rolled up
to gain visibility to the Feature and Epic levels.
KPIs: Several reports and dashboard widgets provide out-of-the box metrics.
Power BI and the Analytics service provide support to create custom reports
quickly.
Large Solution SAFe®

Large Solutions SAFe® includes support for a Solution Backlog, Solution Trains, and
Capabilities.
You can implement large solutions in much the same way as you implement Portfolio
SAFe®. However, you can also add custom work item types and custom backlogs to
support other solution requirements.
Full SAFe®
Full SAFe® includes the three levels of Essential SAFe®, Large Solution SAFe®, and
Portfolio SAFe®.
How SAFe® artifacts map to Azure Boards

The following table maps SAFe® terms or artifacts to the equivalent Azure Boards term
or artifact. Choose the link to learn about implementation details.
SAFe® term or artifact
Azure Boards term or artifact
Agile teams
Teams. You define a hierarchy of teams to meet the needs of feature or development
teams, program and portfolio teams, or solution train teams.
Agile Release Train (ART)
Teams. Agile teams manage the work of deliverables for a set of Features. Each Agile
team has a set of Agile tools to support the flow of work and review progress and
deliverables.
Budgets
Tags, Value Area. You can use tags or the Value Area field to track work associated with
a specific budget or value stream.
Capabilities
Work item. You define, plan, and track Capabilities similar to Epics and Features. You
capture them in work items and within various team backlogs.
Enablers
Work item. You define, plan, and track Enablers similar to Epics, Features, and Stories.
You capture them in work items and within various team backlogs.
Epics
Epic work item. You define an Epic using the Epic work item type. Epics are at the top of
the work item hierarchy of Epics, Features, and Stories.
Features
Feature work item. You define a Feature using the Feature work item type. Features are
a container for many Stories and are represented in their own portfolio backlog.
Innovation and Planning (IP) Iteration
Iteration Path. You define Iteration Paths for a project and set their start and end dates.
Each team subscribes to the iterations they work with.
Iteration
Iteration Path. You define Iteration Paths for a project and set their start and end dates.
Each team subscribes to the iterations they work with.
Milestones
Milestones and key events. Milestones occur at the end of each iteration. Custom fields
and tags can also be used to associate work with milestones and key events.
Portfolio Backlog
Portfolio backlog. A portfolio backlog lists the Epics associated with a portfolio with the
option to expand and display the child Features and Stories.
Portfolio Kanban
Portfolio Epics board. The Portfolio team's board displays the Epics backlog as cards in
an interactive, configurable, and filterable Kanban board.
Portfolio Vision
Wiki. Use the project wiki to share broadly within the organization information related
to strategy, solutions, and how teams collaborate to produce portfolio and program
deliverables.
Program Backlog
Feature backlog. A Feature backlog lists the Features associated with a program with
the option to expand and display the child Stories.
Program Kanban
Program Features board. The Program board displays the Features backlog as cards in
an interactive, configurable, and filterable Kanban board.
Program Increment (PI) Iteration Path
Iteration Path. Iteration Paths define a time box for a project with start and end dates.
Iteration Paths can be defined from one week to 12 weeks or longer.
Retrospectives and reviews
Retrospectives. Each team can add a board to capture, prioritize, and create action
items to support their improvement processes.
Roadmap
Delivery Plans, Feature Timeline. Azure Boards provides configurable and interactive
views to review roadmaps and team deliverables.
Shared Services
Shared services team structure: Resources that are shared across teams can be
represented through their own Agile feature team. Each can manage their backlog while
having their work also appear in the backlogs of the teams they support.
Solutions
Solutions: Solutions can be represented through a custom Solution work item type.
Solution Backlog
Solution portfolio backlog. You can define a custom work item type and portfolio
backlog to capture special business requirements of large solutions, or use Epics and
Epic portfolio backlogs to capture solutions.
Strategic Themes
Wiki. Strategic Themes, similar to Portfolio Vision, can be captured in a project wiki.
Stories
User Story work item. User Stories capture the functionality you want to be delivered.
They're typically sized so as to be completed with a single iteration.
Team Backlog
Stories backlog. The Stories backlog lists the User Stories assigned to the area path
associated with the team.
Team Kanban
Stories board. The Stories board displays the Stories backlog as cards in an interactive,
configurable, and filterable Kanban board.
Value Streams
Tags, Value Area. You can use tags or the Value Area field to track work associated with
a specific budget or value stream.
Azure Boards implementation of SAFe®

Each of the following articles within this suite of tutorials provide details on how you can
configure, customize, and use Azure Boards to implement your SAFe® programs and
projects.
＂ How SAFe® concepts map to Azure Boards artifacts
＂ Configure Azure Boards to support SAFe®
＂ Customize Azure Boards to support SAFe®
＂ Plan and track SAFe® programs and portfolios
＂ View SAFe® progress, roadmaps, and metrics
Next steps
How SAFe® concepts map to Azure Boards artifacts
Related articles
Agile culture
About Sprints, Scrum and project management
Scaled Agile Framework : SAFe® resource site.
Scaling Agile and SAFe® Metrics with TFS : Blog post that illustrates a SQL Server
report developed by InCycle to illustrate how TFS can be used to support scaled
agile or SAFe.
About the authors

Many thanks to the following contributors for their review and feedback to the current
content.
Phillip Eng is a Senior Architect at Microsoft, Digital Pursuit and Guidance.

Hosam Kamel is a technology solution professional for Microsoft and ALM Ranger.
Willy-Peter Schaub is a former program manager with the Visual Studio ALM
Rangers at the Microsoft Canada Development Center. You can follow Willy-Peter
on Twitter at twitter.com/wpschaub .
The articles in this series were updated from a previous white paper developed in
collaboration with the following authors:
Gordon Beeming is a Software Developer at Derivco in the sunny city of Durban,

South Africa. He spends most his time hacking away at the keyboard in Visual
Studio or with his family relaxing. His blog is at gordonbeeming.xyz and you can
follow him on Twitter at twitter.com/gordonbeeming .
Brian Blackman is a principal consultant with Microsoft Premier Developer,
focusing on affecting ISV partners and Enterprises success in engineering and the
marketplace. He has an MBA, and is a CSM, CSP, MCSD (C++), and MCTS and is a
Visual Studio ALM Ranger. When he's not Ruck Mastering and contributing to
Visual Studio ALM Ranger projects, he spends his time writing code, creating and
delivering workshops, and consulting in various concentrations, especially helping
organizations in their quest for business agility.
Gregg Boer is a principal program manager at Microsoft. Gregg is the product
owner for the Agile management experience provided by Azure DevOps and on-
premises TFS.
Kathryn Elliott is a senior technical writer at Microsoft.
Susan Ferrell is a senior technical writer and a Visual Studio ALM Ranger.
Willy-Peter Schaub is a former program manager with the Visual Studio ALM
Rangers at the Microsoft Canada Development Center. Since the mid-'80s, he has
been striving for simplicity and maintainability in software engineering. You can
follow him on Twitter at twitter.com/wpschaub .
Special thanks to the following technical experts for reviewing this article: Mike
Douglas (independent consultant, ALM Ranger), Richard Hundhausen
(independent consultant, ALM Ranger) and Bill Heys (independent consultant, ALM
Ranger).
How SAFe® concepts map to Azure
Boards artifacts
Article • 02/24/2023
2018
If you're interested in using Scaled Agile Framework (SAFe®), you can configure your
Azure Boards project to track SAFe® deliverables. Just as Azure Boards supports Scrum
and Agile practices, it can support SAFe® and large numbers of teams to work together
on Epics that span releases.
This tutorial illustrates how the following SAFe® artifacts map to specific Azure Boards
artifacts.
＂ SAFe® Agile, program, and portfolio teams

＂ SAFe® deliverables such as epics, features, and stories
＂ SAFe® Product, program, and portfolio views
＂ SAFe® Release trains, sprints, and other timeboxes
＂ SAFe® Iteration goals and objectives
＂ SAFe® Value streams and budgets
＂ SAFe® Portfolio Vision and Strategic Themes
＂ SAFe® Roadmaps
＂ SAFe® Milestones and events
＂ SAFe® Retrospectives and reviews
For an overview of how Azure Boards implements Scrum and Kanban, see About Sprints,
Scrum, and project management and About Boards and Kanban.
７ Note
The following image illustrates how you can configure Azure Boards to support a three-
level team hierarchy and map teams to their respective area and iteration paths. The
examples build from the Agile process, However, the changes can be applied to any
project and process hosted on Azure Boards.
Examples provided below illustrate how a three-level team hierarchy is configured using
hierarchical area paths. The examples build from the Agile process, However, you can
apply these changes to any project hosted on Azure Boards.
Agile feature, program, and portfolio teams

Azure Boards supports each team to have its own view their work. By configuring a
hierarchical team structure, each team can focus on their work, and have their work roll
up to the next level within the team hierarchy.
To support SAFe® teams, you reconfigure the default team as the Portfolio team to
manage your epics. You then create subteams for program-level work and team-level
work. Work can be tracked across teams and throughout each of the levels.
Stories, Features, Epics, Enablers, and

Capabilities
All work and deliverables are captured in work items. Each work item is associated with a
specific work item type with a predefined workflow. Each Azure Boards process provides
support for specific work item types that you can use to track any of the SAFe®
deliverables.
The work item types available to you're based on the process used when your project
was created—Agile, Basic, Scrum, or CMMI—as illustrated in the following images.
Agile process
The items in your backlog 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 be delivered and the work to be completed.
You can track Enablers using User Stories or Features, and Capabilities using Features or
Epics. Or, you if you have specific tracking and reporting needs, you can add custom
work item types to track these types of deliverables. For more information, see
Customize Azure Boards, Add custom work item types.
Work items provide support for the following tasks:
Add description and acceptance criteria

Assign to a team or area path and to a project member
Update status and assign to an iteration or sprint
Link work items, attach files, add tags
Add comments and view a discussion thread
Product and portfolio backlogs enable teams to quickly add and prioritize their User
Stories, Features, and Epics. For more information about work items and work item
types, see Track work with user stories, issues, bugs, features, and epics.
Team backlogs and boards

SAFe® backlogs map to team, program, and portfolio backlogs. Out of the box, the
Agile process supports User Story, Feature, and Epic backlog levels. The hierarchical
backlog structure shows work done to support Features and User Stories in the progress
of an Epic.
You can customize your backlog and boards, even adding portfolio backlogs, as
described in Customize Azure Boards, Customize backlogs.
The Kanban board view of each backlog is configurable by each team.
Program Increments, releases, and sprints

SAFe® Release Trains, Releases, Iterations, Program Increments (PIs), and Sprints map
easily to your iteration paths. By sharing iterations across the team hierarchy, you
manage the releases in a cohesive manner.
Because epics can span several release trains, the Portfolio team isn't associated with
any specific iterations. Program teams track their Feature deliverables, which ship with a
PI. And Feature teams work in Sprints to complete several stories. Each team chooses
which iterations support them to track their focused set of deliverables.
Iteration goals and objectives

SAFe® practices include Agile release teams defining their iteration goals and
objectives. We recommend using the project wiki or team dashboards to capture team
information. The project wiki and team dashboards both support Markdown to add and
format information.
For more information, see Share information later in this article.
Value streams and budgets

You can use tags for a quick and easy way to map Features and Epics to their Value
Streams, Strategic Themes, and associated Budgets. You can add custom fields to
capture budget estimates for Features that can then roll up to Epics.
With tags that you add to work items, you can:
Filter any backlog or Kanban board

Create queries based on tags, and filter query results by tags
Create progress and trend charts or reports based on tags
For a more robust mapping of work to architecture or business features, you can specify
the Value Area for each Epic, Feature, or Story.
With rollup, you can get Budget Estimates for Epics from a rollup of the estimates
defined to their child Features, as shown in the following image.
To add custom fields, see Customize Azure Boards, Add a custom field.
Use the project wiki to support your portfolio

vision and strategic themes
Information can be widely shared with an organization using the Azure DevOps project
wiki. The wiki is a similar to a git repository that supports adding and editing pages
using Markdown and a WYSIWYG editor. It versions each page so that it's easy to track
who made changes and recover past versions.
Use your project wiki to support sharing the following SAFe® artifacts:
Portfolio Vision
Strategic Themes
Taxonomy
Goals
Objectives
Customer-centric practices
To learn more about the project wiki, see Share information later in this article.
Milestones and key events

The end of each Program Increment, Sprint, Release Train, or Innovation and Planning
(IP) Iteration represent natural SAFe® milestones. Many milestones are associated with
specific ceremonies or practices, such as conducting retrospectives or demonstrating
working software.
In Azure Boards, you can track other types of milestones or key events in the following
ways.
Custom field, such as Milestone or Release field with predefined picklist
As a tag added to work items
As a work item that specifies a target date
As a one-day Iteration Path
With custom fields and tags, you can quickly filter backlogs, boards, and queries based
on a specific milestone.
Shared services team structure

Resources that are shared across teams can be represented through their own Agile
feature team, such as a UX Design team or a Security Compliance team. They can
manage their backlog while having their work also appear in the backlogs of the teams
they support.
Here we show how area paths are assigned to the UX Design team, and then selective
subarea paths to other Agile teams. Work items that appear on shared area paths
appear on the backlogs and boards of the associated teams.
Retrospectives and reviews

To support teams doing retrospectives and reviews, we recommend using the
Retrospectives extension by Microsoft DevLabs .
This extension allows teams to create their own retrospective boards and capture the
following tasks:
Collect feedback on project milestones

Organize and prioritize that feedback
Create and track actionable tasks to help each team in their improvement
processes.
Share information
Azure Boards provides many ways to share information.
Work item forms provide rich-text fields to capture descriptions, acceptance

criteria and more. File attachments can be added to work items or links to network
file shares.
Project and team dashboards can be used to share information along with status
and progress charts and widgets. For more information, see Add Markdown to a
dashboard.
The Project wiki provides a central repository with versioning control built-in to
share information with all project members. Other wikis can be created as needed.
For more information, see About Wikis, READMEs, and Markdown.
For details on supported Markdown features, see the following articles.
Syntax guidance for Markdown usage in Wiki

Syntax guidance for basic Markdown usage
Next steps
Configure Azure Boards to support SAFe®
Related articles
Agile process
Scrum process
CMMI
View SAFe® progress, roadmaps, and metrics
Culture and scale

Agile culture
Configure Azure Boards to support
SAFe® programs and portfolios
Article • 02/24/2023
2018
This tutorial walks you through the steps to convert a new project with a single team to
one that is configured to support Scaled Agile Framework (SAFe®) programs and
portfolios. Specifically, you'll learn how to configure Azure Boards to support SAFe®
programs and portfolios by completing the following tasks:
＂ Define Agile, program, and portfolio teams

＂ Configure a hierarchy of Area Paths to support your teams
＂ Define Iteration Paths to support SAFe® release trains, PIs, sprints, and IPs
＂ Configure each team to support SAFe®
You'll need to be a member of the Project Administrators group to make these

configurations.
Once you've completed these core configurations, you can then consider customizing
your project to support specific business needs. Customization options are addressed in
Customize Azure Boards to support SAFe® .
 Tip
If you plan to add custom work item types, portfolio backlogs, or workflows; you
may want to make those customizations first and then define and configure your
teams.
If you're new to Azure Boards, we recommend that you review About teams and Agile
tools and About area and iteration (sprint) paths before adding and configuring your
teams. Also, two excellent articles to review around team structure and Agile culture are
Introduction to planning efficient workloads with DevOps and Building productive,
customer focused teams.
７ Note
Understand team hierarchy

In this article, we'll go from having one project and one team, both named "Fabrikam",
to the following set of nine teams.
７ Note
Azure Boards doesn't support a hierarchy of teams. However, by configuring the
Area Paths as indicated in this article, you effectively create a type of team
hierarchy. The hierarchy is defined through the structure of Area Paths.
We'll then configure the area path to the following hierarchy and configuring each
team's area path. This configuration supports each team's backlog view and rollup of
views within the hierarchy.
 Tip
If you have a large number of teams, area paths, and iterations that you need to
add, you may want to use command line or programmatic tools. See the Command
line and programmatic tools provided later in this article.
All teams can manage their own workload and priorities while clearly understanding
how their work supports those epics managed in the portfolio team's backlog. At the
same time, the portfolio team can monitor progress of its backlog on their own Kanban
board, prioritize the items on their backlog, and view progress across release trains.
While the above may sound complicated, it actually takes little configuration to set up
the teams and get started. To go from one project with one default team, first define
each team while automatically creating a default area path for that team. Then
reconfigure the flat set of area paths to a hierarchical structure. Next, define the iteration
paths to support the release structure you want and the program and Agile teams to
use. Lastly, configure each team and populate the membership of teams.
Define your teams
To start, we'll add each team, creating a default area path for each. Later in this article,
we'll configure those area paths into the necessary hierarchy. This structure maps the
following SAFe® teams to Azure Boards teams:
Portfolio team -> default top-level team, the Fabrikam team (already defined)
Program teams -> secondary-level teams, Fiber Suite, and Service Suite
Agile teams -> tertiary-level teams defined under Fiber Suite and Service Suite.
You'll need to be a project administrator to complete these steps. If you need more-
detailed guidance, see Portfolio management.
Add each team, one by one.
７ Note
The following procedure uses the New Teams Page user interface that is in preview.
To enable this feature, see Manage or enable features.
1. From the web portal, choose Project settings and open Teams.
2. Choose New team.
3. Give the team a name, and optionally a description.
Here we add the App team. Choose the team administrator and ensure the Create
an area path with the name of the team checkbox is checked. Optionally add
team members.
Assign the team's Scrum Master, Program Manager, or Portfolio Manager as the
team administrator. As team administrators, they can configure their team's tools
to support their Agile practices and business needs.
4. Repeat steps 2 and 3 to define all teams.

5. Optional. If you have two or more Portfolio teams, create a team for each of them.
Configure Area Paths

To support your team hierarchy, you'll now configure the area paths created in the first
step of defining teams into a hierarchy.
1. From the Project Settings page, choose Project configuration and then Areas. You
should see a flat list of Area Paths.
2. You'll want to choose each feature team's Area Path under the top Area Path and
move it under the Area Path hierarchy to which it belongs.
You can drag and drop each area path under the parent node where it belongs. For
example, here we drag the Migrate node to the Fiber Suite node.
Instead, you can open the context menu for the Area Path, choose Edit, and select
the node where you want to move it.
3. Repeat step 2 and 3 for the remaining Agile team area paths.
If you've defined two or more portfolio teams, you'll need to change the move
each program team's area path under their corresponding portfolio team's area
path.
4. When finished, your area path structure should appear similar to the following
image.
） Important
This structure shows that area paths are owned by Agile teams, program
teams, and the portfolio team. We'll correct this structure later in this article
when we configure each team to be the sole owner of its area path.
To track progress towards Releases, create your iteration path structure. Unlike area
paths, multiple teams can share the same iteration path structure. Sharing the iteration
structure lets multiple teams work in the same sprint cadence towards the same release
trains.
） Important
Deleting, renaming, or moving iteration paths causes a loss of associated historical

data.
If you already have iterations for your default team, you can rename them. You'll want to
create an iteration structure that supports your entire team structure, not just one team.
1. From the Project Settings page, choose Project configuration and then Iterations.
2. Under the default iteration, which shares the same name as the project, create a
child iteration that represents your first program increment (PI). Optionally, add a
start and end date for the PI, but keep in mind that the iteration gets broken down
further into sprints.
3. Next, create a child iteration for each Sprint within the PI. Set dates for these
sprints to correspond your Agile teams' cadences.
4. Continue to add as many iterations as needed to meet the time box cadence
structure for all your teams.
When finished, you should have a structure similar to the following image.
 Tip
You can drag and drop Iteration Paths to structure your iterations, similar to as
shown in Step 2 under Configure Area Paths. Azure Boards always lists the
iteration paths in order of their dates under each parent node.
Configure your teams

Now that your teams, Area Paths, and Iteration Paths are defined, the next step is to
configure each team. You'll want to configure the following settings for each team.
Active backlogs
Working with bugs
Set default Iteration Path
Select team Iteration Paths
The following table lists the recommended settings to make based on the team level.
Configure
Agile feature team
Program team
Portfolio team
Backlog navigation levels
Features, Stories
Features, Stories
Epics
Working with bugs
Bugs are managed with requirements
Bugs are not managed on backlogs and boards
Bugs are not managed on backlogs and boards
Default Iteration
@CurrentIteration
@CurrentIteration
@CurrentIteration
Backlog Iteration
Fabrikam
Fabrikam
Fabrikam
Selected iterations
Sprint 1 thru Sprint 4, IP Sprint
PI 1, PI 2, PI 3
None
Areas
Include sub areas
Exclude sub areas
Exclude sub areas
７ Note
By setting the Default Iteration to @CurrentIteration, all work items created from
the team's backlog or board are assigned to the current iteration based on the
current date. By setting the Backlog Iteration to the root, Fabrikam, indicates that
only the Area Path acts as a filter for work items to appear on the team backlogs
and boards.
1. From the Project Settings page, choose Team configuration.
Choose the team you want to configure from the Team selector.
2. On the General page, uncheck backlogs you don't want to be active.
For example, for the Portfolio team, only check the Epics checkbox.
For program and Agile teams, uncheck the Epics checkbox.

3. For program and portfolio teams, choose the Working with bugs radio button as
shown.
And, for Agile teams, choose the Working with bugs option to track bugs along
with requirements.
4. Choose the Iterations tab to configure the team's iterations.
For Agile teams, configure the settings as shown.

For program teams, choose only the PI iterations.
5. For program and portfolio teams, choose the Areas tab to change the default
setting from Include sub areas to Exclude sub areas.
Open the context menu, and choose Exclude sub areas.
７ Note
Because we created each team with the Create an area path with the name of
the team checked, each team is already preconfigured with their default area
path. This Area Path acts as the main filter for work items that appear on each
team's backlogs and boards.
6. Repeat steps 2 through 5 as needed for each team you need to configure.
7. After you've completed step 5 for all teams, verify the Area Path-Team structure.
Choose Project configuration and Areas. The Area Path and team structure should
now appear as shown, where each team owns their Area Path and doesn't share it
with any other team.
Configure teams to support Shared Services
For teams that support several other teams, such as a UX Design team, configure your
teams as described in the following steps.
1. Add a team for each Shared Services team. Refer to Define your teams for details.
2. Return to the Project configuration>Area Paths page and under each shared
services area path, add sub area paths for each Agile team supported by the
shared services. For more information, see Configure Area Paths provided earlier in
this article.
For example, here we add four sub area paths under the UX Design area path, one
for each Agile team supported by the UX Design team.
3. Configure each Shared Services team as an Agile feature team as described in

Configure your teams.
4. For each Agile team, open the Team configuration>Areas page as shown in Step 5
of Configure your teams. Choose Select areas and add the sub area path for that
team.
Here we add the UX Design\App sub area path to the App feature team.
5. Return to the Project configuration>Area Paths page and verify that the Area Path
structure appears as expected for each Shared Services area path.
For the UX Design team, the structure should appear as shown.
Work items that appear on shared area paths appear on the backlogs and boards
of the associated teams.
Command-line and programmatic tools

You can use Azure DevOps command-line tools to add or update the following artifacts:
Teams: Azure DevOps team create
Area Paths: Azure DevOps area project create
Iteration Paths: Azure DevOps iteration project create
You can use Azure DevOps REST APIs to add or update the following artifacts:
Teams: Teams (REST API)

Area Paths: Classification nodes (REST API)
Iteration Paths: Classification nodes (REST API)
Next steps
Customize Azure Boards to support SAFe®
Related articles
Add teams
Define iteration paths and configure team iterations
Azure DevOps CLI
Teams (REST API)
Customize Azure Boards to support
SAFe® practices
Article • 03/01/2023
2018
The main reason to customize your process is to support progress tracking and
monitoring, report key metrics, and meet specific business needs. This article covers
some process customizations that you can implement and explains why you may want
to adopt them to complement your Scaled Agile Framework (SAFe®) practices. Most of
these customizations are optional.
Learn how Azure Boards supports SAFe® practices through the following operations:
＂ Customize work item types or add custom work item types

＂ Add a custom field or customizing existing fields
＂ Customize the workflow
＂ Add custom rules to a work item type
＂ Add custom controls or custom extensions
＂ Customize your backlogs or add a custom portfolio backlog
７ Note
About customization and the inherited process

Azure Boards provides a graphical user interface to support customization of your
projects. This feature is called the Inherited process. All projects that use an inherited
process are automatically updated when customizations are made to that process.
For an overview of all the customizations you can make to an inherited process, see
About process customization and inherited processes.

Each work item type defines the fields that capture and store information. You can
customize existing work item types in the following ways to support specific SAFe®
tracking requirements.
Add a custom field to support tracking budget costs, value streams, or customer-
centric information
Customize existing fields, such as modifying the picklist or changing a field label
Add custom rules to make select fields required or specify actions to take under
select conditions
Change the workflow to reflect your team's Kanban workflow process
Add a custom control or extension to support custom functions such as a
calculated field
For more information on customizing a work item type, see Add and manage work item
types.
Add a custom field

You can add a custom field to support tracking data requirements that aren't met with
the existing set of fields. Some fields to consider adding to one or more work item types
include those items listed in the following table.
Field name
Work Item Types
Notes
Budget cost
Feature, Epic
Use to capture estimated costs. Can use rollup to capture the total estimated cost of an
Epic's Features.
Category or Group
Feature, Epic, User Story
Use to specify a picklist to indicate the work item is cataloged as one of the following
SAFe® categories: Feature, Capability, Enabler, or Solution.
Milestone
Use to specify a picklist of Milestone of Events which a story, feature, or epic should
meet.
Value Stream
Use to specify a picklist to support a taxonomy of value streams you want to associate
with work.
For more information, see Add a custom field to a work item type.
Field versus tags usage

You can capture a value stream using a field or tags. Tags represent a more informal and
adhoc method for categorizing work. A specific field, particularly one with preset items,
is more formal. When determining how you want to use tags and fields, consider the
following statements:
You can make a field required through custom rules, however, you can't require
tags be added to a work item
You can create query charts based on custom fields, however, you can't specify a
tag for use in query charts
You can filter backlogs, boards, and queries based on fields or tags
The number of tags created can quickly grow as anyone can add new tags as long
as they have the correct permissions
Customize existing fields

You customize existing fields to support one or more of the following actions:
Relabel the name of the field

Change where the field appears or remove it from the form
Add or change a picklist (drop-down menu). For example, the Value Area provides
two options, Business and Architectural. You can add to this picklist of values
Change the default assignment made to a field
Make a field required
Add a rule to a field as described in the next section
For an index of existing fields, see Work item field index. For more information on
customizing a field, see Add and manage fields for an inherited process.
Add rules to a field
Field rules provide support for many business use cases. Rules specify an action to take
based on a selected condition. For example, you can make a field required based on the
value assigned to another field. You can add several rules to a field.
The following images show the supported conditions and actions you can select from.
Supported conditions Supported actions
For more information on setting field rules, see Add a rule to a work item type
(Inheritance process).
Customize the workflow

You may want to customize the workflow for User Stories, Features, and Epics so that it
matches your workflow process. By customizing the workflow early, you minimize the
Kanban board configuration teams must do.
The default workflow for the Agile process includes New, Active, Resolved, and Closed
states. While each team can add workflow columns to their Kanban board, you might
want to customize the workflow to track these columns instead. That way the Kanban
boards for all teams are set up to use the same workflow states.
For example, you can add and rename workflow States to match the Kanban columns
shown in the following image—Backlog, Analyze, Develop, Test, and Done.
Discuss with your team which workflow states best support their Agile practices. For
more information, see the following articles:
Customize the workflow (Inheritance process)

Definition of Done
Custom controls
With custom controls, you can add rich functionality to a work item form. A custom
control is an extension that's been added to the Marketplace Extensions for Azure
DevOps .
You can add controls from the Marketplace or create your own.
WorkBoard OKRs integration helps organizations align, localize, and measure

Objectives and Key Results (OKRs) across the business. With this integration, teams can
view and update their OKRs from within Azure DevOps.
Add custom work item types

The User Story, Feature, and Epic work item types are meant to support product
planning and tracking. However, other work item types might be useful to support your
SAFe® organization's customer-centric focus. Specifically, you might want to add work
items to capture customer feedback, customer requests, and more.
When you define a new work item type, think through the following items:
Information you want to capture, track, and report on
How work is captured
The workflow to support tracking the work
To keep things simple, however, it's always best to minimize the amount of
customizations you make. So, if you can get by with existing work item types, you might
consider adding custom field(s) as needed to track specific information.
Customize your backlogs

Each team's backlog and board is designed to support specific work item types. For the
Agile process, the following work item types are as used.
Agile Release Teams: User Stories and Bugs (optional)

Program Teams: Features
Portfolio Teams: Epics
However, you can include more work item types, either existing ones or customized
ones, into these backlogs. Each team can subscribe to the set of backlogs that they need
to track.
You can also add up to three more portfolio backlogs as shown in the following
illustration. Portfolio backlogs are designed to be hierarchical.
 Tip
You may want to add a Solution (Capabilities) Backlog that appears as a parent of
the Program (Features) Backlog. This SAFe configuration isn't achievable via the
Backlog Levels page. As a less-than-ideal workaround, you can disable the inherited
Epic work item type and recreate it as a custom work item type. For more
information, see Customize process backlogs and boards.
For more information, see Customize your backlogs or boards (Inheritance process).
Add even more functionality

You add the following Marketplace extensions to get access to many rich features that
support SAFe.
Delivery Plans
Feature Timeline and Epic Roadmap
Dependency Tracker
Retrospectives
７ Note
Before you customize your project, we recommend reading Configure and

customize Azure Boards. This article provides detailed information on
administrating a project for several teams and supporting various business
objectives.
Next steps
Plan and track SAFe® programs and portfolios
Related articles
Grant or restrict access
Develop a web extension for Azure DevOps Services
About projects and scaling your organization
Plan your organizational structure
Plan and track SAFe® programs and
portfolios in Azure Boards
Article • 03/22/2023
2018
Once you've configured your Agile tools to support SAFe®, trace relationships can be
created from Stories all the way up to Epics. Additionally, you can view progress from
the portfolio, program, and feature team levels.
This article walks you through some of the basic tools you'll use to plan and track your
SAFe® programs and portfolios. Specifically, you'll learn how to quickly complete these
tasks:
＂ Define epics, features, and stories

＂ Group or map stories to features, and features to epics
＂ Assign value streams
＂ Plan a sprint
＂ Review feature team progress
＂ Review program features
＂ Review portfolio epics
７ Note
Define portfolios and epics

To get started, each team needs to add work items for each deliverable that supports
the product vision. Each team can do that by working from their backlog and then
mapping their work to create a hierarchy of work.
Or, they can develop a list of work items and import them using Excel. By specifying
each team's area path for each work item, they create the mapped hierarchy.
The following sections indicate how to work from Excel or through the web portal.
Import a top-down plan by using Excel
You can import work items using Excel. As shown in the following image, Epics, Features,
and User Stories are defined in a tree-list with their Value Area, Area Path, and a few tags
defined. The State value is New.
Once you publish the list, work item IDs are assigned. Each team can then start working
with their work items, adding details, and assigning work to team members and to
sprints.
To learn more about bulk update, see the Bulk add or update work items section
provided later in this article.
Document Portfolio Vision and Strategic Themes

We recommend you use the project wiki to capture and share the Portfolio Vision,
Strategic Themes, and other information relevant to your programs. Consider defining
and sharing the following information:
How to use tags or custom fields to specify value streams

Taxonomy terms as described in Scale Agile to Large Teams
How release trains and sprints are used
Key milestones and events
Customer-centric programs
Information can be easily shared and updated by any member of the team. To learn
more about using the project wiki, see About Wikis, READMEs, and Markdown
Define and prioritize the Epics portfolio backlog

1. Open the Fabrikam team's Epics portfolio backlog and choose New Work Item.
Enter the title of the Epic and choose Add at selection.
2. Continue adding epics as needed by continuing to type in their titles. You can add
details later.
When finished, you should have a list of epics as shown:
3. As needed, you can drag and drop epics within the list to reflect their priority.
4. Define details. Choose each work item title to open the form. Add information to
the Description, assign to an owner, add tags, and choose the Value Area.
Here we assign the first epic to Jamal, add a Description, and specify Business for
the Value Area.
To update several work items in bulk, see Bulk add or update work items section
７ Note
Since an important aspect of SAFe® is to map work to business or architecture

goals, you'll want to make sure to set the Value Area=Architectural for any Feature
mapped to an architecture epic. Because the default choice is Business, you don't
have to change the field for any item that supports a business epic. You can also
add tags to track the investment.
The same principles apply to Stories in progress. You can map them to Features,
change the Value Area to Architecture for work that you do to support architectural
epics, and add tags for tracking themes.
Define programs and features

In a similar fashion to portfolio teams, program teams work from their Features backlog
and define the features that support the Epics they're tasked with delivering.
Each program manager defines and prioritizes their features. Here, we show the Fiber
Suite team add Features.
Define the Features backlog

1. Open the Fiber Suite team's Features backlog and choose New Work Item.
Enter the title of the Feature and choose Add at selection.
2. Continue adding Features as needed by continuing to type in their titles. You can
add details later.
When finished, you should have a list of Features as shown. The Node Name
indicates the last node in the area path specified for the work item. By adding
Features from the team's Feature Backlog, the Area Path is automatically assigned
the team's Default Area Path. For the Fiber Suite, that is Fabrikam\Fiber Suite.
3. As needed, you can drag and drop Features within the list to reflect their priority.
4. Define feature details. Choose each work item title to open the form. Add
information to the Description, assign to an owner, add tags, and choose the Value
Area.
Map Features to Epics

In this next step, you'll map each Feature to its parent Epic. The Mapping tool quickly
creates parent-child links between Epics and Features.
1. From the Features backlog, choose the view options icon and select Mapping.
2. Choose the Fabrikam Team's backlog of Epics.
3. One by one, drag each Feature onto its parent Epic.

4. When finished, choose the view options icon and enable Parents and turn
Mapping off.
Your list should look something like that shown in the following image. The info
icon appears next to each Epic, indicating that the work item is owned by another
team than the one currently selected.
Define Agile feature team deliverables

In a similar manner to portfolio and program teams, each Agile feature team add Stories
to their backlog to support the Features assigned to them.
Define the Stories backlog
1. Open the App team's Stories backlog and choose New Work Item.
Enter the title of the User Story and choose Add at selection.
2. Continue adding User Stories as needed by continuing to type in their titles. You
can add details later.
When finished, you should have a list of Stories as shown:
3. As needed, you can drag and drop User Stories within the list to reflect their
priority.
4. Define story details. Choose each work item title to open the form. Add
information to the Description and Acceptance Criteria, assign to an owner, add
tags, specify the Story Points, and choose the Value area.
To update several work items in bulk, see Bulk add or update work items section
Map Stories to Features

Just as you earlier mapped each Feature to its parent Epic, now you'll map each User
Story to its parent Feature. The Mapping tool quickly creates parent-child links between
Features and User Stories.
1. From the Stories backlog, choose the view options icon and select Mapping.
2. Choose the Fiber Suite's backlog of Features.
3. One by one, drag each User Story onto its parent Feature.
4. When finished, choose the view options icon and enable Parents and turn
Mapping off.
Your list should look something like that shown in the following image. The info
icon appears next to each Epic and Feature, indicating that the work item is owned
by another team than the one currently selected.
View Kanban boards and update status

Each team's Kanban board provides a visual interactive space for the team to plan and
update status. With it, your team can track the critical information they need by seeing
which work items are in progress, where the bottlenecks are, who work is assigned to,
and more.
For an overview of Kanban board tools and usage, see About Boards and Kanban. Each
team can customize the boards columns, card fields, card styles, and more. For more
information, see Customize your boards.
Open a Kanban board

You open the Kanban board from any backlog by choosing the View as Board link.
Each board supports the following tasks:
Add work items and child work items

Update status through drag-and-drop
Add and specify the labels of each column
Configure the display of cards, add tags, fields, and apply rules
Configure swimlanes and set WIP limits
Assign values or update fields displayed on cards
Filter based on keywords and key fields
Portfolio Kanban board

Child items of Epics are listed within each card. You can expand and collapse the list of
child items.
Program team Kanban board
Agile team Kanban board
Plan a sprint
Each Agile release team can plan their sprints using the sprint planning tools. Starting
with sprint planning, each team can move their backlog items to a sprint using the
Planning tool.
As shown in the following image, the App team plans their sprints.
To learn more about planning and conducting sprints, see the tutorials for Plan and
work a sprint.
Plan a release train

In a similar manner to Agile release teams sprint planning, each program team can plan
a release train.
Here we show the Fiber Suite program team plan the releases for their features.
Tips for working with work items
When creating and updating work items, understand what you can and can't do.
You can only assign a work item to one team member; if you need to assign similar
work to more than one user, copy the work item and make the assignment
Can only assign a work item to a single Area Path and Iteration Path
The quickest way to add backlog work items is from the backlog or Kanban board
You can use work item templates to quickly fill in work item fields
Bulk add or update work items

Common fields you may want to bulk update include:
Area Path
Assigned to
Iteration Path
Tags (Add or Remove)
Value Area
You can bulk update and change the work item type from the web portal. Or, if needed,
you can remove of delete work items. See the following articles:
Bulk modify (web)

Move or change work item type
Remove or delete work items
Also, you can bulk add or update work items with the following tools:
Bulk add or modify work items (Excel)

Bulk import or update work items (CSV)
Next steps
Review progress, delivery plans, and roadmaps
Related articles
About work items
About About Sprints, Scrum, and project management
Plan and work a sprint
Use work item templates
Track your work when assigned to two or more teams
View SAFe® progress, roadmaps, and
metrics
Article • 06/27/2023
2018
With team's configured and working backlogs and boards, you're ready to start viewing
and monitoring progress.
Azure Boards provides many in-context charts and dashboard widgets that allow you to
monitor and report on various SAFe® metrics. Specifically Azure Boards provides access
to the following tools to support teams in deriving SAFe® metrics and monitoring and
reporting progress.
Roll up columns on backlogs

In-context reports
Managed query charts such as pie, bar, stacked bar, trend, and pivot
Dashboard widgets
Team and project dashboards
Analytic Views to support Power BI reports
OData queries to use with Power BI reports
For an overview of these tools, see About dashboards, charts, reports, & widgets.
Another backlog tool is Forecast which teams can use in their iteration planning.
In this tutorial, we illustrate some of the out-of-the-box charts and widgets that you'll
have instant access to monitor some of these key SAFe® metrics
＂ Progress reports
＂ Cumulative Flow Diagram
＂ Lead time and cycle time charts
＂ Iteration planning, team velocity, and forecast
７ Note
View progress rollup
Quick progress views are available from each team's backlog through rollup columns.
Here's an example that shows progress based on completion of child work items.
Other rollup options include progress by specific work item types, progress by story
points, count of work items, or sum of a numeric field. For more information, see Display
rollup progress or totals.
View team velocity

Each team has access to their velocity through the in-context velocity report. These
reports show a bar chart count of planned, completed, completed late, and incomplete
work items for the last six or more iterations. As shown in the example below, the chart
also provides the average velocity calculated for the number of iterations shown.
This average can be used to forecast work by plugging it into the forecast tool.
Use the Forecast tool

By assigning Story Points to each User Story, a team can determine how much work they
can complete using the Forecast tool. For details on its usage, see Forecast your product
backlog.
View the Cumulative Flow Diagram (CFD)
Each Azure Boards backlog and board provide configurable CFD views. So each team at
every level of SAFe® implementation can monitor progress using these built-in charts.
The following image shows an example CFD chart for User Stories with all Kanban
columns displayed.
Teams can use their CFD to identify bottlenecks and monitor the batch size of work in
their various Kanban states.
In-context CFD charts are quickly accessible from each backlog and board view. Also,
CFD charts can be added to team and project dashboards. For more information, see
View/configure a Cumulative Flow Diagram.
View Lead Time and Cycle Time charts

Other metrics that teams use are derived from the Lead time and cycle time charts.
These charts can be added to a team dashboard and monitored to learn the following
information:
Lead time: Days on average to complete deliverables from date created

Cycle time: Days on average to complete deliverables from date work started
Number of outliers
Both Lead Time and Cycle Time widgets display as scatter-plot control charts. They
display summary information and provide several interactive elements. For more
information, see Cumulative flow, lead time, and cycle time guidance.
Example Lead Time widget
Example Cycle Time widget

View and update roadmaps
You can review roadmaps of SAFe® deliverables using the Delivery Plans, Feature Time,
and Epic Roadmap tools. Delivery Plans are fully configurable to show the teams and
work item types of interest.
Review feature team Delivery Plans

Program teams can review roadmaps of the deliverables of their Agile Release Teams. As
an example, the following image shows a snapshot of the Fiber Suite teams story
deliverables.
You can expand each feature team to see details. Story deliverables are assigned to the
PI 1 sprints. Delivery Plans are fully interactive, allowing you to drag and drop work
items to update their sprint assignments, or open work items to update fields, add
comments, and other information.
Review the portfolio features deliverable

Portfolio teams can review the Features under development by their program teams. For
example, Features under development by the Fiber Suite team are shown in the
following delivery plan view. The Features under development show up under the
Program Increment timeboxes.
Review feature timeline roadmaps
The feature timeline tool provides another view into progress of deliverables. Here we
show the Fabrikam Team's Epics as shown in the Feature Timeline tool. Progress bars are
configurable based on completed stories or effort.
Next steps
Sign up for Azure Boards for free
Related articles
Promote an Agile culture within your
team
Article • 06/06/2023
2018
As your team grows, you want your tools to grow with it. And if you're an enterprise
adopting Agile methodologies, you want your Agile tools to support the business goals
of your enterprise.
However, successfully scaling Agile requires addressing both the culture and tools within
your organization.
７ Note
New to Agile? For more information, see Agile Culture and Scaling Agile to Large
Teams.
Enable autonomy
Organizations that aspire to be agile need to consider the twin obligations of creating
alignment across the enterprise and supporting team autonomy. A team needs
autonomy to be efficient. And enterprises need alignment across teams and the
organization to be efficient.
Too much alignment with insufficient team autonomy leads doesn't support innovation
or agility of teams to get things done. Too little alignment with each team running their
own program doesn't provide the insight and coordination required to meet business
goals.
With the right level of alignment across the organization and team autonomy,
individuals get empowered to innovate and inspired to collaborate to meet business
goals.
Create alignment
As you plan how you want to grow your Agile tool set, consider the following areas.
These areas are key to creating enterprise alignment while developing team autonomy.
Area
Create alignment
Support autonomy
Product vision
The organization defines the goals and roadmap for the organization. You can define
goals as epics and features that show up on the portfolio backlog.
A team determines how to best meet the roadmap. The team breaks down goals into
user stories or product backlog items using their team backlogs.
Team structure
Based on business goals, organizations determine the number and size of teams.
Vertically structured feature teams lead to greater autonomy and efficiency.
With teams, there should be some established roles, such as product owner and
development leads, but also room to rotate roles. For example, team members can take
turns acting as Scrum Master, developing sprint demos, running sprint retrospectives, or
crafting sprint emails.
Development cadence
Agile organizations need to release products and feature updates at regular intervals.
Establishing regular release and sprint schedules promotes the rhythm of the business.
Each sprint--a time boxed iteration of constant duration between two and four weeks—
includes planning, executing, delivering value, reflecting, and engaging in continuous
improvement.
All teams manage their work within the set sprint cadence. The team provides input into
the length of sprint that works best for them.
The team chooses the Agile methods that work for them, Scrum, Kanban, or a mix of
both. The team also takes ownership of starting and acting on their own set of
continuous improvement practices.
It's possible for some teams to execute in shorter sprints. For example, if an organization
sets a 2-week sprint cadence, some teams may choose to operate in 1-week sprints,
while still aligning with the organizational schedule.
Communication cadence
Just as sprints bring a natural rhythm to the flow of work, so too do regular
communications. By setting expectations for the types of communications they want to
see to stay aligned and how often they occur, organizations naturally create alignment
across teams and the enterprise.
Team sprint emails, bug bar status, and release team feature delivery status are
examples of such regular communications.
A team determines the details that they communicate and who develops the
communication. Their sprint emails may contain a summary of previous sprint
accomplishments and the next sprint plans or include a demo of recently completed
features.
Quality
Each organization needs to set the criteria and standards by which they assess quality
and set expectations for quality standards. A few ways they define the criteria are to set
exit criteria for new feature development, standards to manage technical debt, and bug
caps for teams or individuals.
Also, they can monitor bug status and trends by creating bug dashboards.
A team chooses how they meet the quality standards. They may stage bug bashes for
new features or at the end of each sprint. They may choose an individual to function as
a bug shield on a rotating basis.
Manage risk, track work
The organization determines how each functional unit communicates status and risk.
They establish a "contract of communication" as to the minimum required information
the organization needs.
Also, the organization provides the infrastructure to reduce risks. The organization owes
the teams anything they can do to reduce risks that are common across teams.
Beyond meeting the needs set by the organization, teams determine any other details
they need to manage and track to reduce their risks. Whether they use a white board
with sticky notes or a full Gantt chart, they manage the details. For example, teams may
add a backlog item to track a dependency they have on another team. Or they may
track their risks via a list of issues or impediments. Also, teams regularly contribute to
improving the process and infrastructure to support the organization's ability to manage
risk and gain insights.
Structure teams
As you scale, one of the most important tasks to consider is how you structure your
teams. Traditionally, horizontal team structures divide teams according to the software
architecture: user interface, service-oriented architecture, and data teams.
However, with the adoption of Agile practices, vertical team structures that span the
architecture provide greater team autonomy. Vertical teams can deliver on the features
they own by working across the software architecture. They also spread the knowledge
needed to work at all architecture levels throughout all the teams.
Configure your teams along the value streams that your organization wants to deliver.
For example, Fabrikam Fiber, organizes their teams into the following seven feature
teams.
Each team plans the features to deliver. They have the autonomy to determine how to
structure the data, architect the services, and design the web and mobile user interfaces.
They plan in adherence with the quality standards set by the organization and to which
all teams contribute.
Configure your Agile tools to scale

As your organization grows, you can scale your Agile tools in the following ways.
Add teams and filtered backlog views: You add teams to support team autonomy
and provide them with the tools they can configure and manage that supports
how they want to work. These tools include product backlogs, Kanban boards,
sprint backlogs, Taskboards, and others.
Also, you can configure teams to support a hierarchy of backlogs and portfolio
backlogs so that portfolio managers can review priority and progress across
several teams.
Set up sprints and releases: You can structure your iterations to support a flat set
of sprints, or a set of sprints embedded within scheduled releases. Each team
activates the set of sprints and releases that they need to participate in.
Manage portfolios: by setting up a hierarchy of teams and backlogs and activating

portfolio backlogs. Feature teams focused on a subset of the product backlog can
remain focused on just their backlog. Portfolio managers who want to view and
organize backlogs to track progress and dependencies can manage portfolio
backlogs of Features and Epics.
If you need other portfolio backlogs, for example, Scenarios or Initiatives, you can
add them as well.
Configure dashboards: With team dashboards, you can configure charts that track
progress within a team or across teams. Specifically, you can add status and trend
charts based on queries you create.
Group or categorize work: There are several ways to group work that you want to
track. Backlogs filter work items based on team area assignments. And portfolio
backlogs allow you to group backlog items under Features and Epics.
If you want to track and report on work items based on other groupings, you can.
You can add tags to work items and then filter backlogs or queries based on tags.
Also, you can add subarea paths to represent more granular feature areas.
Add folders and use team favorites: As your teams grow, you see a growing list of
work item queries, build definitions, and source code folders. By using folders,
subfolders, and team favorites, you can manage many of these lists more easily.
You can add team favorites for shared queries, source code, and build definitions.
Scale with teams and not projects

Often, organizations look at adding a project for each software development project.
We recommend that you add teams to scale your tools rather than add projects for the
following reasons:
Visibility: It's easier to view progress across all teams
Tracking and auditing: It's easier to link work items and other objects for tracking
and auditing purposes
Maintainability: You minimize the maintenance of security groups and process
updates.
For more information, see About projects and scaling your organization.
Related articles
Before you can create or work with any of the Agile tools, you need a project. If you
don't have one yet, you can create one.
If you're ready to move from one team to two teams, or configure several teams, see
Add teams. To add a team administrator or configure team assets, see Manage teams
and configure team tools.
For more information, see these articles:

Implement Scaled Agile Framework® to support epics, release trains, and multiple
backlogs.
Agile culture industry resources

Nexus, the Exoskeleton of Scaled Scrum
Culture over process
The Culture Game - Tools for the Agile Manager
Scaled Agile Framework (SAFe)
Scaling Agile Software Development, - Disciplined Agility at Scale (White Paper)
Implement Agile practices that scale
Article • 02/24/2023
2018
Enterprise organizations adopt Agile practices for many reasons. Prime among these
reasons include:
Shorten time-to-market, accelerate product delivery

Improve organizational effectiveness to manage changing priorities
Enhance software quality and delivery predictability
Improve project visibility and reduce project risk
As your organization grows, you'll want to scale your practices to remain agile and meet
changing goals. To do that, consider these two guiding principles:
What does success look like to you, your teams, and your organization? What's of
most interest: On-time delivery? Product quality? Predictability? Customer
satisfaction?
Return to first principles, return to the principles and shared values enumerated in
the Agile manifesto As noted by Ken Schwaber , one of the founders of Scrum:
"Values and principles scale, but practices are context sensitive."
"Keep the values, keep the principles, think for yourself. A core premise of Agile
is that the people doing the work are the people who can best figure out how
to do it."
Create rhythm and flow

By adopting a shared cadence and set of periodic communications, you create a
constant flow of activity throughout the organization. Practices that help create rhythm
and flow within larger organizations include:
Shared cadence: Regular sprints and releases establish the rhythm of the business.
Having all teams work to a shared cadence helps with all coordination and
collaboration activities.
Sprint emails: To keep the organization and all teams informed about the progress
and plans of feature teams, each feature team can email a summary of their
previous sprint results and current sprint plans.
Sprint demos: A quick--2 to 3 minute--video that illustrates a new feature the
team produced. Links to such videos can be included within sprint emails.
Showcase meetings: To inform other teams and ask for feedback about software
under development, teams showcase the work they've done. Conduct these
meetings at regular intervals throughout the project lifecycle, and open them to all
interested parties.
Bug summary emails: To support insight into product quality and to encourage
maintaining bug discipline, periodically share quality metrics with the organization.
These metrics may include active bugs per feature team, bug trends, and bugs per
engineer.
Coordination meetings: Hold meetings that coordinate teams at either regular
intervals or as often as needed to address overlapping goals, dependencies, and
risks.
Interact with customers

Engaging customers throughout your product lifecycle is a primary Agile principle.
Empower each team to interact directly with customers on the feature sets they own.
Continuous feedback: Build in customer feedback loops. These loops can take
many forms:
Customer voice: Make it easy for customers to give feedback, add ideas, and
vote on next generation features. Giving feedback is often done through a
dedicated website.
Product feedback: In-product feedback buttons are another way to ask for
feedback about the product experience or specific features.
Customer demos: Regularly scheduled demos that ask for feedback from your
customers can help shape next generation products and keep you on track to
build applications your customers want to consume.
Early adopter programs: Such programs should be developed with the idea that
all teams may want to participate as some point. Early adopters gain access to
early versions of working software, which they then can provide feedback. Often,
these programs work by turning on select feature flags for an early adopter list.
Data-driven decisions: Find ways to instrument your product to obtain useful data
and that can test various hypotheses. Help drive to an experiment-friendly culture
that celebrates learning.
Improve project visibility

The more insight you and your teams have into the goal, vision, and progress of the
work being done, the better enabled you'll be to reduce risks and manage
dependencies.
Team structure: No matter how large your organization gets, structuring your
organization around small teams of 6 to 9 scales. Create vertical, autonomous
feature teams grouped under portfolio management areas.
Work breakdown structure: Breaking down large goals, features, or requirements
into smaller ones remains a stable of project management. By breaking down work
into similar-sized tasks, teams can make better estimates and identify risks and
dependencies.
Consolidated views: Use your online tracking tools to aggregate work to gain
knowledge across teams. Build dashboards to show progress and trends.
Experience reviews: These meetings, held before development begins on a
feature, are used to educate leadership on scenarios and priorities, collect
feedback, set expectations, and surface any cross-team issues about the feature.
Empower a productive workforce

Some specific Agile practices that scale well and lead to happier, engaged, and
productive employees include:
Embedded leadership: Empower teams and leaders within the organization to self-
organize and self-manage as much as possible. Team autonomy increases
organizational agility team effectiveness. Ensure teams have the corporate
sponsorship needed to succeed.
Daily stand-ups: Or, Scrum meetings help keeps teams focused on what they need
to do daily to maximize their ability to meet their sprint commitments. As
organizations grow, they should consider staggering these meetings so that cross-
team participation can occur as needed.
Scrum of scrums : Daily stand ups of members from different Agile teams meet
daily to report work completed, next steps, and issues or blocks occurring within
their representative teams.
Team communications: Provide and encourage teams to share their practices and
guidance, which they and other teams can access through the corporate network.
Common tools used for this purpose include team wikis, OneNotes, or Markdown
sites.
Collaboration: Encourage informal team-to-team communications and
collaboration within the team. Institutionalizing practices such as code reviews,
design reviews, spec reviews not only increase team collaboration but help develop
individual and overall corporate competence.
Improve organizational culture

You improve organizational effectiveness by attending to the culture you want to build.
Culture changes occur when individuals, teams, and organizations adopt one or more
continuous improvement practices. Several scalable Agile practices include:
Retrospectives: By asking questions such as: "What went well?", "What should we
do differently?", and "What should we stop doing?" help teams reflect on how they
can improve on their processes and practices. Retrospectives help teams surface
what is working well and what needs improvement. Retrospectives can be
conducted anytime and anywhere. However, institutionalizing certain
retrospectives at a regular cadence help institutionalize continuous improvement
practices. For example:
Sprint retrospectives can help teams identify areas to improve at a regular

cadence.
Release retrospectives can help organizations identify areas to improve

communications and internal practices and fuel improvement for the next
release.
Operational reviews: are typically held monthly and include representatives

from a whole value stream. Spanning a portfolio of projects and other initiatives
and using objective, quantitative data, design these retrospectives to provoke
discussions about the dynamics affecting performance between teams.
See the Agile Retrospective Resource Wiki for ideas, tips, and tools for
planning and conducting retrospectives. See also the Marketplace
Retrospectives extension .
Improvement tracking board: Good ideas to improve processes can arise from any
one at any time. Capturing those ideas to discuss and decide on how to act on
them quickly is a key to support process improvement efforts.
A white board provides any easy and visual means with which to capture ideas.
Also, you can create an Improvement tracking team and capture ideas that you
track on an electronic Kanban board.
Institutionalize sharing: Sharing best practices and communicating ideas helps all
teams within an organization grow and improve. Developing a culture of learning
is key to supporting this and other continuous improvement activities. Some ideas
to consider:
In-house wikis
In-house distribution lists

Hackathon weeks or 10% hack time
Internal Agile support team to support teams who adopt Agile practices
The Culture Game provides a good resource for Agile managers to help
teams adopt Agile and share best practices.
Communities of practice: Support internal common disciplines (for example, DBAs,

SW Architects, UX design)
Working software
"Deliver working software frequently, from a couple of weeks to a couple of months,
with a preference to the shorter timescale."
"Working software is the primary measure of progress."
- Agile manifesto
As the amount of software, features, and complexity increase, you'll need to adopt
practices that help you produce consumable solutions.
Feature flags: Use feature flags to enable or disable access to different features.
Provide support for turning on features to early adopters to get working feedback.
Release trains: Provide another type of cadence to deliver one or more features.
Feature teams understand the pre-planned schedule of pushing out new features,
and plan correctly. Release trains can correspond to the same sprint cadence
establish for the organization, or occur at a different cadence. See Scaled Agile
Framework for how to setup sprints and release trains.
Continuous integration: Adopt processes that eliminate manual work and instead
automate the flow of software through the test, build, and deploy cycles.
Internal Open Source: Bring the value and ethos that's developed in the Open
Source Software community to your internal development teams.
Related articles
Along with the above practices, you'll find more guidance around scaling your Agile
tools in the following articles:
Agile culture
Add teams
Scaling Agile to large teams
Industry resources
Agile manifesto
Agile Alliance
Scaled Agile Lean Development - The Principles
Practices that don't scale

Estimating large initiatives: Part of waterfall project methods involved estimating
resources and schedules. The larger the initiatives, the less likely these estimates
were of any value. As projects grow, risks and unforeseen issues and impediments
can arise, invalidating many estimates.
Velocity: While team velocity can provide a useful metric for gaining insight into
how much work each team can complete during a sprint cycle, you can't add team
velocities to gain meaningful or useful metrics. Also, using velocity gained from
many teams to reliably complete long range forecasts is problematic. Teams vary in
the way they estimate their work, and those variations increase over time.
Top-down prescriptive solutions: One size doesn't fit all, and one solution typically
doesn't fit all teams. Supporting team autonomy means letting teams find their
own solutions.
Manage priorities and gain visibility
across teams
Article • 02/24/2023
2018
Agile tools provide each team a wealth of ways to gain visibility into their work—to
manage priorities and status and to monitor progress and trends. However, how do you
gain visibility across several teams? What tools should you use?
You have three main ways to track progress across several teams.
Management teams can define Delivery Plans that provide visibility into the
deliverables several teams have scheduled
Each management team can use their Agile tools, and in particular portfolio
backlogs, to gain visibility of the feature teams defined under their area path
Management teams can create dashboards that monitor status, progress, and
trends across several teams.
For an overview of all team tools, see Manage teams and configure team tools.
Delivery Plans support a view of team backlogs

on a calendar timeline
With a Delivery Plan, you gain a tailor-made view across several teams and their
development backlogs—stories, features, or epics. You can use these views to drive
alignment across teams by overlaying several backlogs onto your delivery schedule.
When you configure a Delivery Plan, you select the teams and backlog levels of interest.
You can then interact with the plan to update it and drill into more details. To learn more
about Delivery Plans, see Review team plans.
Use portfolio backlogs to track features and
epics
The first level of gaining visibility across several teams is to configure your teams and
backlogs to support the views you want.
We recommend that you structure your teams as follows:
Add a management team for a group of feature teams; these teams own epics and
turn on only the Epic portfolio backlog level
Add feature teams to manage features, stories and tasks, and turn on the stories
and features backlog levels
The management team creates the epics. Then, they or their feature teams break down
the epics into features and then map their features to the epics on the management
backlog.
 Tip
By breaking down large goals, epics, scenarios, or features into smaller ones, teams
can make better estimates and identify risks and dependencies.
Limiting the backlog levels for each team—Epics for management teams and Features
and Stories for feature teams—helps each team to stay focused on monitoring the
progress of their work. For details on managing team backlog levels, see Select backlog
navigation levels.
With the multi-team portfolio backlog view, you can:
Review priorities with your team and reorder features to support current priorities
You can drill down to see the status of each feature's child user stories or PBIs
Filter the backlog based on keyword or tag to focus on specific teams or
categorized items
(Optional) You can use the mapping feature to map user stories or PBIs to features
View child items owned by other teams

Management teams can drill down from their portfolio backlog to see how Epics are
progressing. Drilling down, you can see all the backlog items and features, even though
they belong to one of three different teams: Customer Service, Phone, and Web.
 Tip
Add the Node Name field as a column to identify the area path/team associated
with the work items.
View backlog items and parent items owned by other

teams
Feature teams can turn Show parents on their backlogs to see context and those items
owned by other teams.
 Tip
When estimating stories or product backlog items, start with one story point per
person per day. Feature teams can later calibrate and adjust those estimates as
needed. For example, the velocity of a seasoned team is higher than a new team.
The size of the work stays the same, but a seasoned team can just deliver faster.
To learn more about this configuration, see Portfolio management, Add teams, and
Organize your backlog.
Add management dashboards with multi-team
views
A second method for gaining visibility across teams is to define multi-team focused
dashboards that let you view progress, status, and trends. You do define focused
dashboards primarily by defining queries that either capture the progress of a single
team or several teams. You can then create charts and view trends for each team or for
several teams.
The two areas of most interest to management teams are project health and bug debt.
The widget catalog provides 10+ widgets you can add to a dashboard to track the
status, progress, and health of your project and teams. Also, you can find other widgets
in the Visual Studio Marketplace , Azure DevOps tab.
For example, here we've added three query-based charts, one for each team, to a
dashboard that shows the active and resolved bugs over the previous four weeks.
When you define multi-team dashboards, consider the following questions:
What are you wanting to learn and how will it drive your organization's actions?
What time frame is of interest?
Review Agile culture and Practices that scale for guidance on team autonomy and
organizational alignment.
Project health and progress against goals dashboard

Use the Query Results widget to provide a list of features by state:
Completed features (Done or Closed)

New features (New or Proposed)
Features being actively worked (In Progress or Active)
Use the Chart for work items widget to add query-based charts. To learn more about
creating query-based charts, see Charts.
Technical debt, bug debt, and activity dashboard

Another measure of project health and the health of the teams is to monitor bug activity
and bug debt. Consider the charts you can create that will help you answer these
questions:
Are bugs getting fixed? At a rate that's acceptable?

How stale are bugs?
Is the bug debt per team being maintained?
Is the ratio of high priority bugs being kept within organizational goals?
For tips on creating queries based on counts or numeric fields, see Query by numeric
field.
Use the Analytics Service to gain visibility

across teams
You can add Widgets based on the Analytics Service to a dashboard that show progress
for a team. From one dashboard, you can add widgets for any team within the project.

team
You can track capacity for individuals that participate on more than one team. To learn
how, see Set sprint capacity, Track capacity when working on more than one team.
Limitations of multi-team Kanban board views

While the management teams you configure can use the Kanban board to monitor
feature progress by turning on the Features backlog, there are limitations inherent
within these views. Even if the management team and the feature teams configure their
Feature Kanban board columns with identical workflow mapping, updating the Features
on one team's Kanban board won't be reflected on another team's Kanban board. Only
when the work item state changes does the card column reflect the same on all boards.
） Important
Work items that appear on more than one team's Kanban board can yield query
results that don't meet your expectations. Because each team can customize the
Kanban board columns and swimlanes, the values assigned to work items which
appear on different boards may not be the same. The primary work around for this
issue is to maintain single ownership of work items by team area path. Another
option is to add custom workflow states which all teams can use. For more
Related articles
As you can see, there are many ways you can monitor progress and trends across
several teams. The methods you choose depend on your focus and organizational goals.
Here are some other articles that address working with multiple teams:

Review team plans
Add teams
About Azure Boards-GitHub integration
Article • 06/20/2023
Stay aligned and coordinated with Azure Boards and link your code activity and issues
from GitHub.
Integrate Azure Boards and GitHub

Azure Boards and Azure DevOps support integration with GitHub.com and GitHub
Enterprise Server repositories.
You can start from either Azure Boards or GitHub to integrate and connect up to 250
GitHub repositories to an Azure Boards project.
Install and configure the Azure Boards app for GitHub

Connect an Azure Boards project to one or more GitHub repositories
） Important
We recommend that you use the Azure Boards app for GitHub to configure and
manage your connections to GitHub.com. The app provides a more streamlined
configuration experience and has the advantage of authenticating and operating as
the app rather than an individual. Once you're connected, you can manage the
repositories either from Azure Boards or GitHub.com.
Use integration features

You can do the following tasks with Azure Boards-GitHub integration:
Transition work items to a "Done" or "Completed" state with fix, fixes, or fixed in
GitHub.
Post a comment to a GitHub commit, pull request, or issue when linked to a work
item.
Link from a work item to a GitHub commit, pull request, or issue.
View GitHub objects on a Kanban board.
Manage GitHub repository access
Troubleshoot Azure Boards-GitHub integration
Enable DevSecOps with Azure and GitHub
Add or remove connections

Add or remove GitHub repositories from Azure Boards.
Change repository access to Azure Boards to change connections, suspend the
integration, or uninstall the app.
Restrictions
Only connect a GitHub repository to one Azure DevOps organization and project.
If you connect the same GitHub repo to projects defined in two or more Azure
DevOps organizations, it can lead to unexpected AB# mention linking. For more
information, see Troubleshoot GitHub & Azure Boards integration.
Azure DevOps can only integrate with GitHub repositories or Azure Repos Git
repositories. Integration with other Git repositories isn't supported.
You can't query for work items with links to GitHub artifacts. However, you can
query for work items with an External Link Count > 0 .
Related articles
Build GitHub repositories
Build GitHub Enterprise Server repositories
Trigger an Azure Pipelines run from GitHub Actions
What's Azure Boards?
About work items
Install the Azure Boards app for GitHub
Article • 07/03/2023
Install the Azure Boards app for GitHub to connect Azure Boards to your GitHub
repositories. When you connect Azure Boards projects with GitHub.com repositories,
you support linking between GitHub commits and pull requests to work items. You can
use GitHub for software development while using Azure Boards to plan and track your
work.
For an overview of the integration that the Azure Boards app for GitHub supports, see
Azure Boards-GitHub integration. Once you install the Azure Boards app for GitHub on
your GitHub account or organization, choose which GitHub repositories you want to
connect to from your project.
Prerequisites
To install the Azure Boards app, you must be an administrator or owner of the
GitHub organization.
To connect to the Azure Boards project, you must have read permission to the
GitHub repository. Also, you must be a member of the Project Collection
Administrators group. If you created the project, then you have permissions.
） Important
If your repository is already connected via another authentication type such as

OAuth, you must remove that repository from your existing connection before you
re-connect it via the GitHub App. Follow the steps provided in Add or remove
GitHub repositories later in this article before you configure the GitHub App.
You can connect an Azure DevOps organization to multiple GitHub repositories if

you're an administrator for those repositories. However, you shouldn't connect a
GitHub repository to more than one Azure DevOps organization.
Give Azure Boards organization access

Do the following steps to grant organization access.
1. From the GitHub web portal, open Settings from your profile menu.
2. Select Applications under Integrations.
3. Select Authorized OAuth Apps > Azure Boards.
4. Under Organization access, resolve any issues that may appear. Select Grant to
grant access to any organizations that show as having an Access request pending.
Install and configure the Azure Boards app
1. Go to the Azure Boards app in the GitHub Marketplace .
2. Select Set up a plan.
3. Choose the GitHub organization you want to connect to Azure Boards.

4. Choose the repositories that you want to connect to Azure Boards.
Here we choose to connect to all repositories.

5. Choose the Azure DevOps organization and Azure Boards project you want to
connect to GitHub.com.
You can only connect one project at a time. If you have other projects you want to
connect, you can do that later as described in Configure other projects or
repositories later in this article.
6. Authorize your Azure Boards organization to connect with GitHub.com.

7. Confirm the GitHub.com repositories that you want to connect. Select each
repository you want to connect to. Unselect any repositories that you don't want to
participate in the integration.
Use the connection
At this point, your Azure Boards-GitHub integration is complete. You can skip the next
steps or run through them to understand the features supported with the connection.
1. Select Create to add a work item—Issue (Basic), User Story (Agile), or Product
Backlog Item (Scrum)—depending on the process model used by your Azure
Boards project.
A work item titled Add badge to README appears on your Azure Boards.
2. Select Create and link a pull request.

This step runs the following actions in the background:
Adds a badge to the README file of the first repository in the list of
connected GitHub repositories
Creates a GitHub commit for the update made by adding the badge to the
README file
Creates a GitHub pull request to merge the changes made to the README
file
Links the GitHub commit and pull request to the work item created in step 1.
3. Select View work item to open the work item you created in step 1. Note the links
under the Development section that correspond to the commit and pull request
created in GitHub.com
4. Choose the pull request link, the first link in the list, to open the pull request in
GitHub.
The GitHub pull request opens in a new browser tab.

5. Complete the pull request.
6. Go to your repository README file and view the badge that was added.
For more information, see Configure status badges to add to GitHub README files.
Configure other projects or repositories

You can configure other Azure Boards/Azure DevOps Projects, GitHub.com repositories,
or change the current configuration from the Azure Boards app page. For more
information, see Change GitHub repository access, or suspend or uninstall the
integration.
Add or remove repositories, or remove a

connection from Azure Boards
If you encounter a problem with a connection, we recommend that you remove the
connection and start over with a new connection.
1. To add or remove repositories, choose More options for the connection and
choose Add repositories or Remove repositories from the menu.
2. To remove all repositories and the connection, choose the Remove connection
option. Then, choose Remove to confirm.
Change repository access

1. Sign into the web portal for your GitHub organization and open Account settings.
https://github.com/organizations/fabrikam-fiber/settings/profile
2. Choose Installed GitHub Apps and then Configure next to Azure Boards.
The Azure Boards configuration page opens.
3. Scroll down to the Repository access section.
4. Choose the option you want, All repositories or Only select repositories.
If you choose Only select repositories, select the repositories you want to
participate in integration with Azure Boards.
5. Choose Save when you're done.

Suspend or uninstall Azure Boards integration
1. Starting from step 2 in the previous procedure, scroll down to the Danger zone
section.
2. To suspend the integration, choose Suspend. From the popup confirmation

window, choose OK to confirm the suspension.
To unsuspend the integration, choose Unsuspend.
3. To uninstall the Azure Boards app, choose Uninstall, and then choose OK from the
popup confirmation window.
Update Azure Boards-GitHub connections

If you change the repositories that the Azure Boards app for GitHub supports, you may
be redirected to Azure Boards GitHub connections. A good practice is to remove the
repositories in Azure Boards that can no longer connect to GitHub. For more
information, see Add or remove GitHub repositories.
If you uninstall the Azure Boards app for GitHub, you'll see the following message in
Azure Boards, Project Settings>GitHub Connections. Choose Remove connection to
remove all GitHub connections that have been previously made. See also, Add or
remove GitHub repositories.
Next steps
Related articles
Drive Git development from a work item
Change GitHub repository access, or suspend or uninstall the integration
Configure status badges to add to GitHub README files
Connect Azure Boards to GitHub (cloud)
Article • 07/03/2023
Use GitHub.com repositories for your software development and your Azure Boards
project to plan and track your work. Connect your project and repo so your GitHub
commits and pull requests get linked to your work items in Azure Boards.
７ Note
Azure Boards and Azure DevOps Services support integration with GitHub.com and
GitHub Enterprise Server repositories. If you want to connect from an on-premises
Azure DevOps Server, see Connect Azure DevOps Server to GitHub Enterprise
Server.
Prerequisites
You must have an Azure Boards or Azure DevOps project. If you don't have a
project yet, create one.
You must be a member of the Project Administrators group. If you created the
project, you have permissions.
You must be an administrator or owner of the GitHub repository to connect to. You
can connect to multiple GitHub repositories as long as you're an administrator for
those repositories.
Authentication options
The following authentication options are supported based on the GitHub platform you
want to connect to.
GitHub.com
GitHub Enterprise Server
GitHub.com user account (Recommended)

Personal access token (PAT)
OAuth (preferred, registration required)
PAT
Username plus password
７ Note
If you choose to connect Github with PAT, make sure you configure single sign-on
(SSO) for the PAT on your GitHub account. This is needed to be able to get a list of
repositories of an organization with Security Assertion Markup Language (SAML)
SSO authentication configured.
Connect Azure Boards to a GitHub repo.

1. Sign into your Azure DevOps project.
2. Select Project settings > GitHub connections.

3. If it's the first time you make a connection from the project, choose Connect your
GitHub account to use your GitHub account credentials.
Otherwise, choose New connection, and select your authentication method
from the New Connection dialog.
When you connect using your GitHub account, use your GitHub account
credentials to authenticate. To use PAT, see Add a GitHub connection using PAT. To
connect to a GitHub Enterprise Server, see Register Azure DevOps in GitHub as an
OAuth App.
Add a GitHub connection with GitHub

credentials
You can connect up to 250 GitHub repositories to an Azure Boards project.
1. If it's your first time connecting to GitHub from Azure Boards, you're asked to sign
in using your GitHub credentials. Choose an account for which you're a repository
administrator.
2. Choose the GitHub account or organization that you want to connect. Only those
organizations that you own or are an administrator for are listed.
If all repositories for an organization have already been connected to Azure

Boards, you see the following message.
3. Enter your GitHub credentials. If you have two-factor authentication enabled, enter
the authentication code that GitHub sent you and choose Verify. Otherwise, the
system automatically recognizes your GitHub organization as your GitHub account
has previously been associated with your Azure DevOps Services account.
Choose the repositories

Once you're authenticated, you can select the repositories you want to connect.
1. The Add GitHub Repositories dialog automatically displays and selects all
GitHub.com repositories for which you're an administrator for the organization you
selected. Unselect any repositories that you don't want to participate in the
integration.
 Tip
We recommend that you only connect a GitHub repo to projects defined in a

single Azure DevOps organization. Connecting the same GitHub repo to
projects defined in two or more Azure DevOps organizations can lead to
unexpected AB# mention linking. For more information, see Troubleshoot
GitHub & Azure Boards integration.
If all repositories are connected already to the current or other organization, then
the following message displays.
Confirm the connection

1. Review the GitHub page that displays and then choose Approve, Install, &
Authorize.
2. Provide your GitHub password to confirm.
3. When you're done, you should see the new connection with the selected
repositories listed.
To change the configuration or manage the Azure Boards app for GitHub, see Change
repository access to Azure Boards.
Add a GitHub connection using PAT

We recommend that you use your GitHub account credentials to connect to your
GitHub repository. However, if you need to use a PAT, do so by following these
procedures.
 Tip
When you create your GitHub PAT, make sure that you include these scopes: repo,
read:user, user:email, admin:repo_hook .
1. Choose Personal Access Token.
To create a GitHub PAT, go to GitHub Developer Settings > Personal access

tokens .
2. Enter the PAT and choose Connect.
3. Choose the repositories you want connected to the project by following the
procedures outlined in Choose the repositories earlier in this article.
4. If it's the first time connecting to a GitHub account or organization from Azure
Boards, you also must install the Azure Boards app for GitHub. Confirm the
connection earlier in this article.
Register Azure DevOps in GitHub as an OAuth

App
If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Server,
you first need to register the application as an OAuth App. For more information, see
Create an OAuth App .
Register Azure DevOps Services

1. Sign into the web portal for your GitHub Enterprise server.
2. Open Settings > Developer settings > Oauth Apps > New OAuth App.
3. Enter information to register your application.
For the Homepage URL, specify the Organization URL of your organization.
For the Authorization callback URL, use the following pattern to construct the
URL.
{Azure DevOps Services Organization URL}/_admin/oauth2/callback
For example:
https://dev.azure.com/fabrikam/_admin/oauth2/callback
4. Select Register application.
5. The Client ID and Client Secret for your registered OAuth application appear.
Register your OAuth configuration in Azure DevOps
Services
1. Sign into the web portal for Azure DevOps Services.
2. Add the GitHub Enterprise Oauth configuration to your organization.
3. In Organization settings, select Oauth configurations > Add Oauth configuration.

4. Enter your information, and then select Create.
Connect Azure DevOps Services to GitHub
Enterprise Server
） Important
To connect Azure DevOps Services to your GitHub Enterprise Server, your GitHub
Enterprise Server must be sufficiently accessible from the Internet. Make sure Azure
DNS can resolve your GitHub Enterprise Server name and your firewall allows
access from Azure Data Center IP addresses. To determine the IP address range, see
Microsoft Azure Data Center IP Ranges . A common error message encountered
when connectivity issues exist is:
The remote name could not be resolved: 'github-enterprise-server.contoso.com'
If you encounter this error, check that your server is accessible. For more
information, see Azure DNS FAQ.
1. Select Project settings > GitHub connections > GitHub Enterprise Server for a
first-time connection.
Or, from the New GitHub connection dialog, select GitHub Enterprise Server.
2. Select the authentication method.
Connect with OAuth

Choose the configuration that you set up in Step 4 of Register your OAuth
configuration in Azure DevOps Services, and then choose Connect.
Connect with a Personal Access Token
Enter the URL for your GitHub Enterprise server and the Personal access token
credentials recognized by that server. And then choose Connect.
Connect with a Username and Password

Enter the URL for your GitHub Enterprise server and the administrator account
credentials recognized by that server, and then select Connect.
3. The dialog lists all repositories for which you have GitHub administration rights.
You can toggle between Mine and All to determine if others appear, and then
check the ones that you want to add. Select Save when you're done.
 Tip
You can only make a connection to repositories defined under one GitHub
organization. To connect a project to other repositories defined in another
GitHub organization, you must add another connection.
4. If it's your first time connecting to a GitHub account or organization from Azure
Boards, you also install the Azure Boards app for GitHub. Confirm the connection
Resolve connection issues

The Azure Boards-GitHub integration relies on various authentication protocols to
support the connection. Changes to a user's permission scope or authentication
credentials can cause revocation of the GitHub repositories connected to Azure Boards.
For an overview of the integration that the Azure Boards app for GitHub supports, see
Azure Boards-GitHub integration.
Supported authentication options

The following authentication options are supported based on the GitHub platform you
want to connect to.
Platform
GitHub.com
GitHub Enterprise Server

GitHub.com user account
Personal access token (PAT)
OAuth
PAT
Not applicable
PAT
Not applicable
OAuth
PAT
７ Note
With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services
support integration with GitHub.com and GitHub Enterprise Server repositories.
Azure DevOps Servers 2019 and later versions support integration with GitHub
Enterprise Server repositories only.Integration with other Git repositories is not
supported.
Grant Azure Boards organization access
If the integration between Azure Boards and GitHub isn't working as expected, verify
you've granted organization access.
1. From GitHub web portal, open Settings from your profile menu.
2. Select Applications under Integrations > Authorized OAuth Apps > Azure
Boards.
3. Under Organization access, resolve any issues that may appear. Select Grant to
grant access to any organizations that show as having an Access request pending.
Resolve access issues
When the Azure Boards connection to GitHub no longer has access, it shows an alert
status in the user interface with a red-X. Hover over the alert and it indicates that the
credentials are no longer valid. To correct the problem, remove the connection and
recreate a new connection.
To resolve this issue, consider the following items:
If the connection is using OAuth:
The Azure Boards application had its access denied for one of the repositories.
GitHub might be unavailable/unreachable. This unavailability could be because

of an outage in either service or an infrastructure/network issue on-premises.
You can check service status from the following links:
GitHub
Azure DevOps
Delete and recreate the connection to the GitHub repository. This recreated
connection causes GitHub to prompt to reauthorize Azure Boards.
If the connection is using a PAT:

The PAT may have been revoked or the required permission scopes changed
and are insufficient.
The user may have lost admin permissions on the GitHub repo.
Recreate the PAT and ensure the scope for the token includes the required
permissions: repo, read:user, user:email, admin:repo_hook .
Resolve broken GitHub Enterprise Server connection

If you've migrated from Azure DevOps Server to Azure DevOps Services with an existing
GitHub Enterprise Server connection, your existing connection won't work as expected.
Work item mentions within GitHub may be delayed or never show up in Azure DevOps
Services. This problem occurs because the callback url associated with GitHub is no
longer valid.
Consider the following resolutions:
Remove and re-create the connection: Remove and re-create the connection to
the GitHub Enterprise Server repository. Follow the sequence of steps provided in
Connect from Azure Boards documentation.
Fix the webhook url: Go to GitHub's repository settings page and edit the
webhook url to point out to the migrated Azure DevOps Services organization url:
https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-
preview
Connect to multiple Azure DevOps organizations
If you connect your GitHub repository to two or more projects that are defined in more
than one Azure DevOps organization, such as dev.azure.com/Contoso and
dev.azure.com/Fabrikam, you may get unexpected results when using AB# mentions to
link to work items. This problem occurs because work item IDs aren't unique across
Azure DevOps organizations, so AB#12 can refer to a work item in either the Contoso or
Fabrikam organization. So, when a work item is mentioned in a commit message or pull
request, both organizations attempt to create a link to a work item with a matching ID
(if one exists).
In general, a user intends an AB# mention to link to a single work item in one of the
projects. But, if a work item of the same ID exists in both accounts, then links get
created for both work items, likely causing confusion.
Currently, there's no way to work around this issue, so we recommend that you connect
a single GitHub repository only to a single Azure DevOps organization.
７ Note
When you make the connection by using the Azure Boards app for GitHub, the app
prevents you from connecting to two different organizations. If a GitHub repository
is incorrectly connected to the wrong Azure DevOps organization, you must
contact the owner of that organization to remove the connection before you can
add the repository to the correct Azure DevOps organization.
Update XML definitions for select work item types

If your organization uses the Hosted XML or On-premises XML process model to
customize the work tracking experience and you want to link to and view the GitHub
link types from the Development section in the work item forms, you'll need to update
the XML definitions for the work item types.
For example, if you want to link user stories and bugs to GitHub commits and pull
requests from the Development section, you need to update the XML definitions for
user stories and bugs.
Follow the sequence of tasks provided in Hosted XML process model to update the XML
definitions. For each work item type, find the Group Label="Development" section, and
add the following two lines in the following code syntax to support the external links
types: GitHub Commit and GitHub Pull Request.
XML
<ExternalLinkFilter Type="GitHub Pull Request" />

<ExternalLinkFilter Type="GitHub Commit" />
When it's updated, the section should appear as follows.
XML
<Group Label="Development">
<Control Type="LinksControl" Name="Development">
<LinksControlOptions ViewMode="Dynamic"
ZeroDataExperience="Development" ShowCallToAction="true">
<ListViewOptions GroupLinks="false">
</ListViewOptions>
<LinkFilters>
<ExternalLinkFilter Type="Build" />
<ExternalLinkFilter Type="Integrated in build" />
<ExternalLinkFilter Type="Pull Request" />
<ExternalLinkFilter Type="Branch" />
<ExternalLinkFilter Type="Fixed in Commit" />
<ExternalLinkFilter Type="Fixed in Changeset" />
<ExternalLinkFilter Type="Source Code File" />
<ExternalLinkFilter Type="Found in build" />
<ExternalLinkFilter Type="GitHub Pull Request" />
<ExternalLinkFilter Type="GitHub Commit" />
</LinkFilters>
</LinksControlOptions>
</Control>
</Group>
Next steps
Related articles
Install and configure the Azure Boards app for GitHub
Configure status badges to add to GitHub README files
Troubleshoot GitHub & Azure Boards integration
Build GitHub repositories
Change GitHub repository access
Trigger an Azure Pipelines run from GitHub Actions
Link GitHub commits, pull requests, and
issues to work items in Azure Boards
Article • 07/03/2023
Once you connect your Azure Boards project with a GitHub repository, you can link work
items to your GitHub commits and pull requests. You can add links using the #mention
syntax familiar to GitHub users or you can add a GitHub commit or GitHub pull request
link type from the Azure Boards work item.
７ Note
With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services
support integration with GitHub.com and GitHub Enterprise Server repositories.
Azure DevOps Servers 2019 and later versions support integration with GitHub
Enterprise Server repositories only.Integration with other Git repositories is not
supported.
Prerequisites
Your Azure Boards project must be connected to the GitHub repository where the
commits and pull requests you want to link to/from exist. For more information,
see Azure Boards-GitHub integration.
You must be a Contributor to Azure Boards project and to the GitHub repository.
７ Note
Projects that use the Hosted XML process model require updates to the work item
types to view the Development section and GitHub link types. For more
information, see Update XML definitions for select work item types.
Use AB# to link from GitHub to Azure Boards

work items
From a GitHub commit, pull request or issue, use the following syntax to create a link to
your Azure Boards work item. Enter the AB#ID within the text of a commit message. Or,
for a pull request or issue, enter the AB#ID within the title or description (not a
comment).
AB#{ID}
For example, AB#125 links to work item ID 125.
You can also enter a commit or pull request message to transition the work item. The
system recognizes fix, fixes, fixed and applies it to the #-mention item that follows.
Mentioned work items transition to the first State associated with the Resolved workflow
category state. If there's no State associated with Resolved, then it transitions to the
State associated with the Completed workflow category state. To understand how
workflow states and category states are mapped, see How workflow category states are
used in Azure Boards backlogs and boards.
See the following table of examples.
Commit or pull Action

request message
Fixed AB#123 Links and transitions the work item to the Resolved workflow state
category or, if none is defined, then the Completed workflow state
category.
Adds a new feature, Links and transitions the work item to the Resolved workflow state
fixes AB#123. category or, if none is defined, then the Completed workflow state
category.
Fixes AB#123, Links to Azure Boards work items 123, 124, and 126. Transitions only the
AB#124, and AB#126 first item, 123 to the Resolved workflow state category or, if none is
defined, then the Completed workflow state category.
Fixes AB#123, Fixes Links to Azure Boards work items 123, 124, and 126. Transitions all items
AB#124, Fixes to either the Resolved workflow state category or, if none is defined, then
AB#125 the Completed workflow state category.
Fixing multiple Links to GitHub issue 123 and Azure Boards work item 234. No transitions
bugs: issue #123 are made.
and user story
AB#234
７ Note
If you connected the same GitHub repo to projects defined in two or more Azure
DevOps organizations, you may see unexpected AB# mention linking. For more
information, see Resolve connection issues. For this reason, we recommend that
you only connect a GitHub repo to projects defined in a single Azure DevOps
organization.
Add link from a work item to a GitHub commit,

pull request, or issue
1. To link to a commit or pull request, open the work item and choose Add link under
the Development section.
To link to an issue, choose the Links tab, and then choose Add Link>Existing item.
2. From the Add link dialog, select one of the GitHub link types, enter the URL to the
commit, pull request, or issue and then choose OK.
Here, we add a link to a GitHub pull request.
Azure Boards completes a check to ensure that you've entered a valid link. The
linked-to GitHub repository must be connected to the Azure Boards project or the
validation fails.
View or open links from the Development

section
The Development section within the work item form lists the links created to GitHub
commits and pull requests with the GitHub icon.
Choose the link provided to open the commit or pull request in GitHub.
View GitHub objects on Kanban board

With GitHub annotations enabled on the Kanban board, you can quickly open linked
GitHub commits, pull requests, or issues for more detail. For more information, see
Customize cards.
Next steps
Related articles
Add or remove repositories
Azure Boards-GitHub integration
How workflow category states are used in Azure Boards backlogs and boards
Add status badges for your GitHub repo
Article • 07/12/2023
You can add Markdown syntax to a GitHub repo README.md file to display your Kanban
board status in that repo. Show the status by adding the syntax you choose from your
Kanban board settings.
The syntax shown works whether you connected your project to a GitHub.com or your
GitHub Enterprise Server repository. For GitHub Enterprise Server, your server must be
network accessible to Azure DevOps Services.
Prerequisites
Your Azure Boards project must be connected to the GitHub repository where the
commits and pull requests you want to link to/from exist. For more information,
see Azure Boards-GitHub integration.
You must have a Kanban board you want to configure. When you add a team, you
add a Kanban board for that team. For more information, see About teams and
Agile tools.
You must be added to the team administrator role for the team's settings you want
to modify, or be a member of the Project Administrators security group. To get
added, see Add a team administrator or Change project-level permissions.
To add the status badge to the GitHub.com repository, you must be a contributor
of the repository.
Add a status badge

1. Sign into Azure Boards and open your Kanban board.
3. Select Status badge and then check or uncheck the Allow anonymous users to
access the status badge. When it's unchecked, users who aren't signed in can still
view the status badge.
4. Choose the badge type you want and choose the copy icon to copy the
Markdown syntax for the badge.
Show "In progress" columns only ignores the first and last columns.
Include all columns includes the first and last columns of the board.
You can customize the set of columns by specifying 2 for the columnOptions
and then a comma-delimited list of the board columns to appear. For
example, ?
columnOptions=2&columns=Proposed,Committed,In%20Progress,In%20Review , as
shown in the following syntax. For column labels that include spaces, you
must encode the space with %20 . For example, In%20Progress .
[![Board Status](https://dev.azure.com/fabrikam/677da0fb-b067-4f77-
b89b-f32c12bb8617/cdf5e823-1179-4503-9fb1-
a45e2c1bc6d4/_apis/work/boardbadge/6fa7b56f-d27c-4e96-957d-
f9e7b0f56705?
columnOptions=2&columns=Proposed,Committed,In%20Progress,In%20Review)]
(https://dev.azure.com/fabrikam/677da0fb-b067-4f77-b89b-
f32c12bb8617/_boards/board/t/cdf5e823-1179-4503-9fb1-
a45e2c1bc6d4/Microsoft.RequirementCategory/)
A badge similar to the following displays.
The only setting that you can configure is the Allow anonymous users to access
the status badge. The badge type under Settings only switches the Markdown
syntax for you to copy from the Sample Markdown and Image URL values.
6. Open the README file in your GitHub repo and paste the syntax you copied to
make the badge display.
You should see the same preview image that you selected with values that
correspond to your Kanban board.
Related articles
Customize cards
Configure team settings
Azure Boards-GitHub integration
Enable DevSecOps with Azure and
GitHub
Article • 11/28/2022
DevSecOps, sometimes called Secure DevOps, builds on the principles of DevOps but
puts security at the center of the entire application lifecycle. This concept is called “shift-
left security”: it moves security upstream from a production-only concern to encompass
the early stages of planning and development. Every team and person that works on an
application is required to consider security.
Microsoft and GitHub offer solutions to build confidence in the code that you run in
production. These solutions inspect your code and allow its traceability down to the
work items and insights on the third-party components that are in use.
Secure your code with GitHub

Developers can use code scanning tools that quickly and automatically analyze the code
in a GitHub repository to find security vulnerabilities and coding errors.
You can scan code to find, triage, and prioritize fixes for existing problems. Code
scanning also prevents developers from introducing new problems. You can schedule
scans for specific days and times, or trigger scans when a specific event occurs in the
repository, such as a push. You can also track your repository's dependencies and
receive security alerts when GitHub detects vulnerable dependencies.
Scan your code with CodeQL and token scanning

Manage security advisories for your projects
Secure your code's dependencies with Dependabot
Track your work with Azure Boards

Teams can use Azure Boards web service to manage software projects. Azure Boards
provides a rich set of capabilities, including native support for Scrum and Kanban,
customizable dashboards, and integrated reporting.
Plan and track work with Azure Boards

Connect Azure Boards with GitHub
Build and deploy containers with Azure
Pipelines
Integrate Azure Pipelines and Kubernetes clusters with ease. You can use the same YAML
documents to build multi-stage pipelines-as-code for both continuous integration and
continuous delivery.
Azure Pipelines integrates metadata tracing into your container images, including
commit hashes and issue numbers from Azure Boards, so that you can inspect your
applications with confidence.
The ability to create deployment pipelines with YAML files and store them in source
control helps drive a tighter feedback loop between development and operation teams
who rely on clear, readable documents.
Store Docker images in Azure Container Registry

Build a Docker image with Azure Pipelines
Deploy to Kubernetes with full traceability
Secure your Azure Pipelines
Run and debug containers with Bridge to

Kubernetes
Developing a Kubernetes application can be challenging. You need Docker and
Kubernetes configuration files. You need to figure out how to test your application
locally and interact with other dependent services. You might need to develop and test
multiple services at once and with a team of developers.
Bridge to Kubernetes allows you to run and debug code on your development
computer, while still connected to your Kubernetes cluster with the rest of your
application or services. You can test your code end-to-end, hit breakpoints on code
running in the cluster, and share a development cluster between team members without
interference.
Learn more about Bridge to Kubernetes
Enforce container security with Microsoft

Defender for Containers and Azure Policy
Microsoft Defender for Containers is the cloud-native solution for securing your
containers.
Overview of Microsoft Defender for Containers

Understand Azure Policy for Kubernetes clusters
Azure Kubernetes Service (AKS)
Manage identities and access with the

Microsoft identity platform
The Microsoft identity platform is an evolution of the Azure Active Directory (Azure AD)
developer platform. It allows developers to build applications that sign in all Microsoft
identities and get tokens to call Microsoft APIs, such as Microsoft Graph, or APIs that
developers have built.
Microsoft identity platform documentation
Azure AD B2C provides business-to-customer identity as a service. Your customers use

their preferred social, enterprise, or local account identities to get single sign-on access
to your applications and APIs.
Azure AD B2C documentation
Access management for cloud resources is a critical function for any organization that
uses the cloud. Azure role-based access control (Azure RBAC) helps you manage who
has access to Azure resources, what they can do with those resources, and what areas
they can access.
Learn about access management with Azure RBAC
You can use the Microsoft identity platform to authenticate with the rest of your DevOps
tools, including native support within Azure DevOps and integrations with GitHub
Enterprise.
Authenticate to GitHub Enterprise
Currently, an Azure Kubernetes Service (AKS) cluster (specifically, the Kubernetes cloud
provider) requires an identity to create additional resources like load balancers and
managed disks in Azure. This identity can be either a managed identity or a service
principal. If you use a service principal, you must either provide one or AKS creates one
on your behalf. If you use managed identity, one will be created for you by AKS
automatically. For clusters that use service principals, the service principal must be
renewed eventually to keep the cluster working. Managing service principals adds
complexity, which is why it's easier to use managed identities instead. The same
permission requirements apply for both service principals and managed identities.
Managed identities are essentially a wrapper around service principals, and make their
management simpler.
Use managed identities in AKS
Manage keys and secrets with Azure Key Vault

Azure Key Vault can be used to securely store and control access to tokens, passwords,
certificates, API keys, and other secrets. Centralizing storage of application secrets in Key
Vault allows you to control their distribution. Key Vault greatly reduces the chances that
secrets may be accidentally leaked. When you use Key Vault, application developers no
longer need to store security information in their application, which eliminates the need
to make this information part of the code. For example, an application may need to
connect to a database. Instead of storing the connection string in the app's code, you
can store it securely in Key Vault.
Store certificates, keys, and secrets with Azure Key Vault
Monitor your applications

With Azure Monitor, you can monitor both your application and infrastructure in real-
time, identifying issues with your code and potential suspicious activities and anomalies.
Azure Monitor integrates with release pipelines in Azure Pipelines to enable automatic
approval of quality gates or release rollback based on monitoring data.
Learn how to monitor your applications and infrastructure using Azure Application
Insights and Azure Monitor.
Application performance management with Application Insights

Monitor containerized applications with Azure Monitor
Build the right architecture

Security is one of the most important aspects of any architecture. Security provides
confidentiality, integrity, and availability assurances against deliberate attacks and abuse
of your valuable data and systems. Losing these assurances can negatively impact your
business operations and revenue, as well as your organization’s reputation in the
marketplace.
Applications and services architecture
DevSecOps architecture
Migrate and integrate work tracking
data in Azure Boards
Article • 07/31/2023
2018
You have a choice of tools to help you migrate your work tracking data to the Azure
DevOps platform. This article provides an overview of what's available and links to tools
that support migration of work tracking data and processes. You can also integrate
Azure Boards with many third-party tools and extensions.
７ Note
With Azure DevOps Marketplace extensions for Azure Boards , you can
customize and enhance the default experience. See a list of recommended
extensions for Azure Boards, further in this article.
Migrate from an on-premises Azure DevOps

server
The data migration tool for Azure DevOps provides a high fidelity way to migrate
collection databases from Azure DevOps Server to Azure DevOps Services. For more
information, see Migrate data from Azure DevOps Server to Azure DevOps Services.
Migrate data between Azure DevOps Projects

The Azure DevOps Migration Tools marketplace extension allows you to bulk edit and
migrate data between Azure DevOps Projects on both on-premises and the cloud. This
tool supports the following tasks:
Migrate work items from one project to another project and synchronize changes
after a migration
Merge many projects into a single project
Split one project into many projects
Assist changing process templates
Edit work items in bulk
Migrate test suites and test plans
For more information, see Azure DevOps Migration Tools and OADOM .
OpsHub Azure DevOps Migrator (OADOM), formerly known as OpsHub Visual Studio
Migration Utility(OVSMU), gives a seamless migration between Azure DevOps Server
and Azure DevOps Services. Migrate projects from DevOps Services to a collection on
DevOps Server including:
All version control information and history

All work items and history
All test cases and test results
Supports Team Foundation Server 2018 and Azure DevOps Server versions 2019,
2020, and 2022
Supports Azure DevOps Services
Migrate process models between Azure

DevOps organizations
The Process Tools for Azure DevOps marketplace extension provides support to
complete the following tasks:
Migrate Inherited Processes between Organizations

Upload an On-premises XML process model from an export
For constraints on process template definitions that you can import, see Resolve
validation errors for process import.
Migrate between legacy tools and Azure

DevOps
OpsHub Migration Manager supports full fidelity large-scale data migration projects
out of the box between legacy or ALM tools and Azure DevOps. OMM offers the
following benefits:
Zero downtime migration or nondisruptive migration

Factory approach for large-scale migration projects
Full fidelity migration with history preservation for all artifacts, comments,
attachments, and relationships
Export and import work tracking data

The main tool you can use to import work tracking data you've exported from elsewhere
is Microsoft Excel. Excel supports publishing a flat list of work items or a hierarchical tree
of parent-child linked work items. For more information, see Bulk add or modify work
items with Excel.
If you want to migrate from Jira to Azure Boards, consider using the Marketplace
extension, Jira to Azure DevOps work item migration tool . This tool provides support
for the following tasks:
Export Jira issues from Jira queries

Map users from Jira to users in Azure DevOps
Migrate work item field data
Migrate links and attachments
Migrate history
Integrate with GitHub

Azure Boards and Azure DevOps Server 2019 integrate with GitHub. Connect Azure
Boards with GitHub repositories to link between GitHub commits, pull requests, and
issues to work items. You can use GitHub for software development while using Azure
Boards to plan and track your work.
For more information, see Connect Azure Boards to GitHub.
Integrate with third-party tools using service

hooks
You can integrate Azure Boards with other third-party tools such as Jenkins and Trello.
Using service hooks you can generate actions based on Azure DevOps events. For more
information, see the following articles:
Create a service hook for Azure DevOps with Jenkins

Create a service hook for Azure DevOps with Trello
Integrate with service hooks
Project and portfolio management

The following tools support integration and synchronization with Azure DevOps with
one or more project and portfolio management tools. These tools also support
integration between Azure Boards and Microsoft Project Online or Microsoft Project
Server.
OpsHub Integration Manager(OIM) is an enterprise class integration platform. It

enables bi-directional synchronization for Azure DevOps(Server and Services) with
50+ ALM, DevOps, Project, and Portfolio Management tools out of the box. It
enables synchronization of all work items including test artifacts with an easy to
use mapping UI and is scalable for any number of projects and teams.
ConnectAll helps organizations achieve effective Value Stream Management by
connecting the applications used to collaborate, drive decisions, and manage
artifacts that are used during the software delivery process, like ALM, Agile, and
DevOps.
Project Connect offers a seamless approach to exchange critical information
between development teams and project teams using Microsoft Project Online and
Extensions for Azure Boards
Product planning
For more information, see Review team Delivery Plans.
Azure DevOps Open in Excel

Epic Roadmap extension , Feature Timeline (Deprecated)
Feature Timeline extension , Feature Timeline (Deprecated)
Retrospectives
Split!
Team Calendar
Reactivations Report
Customizing work item types

Cascading Lists
Clickable Links
Color picklist control
Multi-value control
Work item form control library
Work item form one-select actions
Work Item Visualization
WSJF (Weighted Shortest Job First)
Querying and reporting
Open in Power BI
Query Based Boards
Tags Manager
Wiql Editor
Wiql to OData
Dashboard widgets
Azure Application Insights Widgets
Countdown Widget
GitHub Stats Widget
Work Item Details Widget
Roll-up Board Widget
Command-line interface
Azure DevOps CLI
Azure Boards Teams Tool CLI
Automation and miscellaneous tools

Azure Boards Kanban Tools
Migration Tools for Azure DevOps
Microsoft Flow, Power Apps and Power Automate
Power Automate, Azure DevOps
Related articles
Bulk add or modify work items with Microsoft Excel
Plan and track dependencies using the
Dependency Tracker
Article • 02/24/2023
７ Note
We recommend that you use Delivery Plans to track dependencies instead of

Dependency Tracker. The Dependency Tracker extension is not a supported feature
of Azure Boards and isn't supported by any product team. For questions,
suggestions, or issues you have when using the extension, visit the Marketplace for
Azure DevOps, Dependency Tracker extension page. The Dependency Tracker
extension is only available on Azure DevOps Services.
The Dependency Tracker extension enables management of dependencies across teams,

projects, and organizations. It provides filterable views to show all dependencies a team
is consuming and producing. These views allow you to track the state and schedule of
dependencies to support you in assessing the risk of dependencies to product
deliverables.
You use the Dependency Tracker to plan dependencies at the beginning of an iteration
or release, and to track the status during development. For any given dependency, there
are two parties involved:
Consumer: Feature team who has a need and starts a request for work
Producer: Feature team who makes a commitment to deliver work
Each work request and work deliverable is defined as a work item. The work items are
linked by the Successor-Predecessor link type or other directional link type. For details
about link types, see Link type reference Producing for/Consuming from link.
 Tip
While any work item type can participate in dependency tracking, you may want to
decide if you want to limit dependencies to specific types, such as Features, Epics,
User Stories, or Bugs. You can create that restriction through Configuration of
Dependency Tracker.
From the Dependency Tracker, you can choose different views and filters, and drill down
to obtain specific details. These views and options are described in the following
sections:
Filter options
Drill-down
Consuming Dependencies
Producing Dependencies
Timeline
Risk Graph
Recommended use and key terms

You can use Dependency Tracker to visualize and track the following work items:
Dependencies on deliverables for work that your team is delivering

Dependencies you have on other teams for work that your team is delivering
Dependencies that other teams have on work your team is delivering
All teams across organizations can participate in tracking dependencies.
７ Note
Dependency Tracker doesn't replace the in person interactions required to agree to

doing the work. It provides easier planning and tracking capabilities. Dependencies
should be agreed upon by all parties before they are entered in to the Dependency
Tracker.
Key terms
Dependency: work that Team A requires from Team B to do the work Team A is
trying to do
Consumer: the team that wants work done
Producer: the team that is being asked to do the work
Sequencing: when a producing team's work is needed before the consuming team
can start their work
Recommended practices
The consumer is the team that asks for the work – they start all discussions on the
work they require
The consumer owns the engagement and tracking of that work – since it's the
work their scenario requires, the burden is on the consumer to file, monitor, and
track the status of the work
The consumer owns entering the work into Azure Boards and submitting that work
request to the producer
Once the work has been submitted to the producer, the producer owns the work
item,
The producer is responsible for maintaining the work item in Azure Boards
The producer owns the state of the work item and iteration
The consumer shouldn't touch these values, once the work item has been
handed off
The consumer is in charge of managing the work they requested so that they're
aware of any material changes and adjustments
Prerequisites
Install the Dependency Tracker extension for the organization(s) for which you
want to track dependencies.
To view dependencies, you must be a member of the Project Valid Users group for
the project.
To create a dependency, you must be a member of the Contributors group for
both projects that participate in the dependency linking.
To support cross-organization participation, all organizations must authenticate
users through the same Azure Active Directory.
Azure Boards must be enabled as a service. If it's disabled, then you'll need to have
it reenabled. For more information, see Turn a service on or off.
To modify the configuration, you must be a member of the Project Collection
Administrator Group.
） Important
The default configuration for Dependency Tracker supports the Agile process. If
your project(s) are based on a different process or you have customized your
process, you may need to modify the configuration. See Configure the
Dependency Tracker later in this article.
Also, the following configuration or customization tasks should be performed:
Set up the area paths and teams to participate in dependency tracking.

Configure iteration paths/sprints for the project and assign them to work items
participating in dependency tracking. This task is essential for the Timeline view to
yield meaningful data.
Customize your process as needed to support any other work items or fields.
Configure the Dependency Tracker to support your business needs and address
any customizations you've made.
Open the Dependency Tracker

1. Open the web portal for the project where your team is defined.
2. Choose Dependency Tracker from under the Boards group.
3. To focus on your area of ownership, choose the Area that corresponds to the team
you want to view dependencies for.
You can only filter on those Area paths defined for the project.
Filter options
You can filter each supported view by entering a keyword or using one or more of the
fields. Provided fields include State, Work item type, and Iteration Path. Based on the
keyword that you enter, the filter function lists work items based on any displayed
column field.
To show the filter toolbar, choose the filter icon.
You can toggle filters on and off by choosing the filter icon. To see more filters use the
arrows at the end of the list of filters.
Choose one or more values from the multi-select drop-down menu for each field. The
values for these fields are populated as follows:
State: Check one or more check boxes for the work item states you want to view.
The drop-down list should include all workflow States defined for all work item
types shown in the selected view.
Work item type: Check one or more check boxes for the Work item types you want
to view. Work item types configured to participate in dependency tracking. The
default work item types are: Epic, Feature, User Story, and Bug. To modify the
configuration, see Configuration of Dependency Tracker.
Iteration: Check one or more check boxes for the Iteration Paths you want to view.
The drop-down list should include all Iteration Paths configured for the project and
for which there are work items listed in the current view.
Priority: Check one or more check boxes for the Priorities you want to view. The
priority values assigned to work items
Partner: The partner organization for which the work item is defined.
７ Note
Filter options are dependent on the configuration defined for the Dependency
Tracker. Also, only those options that correspond to work items shown in the
selected view that meet the filter criteria. For example, if you don't have any work
items assigned to Sprint 4, then the Sprint 4 option won't appear in the filter
options for the Iteration Path.
Ability to drop dependencies within the selected area (used for excluding dependencies
inside my team)
View drill-down options

Several views provide interactive visualizations through drill-downs. These features are
addressed in the tabbed views descriptions later in this article.
Create a dependency
A dependency represents work where one team is dependent on another team. Both
teams should track their own work in their own area path. By linking the work that is
dependent on the other teams work, the dependencies can be visualized and tracked.
1. Choose New Dependency.
If the partner team is in a different organization, then first choose the Partner
Account. The Partner Account option can be enabled or disabled by configuring
the Dependency Tracker.
2. You can search for work items by ID or by entering a keyword contained within the
work item title. Here, we link a user story and a bug.
The Producer is the team that commits to delivering the work.

The Consumer is the team that needs or is dependent on the work.
The fastest way to create a dependency link is to type the Producer and
Consumer work item IDs in the search boxes and then choose Save.
Optionally, you can choose Create New to add work items that you then link as
dependent upon each other. Here we create two new features and link them.
If no work items exist for one half of the dependency, you can create a new work
item as needed.
3. Choose Save. The Save button becomes available only after you've chosen two
work items to link.
4. From the success confirmation dialog, choose View dependency.
5. The work items that you linked are highlighted.
As shown in this example, the Fabrikam Fiber/Service Delivery/Voice team is

dependent on the MyFirstProject team to deliver their User Story 706: Cancel
order form to complete Bug 390: Cancel order form .
Create links manually
You can also link work items using the Links tab to create Successor/Predecessor links. A
Predecessor is the producer of the work item, or the item that must come first. A
Successor is the consumer of the work item, or the item that is dependent on the first
item.
７ Note
The Successor/Predecessor (consumes/produces) link types are the default link
types used by the Dependency Tracker. If you're projects are customized using a
Hosted XML process model, it's possible to specify different link types in the
Dependency Tracker configuration. See Configure the Dependency Tracker later in
this article.
For more information, see Link user stories, issues, bugs, and other work items.
Remove dependency links

You can remove a dependency by choosing the actions icon from the linked work
item and choose Remove Dependency Link option from the menu.
Optionally, you can remove the link from the work item's Links tab.
Create a query of dependencies

To open a set of dependent work items, select them in the same way you would via a
bulk edit, choose the actions icon from one of the selected linked work items and
choose Open in Query option from the menu.
A new tab opens to the Query Results page.

You can also create a custom query by selecting the Work items and direct links query
type and choose any work item type.
Choose Copy to HTML to copy the selected work items to the clipboard as a formatted
table.
Consuming Dependencies view

The Consuming Dependencies view shows work that a team is dependent upon other
teams/area paths. It's useful for answering the following questions:
Which dependencies am I consuming as the owner of the selected areas and sub
areas?
How many dependencies per producer team (by area level 3)?
What are the workflow states of my consumer dependencies?
Each column on the bar chart represents another area path that is producing
dependencies by workflow state for the selected Area View. The table shows the
number of unique dependencies. It also lists all work items participating in the filtered
view of tracked dependencies.
Within the table, you can complete the following actions.

Filter the list of work items by choosing one of the area path bars and progress
states in the bar chart graph
Expand or collapse the list of work items to show the full list of dependent work
items using the expand and collapse icons
Add or remove column fields by opening Column Options
Switch the sequence of work items by choosing the Display: Consumer on top or
Producer on top
Producing Dependencies view

The Producing Dependencies view shows work that other teams/area paths are
dependent on per the selected area. It's useful for answering the following questions:
Which dependencies is my team responsible for delivering as the owner of the

selected area(s)?
How many dependencies exist per consumer team (by area level 3)?
What are the workflow states of my producer dependencies?
Each column on the bar chart represents another area path that is consuming
dependencies by workflow state for the selected Area View. The table shows the
number of unique dependencies and lists all work items included in the filtered view of
tracked dependencies.
Within the table, you can complete the same actions as in the Consuming Dependencies
view.
Timeline tab
The Timeline tab provides a calendar view of dependencies. The Timeline view is in Beta.
The Timeline view helps answering the following questions:
What is the sequence of dependencies within the time window.

What are all the deliverable dependencies against within the three-month time
window for a given team?
） Important
For the Timeline to show meaningful data, you must have assigned the dependent
work items to Iteration Paths, and the Iteration Paths must have start and end dates
assigned.
There are two versions of the Timeline view: Correct Flow and Incorrect Flow. Each
version shows the color-coded workflow state. Color codes can be customized within
the Dependency Tracker configuration.
Correct Flow view

The Correct Flow view shows those dependencies that are in the correct sequence.
Successor work items are scheduled to be completed after their predecessor work item.
Incorrect Flow view
The Incorrect Flow view shows those dependencies that are out of order. At least one
predecessor work item is scheduled to be completed after its successor work item.
Risk Graph
The Risk Graph provides a visualization of how dependencies flow from Consumer team
to Producer team, or from Producer to Consumers. The graph allows a team to, at a
glance, understand the number of dependencies and level of risks associated. Also, the
risk graph view demonstrates the value of linking dependencies and laddering them up
to Stories.
There are two views: Consuming From and Producing For. The workflow state color
coding is configurable. The width of the lines indicates how many dependencies exist in
that area, the thicker the link the more dependencies as indicated in the legend.
Consuming From
Producing For
Filtered on a specific dependency
You can drill down into specifics by choosing one of the dependencies.
Configure the Dependency Tracker
You must be a member of the Project Collection Administrator Group to modify the
configuration. All changes to the configuration apply to all projects defined in the
organization.
To change the configuration, choose the gear icon and modify the syntax listed.
Choose Save when you're done.
The main properties you can modify are summarized as follows:
The link types to use to create dependency links. Defaults are the
Successor/Predecessor link types. Only customize when you use the Hosted XML
process model to customize work tracking.
Work items and work item types
Work item types to participate in dependency tracking
Mapping of work item category states to colors
Mapping of work item workflow states and colors
Default field columns in dependency list tables
Default filter selections:
Selected dependency work item types
Selected Iteration Paths
Enabled options:
Timeline
New Dependency link
Cross account (organization) dependencies
Cross account dependency toggle default state
Risk graph configuration:
Work item state(s) associated with at risk (Red color) work items
Work item state(s) associated with neutral (Gray color) work items
Work item state(s) associates with on track (Green color) work items
For a full list and description, see the Property descriptions provided later in this section.
Enable or disable the New Dependency option

The newDependencyButtonEnabled property enables or disables the New Dependency link
option. When enabled, the link appears on the Dependency Tracker page. When
disabled, users can't create dependencies from the tracker, only review the
dependencies that have been created through other means. The default value is set to
true (enabled).
Enable or disable cross-organization linking

The crossAccountConfigs property enables or disables cross-organization dependency
linking from the New dependency dialog. The default value is set to true (enabled).
To disable, set the following syntax in the JSON configuration to false .
{
"crossAccountConfigs": {
"crossAccountDependencyEnabled": false,
"crossAccountDependencyToggleDefaultState": false, //default state for
cross account toggle
"crossAccountDependencyToggleOnText": "Cross-account dependencies on",
"crossAccountDependencyToggleOffText": "Cross-account dependencies off"}
}
Cross account linking requires the use of a special link type and should only be used in
coordination with the New Dependency option.
Property descriptions
The following table describes each of the property items specified in the configuration
file.
Property/Description
Default/Example
consumesLinkName
Specifies the link type used to create the link from producer to consumer.
System.LinkTypes.Dependency-Reverse
producesLinkName
Specifies the link type used to create the link from consumer to producer.
System.LinkTypes.Dependency-Forward
queryFields
Specifies the custom fields to use in place of the system fields used by the
dependency tracker to return linked work item results. By default. system reference
names are used to return values for the following fields:
areaPath - Area Path
assignedTo - Assigned To
id - ID
areapath - IterationID
areapath - Iteration Path
areapath - Priority
areapath - State
areapath - Tags
teamProject - Team Project
title - Title
workItemType - Work Item Type
If a custom field is used in place of one of the system fields, you specify the substitution
by entering:
{
title: "Custom.Title",
assignedTo: "Custom.AssignedTo"
}
dependencyWorkItemTypes
Specifies the work item types that participate in dependency tracking. From the
Create a dependency dialog, only those work item types listed can be created.
Default:
[
"Epic",
"Feature",
"User Story",
"Bug"
]
If using the Scrum process, you would change the entry to:
[
"Epic",
"Feature",
"Product Backlog Item",
"Bug"
]
selectedDependencyWorkItemTypes
Restricts the initial focus to just those work item types that the dependency tracker
displays or lists. Based on the default "Any", any work item type that contains a
dependency link type is displayed or listed. Users can change the focus through
filtering.
Default:
Any
To restrict the work item types to just Epics and Features, specify:
[
"Epic",
"Feature"
]
selectedReleases
Restricts the initial focus to just those work items that are assigned to those
Iteration Paths equal to or under the specified releases. Based on the blank default,
no restrictions are applied. Users can change the focus through filtering.
Default:
[]
To restrict the work item types to just Release 1 and Release 2 for the Fabrikam project,
specify:
[
"Fabrikam/Release 1",
"Fabrikam/Release 2",
]
workItemCategoriesAndColors
Specifies the colors used to represent work items based on their category and
workflow state. For more information, see How workflow states and state categories
are used in Backlogs and Boards.
Default:
{
"Proposed": {
"displayName": "Proposed",
"color": "#a6a6a6"
},
"InProgress": {
"displayName": "In Progress",
"color": "#00bcf2"
},
"Completed": {
"displayName": "Completed",
"color": "#9ac70b"
},
"Removed": {
"displayName": "Removed",
"color": "#d9242c"
},
"Resolved": {
"displayName": "Resolved",
"color": "#ff9d00"
}
}
workItemDislayStatesAndDisplayColors
Maps the workflow states to colors used to display them. If you customize the
workflow states, or use a process that uses different workflow states, you must
update this property.
Default:
{
"New": {
"textColor": "rgb(112, 112, 112)",
"chartColor": "rgb(112, 112, 112)",
"states": [
"New"
]
},
"Active": {
"textColor": "rgb(0, 122, 204)",
"chartColor": "rgb(0, 122, 204)",
"states": [
"Active",
"Resolved"
]
},
"Closed": {
"textColor": "rgb(16, 124, 16)",
"chartColor": "rgb(16, 124, 16)",
"states": [
"Closed"
]
},
"Removed": {
"textColor": "rgb(204, 41, 61)",
"chartColor": "rgb(204, 41, 61)",
"states": [
"Removed"
]
},
"Other": {
"textColor": "rgb(178, 178, 178)",
"chartColor": "rgb(178, 178, 178)",
"states": []
}
}
riskAssessementValues
Specifies the Risk field values. The Risk field specifies a subjective rating of the
relative uncertainty around the successful completion of a user story. It is defined
for the Agile process, but can be added to work item types used in other processes.
Default:
["1-High", "2-Medium", "3-Low"]
partnerAccounts
Optional configuration that specifies which Azure DevOps organizations are

selectable from the Dependency dialog when creating a Cross account dependency.
If not specified generates a list based on previous organizations that the user has
visited.
Default:
[]
Example:
["account-1", "account-2"]
timelineEnabled
Enables or disables the Timeline view.
Default:
true
newDependencyButtonEnabled
Enables or disables the New Dependency link to create a new linked dependency.
Default:
true
crossAccountConfigs
(1) Enables or disables the support of creating new dependencies to work items in
other partner accounts, and (2) specifies the default state of the Partner account
options in the Create a dependency dialog.
Default:
{
"crossAccountDependencyEnabled": true,
"crossAccountDependencyToggleDefaultState": false
}
If you don't want any dependencies created that belong to other organizations, then
change this configuration to:
{
"crossAccountDependencyEnabled": false,
}
priorityValues
Specifies the Priority field values. The Priority field specifies a subjective rating of a
bug, issue, task, or user story as it relates to the business. It is defined for most
backlog work item types and processes, but can be added to work item types used
in other processes.
Default:
["0","1","2","3","4","(blank)"]
defaultColumns
Specifies the field columns and order used to display dependency lists.
Default:
[
"Id",
"Area Path",
"Dependency Title",
"State",
"Consumers",
"Producers"
]
riskAnalysisEnabled
Specifies whether or not Risk functionality is enabled. If set to true, then the
riskAssessmentValues property must be defined.
Default:
False
riskAssessmentValues
Default:
[]
riskGraphConfig
Maps the workflow States to one of the three Risk areas displayed on the Graph:
atRisk is Red, nuetral is Gray, and onTrack is Green.
Default: 8
{
"atRisk": [
"Removed"
],
"neutral": [
"New"
],
"onTrack": [
"Active",
"Resolved",
"Closed",
"Other"
]
}
Add or remove workflow states used in work item types participating in dependency
tracking.
iterationDepth
Specifies the hierarchical depth of Iteration Paths that the Dependency Tracker
queries to build the Timeline view.
Default: 8A depth of 3 would correspond to: Fabrikam/Release 1/Sprint 20.
Default configuration syntax

{
"consumesLinkName": "System.LinkTypes.Dependency-Reverse",
"producesLinkName": "System.LinkTypes.Dependency-Forward",
"queryFields": {},
"dependencyWorkItemTypes": [
"Epic",
"Feature",
"User Story",
"Bug"
],
"selectedDependencyWorkItemTypes": "Any",
"selectedReleases": "",
"workItemCategoriesAndColors": {
"Proposed": {
"displayName": "Proposed",
"color": "#a6a6a6"
},
"InProgress": {
"displayName": "In Progress",
"color": "#00bcf2"
},
"Completed": {
"displayName": "Completed",
"color": "#9ac70b"
},
"Removed": {
"displayName": "Removed",
"color": "#d9242c"
},
"Resolved": {
"displayName": "Resolved",
"color": "#ff9d00"
}
},
"workItemDislayStatesAndDisplayColors": {
"New": {
"textColor": "rgb(112, 112, 112)",
"chartColor": "rgb(112, 112, 112)",
"states": [
"New"
]
},
"Active": {
"textColor": "rgb(0, 122, 204)",
"chartColor": "rgb(0, 122, 204)",
"states": [
"Active",
"Resolved"
]
},
"Closed": {
"textColor": "rgb(16, 124, 16)",
"chartColor": "rgb(16, 124, 16)",
"states": [
"Closed"
]
},
"Removed": {
"textColor": "rgb(204, 41, 61)",
"chartColor": "rgb(204, 41, 61)",
"states": [
"Removed"
]
},
"Other": {
"textColor": "rgb(178, 178, 178)",
"chartColor": "rgb(178, 178, 178)",
"states": []
}
},
"riskAssessmentValues": [],
"releases": [],
"partnerAccounts": [],
"timelineEnabled": true,
"newDependencyButtonEnabled": true,
"crossAccountConfigs": {
"crossAccountDependencyEnabled": true,
},
"priorityValues": [
"0",
"1",
"2",
"3",
"4",
"(blank)"
],
"defaultColumns": [
"Id",
"Area Path",
"Dependency Title",
"State",
"Consumers",
"Producers"
],
"riskGraphConfig": {
"atRisk": [
"Removed"
],
"neutral": [
"New"
],
"onTrack": [
"Active",
"Resolved",
"Closed",
"Other"
]
},
"iterationDepth": 8
}
Related articles
Hosted XML process model
How workflow states and state categories are used in Backlogs and Boards
Related Marketplace extensions

Work Item Visualization
Use the Azure Boards app with Slack to
manage work items
Article • 02/24/2023
If you use Slack , you can use the Azure Boards app for Slack to create work items
and monitor work item activity in your Azure Boards project from your Slack channel.
The Azure Boards app for Slack allows users to set up and manage subscriptions in their
Slack channel. They can manage subscriptions for create, update, and other work item
events. Users can also get notifications for these events in their Slack channel.
Conversations in the Slack channel can be used to create work items. Previews for work
item URLs help users to start discussions around work.
Read this article to learn how to:
＂ Add the Azure Boards app to your Slack workspace

＂ Link and unlink your Azure Boards project to the Azure Boards app
＂ Set up subscriptions to work item related events in your Slack channel
＂ Create work items from your Slack channel
＂ Monitor work item activity in your Slack channel
＂ Get notifications in private Slack channels
７ Note
Azure Boards and Slack integration is only supported for Azure DevOps
Services.
Notifications are currently not supported inside direct messages.
Prerequisites
To create a work item, you must be a contributor to the Azure Boards project. If
you don't have a project yet, you can sign up and create a project. For more
information, see Start using Azure Boards.
To create subscriptions in a Slack channel for work item events, you must be a
member of the Azure Boards Project Administrators group or Team Administrators
group. To get added, see Change project-level permissions or Add Team
Administrator.
To receive notifications, the Third party application access via OAuth setting must
be enabled for the organization. See Change application access policies for your
organization
Add the Azure Boards app to your Slack

workspace
1. To install the Azure Boards app to your Slack workspace, open a web browser, sign
into Slack, and open the Azure Boards app .
2. Once added, you'll see a welcome message from the app as shown in the following
image.
3. Use the /azboards Slack handle to interact with the app. A list of commands is
provided later in this article, Command reference.
Link your Azure Boards project to the Azure

Boards app
To use the app, you must first link your Azure Boards project to your Slack channel.
1. Once the app has been installed in your Slack workspace, connect and
authenticate yourself to Azure Boards.
2. After signing in, use the following slash command inside a Slack channel to link to
the Azure Boards project that you specify with the URL:
/azboards link [project url]
For example:
/azboards link https://dev.azure.com/myorg/myproject
Once the project is linked, you can create work items using /azboards create command
or use message actions.
Set up subscriptions to monitor work items

You can create subscriptions to monitor work items at any time using the /azboards
subscriptions command. You have an option of setting up subscriptions just after
linking a project.
1. Select area path you want, the event that you're interested in, and use the
associated filters to customize your Slack channel. To easily set up subscriptions,
your recently accessed area paths are shown in the area path dropdown.
In case your team's area path doesn't appear in the Area path dropdown menu,
follow the instructions mentioned in the next section, Add area paths. Area paths
added using the /azboards addAreapath command and area paths for which
subscriptions are created in the Slack channel always appear in the Area path
dropdown along with recently accessed area paths.
Add area paths

You can add areas that your team works on to the channel so that they're always
available for creating work items and subscriptions. This is important mainly for the
teams with more than 100 area paths.
Use the following command to add area paths from your project to the Slack
channel.
/azboards addAreapath [area path]
For example:
/azboards addAreapath myproject\fabrikam

If you choose project name as your area path, then you'll receive notifications for
all the area paths in the project. It's logically equivalent to choosing 'Any' area
path.
Create a work item with a command

1. With the Azure Boards app, you can create work items from your channel. The app
supports custom work items as well.
To create a work item, use /azboards create .
2. You can create work items directly from a command by passing work item type
and title as parameters. Work items get created only if they don't have any fields to
be mandatorily filled.
/azboards create [work item type] [work item title]
For example:
/azboards create 'user story' Push cloud monitoring alerts to mobile
devices
Create a work item from message actions

Often, discussions in a channel call for creation of work items. You can use message
actions to create a work item. The selected message is prefilled in the description
section of the work item. A link back to the conversation in the channel is stored in the
Discussion section of the newly created work item, giving users access to the discussion
that led to the creation of the work item.
To create work items using message actions

Manage Azure Boards subscriptions
1. To view, add and remove subscriptions for a channel, use the /azboards
subscriptions command:
/azboards subscriptions
This command lists all the current subscriptions for the channel and allows you to
add new subscriptions and remove existing ones. As part of adding subscriptions,
you can also customize what you get notified on by using various filters.
[!NOTE]Team administrators aren't able to remove or modify subscriptions created by

Project administrators.
Previews of work item URLs

To support collaboration around work items discussed within a channel, a preview of
work items referenced in the channel is displayed. When a user pastes the work item
URL, a preview is shown similar to the following image. This preview helps to keep work-
item-related conversations relevant and correct.
For this feature to work, users have to be signed-in. Once they're signed in, this feature
works for all channels in a workspace.
Unlink a project from a channel

A Slack channel can only link to one Azure Boards project at a time. To link to a different
project, you must first unlink the current project using /azboards unlink command.
Unlinking a project deletes all the subscriptions along with added area paths from the
channel. If the channel has no subscriptions, any user can unlink a project. However if a
channel has subscriptions, only project admins can unlink a project from a channel.
Command reference
The following table lists all the /azboards commands you can use in your Slack channel.
Slash command Functionality
/azboards link [project url] Link a project to this channel to create work items
and receive notifications
/azboards subscriptions Add or remove subscriptions for this channel
/azboards create or /azboards create Create a work item

[work item type] [title]
/azboards addAreapath [area path] Add an area path from your project to this channel
/azboards signin Sign in to your Azure Boards organization
/azboards signout Sign out from your Azure Boards organization
/azboards unlink Unlink a project from this channel
/azboards feedback Report a problem or suggest a feature
Manage work in private channels

The Azure Boards app for Slack can help you create work items and monitor the work
item activity in your private channels as well. To invite the bot to your private channel,
enter /invite @azboards . After you post that, you can create work items and manage
your notifications in the same way as you would for a public channel.
Troubleshoot errors
If you're experiencing the following errors when using the Azure Boards App for Slack ,
follow the procedures in this section.
Sorry, something went wrong. Please try again.

Configuration failed. Please make sure that the organization '{organization name}'
exists and that you have sufficient permissions.

The Azure Boards app uses the OAuth authentication protocol, and requires Third-party
application access via OAuth for the organization to be enabled. To enable this setting,
go to Organization settings > Security > Policies, and set the Third-party application
access via OAuth for the organization setting to On.
Configuration failed. Please make sure that the
organization '{organization name}' exists and that you
have sufficient permissions.
Sign out of Azure DevOps by going to https://aka.ms/VsSignout using your browser.
Open an In private or incognito browser window and go to

https://aex.dev.azure.com/me and sign in. In the dropdown under the profile icon to
the left, select the directory that contains the organization containing the project that
you want to link.
In the same browser, start a new tab, go to https://slack.com , and sign in to your work
space (use web client). Run the /azboards signout command followed by the /azboards
signin command.
Select the Sign in button and you'll be redirected to a consent page like the one in the
following example. Ensure that the directory shown beside the email is same as what
was chosen in the previous step. Accept and complete the sign-in process.
If these steps don't resolve your authentication issue, reach out to us at Developer
Community .
Related articles
Azure Pipelines with Slack
Azure Repos with Slack
Create a service hook for Azure DevOps with Slack
Use the Azure Boards app in Microsoft
Teams
Article • 02/24/2023
If you use Microsoft Teams , you can create work items and monitor work item activity
in your Azure Boards project from your Teams channel. You accomplish this by adding
the Azure Boards app for Microsoft Teams to your Teams channel.
The Azure Boards app for Microsoft Teams enables users to complete the following
tasks:
Set up and manage subscriptions for creating and updating work items
Manage other work item events
Receive and manage notifications for work item events in their Teams channel
Create work items from conversations in the channel
Search and share work items with other members in the channel using the
messaging extension
View work item previews from their URLs to start discussions and keep the
conversations contextual.
Read this article to learn how to:
＂ Add the Azure Boards app to your team in Microsoft Teams

＂ Link and unlink your Azure Boards project to the Azure Boards app
＂ Set up subscriptions to work item related events in your Teams channel
＂ Create work items from your Teams channel
＂ Monitor work item activity in your Teams channel
７ Note
Azure Boards and Microsoft Teams integration is only supported for Azure DevOps
Services.
Also, Azure Boards and Microsoft Teams integration isn't supported if you're an
O365 Government Community Cloud (GCC) customer that uses an Azure
Commercial subscription in conjunction with your GCC tenant.
Prerequisites
To create a work item, you must be a contributor to the Azure Boards project. If
you don't have a project yet, you can sign up and create a project. For more
information, see Start using Azure Boards.
To create subscriptions in a Teams channel for work item events, you must be a
member of the Azure Boards Project Administrators group or added to the team
administrator role for the team. To get added, see Change project-level
permissions or Add team administrator.
To receive notifications, you must enable the Third-party application access via
OAuth setting for the Azure DevOps organization. See Change application access
policies for your organization.
７ Note
You can link the Azure Boards app for Microsoft Teams only to a project
hosted on Azure DevOps Services at this time.
Notifications are currently not supported inside direct messages.
Only public channels are supported.
Add the Azure Boards app to Microsoft Teams

You add the app to your Teams channel in Microsoft Teams.
1. Visit the App store in Microsoft Teams and search for the Azure Boards app. Upon
installing, a welcome message from the app displays as shown in the following
image.
2. Use the @azure boards handle to interact with the app. For a list of commands, see
Command reference provided later in this article.
Link your Azure Boards project to the Azure

Boards app
To use the app, you must first link your Azure Boards project to your Teams channel.
1. Once the app has been installed in your team, connect and authenticate yourself
to Azure Boards. Use Sign in with different email if your Microsoft Teams and
Azure Boards are in different tenants.
2. After signing in, use the following command inside a Teams channel to link to the
Azure Boards project that you specify with the URL:
@azure boards link [project url]
For example:
@azure boards link https://dev.azure.com/myorg/myproject
Once the project is linked, you can create work items using @azure boards create
command or use message actions.
Set up subscriptions
You can create subscriptions to monitor work items at any time using the @azure boards
subscriptions command.
1. Select the area path you want and event that you're interested in. Use the
associated filters to customize what you get notified on in your Teams channel. To
help easily set up subscriptions, your recently accessed area paths are shown in the
area path dropdown.
In case the area path you want doesn't appear in the Area path dropdown menu, follow
the instructions mentioned in the next section, Add area paths. Area paths added using
the @azure boards addAreapath command and area paths for which subscriptions are
created in the channel always appear in the Area path dropdown along with recently
accessed area paths.
Add area paths

You can add areas that your team works on to the channel so that they're always
available for creating work items and subscriptions. This feature is useful for teams with
more than 100 area paths in their project.
Use the following command to add area paths from your project to the Teams
channel.
@azure boards addAreapath [area path]
For example:
@azure boards addAreapath myproject\fabrikam
If you choose project name as your area path, then you'll receive notifications for
all the area paths in the project.
Create a work item with a command

With the Azure Boards app, you can create work items from your channel. The app
supports custom work items as well.
To create a work item, use @azure boards create .

Create a work item from message actions
Often, discussions in a channel require creation of work items. You can use message
actions to create a work item. The selected message is pre-filled in the description
section of the work item. The Discussion section of the newly added work item stores a
link back to the conversation in the channel.
To create work items using message actions
Manage Azure Boards subscriptions

1. To view, add and remove subscriptions for a channel, use the @azure boards
subscriptions command:
@azure boards subscriptions

This command lists all the current subscriptions for the channel and allows you to add
new subscriptions and remove existing ones. As part of adding subscriptions, you can
also customize what you get notified on by using various filters.
７ Note
Team administrators aren't able to remove or modify subscriptions created by

Project administrators.
Search and share work items using compose

extension
To help users search and share work items, the Azure Boards app for Microsoft Teams
supports compose extension. You can search for work items by work item ID, title, or
supported functional command. For a list of commands, see Functional work item
search. To use the compose extension, users must sign in to Azure Boards app either by
running @azure boards signin command or by signing into the compose extension
directly.
Preview work item URLs
To support collaboration around work items discussed within a channel, the channel
displays a preview of work items referenced. When a user pastes the work item URL, a
preview is shown similar to the following image. This preview helps to keep work item-
related conversations relevant and correct.
For this feature to work, users must be signed in. Once signed in, this feature works for
all channels in a team in Microsoft Teams.
Unlink a project from a channel

A Teams channel can only link to one Azure Boards project at a time. To link to a
different project, you must first unlink the current project using @azure boards unlink
command.
Unlinking a project deletes all the subscriptions along with added area paths from the
channel. If the channel has no subscriptions, any user can unlink a project. However if a
channel has subscriptions, only project admins can unlink a project from a channel.
Threaded notifications to link and reduce

notifications
The Teams channel threads notifications so as to logically link and reduce related
notifications in the channel. All notifications linked to a particular work item are linked
together.
Compact view of threaded notifications
Expanded view of threaded notifications

Azure Boards command reference
The following table lists all the @azure boards commands you can use in your Microsoft
Teams channel.
Command Functionality
@azure boards link [project url] Link a project to this channel to create work items and receive
notifications
@azure boards subscriptions Add or remove subscriptions for this channel
@azure boards create Create a work item
@azure boards addAreapath Add an area path from your project to this channel
[area path]
Command Functionality
@azure boards sign in Sign in to your Azure Boards organization
@azure boards sign out Sign out from your Azure Boards organization
@azure boards unlink Unlink a project from this channel
@azure boards feedback Report a problem or suggest a feature
Configure Azure DevOps Services tabs in

Microsoft Teams
1. To bring your Kanban board or Dashboard into Microsoft Teams, select the '+'
('add new tab') button on the top nav of your team channel.
The Add a tab dialog displays. Icons are arranged typically according to most
recent access. You can select A-Z for an alphabetized list.
2. Choose the Azure DevOps icon and authenticate your identity. Optionally, you can
choose the Website icon and add the URL of your Kanban board or dashboard to
the channel.
3. Choose the organization whose board or dashboard you want to add.
4. Complete the form presented. For example, here we add a dashboard for the
Azure DevOps team for the TechnicalContent project.
5. The Kanban board or dashboard you selected displays.
Multi-tenant support
In your organization if you're using a different email or tenant for Microsoft Teams and
Azure DevOps, complete the following steps to sign in and connect based on your use
case.
Case
Email ID and tenant in Microsoft Teams
Email ID and tenant in Azure DevOps
Steps to take
1
email1@abc.com
(tenant 1)
email1@abc.com
(tenant 1)
Sign in using Sign in button.
email1@abc.com
(tenant 1)
email1@abc.com
(tenant 2)
Sign in the Azure DevOps account
In the same browser, start a new tab, go to https://teams.microsoft.com
Run the signin command and choose the Sign in button.
email1@abc.com
(tenant 1)
email2@pqr.com
(tenant 2)
Sign in using Sign in with different email address, in the email ID picker use the email2
to sign in to Azure DevOps.
email1@abc.com
(tenant 1)
email2@pqr.com
(non default tenant 3)
This scenario isn't supported today
Troubleshoot errors
If you're experiencing the following errors when using the Azure Boards App for
Microsoft Teams , follow the procedures in this section.

Configuration failed. Please make sure that the organization '{organization name}'
exists and that you have sufficient permissions.

The Azure Boards app uses the OAuth authentication protocol, and requires Third-party
application access via OAuth for the organization to be enabled. To enable this setting,
go to Organization settings > Security > Policies, and set the Third-party application
access via OAuth for the organization setting to On.
Configuration failed. Please make sure that the

organization '{organization name}' exists and that you
have sufficient permissions.
Sign out of Azure DevOps by going to https://aka.ms/VsSignout using your browser.
Open an In private or incognito browser window and go to

https://aex.dev.azure.com/me and sign in. In the dropdown under the profile icon to
the left, select the directory that contains the organization containing the project that
you want to link.
In the same browser, start a new tab, go to https://teams.microsoft.com/ . Run the

@azure boards signout command and then run the @azure boards signin command in
the channel where the Azure Boards app for Microsoft Teams is installed.
Select the Sign in button and you'll be redirected to a consent page like the one in the
following example. Ensure that the directory shown beside the email is same as what
was chosen in the previous step. Accept and complete the sign-in process.
If these steps don't resolve your authentication issue, reach out to us at Developer
Community .
Related articles
Azure Pipelines with Microsoft Teams
Azure Repos with Microsoft Teams
Connect Azure Boards to an Office client
Article • 02/24/2023
2018
To support your work tracking efforts, you can use Microsoft Excel. You can either work
in online mode, where you're connected to either Azure Boards or Azure DevOps Server.
Or, work in offline mode, where you access the local computer and document.
） Important
All Office integration tasks require that you have installed a version of Visual Studio
or the free Azure DevOps Office Integration 2019 .
In this article you'll learn about the following items:
＂ Which Office clients support connection to Azure DevOps

＂ Prerequisites for connecting from an Office client to Azure DevOps
＂ Importance of publishing and refreshing work from an Office client
＂ How to connect Excel to an Azure Boards project
＂ How to work offline and reconnect to Azure DevOps
＂ Marketplace extensions that support integration with Office clients
Supported Office clients and Azure DevOps

versions
The following table indicates the Office clients supported for each Azure DevOps
version.
７ Note
Azure DevOps from Excel or any other Office client isn't supported.
Azure DevOps/Visual Studio version
Excel
Project1
PowerPoint Storyboarding2

Visual Studio 2019
Azure DevOps Office Integration 2019
✔️
TFS 2018
Visual Studio 2017
✔️
✔️
✔️
７ Note
1. Support for Project integration and the TFSFieldMapping command is

deprecated for Azure DevOps Server 2019 and later versions. You might find
support using one of the Marketplace extensions.
2. Support for linking PowerPoint files to work items from within PowerPoint has
been deprecated starting with Visual Studio 2019 and Azure DevOps Office
Integration 2019. You can still link to PowerPoint using the Storyboard link
from within a work item. Also, the Visual Studio Gallery for PowerPoint
Storyboarding has been deprecated.
Prerequisites
Connection from an Office client to an Azure Boards project requires that you've
installed the necessary software and have the necessary permissions.
To connect Excel to Azure Boards, you must have installed Office Excel 2010 or
later version, including Office Excel 365.

７ Note
installing one of the latest editions of Visual Studio or Azure DevOps Office
Integration. The plug-in supports connection to Azure DevOps from Excel.

To learn more about compatibility requirements, see Compatibility with Azure DevOps.
Microsoft Excel 2010 or later version, including Microsoft Office Excel 365
Visual Studio 2013 or later version or Team Foundation Server Standalone Office
Integration (free)
Permissions to connect to the project in Azure Boards.
To learn more about compatibility requirements, see Azure DevOps client compatibility.
） Important
You may receive the following error if you install Microsoft Office 2010 on the same
computer as a previous version of Office.
Team Foundation Error
Interface not registered (Exception from HRESULT: 0x80040155)
You may be able to resolve this error by repairing Office. You can access the Repair
option by opening the Control Panel, choose Uninstall or change a program, open
the context menu for Office 2010, and then choose Change. See also, Azure
DevOps-Office integration issues.
Publish and refresh work items

When you add or update work items from Excel, local copies of your work items are
created. To keep data in sync, it's important to refresh your local file when you open it
and publish and refresh frequently during a long online session.
At first, the data in the local document matches the data in the database. But you or
other team members can change the data about work items and cause the two to differ.
To view the most recent changes from the database, refresh the document. The refresh
downloads the latest values in the data store to your local document. To write changes
from the document to the database, publish the changes. Publishing uploads the
changes you made to the work item tracking data store.
To keep work items in sync from your local data store and Azure Boards, publish and
refresh often.
Azure DevOps and Excel
To work in Excel, see Bulk add work items with Excel.
Connect an Azure DevOps project to Excel
７ Note
While this section illustrates how to connect Excel to an Azure Boards project, the
steps for connecting from Project or PowerPoint are similar.
To add or modify work items by using Excel, you connect your worksheet to a project.
Establishing this connection binds the document to the Azure DevOps project to
exchange information.
７ Note
When you connect to Azure Boards in the cloud, the Team Project Collection is
automatically selected as there is only one collection associated with your Azure
DevOps Services organization. When you connect to Azure Boards in an on-
premises server, you choose the Team Project Collection prior to choosing the
project.
You can start work from the web portal, Excel, or Visual Studio/Team Explorer. Your
worksheet is associated with either a list of work items or a work item query.
Open query in Excel (web portal)

This connection method requires that you have installed Azure DevOps Open in
Excel . It also requires Visual Studio 2017 or later version.
1. From your web browser, (1) check that you've selected the right project, (2)
2. Choose the query you want to open in Excel.
3. From the Results tab, choose the actions icon.
For more information, see Bulk add work items with Excel.
 Tip
You can use multiple worksheets within an Excel workbook to work with different
input or query lists. However, you can only connect to one project per workbook.
Work offline and reconnect to Azure Boards

One advantage of working in Excel or Project is that you can work offline and add or
modify work items. The following procedures show you how to disconnect an Excel work
item list or a Project plan from Azure Boards. You can then reconnect later to
synchronize the document with the work item database.
７ Note
If the project that contains work items for your Excel or Project document is moved
to a different organization or Azure DevOps Server instance, you must reconfigure
the server to which the document connects. For more information, see Connect
Azure DevOps project to Excel provided earlier in this article.
Disconnect a document file from the network

To disconnect an Excel or Project document file from the network:
1. Open the document that you want to change while you're offline.
2. Refresh the work item list to retrieve the latest information from the work item
database.
If you're using Excel, on the Team ribbon, in the Work Items group, choose
Refresh.
If you're using Project, on the Team menu, choose Refresh.
3. If you're using Excel, add to the work item list the columns for all fields that you
want to modify.
You can't add columns when the work item list is disconnected from the server.
4. Disconnect your computer from the network, or save the work item list file and
copy it to another computer.
An error message might appear that tells you the Office program couldn't establish
a connection with an Azure DevOps Server.
5. Modify or update the work item list as needed.
７ Note
You can't create most types of links between work items when the work item
document is disconnected from the system. The exceptions are parent-child
links in an Excel tree list, and both parent-child and predecessor-successor
links in a Project plan.
Reconnect a file to Azure Boards

To reconnect an Excel or Project document file:
1. Reconnect your computer to the network, or copy the file to a computer that is
2. If you changed the document while you were offline, follow one of these steps:
Publish.
If you're using Project, on the Team menu, choose Publish Changes.
3. If you didn't change the document while you were offline, follow one of these
steps:
Refresh.
If you're using Project, on the Team menu, choose Refresh.
4. Resolve any data validation errors or conflicts that occur.
The following Marketplace extensions support integration between Azure DevOps and
Office products.
Azure DevOps Open in Excel : Opens a selected query in Excel.

Office 365 Integration : Pushes notification of configurable Azure DevOps events
to an Office 365 Group.
For more extensions that integrate with Microsoft Project, see Azure Boards migration
and integration, Project and portfolio management.
Related articles
Create your backlog
Requirements and compatibility
Article • 02/24/2023
2018

７ Note
Prerequisites
７ Note
７ Note

Server.

Editor.
Query types:
List types:
Query types
feature in Excel.
Tree lists

Agile process
this article.


no hierarchy
items, no hierarchy
Use Excel features


Fill down cells
Filter
Sort work items


reconnect.


７ Note
the project.

list.
 Tip

topology link type.
） Important
relationships.
restrictions.
type.
was imported.
created.

Remove a tree level
removed.

work items:
item tasks.

 Tip
Choose Columns.
periodically.
the drop-down menu.

or query.


７ Note
search.
3. Choose Find.

interest.
up and down arrows.

this feature.
 Tip
Team ribbon.

Link work items

Delete links
other work items.
View and add links


following dialog.




Add attachments
Create a report
） Important

articles:

Related articles
Basic Excel tasks
Work in Excel connected to Azure
Boards FAQs
FAQ
2018
Find answers to frequently asked questions when using Microsoft Excel to add or modify
work items defined in Azure DevOps.
If you're having connection issues, make sure you meet the prerequisites as listed in
Bulk add or modify work items with Excel. Also be sure you've reviewed the information
in Azure Boards and Office integration.
 Tip
The recommended approach for bulk import or update of work items is to use the
web portal or CSV import.
Connect and versioning support

What versions of Azure DevOps work with Excel?
All versions from TFS 2013 through Azure DevOps Server 2020 and Azure DevOps
Services/Azure Boards support integration with Microsoft Excel.
What do I need to use Excel to add or modify

work items?
You must get the Azure DevOps Office Integration add-in available from the Downloads
page, Other Tools, and Frameworks . This add-in typically installs when you install any
version of Visual Studio or Team Explorer. Also, you need to use Microsoft Excel 2010 or
later version, including Microsoft Office Excel 365.
） Important
Microsoft Project Integration and the TFSFieldMapping command aren't supported

for:
Services.
However, full support for Microsoft Excel integration is maintained and is the
recommended alternative.
Once you've installed the add-in, open Excel and look for the Team ribbon.
Can I use Excel on my Mac?

No. macOS isn't supported. Even if you've installed Visual Studio for Mac, connection to
Azure DevOps from Excel or other Office client isn't supported.
Can I open a query in Excel from the web portal?

Yes. To open Excel from the web portal, install the Azure DevOps Open in Excel
Marketplace extension. Otherwise, you can open Excel and then open a query that
you've created in the web portal or from Team Explorer.
Azure DevOps Open in Excel extension
Can I import or update work items without using

Excel?
Yes. You can do a bulk import of new work items or update existing work items without
using Excel. See Import work items.
How do I connect an existing Excel workbook to

Azure DevOps?
See Connect Azure Boards to an Office client.
How do I share an Excel workbook with others?

If you want to share an Excel workbook that has work items listed within it, you may
want to disconnect the connection to Azure DevOps to prevent accidental publishing of
changes by others. You can disconnect the workbook, share it or work offline, and later
reconnect the workbook. For more information, see Connect Azure Boards to an Office
client, Disconnect a document file from the network.
How do I connect when special protocols are in
use on my network?
If your network uses TLS 1.1 or TLS 1.2 security protocol, then you may have network
connection issues. To resolve these issues, see Allowed address lists and network
connections, Domain URLs to allow.
How do I disable the Team menu?

If you want to disable the add-in, see Add or remove an add-in .
Unsupported queries
What query macros aren't supported in Excel?
@RecentProjectActivity, @TeamAreas. Queries that contain these macros don't work
when opened in Visual Studio/Team Explorer, Microsoft Excel, or Microsoft Project.
Can I view queries that list work items from

different team projects?
No. You receive an error message with error code TF208015. You can only view work
items defined in the team project that you connect to from Excel. To view work items
from other team projects, create a query and open it in a separate Excel workbook. Each
Excel workbook can only connect to one team project at a time.
Work with linked work items

How do I publish to a tree?
Follow the instructions provided in Bulk add or modify work items with Excel, Import
work items, tree list
Why does my direct-links query appear as a flat

list in Excel?
When you open a direct-links query in Excel, the add-in converts the list to a flat list.
While you can modify values for the fields and add work items, you can't view nor
modify link relationships.
Can I bulk-edit link types other than tree-

topology link types?
No. Excel only supports adding and modifying hierarchical links. To bulk edit links of
other types, you can use the following clients:
Use the web portal, to map backlog items to portfolio backlog items which creates
parent-child links.
Use either the web portal or Team Explorer, to modify parent-child links by
dragging items within a hierarchical backlog page or within a tree query.
Use the az boards work-item relation add command.
Work with test work items

Can I bulk add or edit test cases with Excel?
No. You can't use Excel to export and import test case steps or other test artifacts.
Instead, use the grid view to bulk edit test cases supported via the web portal.
Publish and refresh

How can I show other fields?
If you start your worksheet with a New List, you see only a set of default field columns.
You can add columns using the Choose Columns on the Team menu.
If you start your worksheet from an existing query, you see all the column fields defined
for the query. From there, you can add columns using the Choose Columns on the Team
menu. However, your additions don't modify the underlying query.
How do I resolve publishing issues?

articles:
Resolve data conflicts: A data conflict occurs when one team member changes a
field value in Excel at the same time another team member changes the same field
in Azure Boards.
Resolve data validation errors: A data validation error occurs if a team member
changes a work item in a way that violates the rules for that type of work item.
Address inaccuracies published for summary values: If you determine that hours
are counted twice in reports that contain task hours, you can correct the problem
by using the Work Items With Summary Values team query.
How do I resolve invalid links tree list in Excel?

If you try to publish a tree list that contains an invalid link, the Work Item Publishing
Errors dialog box appears and displays an error message that states why the tree is
invalid. When you work with work items in a tree in Excel, the tree must be in a valid
state before it can be published. In Excel, an invalid link occurs in a tree list of work
items. It occurs if the title of a work item title is missing or occurs in the wrong title
column.
To update work items, you must be a member of the Contributors group or have your
View work items in this node and your Edit work items in this node permissions set to
Allow. For more information, see Change project-level permissions.
Error message TF208000: Duplicate titles
If you add a value to multiple Title columns of a work item, when you try to publish the
tree, the error message TF208000 appears in the Work Item Publishing Errors dialog
box. The error message specifies the row number of the invalid link.
1. Note the row number that appears in the dialog box.

2. Close the Work Item Publishing Errors dialog box.
3. In the work item list, find the row that the error message specified.
4. Delete the duplicate title or titles so that only one title column has a value.
5. On the Team tab, in the Work Items group, choose Publish.
Error message TF208001: Child work item disconnected from parent
If you remove the title of a child work item, when you try to publish the work item list
the error message TF208001 appears in the Work Item Publishing Errors dialog box.
The error message specifies the row number of the invalid link. This error message also
appears if you create an invalid link structure by putting the title of a child work item
into the wrong column.
If you put a title in the wrong column, the resulting tree structure might be valid but not
match your intent. The system can't detect this problem, therefore, an error message
doesn't appear.
Resolve an orphaned work item
1. Note the row number that appears in the dialog box.

3. Find the row that the error message specified. The misplaced title might be in this
row, or it might be in the next row.
4. Move the title to the correct column to fix the invalid link.
Error message TF208017: Missing Title 1 in the first row
If the first work item in the list has no value in the Title 1 column, the error message
TF208017 appears in the Work Item Publishing Errors dialog box when you try to
publish the work item list.

2. Determine why the first work item lacks a Title 1 value. The analysis of the cause of
the error determines what you must do to repair the work item list.
3. If the first work item should be at the top of the list, move its title value into the
Title 1 column.
4. If the first work item should be lower in the list, move the correct work item to the
top of the list. For more information about how to move work items, see Bulk add
work items with Excel.
Error message TF208022: Sorted tree list
If you haven't installed Service Pack 1 for Visual Studio 2010 or later version, the
following error message appears when you choose Publish after you've sorted the work
items in a tree list:
TF208022: Can't publish a sorted tree list. Before you can publish, you must clear any
sort criteria applied to this work item list. The order of work items has changed.
Removing sort criteria won't return the list to its original order. Verify that all of the
parent-child relationships in the tree are correct before you publish.
You can't publish your changes until you re-establish the tree hierarchy. You can resolve
this error either by discarding your changes and refreshing the list or by manually
restoring the hierarchy and then publishing the list.
Resolve sorted tree list issues
Choose Refresh to discard your changes and restore the tree hierarchy. If you refresh
the tree list, you remove all your changes other than the sort. To refresh the tree list, on
the Team tab, in the Work Items group, choose Refresh.
Manually restore the tree hierarchy by moving the row entries of child items under their
parent items. Then, on the Team tab, in the Work Items group, choose Publish.
Error message TF208102: Excel sort on a tree list
The following error message appears if you sort the work items in a tree list in Excel:
TF208102: You have performed an Excel sort on a tree list. This action removed the
modified or newly introduced hierarchical link relationships of the tree. You can still
publish the changes you have made to individual work items. After you publish, the list
restores to previous hierarchy. In general, you shouldn't sort a tree list whose hierarchy
has been modified.|
This message indicates that you can publish the changes that you made to the fields,
but all changes that you made to the link hierarchy have been discarded. The tree
hierarchy automatically reverts to its original structure.
Publish changes and retrieve the tree hierarchy

2. Choose Refresh.
Error message TF208104: Hierarchical link Relationship is locked
If you publish a worksheet that contains work items that are synchronized with Project
Server and whose hierarchical link relationships are locked ( ), the following error
message may appear:
TF208104: You have modified one or more hierarchical link relationships that might be
locked by other processes, such as Project Server. Changes that you made to individual
work items were published. Changes that you made to locked links were autocorrected.
This error appears when you change the link hierarchy that contains locked links. This
message indicates that the changes that you made to the fields are published. All
changes you made to the link hierarchy, whether locked or not locked, aren't published
and were reverted to their original assignments.
To modify locked hierarchical, make your changes in the enterprise project plan mapped
to the project. For more information, see Manage project details.
To publish changes to links that aren't locked:
For work items that aren't synchronized, you can modify the hierarchical link relationship
from Team Explorer or the web portal. For more information, see Bulk add or modify
work items with Excel.
To modify unlocked hierarchical link relationships in Excel, revise the query that you use
to export the work items to exclude all work items with locked links. For example, you
can add a clause to the filter criteria to omit items whose Project Server Is Linked field is
set to Yes.
Can I delete work items from Excel?

No. You can't delete work items from Excel. The only way to delete work items is from
the web portal or the az boards work-item delete command-line tool. For more
information, see Move, change, or delete work items.
Use built-in Excel functions

Can I use multiple worksheets within Excel?
Yes. Each worksheet in Excel can contain a different input list or query. However, all
To bulk add or modify work items in a different project, open a new Excel workbook.
Can I use Excel cut and paste functions?

Yes. You can use many Excel features, such as cut, paste, automatic fill, format, sort (flat
list only), filter, and add formulas. You can cut and paste rows to resequence items
within a list and change link relationships among work items.
To drag a work item, select the work item or contiguous set of work items that you want
to move, open the context menu and choose Select, Table Row, point to the border of
the selection, and—when the pointer becomes a move pointer —drag the row to
another location.
 Tip
When you refresh the work item list, not all formats may be retained. For example,
date formats get set by the server data store. Changes you make to a date format
field are overwritten with the date format used by the server.
How do I enable the Developer tab?

See Show the Developer Tab on the Ribbon.
Related articles
Query FAQs
Create your backlog
Basic Excel tasks
Resolve Azure DevOps Office
integration issues
Article • 08/14/2023
2018
All Office integration tasks require that you have installed a version of Visual Studio or
the free Azure DevOps Office Integration 2019 . These software installs the Azure
DevOps Office Integration Add-in or Team Foundation Office Integration Add-in For a
list of prerequisites, see Azure Boards and Office integration.
If you don't see the Team ribbon in Microsoft Excel, as shown in the image below, you
may want to resolve the issue with the procedures provided in this article.
） Important

supported for:

Services.
However, full support for Microsoft Excel integration is maintained and supports
bulk import and update of work items. Alternatives to using Microsoft Project
include the following:
Delivery plans
Enable the Azure DevOps add-in

1. From the Excel File menu, choose Options.
2. Choose Add-ins and from the Manage picklist, choose COM Add-ins, and then
choose Go.
3. Make sure that a check is placed in the Team Foundation Add-in checkbox.
4. Restart Excel. You should now see the Team ribbon.

If the Team ribbon doesn't appear at next launch, the load behavior of the add-in may
have changed and you'll need to complete the following steps:
Update the registry

1. Launch the Registry Editor from your Windows Start Menu by entering regedit in
the Search or Run box.
2. Go to one of the following paths containing the TFCOfficeShim.Connect.[version]

folder:
７ Note
If there are multiple folders with the same name, select the one with the
highest version number.
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Excel\Addins (if this key
doesn't exist, try one of the options below)

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Excel\Addins
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Office\Excel\Addins
3. Double-click to open LoadBehavior and set the value data field to 3 (if the value is
0, the Team ribbon won't load).
4. Press OK and restart Excel.
To learn more about the LoadBehavior entry, see Registry Entries for VSTO Add-ins,
LoadBehavior values.
Office add-in doesn't load or open in Excel

when Visual Studio fails
To connect to Azure Boards, go to the Team ribbon and choose New List. If the New List
dialog fails to open, or you receive TF86001 or similar error message, then you may
need to repair Visual Studio.
This error is typically caused when you install Visual Studio before you install Office Excel
or Project. In this instance, the Visual Studio Tools for Office Run Time aren't correctly
configured. To correct this error, you must repair Visual Studio.
７ Note
For authentication issues, such as TF31003 and TF30063 , please refer to User
account does not have permission.
Prerequisites
Install Visual Studio to ensure that you have access to the Visual Studio Command
Prompt and the Gacutil.exe (Global Assembly Cache Tool). If you don't have Visual
Studio, you can install the Visual Studio Community edition for free .
Run the Gacutil tool
1. Open the Visual Studio Command Prompt and choose to run it as an
administrator.
2. For Microsoft 365, run the following commands:
GACUTIL /I
C:\Windows\assembly\GAC_MSIL\Policy.14.0.Microsoft.Office.Interop.Excel
\15.0.0.0__71e9bce111e9429c\Policy.14.0.Microsoft.Office.Interop.Excel.
dll
GACUTIL /I
C:\Windows\assembly\GAC_MSIL\Policy.14.0.office\15.0.0.0__71e9bce111e94
29c\Policy.14.0.Office.dll
For Office 2016 and Office 2013, run the following commands:
GACUTIL /I
dll
GACUTIL /I
For Office 2010, run the following commands:
GACUTIL /I
dll
GACUTIL /I
3. Once you've successfully run the GACUTIL commands, restart Excel and look for the
Azure DevOps Integration Tool for Office add-in.
If the above steps are unsuccessful, try the following steps:
1. Run a full repair of Office .
2. Uninstall Office and Reinstall Office.
3. Contact the Microsoft support team.
Intermittent issues doing refresh and publish

If a user has errors when doing a refresh or publish, it may be due to a Conditional
Access Policy in AAD. To resolve this issue, try clearing the contents of the folder
%LOCALAPPDATA%\.IdentityService .
Related articles
Add or remove add-ins
Resolve data conflicts when you publish
or refresh Excel data
Article • 07/12/2023
2018
A data conflict occurs when you try to publish a work item from Excel and the version of
that work item differs from the version in the work item database. The following
example shows how two team members can create such a conflict.
1. A team member opens a copy of a work item in a work item list in Excel or Project.
2. Team member A edits the work item and makes one set of changes.
3. Team member B edits that same work item and makes a different set of changes,
and publishes those changes.
4. Team member A finishes editing the work item and tries to publish the changes to
the work item.
5. Excel or Project displays the Work Item Publishing Errors dialog box, which shows
items that it couldn't publish.
To resolve a data conflict

1. In the Work Item Publishing Errors dialog box, for each work item in the
Unpublished work items box that has Conflict in the Issue column, follow these
steps.
a. In the Unpublished work items box, select the work item.
The Details area shows a list of conflicts for the selected work item. The
Conflicting field column shows the name of the field in which the conflict
occurs. The Local version and Server version columns show the local and server
data, respectively, and a check box appears next to the data in each of these
columns.
b. For each row in the Details box, select the check box next to the correct value.
When you select the local version, the data in Office Excel or Office Project
overwrites the data on the server. If you select the server version, the server
data overwrites the data in Office Excel or Office Project.
2. Select Publish.
７ Note
This step publishes only the work items that you corrected. If you do not
resolve all data validation errors related to a work item, that work item is not
published.
Related articles
Resolve data validation errors
Required permissions
Resolve data validation errors that occur
when you publish from Excel
Article • 05/23/2023
2018
A data validation error occurs when a change in the work item list or project plan
violates a work item type's rule. The following examples show common data validation
errors:
Someone assigns a work item to a team member whose name isn't included in the
list of allowed values
Someone creates a work item but forgets to complete a required field, such as the
work item type.
If a data validation error occurs when you try to publish changes, the Work Item
Publishing Errors dialog box appears, and in the Unpublished work items list the
Issue column shows Validation error or another phrase that contains Invalid.
Prerequisites
Resolve a data validation error

You can use the Work Item Publishing Errors dialog box to resolve a data validation
error.
1. In the Work Item Publishing Errors dialog box, for each work item that appears
with a data validation error, follow these steps.
７ Note
If the data validation error is an invalid work item type, the Edit Work Item
button is not visible, and a work item form does not appear. You must correct
the error in the Office Excel worksheet or the Office Project plan. For
information about how to resolve an error in Office Excel, see the next
procedure in this article.
a. In the Unpublished work items box, select the work item, and then select Edit
Work Item.
A work item form appears.
b. In the work item form, review the information and correct the value.
c. Select Close to save your changes and close the work item form.
2. After you correct the data validation errors, select Publish to publish the corrected
work items.
７ Note
This step publishes only the work items that you corrected. If you do not
resolve a data validation error, that work item is not published.
3. Select Close to close the Work Item Publishing Errors dialog box.
Resolve a data validation error by using error

checking in Excel
You can use the Office Excel tools to find and resolve an error in a work item list. For
more information about how to use Office Excel error checking tools, see the Office
Excel Help.
To resolve a data validation error by using error checking

in Excel 2007
1. Start Excel, and select the Formulas tab.
2. In the Formula Auditing group, select Error Checking.
If the error checking tool finds an error, the Error Checking dialog box appears.
3. For basic information about the error, see the text that describes the error in the
Error Checking dialog box. For more information about the error, select Help on
this error.
4. In the work item list, select the cell that contains the error, and then correct the
value.
5. In the Error Checking dialog box, select Resume to find the next data validation
error.
If the Error Checking dialog box shows another error, repeat the previous
two steps to resolve the error.
If a message appears that indicates error checking has completed, select OK

to close both this message and the Error Checking dialog box.
Related articles
Resolve data conflicts
Configure or add a project portal
Article • 05/02/2023
2018
The project portal is a site associated with a team project for the purposes of sharing
information.
） Important
Configuring the project portal and process guidance features have been
deprecated. You can only set them from Visual Studio 2017 or earlier versions and
when connected to TFS 2017 or earlier versions. SharePoint integration with Azure
DevOps (formerly named Team Foundation Server) was deprecated with the release
of TFS 2018. For TFS 2018 and later versions, you can use the built-in wiki feature to
share information, guidance, and documents. To learn more, see About Wikis,
READMEs, and Markdown.
Related articles
About SharePoint integration
Discontinue SharePoint integration: TFS 2017 and earlier versions
Azure Boards FAQs
FAQ
2018
Find answers to frequently asked questions when using Azure Boards. For FAQs specific
to queries or Microsoft Excel integration to add or modify work items defined in Azure
DevOps, see Query FAQs and FAQs: Work in Excel connected to Azure Boards.
You can view a list of features that are on our roadmap for Azure Boards from the
Features Timeline. To request a feature or up-vote a feature, go to our Developer
Community page .
Access and permissions

Who can contribute to Azure Boards?
As a member of an Azure Boards project, you can use most features to track work.
Limitations to select features are based on the access level and security group to which
a user is assigned. Other limitations can be imposed based on work tracking permissions
or custom rules. For more information, see Default permissions and access for Azure
Boards.
How can noncontributors view or modify work

items?
For private projects, you can grant access to an unlimited number of users by assigning
them Stakeholder access. For public projects, anonymous users—ones who don't sign
into the project—can view all work items. For more information, see Stakeholder access
quick reference and Make a private project public.
Also, if your organization uses Azure Active Directory to manage user access, you can
add external users to your organization.
How can I restrict viewing or modifying select

work items?
You can restrict access by setting permissions for an area path. For more information,
see the following articles:
Set work tracking and plan permissions

Grant or restrict permissions to select tasks
Can caching impact rules applied to work items?

Yes. Conditional rules based on user or group membership get cached for your web
browser. If you find yourself restricted to update a work item, you may have
encountered one of these rules. For more information about conditional rules, see Rules
and rule evaluation. If your cache stores outdated rules, you can wait for the client cache
to expire within three days, or you can clear the cache.
To clear the cache, run the following command in the browser command window and
then refresh the browser: window.indexedDB.deleteDatabase("wit")
What client tools support work tracking with

Azure Boards?
See Tools and clients that connect to Azure DevOps.
Work items
Where should I start to learn about work items
and work item types?
For an introduction to work items, see About work items.
How do I view all work items?

To view all work items defined in a project, open a query and add two clauses:
Work Item Type = [Any]
State = [Any]
From there, you can add filters to refine the query. For more information, see Create and
save managed queries with the query editor.
Can a work item be assigned to several users or
a user group?
No. Work items can only be assigned to a single user. Also, you can only add a user that
is available from the people picker.
What's the recommended method to group

work?
The main method to group work is to assign it to the same area path. Area paths are
used to group work items by product, feature, or business areas and to support teams
responsible for work assigned to those areas. In addition, you can group work under a
parent work item using parent-child links, referred to as a hierarchical grouping.
For a discussion of these two usages and the tools they support, see Configuration and
customization of Azure Boards, Area paths, product teams, and portfolio management.
How do I mark a task or work item as a

milestone task?
Delivery Plans provide a calendar view and allow you to define a milestone marker. For
more information, see Review team Delivery Plans.
milestone:
Prepend or append the word Milestone in the title of your work item
milestone work item
Assign the milestone work item to the sprint in which it's targeted for completion.
How can I best track dependencies?

You can track dependencies between work items by linking them using a related or
other link type. See Link work items and Linking, traceability, and managing
dependencies.
You can view dependencies using Delivery Plans (Preview).

If you're tracking dependencies across one or more organizations, you may want to use
the Dependency Tracker.
What determines which work item type should

be a parent for another work item type?
Each process defines four default backlog levels: the iteration backlog, requirement
backlog, feature and epic portfolio backlogs. The work item types added to each
backlog level are the natural work item types to form parent-child relationship and
group work items into a hierarchy. For more information, see Organize your backlog,
map child work items to parents. To customize the process, see Customize your
backlogs or boards, Edit or rename the requirement backlog.
How do I copy or clone a work item with all

linked items?
With Azure Boards (cloud service), you can choose to copy child work items when
copying a work item. For more information, see Copy or clone work items.
How do I bulk modify a rich-text field?

See Bulk modify work items, Bulk modify rich-text fields.
Backlogs and Boards

What's the difference between a backlog and a
board?
Each backlog and board represents a filtered set of work items based on team area path
and iteration path assignments. Backlogs list work items, boards display work items as
cards. To understand how the filtering is applied, see About teams and Agile tools, Team
defaults referenced by backlogs and boards.
How do I add a backlog or board?

To add a backlog or board, you add a team. Each team is configured with its own set of
backlogs and boards as described in About teams and Agile tools. Each team can
customize these Agile tools.
What limits should I be aware of?
Azure DevOps imposes limits such as the number of work items that display on a
backlog or board, numbers of teams you can define, and more. For a full list, see Work
tracking, process, and project limits.
How do I migrate my existing backlog to Azure

Boards?
See Azure Boards migration and integration.
How do the three types of backlogs--product,

portfolio, and sprint backlogs--differ?
Each backlog lists a filtered set of work items based on the team's selected area path,
iteration paths, and work item types.
Product backlog: By default lists User Stories (Agile), Issues (Basic), Product
Backlog Items and Bugs (Scrum), or Requirements (CMMI). Provides options to
show Parents, Forecast, and In Progress or Completed child items.
Portfolio backlog: By default lists Features (all process models) for the Features
backlog, and Epics (Agile, Scrum, and CMMI) for the Epic backlog. Provides options
to show Parents and In Progress or Completed child items.
Sprint backlog: By default lists all product backlog items assigned to the selected
iteration, regardless of status. Provides options to show Work details.
Can I define sprints and use them with my

Kanban board?
Yes. You can assign sprints to work items and filter your Kanban board based on the
iteration path. For more information, see Filter your Kanban board.
If I manage bugs with tasks, can I add bugs as a

checklist to a requirement?
No. Task checklists only support the task work item type.
How do I create a view of the critical path?

Azure DevOps doesn't provide a native view of the critical path. In part, as Agile
epics, features, stories and tasks.
That said, we recommend that you use Delivery Plans to view dependencies and a
calendar view of work.
If your organization supports connection to Microsoft Project, you may find more
Marketplace extensions that support connection of Azure DevOps to Microsoft
Project.
For more context, see The Critical Path on Agile Projects and Running a lean startup
on Azure DevOps .
Rollup
How can I get a rollup of Story Points, Effort, or
other work item fields?
Rollup columns allow you to view progress bars or totals of numeric fields or
within the hierarchy. You can add one or more rollup columns to a product or portfolio
backlog. You can add rollup columns to a product or portfolio backlog. See {Display
rollup progress or totals](backlogs/display-rollup.md).
Can I get a rollup of team capacity?

No. The data entered for team capacity isn't stored in the regular data stores.
Kanban boards
Is there a way to widen columns on a Kanban
board?
No. This feature isn't supported. It's a suggested feature, which you can upvote by going
to our Developer Community page .
Can I query based on Kanban board columns?

Yes, see Query by assignment or workflow changes, Kanban board change queries.
Can I view a query as a Kanban board?

Yes, by adding the Query Based Boards Marketplace extension.
Is there a way to copy a Kanban configuration to

another team?
Yes, by adding the Azure Boards Kanban Tools Marketplace extension.
Can I list items based on their Kanban column

assignment?
Yes, you can track column moves on a Kanban board by using the Board Column and
Board Column Done fields.
What if I get the error message, "The column

configurations aren't valid"?
If you get the following error when you open your Kanban board, you need to correct
types that have been added to the Requirement category aren't mapped to the column.
Select Correct this now to open the Settings dialog. In the following example, two new
states are added: Triaged for bug, and Investigate for user story. Each state is then
mapped to an existing or new column. After each state is mapped to a column, the
Kanban board displays the work items assigned to these states.
Can I use swimlanes and set up swimlane rules?
Yes, you can add or remove swimlanes on your Kanban board. You can also set up
swimlane rules, where when certain conditions are met, Azure Boards automatically
moves work items into specific lanes.
Work item templates

Where should I start to learn about work item
templates?
You can define work item templates for teams you belong to. To define work item
templates to specify defaults for select fields, see Use templates to add and update work
items.
How do I set a default template for a team?

The feature to set a default template for a team isn't a supported feature at this time.
Can I copy a work item template to another

team or project?
No. This feature isn't supported at this time.
Can I create a work item template that creates

links to other work items?
Example request: When creating a template, I would like the Parent User Story to be
defaulted. There isn't a predetermined field in the template. Would/could this function be
under a user-defined selection?
No, there's no native support for creating hierarchy templates. In particular, you can't
specify a default parent work item. You can, however, quickly copy tasks, bugs, and
other items using Excel to apply parent-child links in a tree list. Or, you can use a
Kanban board to add child tasks, backlog items, or features. For more information, see:
Add task checklists

Add features and epics
Alternatively, you may find a solution for creating child work items by installing one of
the following Marketplace extensions:
Work item form one select actions

1-Click Child-Links
1-Click Tasks
How do I delete a work item template?

From the work item type page, choose the actions icon for an existing template and
select the Delete option.
GitHub integration
How do I connect Azure Boards to GitHub?
Azure Boards integrates with GitHub for Azure DevOps Server 2019 and later versions.
For more information, see Azure Boards & GitHub.
Can I specify the status when linking a work item

to a GitHub commit or PR?
No. This feature isn't supported at this time.
Configuration and customizations

What is configurable or customizable?
Configuration and customization of Azure Boards occurs at the project and team level.
For an overview of what you can configure and customize to support your business
needs, see Configuration and customization of Azure Boards.
For FAQs on configuration and customization, see Azure Boards Configuration and
Customization FAQs.
Related articles
Query FAQs
Work tracking, process, and project limits
Azure Boards Configuration and Customization FAQs
Azure Boards extensions
Article • 06/27/2023
2018
boards.
tools.

backlog name.

items

boards
example:

７ Note

７ Note
with requirements.

column.



board checklist
cards.



７ Note

model

backlogs and boards

Related articles
Create your backlog
Resolve nest, display, and reorder issues
for work items
Article • 07/07/2023
2018
When you add parent-child work item links that aren't in the natural hierarchy,
reordering is disabled. Items may not display and the system may disable the drag-and-
drop reorder feature.
Use this article to address error messages that are similar to the following message:
"You can't reorder work items and some work items may not be shown."
"Work item can't be reordered because its parent is on the same category."
"Items added to the backlog may disappear on a refresh because your team
project marks them as "in progress." Those items appear when you change the "In
progress" filter to Show."
７ Note
For other issues that may occur with multi-team ownership, see Configure a
hierarchy of teams, Exercise select features with shared area paths.
Natural hierarchy for work item types

The following image shows the natural hierarchy for the Agile, Scrum, and Capability
Maturity Model Integration (CMMI) processes.
The natural hierarchy breaks when you create same-category or same-type links
between work items. For example, parent-child links that are bug-bug or user story-user
story or requirements category-task category.
Recommended configuration
Maintain a flat list, rather than nesting requirements, bugs, and tasks. Only create
parent-child links one level deep between items that belong to a different
category. The category a work item belongs to gets determined by your process
backlog levels and your team's selected bug behavior.
Use the feature work item type to group user stories (Agile), issues (Basic), product
backlog items (Scrum), or requirements (CMMI). You can quickly map product
backlog items to features, which creates parent-child links in the background.
Don't create a hierarchy of backlog items, tasks, and bugs. Don't create same-
category hierarchies, like parent-child links among work items of the same type,
such as story-story, bug-bug, task-task, or issue-issue. The backlog, board, and
sprints experiences don't support reordering for same-category hierarchies, as it
introduces confusion by ordering a work item that doesn't belong on that level.
Resolve - Cannot reorder work items

You may see a message like: You cannot reorder work items and some work items may
not be shown . No work item IDs are listed.
To address this error, do the following steps:
1. Open your backlog.
2. Review the list of items to determine which items of the same type are nested.
Example #1: The following image shows a user story as a child of another user
story.
Example #2: The following image shows a bug as a child of a user story. Because
the team configured their backlog to display user stories and bugs at the same
level (Requirements category), this configuration results in a nested item that
disables the ordering feature.
3. Remove all parent-child links that exist among nested items of the same work item
type or same category. Or, change the link to 'Related.'
4. Refresh your backlog.
The message no longer displays.
Resolve - Cannot reorder work items, change

link type or category
You may see a message like: You cannot reorder work items and some work items may
not be shown. See work item(s) 7 to either remove the parent to child link or
change the link type to 'Related'." or "Work item 3 can't be reordered because its
parent is on the same category" .
To address this error, do the following steps:
1. Open the work item listed in the error message.

2. Look for a parent or child link. Make sure this link goes to a work item within the
same category as the work item you opened. This link goes to another work item
that appears on the same backlog level as the work item you opened. Depending
on your team's bug behavior setting, bugs may appear with requirements or tasks.
3. Remove the problem parent-child link. If you would like to keep these items
associated, use 'Related' link type instead.
The message no longer displays.

Resolve - Work items in progress may
disappear on refresh
You may see a message like: Items added to the backlog may disappear on a refresh
because your team project marks them as "in progress". Those items appear when you
change the "In progress" filter to Show. . This message indicates that the In Progress
filter for the backlog is turned off.
When you refresh your browser, the backlog displays those work items based on your
selected filters. To reset the filters, complete the following steps.
1. Open your backlog.

2. From the View options selector, choose to show or hide In Progress items.
If you turn the In Progress control off, then items that are in the Active, Committed,
or Resolved states or states that map to the In Progress category state don't
appear in the backlog.
Hide In Progress items when you want to forecast work. For more information, see
Forecast your product backlog.
Each team can choose how to track bugs, like requirements or tasks, or neither.
If you track bugs as requirements, only nest bugs under the Feature level.
If you track bugs as tasks, only nest bugs under the Requirement level.
Display nested items on backlogs and boards

Sprint backlogs and Taskboards only show the last node in a same-category hierarchy,
called the leaf node.
Sprint backlogs and Taskboards

When bugs appear in the backlog with tasks, linking tasks and bugs to their parent
requirements groups them correctly on the sprint backlog and Taskboard.
But, if you create parent-child links between a requirement and a bug, and the bug and
a task, as shown here, the task appears on the sprint backlog and Taskboard, but not the
bug.
Hierarchy of items assigned to a sprint backlog

Only leaf nodes appear on sprint backlogs
Only leaf nodes appear on Taskboards

Q: Is there a workaround to display
intermediate nodes within a hierarchy?
A: No, not at this time. You can always check the entire list of items assigned to a sprint
when you select Create query.
Related articles
Set up your backlogs and boards
About boards and Kanban, Limitations of multi-team Kanban board views
Field descriptions for default and work
item fields used in process templates
Article • 05/02/2023
2018
Use this index to look up a description of each field used to track work items. This
reference includes all fields defined within the core system processes/process templates:
Basic, Agile, Scrum, and CMMI. The fields and work item types (WITs) available to you
depend on the process you chose when you created your project.
To support other tracking needs, you can define your own custom work item fields.
７ Note
The Analytics Service doesn't support reporting on plain text and HTML fields.
Alphabetical index
Values in parenthesis indicate the following criteria:
System: Core system field assigned to all work item types for all processes
Agile: Used only by the Agile process
CMMI: Used only by the CMMI process
Scrum: Used only by the Scrum process
TCM: Used to support Test case management
A
Acceptance Criteria (Scrum)
Accepted By
Accepted Date
Activated By
Activated Date
Activity
Actual Attendee 1-8 (CMMI)
Analysis (CMMI)
Application Launch Instructions
Application Start Information
Application Type
Area ID (System)
Area Path (System)
Assigned To
Associated Context
Associated Context Code
Associated Context Owner
Associated Context Type
Attached File Count
Authorized As (Not used)
Automated Test Id (TCM)
Automated Test Name (TCM)
Automated Test Storage (TCM)
Automated Test Type (TCM)
AutomatedTestId (TCM)
AutomatedTestName (TCM)
Automation Status (TCM)
B
Backlog Priority (Scrum)
Blocked
Board Column
Board Column Done
Board Lane
Business Value
C
Called By (CMMI)
Called Date (CMMI)
Changed By (System)
Changed Date (System)
Closed By (System)
Closed Date (System)
Closed Status
Closed Status Code
Closing Comment
Comment Count
Comments (CMMI)
Committed (CMMI)
Completed Work
Contingency Plan (CMMI)
Corrective Action Actual Resolution (CMMI)
Corrective Action Plan (CMMI)
Created By (System)
Created Date (System)
D-E-F
Discipline (CMMI)
Description (System)
Due Date
Effort
Escalate (CMMI)
External Link Count
Finish Date
Found In Build (TCM)
Found In Environment (CMMI)
H
History (System)
How Found (CMMI)
Hyperlink Count
I
ID (System)
Impact Assessment (CMMI)
Impact on Architecture (CMMI)
Impact on Development (CMMI)
Impact on Technical Publications (CMMI)
Impact on Test (CMMI)
Impact on User Experience (CMMI)
Integrated in Build (TCM)
Issue (TCM)
Iteration ID (System)
Iteration Path (System)
J-L-M-N
Justification (CMMI)
Link Comment (System)
Link Description (System)
Local Data Source (TCM)
Meeting Type (CMMI)
Minutes (CMMI)
Mitigation Plan (CMMI)
Mitigation Triggers (CMMI)
Node Name (System)
O-P-Q
Optional Attendee 1-8 (CMMI)
Original Estimate
Parameters (TCM)
Parent1
Priority
Probability (CMMI)
Proposed Fix (CMMI)
Purpose (CMMI)
Query Text (TCM)
R
Rating
Reason (System)
Related Link Count (System)
Remaining Work
Remote Link Count2 (System)
Repro Steps
Required Attendee 1-8 (CMMI)
Requirement Type (CMMI)
Requires Review (CMMI)
Requires Test (CMMI)
Resolution (Scrum)
Resolved By
Resolved Date
eso ed ate
Resolved Reason
Rev (System)
Reviewed By
Reviewed Date
Revised Date (System, TCM)
Risk (Agile)
Root Cause (CMMI)
S
Severity
Size (CMMI)
Stack Rank
Start Date
State (System)
State Change Date
State Code
Steps (TCM)
Steps to Reproduce (TCM)
Story Points (Agile)
Subject Matter Expert (CMMI)
Symptom (CMMI)
System Info (TCM)
T
Tags
Target Date
Target Resolve Date (CMMI)
Task Type (CMMI)
Team Project (System)
Test Suite Audit (TCM)
Test Suite Type (TCM)
Test Suite Type ID (TCM)
Time Criticality
Title (System)
Triage (CMMI)
U-V-W
User Acceptance Test (CMMI)
Value Area
Watermark (System)
Work Item Type (System)
７ Note
1. This field is available from Azure DevOps Services and Azure DevOps Server
2020 and later versions.
2. This field is available for Azure DevOps Services only.
By using the system fields or other fields you've added to your project collection, you
can enable meaningful cross-project reports and queries. Also, any non-system field that
is referenced in the workflow or forms section of the work item type definition must
have a FIELD element that defines it in the FIELDS section of the work item type
definition XML file. Also, you must specify any non-system field that you might want to
use to generate a query or report in the FIELDS section.
Field reference articles

The following articles describe fields that are used in common by several WITs, or those
fields that are functionally specific to just one or a few WITs.
Fields common to many work types

Titles, IDs, and descriptive fields
History and revision changes
Areas and iterations
Assignments and account-specific fields
Planning, ranking, and priorities
Work estimates, activity, and other numeric fields
Build and test integration fields
Links and attachment related fields
Fields used by specific work item types

Code Review Request
Feedback Request
Feedback Response
Shared Steps
Test Case
Fields used to track CMMI work items

Requirements
Bugs
Change Requests
Issues
Review Meetings
Risks
Related articles
About work item fields
Define a query
Work item fields and attributes in Azure
Boards
Article • 05/08/2023
2018
Work item fields are used to track information. Fields are defined for an organization
and shared across all projects defined for that organization. You can use one of two
tools to review the fields defined for the organization. These tools are available for both
Inherited and Hosted XML process models.
Process>Fields web page

Work Item Field Explorer
For a description of each field defined with a system process, see Work item field index.
Prerequisites
To view the fields defined for an organization or collection, you must be a member
of the Project Collection Valid Users application group or have the View instance-
level information permission set to Allow for the organization or collection.
List or review fields

To list or review fields, you can use one of the following tools, depending on the process
model—Inheritance, Hosted XML, or On-premises XML—you use. For an index of fields
defined within the default processes, see Work item field index.
Tool Inheritance Hosted On-premises

XML XML
Web portal: List inherited and custom-defined ✔️ ✔️1

fields
Work item field explorer ✔️ ✔️ ✔️
witadmin listfields command line tool ✔️ ✔️ ✔️
７ Note
1. Only supported for default processes (Agile, CMMI, Scrum).
Field data types and names

Each work item type specifies the fields defined for the work items that reference that
type. Each field is associated with a number of attributes, many of which are set by the
system and cannot be changed.
Each field is defined by the following three attributes.
Data type: Specifies the type of data that can be entered into the field, such as
Boolean, Double, Integer, HTML, and String. For descriptions of each data type, see
Query fields, operators, and macros.
Friendly name: Specifies the name assigned to the field and that you select for a
Field in a query clause. This name may differ from the name displayed on the work
item form.
Reference name: Specifies the name that you use when creating WIQL query or an
improvised work item template, using REST API commands, or defining XML work
item type definitions. Once defined, the reference name cannot be changed.
For a description of each field attribute and how you can list them, see Field attributes
and List field attributes later in this article. For an overview of WITs and work items, see
Track work with user stories, issues, bugs, features, and epics.
What is a field? How are field names used?

Each work item type is associated with 31 system fields and several more type-specific
fields. You use work items to plan and track your project.
Each field supports tracking a piece of information about the work to perform. Values
you assign to a field are stored in the work tracking data store which you can create
queries to determine status and trends.
For descriptions and usage of each field defined for the core system processes, Agile,
Basic, Scrum, and CMMI processes, see Work item field index.
Field names
A work item field name uniquely identifies each work item field. Make sure your field
names fall within these guidelines:
Field names must be unique within the account/project collection
Field names must be 128 or fewer Unicode characters
Field names can't contain any leading or trailing spaces, nor two or more
consecutive spaces
Field names must contain at least one alphabetic character
Field names can't contain the following characters: .,;'`:~\/\*|?"&%$!+=()[]{}<> .
Because custom fields are defined for an organization or collection, you can't add a
custom field to a process with the same field name that you add to another process.
For more information, see Naming restrictions and conventions.
System and predefined fields

All system defined fields have reference names that begin with System, for example,
System.AreaPath, System.AssignedTo, and continue in that pattern.
Predefined fields defined by the default process begin with Microsoft.VSTS and then
further differ based on their usage. Examples of predefined fields that are used in
common, for scheduling purposes and integration with Office Project, for integration
with Team Foundation Build, and integration with test case management (TCM) are as
follows:
Microsoft.VSTS.Common.Priority
Microsoft.VSTS.Scheduling.DueDate
Microsoft.VSTS.Build.FoundIn
Microsoft.VSTS.TCM.Steps
For an overview of all system and predefined fields that are defined for the default
processes/process templates, see Work item field index. For more information about
specifying field names, see Naming restrictions.
Custom fields
Because custom fields are defined for an organization or project collection, you can't
add a custom field to a process with the same field name that you add to another
process.
When adding custom fields, note the following limits:
A maximum of 64 fields can be defined for each WIT

A maximum of 512 fields can be defined per process
The field data type determines the kind and size of data that you can store in the field. A
field can have only one type defined within a project collection. This restriction
encourages organizations to use common fields across projects and work item types.
When you add a custom field to an inherited process, Azure DevOps assigns a reference
name prefixed with Custom and then the name of the field with spaces removed. For
example, you add a field named DevOps Triage, the reference name is
Custom.DevOpsTriage. No spaces are allowed within the reference name.
How can I determine the field data type?

You can view the data type of fields defined for your organization by opening the
Process>Fields page.
Process>Fields web page

To review the list of fields defined for an organization or collection, open Organization
settings>Process>Fields.
1. Choose the Azure DevOps logo to open Projects. Then choose Organization
settings.
2. Then, choose Process.
７ Note
If you don't see Process, then you're working from TFS-2018 or earlier version.
The Process page isn't supported. You must use the features supported for
the On-premises XML process model.
3. Then, choose Fields.
Fields listed correspond to all fields defined for the organization or collection. This
includes all custom fields and those defined for system processes.
７ Note
If you don't see Fields, then your collection uses the On-premises XML
process. The Fields page isn't supported for that process.
For descriptions and usage of each field, as well as the Reference name for each
field, you can look it up from the Work item field index. You can also get the
Reference name of fields from the Work Item Types Field - List REST API.
Work Item Field Explorer

You can look up the assignments of field attributes using the Work Item Field Explorer
tool.
To access the Work Item Field Explorer, you must install the Process Editor Tool. Based
on the version of Visual Studio you have installed, get the Process Editor Tool from one
of the following extensions.
Visual Studio 2019: Process Template Editor .

Visual Studio 2017: TFS Process Template Editor . You can also use this version of
the Process Editor to modify the old-style work item forms. You can't use it to edit
forms associated with the new web forms.
Visual Studio 2015: TFS Power Tools .
Field attributes
There are many non-changeable and hidden attributes for each work item field. The
following table describes each attribute. Attributes have different names based on if you
get them through the Fields - Get REST API or view through the Work Item Field
Explorer (WIFE) tool.
Attributes assigned to a field depend on the platform and version you use. For example,
some attributes aren't support with the Inheritance process. To look up the reference
name for a field, see Work item field index.
Attribute
Attribute type
Description
REST:
WIFE: AllowedValues
collection
Gets the collection of valid values for a field that contains picklist values. You can change
this by specifying a picklist or global list (on-premises).
Can change?=Yes
REST: canSortBy
WIFE: CanSortBy
boolean
Indicates whether you can sort query results with this field.
Can change?=No
REST: description
WIFE: HelpText
string
Specifies a description for the field, which also defines the help text that appears when
you hover over the field within the work item form.
Can change?=Yes
REST:
WIFE: ID
Integer
Specifies the internal ID of the field.

Can change?=No
REST:
WIFE: IsCloneable
boolean
Indicates whether the value defined for the field is copied when a user chooses to copy
a work item. For example, Title, Tags, and Description fields are copied, but the ID and
History fields aren't copied.
Can change?=No
REST:
WIFE: IsComputed
boolean
Indicates if the value set by this field is computed by the system (True) or not (False).
Examples of computed fields are ones that are set by the system, such as the ID, Revised
Date, Changed Date, and External Link Count.
Can change?=No
REST:
WIFE: IsCoreField
boolean
Indicates whether this field is specified for all work item types.
Can change?=No
REST:
WIFE: IsEditable
boolean
Indicates if users can modify this field (True) or not (False). Examples of non-editable
fields are ones that are set by the system, such as the ID, Revision, Created By, and
Changed By fields
Can change?=No
REST: isIdentity
WIFE: IsIdentity
boolean
Indicates whether this field is an Identity field. Identity fields are string fields used to
store user identities.
Can change?=No
REST:
WIFE: IsIndexed1
boolean
Indicates whether this field is indexed to support search.

Can change?=No
REST:
WIFE: IsLongText
boolean
Indicates that the field can contain more than 255 characters, such as fields assigned a
data type of PlainText, HTML, or History.
Can change?=No
REST: isPicklist2 WIFE:
boolean
Indicates whether the field is associated with a picklist. The value is set to True when a
custom field is defined for Azure DevOps and Picklist (String) or Picklist (Integer) type is
selected. The value is set to False for inherited fields that define picklists.
Can change?=No
REST: isPicklistSuggested2 WIFE:
boolean
Indicates whether the field allows users to enter their own values for a picklist. The value
is set to True when a custom field is defined for Azure DevOps, Picklist (String), or Picklist
(Integer) type is selected, and the checkbox for Allow users to set their own values is
checked.
Can change?=Yes
REST: isQueryable
WIFE: IsQueryable
boolean
Indicates if the field shows up within the set of fields you can add to filter a work item
query (True), or not (False). Most fields are queryable.
Can change?=No
REST:
WIFE: IsReportable 3
boolean
Indicates if the reportable attribute is defined or set to anything other than None. This
attribute can be changed for on-premises environments.
Can change?=Yes
REST:
WIFE: IsUsedInGlobalWorkflow
boolean
Indicates if the field is defined within a global workflow.

Can change?=No
REST:
WIFE: IsUserNameField
boolean
Indicates if the field is used to display an Identity field.

Can change?=No
REST: name
WIFE: Name
string
Friendly name assigned to the field. The friendly name can't be changed for Azure
DevOps, but can be changed for on-premises using the witadmin changefield
command.
Can change?=On-prem only
REST: picklistId
WIFE: HelpText
GUID
If the field is a picklist, the identifier of the associated picklist, otherwise null. A unique
GUID value is assigned when a custom field is defined for Azure DevOps and Picklist
(String) or Picklist (Integer) type is selected.
Can change?=No
REST:
WIFE: ProhibitedValues
collection
Gets the collection of prohibited values for a field that specifies such values. You can
only define prohibited values for on-premises deployments.
REST: readOnly
WIFE:
boolean
Indicates whether the field is set to read only. For Azure DevOps Services, only custom
fields can be changed to be read-only. System fields cannot be modified.
Can change?=Yes
REST: referenceName
WIFE: ReferenceName
string
Specifies the reference name of a field.

Can change?=No
REST:
WIFE: ReportingAttributes3
Specifies Detail, Dimension, or Measure, depending on whether and how you want the
field to be included in reports. Data from fields that have a value other than None for
this attribute are exported to the data warehouse and can be included in SQL reports.
REST:
WIFE: ReportingName3
string
Specifies the label for a field when data appears in SQL reports. If you don't specify a
value, the field's friendly name is used.
Can change?=On-premises only
REST:
WIFE: ReportingReferenceName3
string
Specifies a different reference name to a field that is used when data is exported to the
relational data warehouse. If you don't specify a value, the fields reference name is used.
Can change?=On-premises only
REST: supportedOperations
WIFE:
set
The set of query operators that are valid for use when referencing this field. For a quick
reference of supported operations based on data type, see Query quick reference,
Operators, and macros supported for each data type.
Can change?=No
REST:
WIFE: SupportsTextQuery
boolean
Indicates whether the field supports text queries such as Contains Words, Does Not
Contains Words.
Can change?=No
REST:
WIFE: SystemType
string
Specifies the data type of the field, referencing the system name such as
System.DateTime or System.String.
Can change?=No
REST: type
WIFE: FieldType
string
Specifies the data type of the field, such as Boolean, DateTime, Integer, String, and so on.
For a complete list and descriptions, see Query fields, operators, and macros.
Can change?=No
REST: usage
WIFE: Usage
string
Specifies whether the field is intended for use with work items (WorkItem) or work item
link (WorkItemLink) objects. The usage for most fields is WorkItem. For a complete list of
usage values, see Get Fields, FieldUsage.
Can change?=No
７ Note
1. For on-premises deployments, you can enable indexing for a field to improve
query response times when filtering on the field. For more information, see
Indexed fields later in this article.
2. The isPicklist and isPicklistSuggested attributes are only assigned to custom
fields defined for an inherited process. The Inherited process model is
supported for Azure DevOps Server 2019 and later versions. For more
information, see Inherited process model.
3. All reporting attributes are valid only for on-premises deployments whose
projects have been configured to support SQL Server Reporting and SQL
Server Analysis Services.
List field attributes

You can list the attributes assigned to a field by using the Fields - Get REST API. Enter
your organization name for OrganizationName.
REST
https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName
For example, here we list the attributes for the Iteration Path, specifying the reference
name, System.IterationPath , for the fabrikam organization.
REST
https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath
Returned data:
JSON
{
"name": "Iteration Path",
"referenceName": "System.IterationPath",
"description": "The iteration within which this bug will be fixed",
"type": "treePath",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "SupportedOperations.Under",
"name": "Under"
},
{
"referenceName": "SupportedOperations.NotUnder",
"name": "Not Under"
},
{
"referenceName": "SupportedOperations.Equals",
"name": "="
},
{
"referenceName": "SupportedOperations.NotEquals",
"name": "<>"
},
{
"referenceName": "SupportedOperations.In",
"name": "In"
},
{
"name": "Not In"
}
],
"isIdentity": false,
"isPicklist": false,
"isPicklistSuggested": false,
"url": "https://dev.azure.com/mseng/_apis/wit/fields/System.IterationPath"
}
Add and modify fields

To add fields to a process, you add them to one or more work item types. For more
information, see Customize an inheritance process.
Related articles
Add and manage fields for an inherited process
Metadata reference for Azure Boards Analytics
Code review and feedback field
reference in Azure Boards and Azure
DevOps
Article • 02/24/2023
2018
You can use the code review and feedback fields to create queries and reports that track
the status of these processes. The fields appear in the following work item types, which
are included with the default processes for Azure Boards and TFS: Code Review Request,
Code Review Response, Feedback Request, and Feedback Response.
Fields used to track code reviews

The following fields are used to track code review requests and responses. You can only
make a Code Review request against code maintained in a Team Foundation version
control (TFVC) repository. A code review response is created for each person who
provides review comments. See Day in the life of a Developer: Suspend work, fix a bug,
and conduct a code review.
７ Note
Retrieving code review comments programmatically isn't a supported feature.
Field name Description Data

type
Accepted The name of the code reviewer. String

By Reference name=Microsoft.VSTS.CodeReview.AcceptedBy
Accepted The date and time when the code-reviewer responded. DateTime
Date Reference name=Microsoft.VSTS.CodeReview.AcceptedDate
Associated The name assigned to the code work requested for review. String
Context Reference name=Microsoft.VSTS.CodeReview.Context
Associated An integer value that captures whether the code review is for 1 Integer
Context (shelveset) or 2 (changeset).
Code Reference name=Microsoft.VSTS.CodeReview.ContextCode
type
Associated The GUID assigned to the shelveset owner who requested the code String
Context review.
Owner Reference name=Microsoft.VSTS.CodeReview.ContextOwner
Associated The type of code work requested for review: Shelveset or Changeset. String
Context Reference name=Microsoft.VSTS.CodeReview.ContextType
Type
Closed The status selected by the reviewer when closing the code review String
Status request. The number is stored in the system and written to the data
warehouse as follows:
- 0 — Not Reviewed
- 1 - Looks Good
- 2 - With Comments
- 3- Needs Work
- 4 - Declined
- 5 - Removed
Reference name=Microsoft.VSTS.CodeReview.ClosedStatus
Closed A value ranging from 0 to 5 that corresponds to the status selected by Integer
Status the reviewer when closing the code review request.
Code Reference name=Microsoft.VSTS.CodeReview.ClosedStatusCode
Closing The comment entered by the reviewer when closing the review String
Comments request.
Reference name=Microsoft.VSTS.CodeReview.ClosingComment
Reviewed The name of the team member who reviewed the code. The State String
By transitions to Reviewed when the code reviewer responds. (Code
Review Response)
Reference name=Microsoft.VSTS.Common.ReviewedBy
Reviewed The date-time stamp when the reviewer closed the request. (Code Date-
Date Review Response) Time
Reference name=Microsoft.VSTS.Common.ReviewedDate
State Code Mirror field used to track the current state in code. Integer
Reference name=Microsoft.VSTS.Common.StateCode
Fields used to track feedback

The following fields track feedback requests and responses. You complete the first three
fields in the feedback request form. A feedback response is created for each person and
for each item for which feedback is provided. See Get feedback.
type
Application Instructions to stakeholders on how to start the application. HTML

Launch Reference
Instructions name=Microsoft.VSTS.Feedback.ApplicationLaunchInstructions
Application Guidelines to direct stakeholder feedback. PlainText

Start Reference name=Microsoft.VSTS.Feedback.ApplicationStartInformation
Information
Application The type of application that stakeholders provide feedback on. The String
Type valid types are specified in the process configuration file,
ProcessConfiguration. The default values are Web Application, Remote
Machine, and Client Application.
Reference name=Microsoft.VSTS.Feedback.ApplicationType
Rating The number of stars that an item receives from a reviewer in a star- String
based ranking system. (Feedback Response)
The number is stored in the system and written to the data warehouse
as follows:
- 0 — Not Rated
- 1 - Poor
- 2 - Fair
- 3- Good
- 4- Very Good
- 5 - Excellent
Reference name=Microsoft.VSTS.Common.Rating
Related articles
Index of work item fields
Get feedback
Day in the life of a Developer: Suspend work, fix a bug, and conduct a code review
Bugs, issues, and risks in Azure Boards
Article • 02/24/2023
2018
The following fields track information about bugs, issues, and risks. These work item
types are defined within the process template for the CMMI process.
Bug tracking fields

These fields are neither reported nor indexed.

type
Symptom The unexpected behavior. HTML

Reference name=Microsoft.VSTS.CMMI.Symptom
Proposed The proposed change to fix the reported problem. HTML

Fix Reference name=Microsoft.VSTS.CMMI.ProposedFix
Found in The software setup and configuration where the bug was found. String
Environment Reference name=Microsoft.VSTS.CMMI.FoundInEnvironment
Root Cause The cause of the error. You can specify one of the following values: String
<br /- Coding Error
- Design Error
- Specification Error
- Communication Error
- Unknown
To change the menu selection, see Customize a picklist.

Reference name=Microsoft.VSTS.CMMI.RootCause
How Found How the bug was found. For example, a bug might have been found String
during a customer review or through ad hoc testing.
Reference name=Microsoft.VSTS.CMMI.HowFound
Issue tracking fields

type
Analysis The root cause of the issue and one or more solutions that HTML
might resolve it.
Reference name=Microsoft.VSTS.CMMI.Analysis
Corrective Action What the team actually did to correct the issue. HTML
Actual Resolution Reference
name=Microsoft.VSTS.CMMI.CorrectiveActionActualResolution
Corrective Action The proposed corrective action on which the team has agreed. HTML
Plan Reference name=Microsoft.VSTS.CMMI.CorrectiveActionPlan
Target Resolve The date when the issue becomes critical and starts to affect DateTime
Date the critical path of the project plan.
Reference name=Microsoft.VSTS.CMMI.TargetResolveDate
Risk tracking fields


type
Contingency The actions to take if the risk occurs. HTML

Plan
You can create and link tasks to the Risk work item to track the work that
the team must complete to implement the contingency plan. Also, you
can create an Issue work item to track one or more issues on which the
risk has an impact.
Reference name=Microsoft.VSTS.CMMI.ContingencyPlan
Mitigation The actions to take to reduce the probability or impact of the risk. HTML
Plan
You can create and link tasks to the Risk work item to track the work that
the team must complete to implement the mitigation plan.
Reference name=Microsoft.VSTS.CMMI.MitigationPlan
Mitigation The conditions or events that determine how the team might mitigate a HTML
Triggers risk. For example, the triage team might authorize and obtain a reserve
generator if the weather forecast is predicting an ice storm or hurricane
to hit within 50 miles of the office within the next four days.
Reference name=Microsoft.VSTS.CMMI.MitigationTriggers
type
Probability A number that indicates the chance that the risk will occur. A valid Integer
probability number is between 1 and 99, where 99 indicates that the risk
is almost certain to occur.
Reference name=Microsoft.VSTS.CMMI.Probability
Related articles
Index of work item fields
Work Items
Reference
Service: Work Item Tracking
API Version: 7.1-preview
The Work Item API is used for listing, creating and updating work items
Operations
Create Creates a single work item.
Delete Deletes the specified work item and sends it to the Recycle Bin,
so that it can be restored back, if required. Optionally, if the
destroy parameter has been set...
Delete Work Items Deletes specified work items and sends them to the Recycle Bin,
so that it can be restored back, if required. Optionally, if the
destroy parameter has been set ...
Get Work Item Returns a single work item.
Get Work Items Batch Gets work items for a list of work item ids (Maximum 200)
Get Work Item Template Returns a single work item from a template.
List Returns a list of work items (Maximum 200)
Update Updates a single work item.

Fields
Reference
Operations
Create Create a new field.
Delete Deletes the field. To undelete a filed, see "Update Field" API.
Get Gets information on a specific field.
List Returns information for all fields. The project ID/name parameter
is optional.
Update Update a field.

Boards
Reference
Service: Work
API Version: 5.0
Operations
Get Get board
List Get boards
Set Board Options Update board options

Backlogs
Reference
Service: Work
Operations
Get Backlog Get a backlog level
Get Backlog Level Work Items Get a list of work items within a backlog level
List List all backlog levels

Queries
Reference
The queries in a team project are organized in folders.
A sample structure of queries and folders might appear as shown here.
My Queries
Shared Queries
Feedback (Query)
Current Sprint
Blocked Tasks (Query)
Open Impediments (Query)
Test Cases (Query)
Unfinished Work (Query)
Work in Progress (Query)
Operations
Create Creates a query, or moves a query.
Learn more about Work Item Query Language (WIQL) syntax

here.
Delete Delete a query or a folder. This deletes any permission change

on the deleted query or folder and any of its descendants if it is
a folder. It is important to n...
Get Retrieves an individual query and its children
Get Queries Batch Gets a list of queries by ids (Maximum 1000)
List Gets the root queries and their children
Search Queries Searches all queries the user has access to in the current project
Update Update a query or a folder. This allows you to update, rename

and move queries and folders.
Plans
Reference
Service: Work
Controller for the Scaled Agile plans REST API
Operations
Create Add a new plan for the team
Delete Delete the specified plan
Get Get the information for the specified plan
List Get the information for all the plans configured for the given
team
Update Update the information for the specified plan

Wiql
Reference
API Version: 5.0
The WIQL API is used to run a query given the WIQL text or a saved query ID.
Learn more about Work Item Query Language (WIQL) syntax here.
Operations
Get Gets the results of the query given the query ID.
Query By Id Gets the results of the query given the query ID.
Query By Wiql Gets the results of the query given its WIQL.
What is Agile?
Article • 11/28/2022
Agile is a term that describes approaches to software development that emphasize

incremental delivery, team collaboration, continual planning, and continual learning. The
term Agile was coined in 2001 in the Agile Manifesto . The manifesto set out to
establish principles to guide a better approach to software development. At its core, the
manifesto declares four value statements that represent the foundation of the Agile
movement. As written, the manifesto states:
We have come to value:
Individuals and interactions over processes and tools.

Working software over comprehensive documentation.
Customer collaboration over contract negotiation.
Responding to change over following a plan.
The manifesto doesn't imply that the items on the right side of these statements aren't
important or needed. Rather, items on the left are simply more valued.
Agile methods and practices

It's important to understand that Agile isn't a thing. You don't do Agile. Rather, Agile is a
mindset that drives an approach to software development. Because there's no single
approach that works for all situations, the term Agile has come to represent various
methods and practices that align with the value statements in the manifesto.
Agile methods, which are often called frameworks, are comprehensive approaches to
phases of the DevOps lifecycle: planning, development, delivery, and operations. They
prescribe a method for accomplishing work, with clear guidance and principles.
Scrum is the most common Agile framework, and the one that most people start with.
Agile practices, on the other hand, are techniques that are applied during phases of the
software development lifecycle.
Planning Poker is a collaborative estimation practice that's designed to

encourage team members to share their understanding of what done means. Many
people find the process fun, and it has proven to help foster teamwork and better
estimates.
Continuous integration (CI) is a common Agile engineering practice that involves
integrating code changes into the main branch frequently. An automated build
verifies changes. As a result, there's a reduction in integration debt and a
continually shippable main branch.
These practices, like all Agile practices, carry the Agile label, because they're consistent
with the principles in the Agile manifesto.
What Agile isn't

As Agile has gained popularity, many stereotypes and misinterpretations have cast a
negative shadow on its effectiveness. It's easy to say "Yes, we're doing Agile," without any
accountability. Keeping this point in mind, consider a few things that Agile isn't.
Agile isn't cowboy coding . Agile shouldn't be confused with a "we'll figure it out
as we go" approach to software development. Such an idea couldn't be further
from the truth. Agile requires both a definition of done and explicit value that's
delivered to customers in every sprint. While Agile values autonomy for individuals
and teams, it emphasizes aligned autonomy to ensure that the increased
autonomy produces increased value.
Agile isn't without rigor and planning. On the contrary, Agile methodologies and
practices typically emphasize discipline in planning. The key is continual planning
throughout the project, not just planning up front. Continual planning ensures that
the team can learn from the work that they execute. Through this approach, they
maximize the return on investment (ROI) of planning.
"Plans are worthless, but planning is everything." — Dwight D. Eisenhower
Agile isn't an excuse for the lack of a roadmap. This misconception has probably
done the most harm to the Agile movement overall. Organizations and teams that
follow an Agile approach absolutely know where they're going and the results that
they want to achieve. Recognizing change as part of the process is different from
pivoting in a new direction every week, sprint, or month.
Agile isn't development without specifications. It's necessary in any project to
keep your team aligned on why and how work happens. An Agile approach to
specs includes ensuring that specs are right-sized, and that they reflect
appropriately how the team sequences and delivers work.
Agile isn't incapable of accommodating unplanned work and other interruptions.
It's important to complete sprints on schedule. But just because an issue comes up
that sidetracks development doesn't mean that a sprint has to fail. Teams can plan
for interruptions by designating resources ahead of time for problems and
unexpected issues. Then they can address those issues but stay on track with
development.
Agile isn't inappropriate for large organizations. A common complaint is that
collaboration, a key component of Agile methodologies, is difficult in large teams.
Another gripe is that scalable approaches to Agile introduce structure and
methods that compromise flexibility. In spite of these misconceptions, it's possible
to scale Agile principles successfully. For information about overcoming these
difficulties, see Scaling Agile to large teams.
Agile isn't inefficient. To adapt to customers' changing needs, developers invest
time each iteration to demonstrate a working product and collect feedback. It's
true that these efforts reduce the time that they spend on development. But
incorporating customer requests early on saves significant time later. When
features stay aligned with the customer's vision, developers avoid major overhauls
down the line.
Agile isn't a poor fit for today's applications, which often center on data streaming.
Such projects typically involve more data modeling and extract-transform-load
(ETL) workloads than user interfaces. This fact makes it hard to demonstrate usable
software on a consistent, tight schedule. But by adjusting goals, developers can still
use an Agile approach. Instead of working to accomplish tasks each iteration,
developers can focus on running data experiments. Instead of presenting a
working product every few weeks, they can aim to better understand the data.
Why Agile?
So why would anyone consider an Agile approach? It's clear that the rules of
engagement around building software have fundamentally changed in the last 10-15
years. Many of the activities look similar, but the landscape and environments where we
apply them are noticeably different.
Compare what it's like to purchase software today with the early 2000s. How often
do people drive to the store to buy business software?
Consider how feedback is collected from customers about products. How did a
team understand what people thought about their software before social media?
Consider how often a team desires to update and improve the software that they
deliver. Annual updates are no longer feasible against modern competition.
Forrester's Diego Lo Guidice says it best in his blog, Transforming Application Delivery
(October, 2020).
"Everything has dramatically changed. Sustainability, besides green and clean,

means that what we build today has to be easily and quickly changed tomorrow.
Strategic plans are short-term, and planning and change are continuous." — Diego
Lo Guidice, Forrester
The rules have changed, and organizations around the world now adapt their approach
to software development accordingly. Agile methods and practices don't promise to
solve every problem. But they do promise to establish a culture and environment where
solutions emerge through collaboration, continual planning and learning, and a desire
to ship high-quality software more often.
Next steps
Deciding to take the Agile route to software development can introduce some
interesting opportunities for enhancing your DevOps process. One key set of
considerations focuses on how Agile development compares and contrasts with an
organization's current approach.
Article • 11/28/2022
Agile development is a term that's used to describe iterative software development.

Iterative software development shortens the DevOps life cycle by completing work in
short increments, usually called sprints. Sprints are typically one to four weeks long.
Agile development is often contrasted with traditional or waterfall development, which
plans larger projects up front and completes them according to the plan.
Delivering production quality code every sprint requires the Agile development team to
account for an accelerated pace. All coding, testing, and quality verification must be
done each and every sprint. Unless a team is properly set up, the results can fall short of
expectations. While these disappointments offer great learning opportunities, it's helpful
to learn some key lessons before getting started.
This article lays out a few key success factors for Agile development teams:
Diligent backlog refinement

Integrating early and often
Minimizing technical debt
Diligent backlog refinement

An Agile development team works off a backlog of requirements, which are often called
user stories. The backlog is prioritized, with the most important user stories at the top.
The product owner owns the backlog and adds, changes, and reprioritizes user stories
based on the customer's needs.
One of the biggest drags on an Agile team's productivity is a poorly defined backlog. A
team can't be expected to consistently deliver high quality software each sprint unless
they have clearly defined requirements.
The product owner's job is to ensure that every sprint, the engineers have clearly
defined user stories to work with. The user stories at the top of the backlog should
always be ready for the team to start on. This notion is called backlog refinement.
Keeping a backlog ready for an Agile development team requires effort and discipline.
Fortunately, it's well worth the investment.
When you refine a backlog, remember the following key considerations.
1. Refining user stories is often a long-lead activity. Elegant user interfaces, beautiful
screen designs, and customer-delighting solutions all take time and energy to
create. Diligent product owners refine user stories two to three sprints in advance.
They account for design iterations and customer reviews. They work to ensure
every user story is something the Agile team is proud to deliver to the customer.
2. A user story isn't refined unless the team says it is. The team needs to review the
user story and agree it's ready to work on. If a team doesn't see the user story until
day one of a sprint, problems can likely result.
3. User stories further down the backlog can remain ambiguous. Don't waste time
refining lower-priority items. Focus on the top of the backlog.
Integrate early and often

Continuous integration and continuous delivery (CI/CD) set up your team for the fast
pace of Agile development. As soon as possible, automate the build, test, and
deployment pipelines. Set up that automation as one of the first tasks your team tackles
when you start a new project.
With automation, the team avoids slow, error-prone, and time-intensive manual
deployment processes. Since teams release every sprint, there isn't time to do these
tasks manually.
CI/CD also influences your software architecture. It ensures you deliver buildable and
deployable software. When teams implement a difficult-to-deploy feature, they become
aware immediately if the build and deployments fail. CI/CD forces a team to fix
deployment issues as they occur. The product is then always ready to ship.
There are some key CI/CD activities that are critically important for effective Agile
development.
1. Unit testing. Unit tests are the first defense against human error. Consider unit
tests a part of coding. Check tests in with the code. Make unit testing a part of
every build. Failed unit tests mean a failed build.
2. Build automation. The build system should automatically pull code and tests
directly from source control when builds run.
3. Branch and build policies. Configure branch and build policies to build
automatically as the team checks code in to a specific branch.
4. Deploy to an environment. Set up a release pipeline that automatically deploys

built projects to an environment that mimics production.
Minimize technical debt

With personal finances, it's easier to stay out of debt than to dig out from under it. The
same rule applies with technical debt. Technical debt includes anything that the team
must address because of shortcuts that were taken earlier. For instance, if you're on a
tight schedule, you might sacrifice quality to meet a deadline. Technical debt is the price
you pay later, when you have to refactor code to make up for that lack of quality.
Examples include fixes to address poor design, bugs, performance issues, operational
issues, accessibility concerns, and other issues.
Keeping on top of technical debt requires courage. There are many pressures to delay
reworking code. It feels good to work on features and ignore debt. Unfortunately,
somebody must pay off the technical debt sooner or later. Just like financial debt,
technical debt becomes harder to pay off the longer it exists. A smart product owner
works with their team to ensure there's time to pay off technical debt every sprint.
Balancing technical debt reduction with feature development is a difficult task.
Fortunately, there are some straightforward techniques for creating productive,
customer-focused teams.
Always be Agile
Being Agile means learning from experience and continually improving. Agile
development provides more learning cycles than traditional project planning due to the
tighter process loops. Each sprint provides something new for the team to learn.
For example:
A team delivers value to the customer, gets feedback, and then modifies their
backlog based on that feedback.
They learn that their automated builds are missing key tests. They include work in
their next sprint to address this issue.
They find that certain features perform poorly in production, so they make plans to
improve performance.
Someone on the team hears of a new practice. The team decides to try it out for a
few sprints.
Teams that are just starting with Agile development should expect more learning
opportunities. They're an invaluable part of the process because they lead to growth
and improvement.
Next steps
There are many ways to settle on an Agile development process that's right for a team.
Azure DevOps provides various process templates. Teams that are looking for different
baseline structures to their planning can use these templates as starting points. For
information about selecting a process template that best fits a team's culture and goals,
see Choose a process flow or process template to work in Azure Boards.
As organizations grow, it can be a challenge to stay disciplined. Learn more about

scaling Agile to large teams.
Building productive teams
Article • 11/28/2022
Engineers thrive in environments where they can focus and get in the zone. Teams often
face distractions and competing priorities that force engineers to shift context and
divide their attention. They struggle to balance heads down time with heads up time.
Adding new features requires team members to be heads down and focused.
Responding to customer issues and addressing live site issues requires the team to be
heads up and aware of what's going on.
To mitigate distractions, a team can divide itself into two crews: one for features and one
for live site health.
The two-crew approach yields greater productivity and predictability. Successful

implementation relies on these key elements:
Clearly defined crew roles

A well-defined crew rotation process
Frequent adjustments to crew size
Feature crew
The feature crew, or F-crew, focuses on the future. They work as an effective unit with a
clear mission and goal: to build and ship high-quality features.
The F-crew is shielded from the day-to-day chaos of the live service to ensure they have
time to design, build, and test their work. They can rely on minimal distractions and
freedom from having to fix issues that arise at random. They're encouraged to seldom
check their email and avoid getting pulled into other issues unless they're critical.
When an F-crew member joins a conversation or occasionally gets sucked into an email
thread, other team members should chide them: "You're on the F-crew, what are you
doing?" If an F-crew member needs to address a critical issue, they're encouraged to
delegate it to the customer crew and return to feature work.
The F-crew operates as a tight-knit team that swarms on a small set of features. A good
work-in-progress (WIP) limit is two features in flight for 4-6 people. By working closely
together, they build deep shared context and find critical bugs or design issues that a
cursory code review would miss. A dedicated crew allows for a more predictable
throughput rate and lead time. Team members often refer to the F-crew as serene and
focused. They find it peaceful and rejuvenating to focus deeply on a feature, to dedicate
full attention to it. People leave their time on the F-crew feeling refreshed and
accomplished.
Customer crew
The customer crew, or C-crew, focuses on the now and provides frontline support for
customer and live-site issues, bugs, telemetry, and monitoring. The C-crew often
huddles around a computer, debugging a critical live-site issue. Their number one
priority is live-site health. Laser-focused on this environment, they build expert
debugging and analysis skills. The customer crew is often referred to as the shield team,
because it shields the rest of the team from distractions. Rather than work on upcoming
features, the C-crew is the bridge between customers and the current product. Crew
members are active on email, Twitter, and other feedback channels. Customers want to
know they're heard, and the C-crew's job is to hear them. The C-crew triages customer-
reported issues immediately and quickly engages and assists blocked customers.
With a deluge of incoming tasks, working on a fast-paced C-crew can, at times, be

exhilarating. In a busy week, they address multiple emails, live-site investigations, and
bugs. As operations quiet down, they work to improve telemetry and reporting,
investing their time to make service upkeep easier.
C-crews allow the team to address issues without pulling team members off other
priorities, and ensure customers and partners are heard. Responsiveness to questions
and issues becomes a point of pride for C-crews. However, this pace can be draining,
necessitating a frequent rotation between crews.
Crew rotation
A well-defined rotation process makes the two-crew system work. You could simply
swap the crews (F-crew becomes C-crew and vice versa), but this limits knowledge
sharing between and within the crews. Instead, opt for a weekly rotation.
At the end of each week, conduct a short swap meet where the team decides who swaps
between crews. You can use a whiteboard chart to track who is currently on each crew
and when they were swapped. The longest tenured people on each crew should
typically swap with each other. However, in any given week, someone may want to
remain to complete work on a live-site investigation or feature. While there's flexibility,
the longer someone is on a crew, the more likely they should be swapped.
Weekly rotations help prevent silos of knowledge in the team and ensure a constant
flow of information and perspective between crews. The frequent movement of
engineers creates shared knowledge of the team's work, which helps the C-crew to
resolve issues without the help of others. Often, new F-crew members will quickly find a
previously overlooked design or code flaw.
Crew size
Crew size varies to maintain the health of the team. If a team has a high incoming rate
of live-site issues or has a lot of technical debt, the C-crew gets larger, and vice versa.
Adjusting sizes weekly increases predictability in the team's deliverables and
dependencies. In some weeks, a team may move everyone to the C-crew to address the
feedback from a big release.
This strategy simplifies communication with management. Without a two-crew system,

engineers often work on multiple things simultaneously. When several distractions occur
in a single week, in-progress features are often delayed. As a result, a team may be
unable to confidently give timelines for future feature work.
A dedicated F-crew leads to predictable throughput and lead time. Splitting resources
between crews increases accountability within the team and with management about
what the team can accomplish each week and each sprint.
Next steps
The two-crew system can help teams understand where engineers should spend their
time and to make progress on many competing priorities.
In addition to improving productivity and predictability, the two-crew system can

increase team morale. Engineers on each team clearly understand their roles and
responsibilities and function more independently and with much greater accountability.
This approach is ideal for DevOps teams, those responsible for both development and
operations. However, this approach can be applied to nearly any Agile team dealing
with competing priorities.
Microsoft is one of the world's largest Agile companies. Learn how Microsoft organizes
teams in DevOps planning.
What is Scrum?
Article • 11/28/2022
Scrum is a framework used by teams to manage work and solve problems

collaboratively in short cycles. Scrum implements the principles of Agile as a concrete
set of artifacts, practices, and roles.
The Scrum lifecycle

The diagram below details the iterative Scrum lifecycle. The entire lifecycle is completed
in fixed time periods called sprints. A sprint is typically one-to-four weeks long.
Scrum roles
There are three key roles in Scrum: the product owner, the Scrum master, and the Scrum
team.
Product owner
The product owner is responsible for what the team builds, and why they build it. The
product owner is responsible for keeping the backlog of work up to date and in priority
order.
Scrum master
The Scrum master ensures that the Scrum process is followed by the team. Scrum
masters are continually on the lookout for how the team can improve, while also
resolving impediments and other blocking issues that arise during the sprint. Scrum
masters are part coach, part team member, and part cheerleader.
Scrum team
The members of the Scrum team actually build the product. The team owns the
engineering of the product, and the quality that goes with it.
Product backlog
The product backlog is a prioritized list of work the team can deliver. The product owner
is responsible for adding, changing, and reprioritizing the backlog as needed. The items
at the top of the backlog should always be ready for the team to execute on.
Plan the sprint

In sprint planning, the team chooses backlog items to work on in the upcoming sprint.
The team chooses backlog items based on priority and what they believe they can
complete in the sprint. The sprint backlog is the list of items the team plans to deliver in
the sprint. Often, each item on the sprint backlog is broken down into tasks. Once all
members agree the sprint backlog is achievable, the sprint starts.
Execute the sprint

Once the sprint starts, the team executes on the sprint backlog. Scrum does not specify
how the team should execute. The team decides how to manage its own work.
Scrum defines a practice called a daily Scrum, often called the daily standup. The daily
Scrum is a daily meeting limited to fifteen minutes. Team members often stand during
the meeting to ensure it stays brief. Each team member briefly reports their progress
since yesterday, the plans for today, and anything impeding their progress.
To aid the daily Scrum, teams often review two artifacts:
Task board
The task board lists each backlog item the team is working on, broken down into the
tasks required to complete it. Tasks are placed in To do, In progress, and Done columns
based on their status. The board provides a visual way to track the progress of each
backlog item.
Learn more about Kanban task boards.

The sprint burndown is a graph that plots the daily total of remaining work, typically
shown in hours. The burndown chart provides a visual way of showing whether the team
is on track to complete all the work by the end of the sprint.
Sprint review and sprint retrospective

At the end of the sprint, the team performs two practices:
Sprint review
The team demonstrates what they've accomplished to stakeholders. They demo the
software and show its value.
Sprint retrospective
The team takes time to reflect on what went well and which areas need improvement.
The outcome of the retrospective are actions for the next sprint.
Increment
The product of a sprint is called the increment or potentially shippable increment.
Regardless of the term, a sprint's output should be of shippable quality, even if it's part
of something bigger and can't ship by itself. It should meet all the quality criteria set by
the team and product owner.
Repeat, learn, improve

The entire cycle is repeated for the next sprint. Sprint planning selects the next items on
the product backlog and the cycle repeats. While the team executes the sprint, the
product owner ensures the items at the top of the backlog are ready to execute in the
following sprint.
This shorter, iterative cycle provides the team with lots of opportunities to learn and
improve. A traditional project often has a long lifecycle, say 6-12 months. While a team
can learn from a traditional project, the opportunities are far less than a team who
executes in two-week sprints, for example.
This iterative cycle is, in many ways, the essence of Agile.
Scrum is very popular because it provides just enough framework to guide teams while
giving them flexibility in how they execute. Its concepts are simple and easy to learn.
Teams can get started quickly and learn as they go. All of this makes Scrum a great
choice for teams just starting to implement Agile principles.
Next steps
Find more information about Scrum resources, training, and certification:
Scrum.org
ScrumAlliance.org
Learn how to manage your Scrum process.
Larger, more complex organizations may find that Scrum doesn't quite fit their needs.
For those cases, check out Scaled Agile Framework.
Add, rename, and delete dashboards in
Azure DevOps
Article • 02/24/2023
2018
Share progress and status with your team using configurable team or project
dashboards. Dashboards provide easy-to-read, easy access, real-time information. At a
glance, you can make informed decisions without having to drill down into other parts
of your project.
When a project is first created, a default team and default team dashboard is created
labeled Overview. You can customize this dashboard by adding widgets. Each widget
provides access to one or more features or functions. To learn more about each widget,
see Widget catalog.
Project and team dashboards

When you add a dashboard, you can choose to make it a project dashboard or one
specific to a team. Use project dashboards to display information or status about the
project or when you want to control who can edit the dashboard. Use team dashboards
to focus information specific to a team.
７ Note
Project dashboards are owned by the person that created the dashboard. The
owner can set permissions as to who can edit the dashboard. Team dashboards are
owned by team administrators and can be edited by any member of the team. All
dashboards can be viewed by members of the project. All widgets available to team
dashboards are available for project dashboards. For team-specific widgets, if you
aren't able to select a team through the widget, then the team defaults to the
default project team.
Prerequisites
You must be a member of a project. If you don't have a project yet, create one.
If you haven't been added as a project member, get added now.
Anyone with access to a project, including Stakeholders, can view dashboards.
To add, edit, or manage a team dashboard, you must have Basic access, be a
member of the team, a member of the Project Adminstrators group, or have
dashboard permissions granted to you.
To add, edit, or manage a project dashboard, you must have Basic access or have
dashboard permissions granted to you for the select project dashboard.
７ Note
Data displayed within a chart or widget is subject to permissions granted to the

signed in user. For example, if a user doesn't have permissions to view work items
under an area path, then those items won't display in a query results widget in a
dashboard. To learn more, see FAQs on Azure DevOps dashboards, charts, and
reports, Access and permissions.
Open Dashboards
All dashboards are associated with either a team or a project. From the
Overview>Dashboards page, you can browse all dashboards and see which team they
belong to, or if they are project dashboard.
Open a web browser, connect to your project, and select Overview>Dashboards. The
dashboard directory page opens.
It lists dashboards in the following order:
Your last visited dashboard

Your favorited dashboards
All dashboards of teams that you belong to
All dashboards defined for the project in alphabetical order.
Select the filter icon to filter the list by keyword or team. Keywords apply to
dashboard titles, descriptions, and team names.
If you need to switch to a different project, select the Azure DevOps logo to browse
all projects.
Select a dashboard
1. Select a dashboard from the directory list, or from the selector. To return to the
dashboard directory, select the Browse all dashboards option.
2. To favorite a dashboard, hover over the dashboard and select the .
Favoriting a dashboard will cause it to appear under My Favorites dashboards list

on the dashboards directory. Also, it will appear towards the top in the
Dashboards selector and in your personal Favorites list.
Add a dashboard
Add a new dashboard as needed to support your team's needs. You can also edit and
rename any existing dashboards associated with your team.
７ Note
There is a limit of 500 dashboards per project. You'll receive an error message if you
try to create a dashboard beyond that limit. Delete unused dashboards to resolve
the error.
1. From the Dashboards directory, select New Dashboard. Or, when viewing a
dashboard, open the selector and select the New Dashboard option.
If you don't see the New Dashboard option, then you're not a team admin for
the currently selected team, or you don't have permissions to add and edit
dashboards. Either switch the context to your team, or request you be added as a
team admin.
2. Enter the name of the dashboard and other information you want to capture.
Here we choose to create a Project dashboard. To create a team dashboard, select

Team Dashboard and then select a team. To add a team, see Add a team.
3. Select Save.
4. The widget catalog opens. You can add one or more widgets to the dashboard.
You can then configure and resize each widget as needed.
5. You can move the widgets around the dashboard to place them where you want
them.
6. When you're done making changes, select Done Editing.
Rename, delete, and enable auto-refresh

You can rename or delete a dashboard. When you enable auto-refresh, the dashboard
automatically updates every 5 minutes.
７ Note
To delete a project dashboard, you must be a member of theProject Collection
To rename a dashboard, modify its description, or change its automatic refresh

setting, open the dashboard, select the gear icon, and change the field options
shown. Save your changes.
To delete a dashboard, open the Dashboards directory, select More Actions for
the dashboard, and select Delete.
To set permissions for a dashboard, select the Security option. For details, see Set
dashboard permissions.
Move or delete a widget

Just as you have to be a team admin, a project admin, or have the necessary permissions
to add items to a dashboard, you must have the necessary permissions to remove items.
 Tip
When you're in dashboard edit mode, you can remove, rearrange, and configure
widgets, as well as add new widgets. Once you leave edit mode, the widget tiles
remain locked, reducing the chances of accidentally moving a widget.
Select Edit to modify your dashboard.
You can now add widgets or drag tiles to reorder their sequence on the dashboard.
To remove a widget, select More actions and select Delete .
When you're finished with your changes, select Done Editing to exit dashboard edit
mode.
Extensibility
Using the REST API service, you can create a dashboard widget. To learn more about the
REST APIs for dashboards and widgets, see Dashboards (API).
Try this next

As you can see, you can use team dashboards to provide guidance and keep your team
in sync, providing visibility across your org about status, trends, and progress.
Add a widget to a dashboard
Related articles
FAQs on Azure DevOps dashboards, charts, and reports
Add a team
Widget catalog
Marketplace widgets
Azure Boards Configuration &
Customization documentation
Configure and customize Azure Boards including area paths, iteration paths, projects,
and processes.
Configure teams
ｐ CONCEPT
About teams & Agile tools
ｆ QUICKSTART
Configure team tools
Set team area paths
Set team iterations
Configure projects
ｐ CONCEPT
Configure & customize Boards
About projects & scaling up
ｆ QUICKSTART
Define area paths
Define iteration paths (sprints)
Customize an Inheritance process
ｅ OVERVIEW

ｆ QUICKSTART
Add a custom field
ｇ TUTORIAL
Customize a workflow
Apply rules to workflow
Customize a project
Create & manage a process
Customize an On-premises XML process
ｅ OVERVIEW
ｃ HOW-TO GUIDE
Add or modify a field
Add or modify a work item type
ｉ REFERENCE
XML element reference
Customize a process template (on-premises)
ｅ OVERVIEW
About processes & process templates
Process template files
ｃ HOW-TO GUIDE
Customize a process template

Upload/download process templates
ｉ REFERENCE
XML element reference
Reference
ｉ REFERENCE
Naming restrictions
Workflow states & categories
Work tracking object limits

Azure Test Plans documentation
Improve your overall code quality by using manual and exploratory testing services for
your apps.
About Azure Test Plans
ｅ OVERVIEW
What is Azure Test Plans?
Navigate Test Plans
Run manual tests
ｆ QUICKSTART
Create test plans and suites
Create manual test cases
Run manual tests
ｇ TUTORIAL
Test different configurations
Test & Feedback extension
ｆ QUICKSTART
Install the Test & Feedback extension
Test in Connected mode
Configure Test resources
ｃ HOW-TO GUIDE
Set test retention policies
Run automated tests
ｐ CONCEPT
Run automated tests from test hub
Associate automated tests with test cases
Set up continuous testing
ｇ TUTORIAL
.NET Core apps
Go
Python
UI testing using Selenium
Review code coverage results
Review test results
Analyze test results

Tools and clients that connect to Azure
DevOps
Article • 01/18/2023
2018
Our platform of software development tools began more than 20 years ago. We
released Visual Basic and Visual Studio as an integrated development environment (IDE).
Visual Studio supports many plug-ins that extend its functionality. In particular, the Team
Explorer plug-in allows the Visual Studio client to connect to Azure DevOps to support
source control, work tracking, build, and test operations.
Desktop client developer tools

Developers have access to many tools through these versions of Visual Studio and plug-
ins. To download any version of Visual Studio, go to the Visual Studio Downloads
page . To understand what features you get with the Visual Studio versions, see
Compare Visual Studio offerings .
Visual Studio Community: A fully featured and extensible IDE for creating modern
applications for Android, iOS, and Windows, including web applications and cloud
services. (Replaces Visual Studio Express.)
Visual Studio Professional: Development tools and services to support individual
developers or small teams.
Visual Studio Enterprise: Integrated, end-to-end development tools and solutions
for teams of any size, and with a need to scale. It supports designing, building, and
managing complex enterprise applications.
Visual Studio Test Professional: Provides access to Microsoft Test and
development tools to support quality and collaboration throughout the
development process.
Visual Studio Code : Free, open-source code editor with a free extension to
support connecting to Git repositories on Azure DevOps.
Android Studio with the Azure DevOps Services Plug-in for Android Studio: Free
plug in to support Android developers and connect to Git repositories on Azure
DevOps.
IntelliJ with the Azure DevOps Services Plugin for IntelliJ: Free plug in to support
developers who use IntelliJ IDEA or Android Studio to connect to Git repositories
on Azure DevOps.
To get started with client libraries, see Client library samples.
Team Explorer plug-in
Team Explorer, a plug-in to all Visual Studio versions, connects Visual Studio to projects
defined in Azure DevOps. You can manage source code, work items, and builds. To learn
more, see Work in Team Explorer.
Home page with Git Home page with TFVC
Visual Studio Git experience
Visual Studio 2019 and later versions provide a new Git experience through the Git
menu as shown below. To learn more, see Git experience in Visual Studio and Side-by-
side comparison of Git and Team Explorer.
Office integration tools
You can integrate the following Microsoft Office tools with Azure DevOps.
Excel: Use Excel to add and bulk modify work items.
） Important
Starting with Visual Studio 2019, the Team Foundation plug-in for Office is
deprecating support for Microsoft Project. Project integration and the
TFSFieldMapping command is not supported for Azure DevOps Server 2019 nor for
Azure DevOps Services. However, you can continue to use Microsoft Excel.
Task-specific clients
The following clients support specific tasks, such as managing testing efforts, providing
feedback, or modifying work items:
Azure Test Plans: Manage your test efforts, create and run manual tests, and create
and track bugs that are found during test efforts.
Test & Feedback extension (previously called the Exploratory Testing extension):
This extension provides a lightweight plug-in to a web browser. Stakeholders can
respond to feedback requests for user stories and features created in Azure
DevOps. This extension is free to Stakeholders.
Microsoft Feedback Client: Your Stakeholders can use this client to record feedback
for your application as video, audio, or type-written comments. This client is
installed with all versions of Visual Studio, or it can be installed from the free
download . All feedback is stored in the work item data store and requires
Stakeholders to have permissions.
Browser-based web tools
Web portal
The collaboration tools supported through the web portal are summarized under
Essential services. New features are deployed every three weeks for Azure DevOps
Services, and quarterly for Azure DevOps Server. For release notes, see Azure DevOps
Services Features Timeline.
You can use the following browsers to access the web portal:
Version Edge Internet Safari Firefox Chrome

Explorer (Mac)
Azure DevOps Services Most Not supported 14.1 and Most Most
Azure DevOps Server recent later recent recent
2020.1
Azure DevOps Server Most 11 and later 14.1 and Most Most
2020 recent later recent recent
Azure DevOps Server
2019
TFS 2018
TFS 2017
TFS 2015 Most 9 and later 5 and later Most Most

recent recent recent
TFS 2013 9 and later 5 and later Most Most

recent recent
Microsoft Edge, Firefox, and Chrome automatically update themselves, so Azure DevOps
supports the most recent version.
For more information, see Web portal navigation.

Browser-based extensions
Several extensions are built and maintained by the Azure DevOps Services product
team:
Code search : Increase cross-team collaboration and code sharing. Enables

developers to quickly locate relevant information within the code base of all
projects that are hosted within an organization or collection. You can discover
implementation examples, browsing definitions, and error text.
Work item search : To quickly find relevant work items, search across all work
item fields over all projects in an organization. Do full-text searches across all fields
to efficiently locate relevant work items. Use inline search filters, on any work item
field, to quickly narrow down a list of work items.
Find more extensions in Azure DevOps Organization settings > Extensions > Browse
marketplace. See also, Overview of extensions for Azure Boards.
Command-line tools
You can do many code development and administrative tasks by using the following
command-line tools:
az devops commands
Git commands
TFVC commands
TCM commands
Manage permissions with command line tool (az devops security)
witadmin (work item tracking)
Integrated tool support for third-party

applications
The following tools provide support for monitoring and interacting with Azure DevOps
from a third-party application.
Azure Boards:
Use the Azure Boards app with Slack to manage work items
Use the Azure Boards app in Microsoft Teams
Azure Repos:
Azure Repos with Slack
Azure Repos with Microsoft Teams
Azure Pipelines:
Use Azure Pipelines with Microsoft Teams
Azure Pipelines with Slack
Integrate with ServiceNow change management
Continuously deploy from a Jenkins build
Visual Studio and Azure DevOps provide a wealth of features and functionality. They
also provide a means to extend and share that functionality.
Extensions are simple add-ons that you can use to customize and extend your DevOps
and work tracking experiences. They're written with standard technologies—HTML,
JavaScript, and CSS. You can develop your own extensions by using your preferred dev
tools.
You build extensions by using our RESTful API library. Publish your extensions to the
Azure DevOps Marketplace. You can privately maintain or share them with millions of
developers who use Visual Studio and Azure DevOps.
To learn more, visit the Azure DevOps Marketplace and see Overview of extensions.
REST APIs
The Azure DevOps APIs are based on REST, OAuth, JSON, and service hooks—all
standard web technologies broadly supported in the industry.
REST APIs are provided to support building extensions to Azure DevOps. To learn more,
see REST API overview.
Related articles
A tour of services
Software development roles
Pricing
Azure DevOps data protection overview
az boards
Reference
７ Note
This reference is part of the azure-devops extension for the Azure CLI (version
2.30.0 or higher). The extension will automatically install the first time you run an az
boards command. Learn more about extensions.
Manage Azure Boards.
This command group is a part of the azure-devops extension.
Commands
Name Description Type Status
az boards area Manage area paths. Extension GA
az boards area project Manage areas for a project. Extension GA
az boards area project create Create area. Extension GA
az boards area project delete Delete area. Extension GA
az boards area project list List areas for a project. Extension GA
az boards area project show Show area details for a project. Extension GA
az boards area project update Update area. Extension GA
az boards area team Manage areas for a team. Extension GA
az boards area team add Add area to a team. Extension GA
az boards area team list List areas for a team. Extension GA
az boards area team remove Remove area from a team. Extension GA
az boards area team update Update team area. Extension GA
az boards iteration Manage iterations. Extension GA
az boards iteration project Manage iterations for a project. Extension GA
az boards iteration project create Create iteration. Extension GA

az boards iteration project delete Delete iteration. Extension GA
az boards iteration project list List iterations for a project. Extension GA
az boards iteration project show Show iteration details for a project. Extension GA
az boards iteration project update Update project iteration. Extension GA
az boards iteration team Manage iterations for a team. Extension GA
az boards iteration team add Add iteration to a team. Extension GA
az boards iteration team list List iterations for a team. Extension GA
az boards iteration team list- List work-items for an iteration. Extension GA

work-items
az boards iteration team remove Remove iteration from a team. Extension GA
az boards iteration team set- Set backlog iteration for a team. Extension GA
backlog-iteration
az boards iteration team set- Set default iteration for a team. Extension GA
default-iteration
az boards iteration team show- Show backlog iteration for a team. Extension GA
backlog-iteration
az boards iteration team show- Show default iteration for a team. Extension GA
default-iteration
az boards query Query for a list of work items. Extension GA
az boards work-item Manage work items. Extension GA
az boards work-item create Create a work item. Extension GA
az boards work-item delete Delete a work item. Extension GA
az boards work-item relation Manage work item relations. Extension GA
az boards work-item relation add Add relation(s) to work item. Extension GA
az boards work-item relation list- List work item relations supported in Extension GA
type the organization.
az boards work-item relation Remove relation(s) from work item. Extension GA

remove
az boards work-item relation Get work item, fill relations with friendly Extension GA
show name.
az boards work-item show Show details for a work item. Extension GA
az boards work-item update Update work items. Extension GA
az boards query
Query for a list of work items.
Only supports flat queries.
Azure CLI
az boards query [--detect {false, true}]

[--id]
[--org]
[--path]
[--project]
[--wiql]
Optional Parameters
--detect
Automatically detect organization.

accepted values: false, true
--id
The ID of an existing query. Required unless --path or --wiql are specified.
--org --organization
Azure DevOps organization URL. You can configure the default organization using az
devops configure -d organization=ORG_URL. Required if not configured as default or
picked up via git config. Example: https://dev.azure.com/MyOrganizationName/ .
--path
The path of an existing query. Ignored if --id is specified.

--project -p
Name or ID of the project. You can configure the default project using az devops
configure -d project=NAME_OR_ID. Required if not configured as default or picked
up via git config.
--wiql
The query in Work Item Query Language format. Ignored if --id or --path is specified.
Global Parameters
--debug
Increase logging verbosity to show all debug logs.
--help -h
Show this help message and exit.
--only-show-errors
Only show errors, suppressing warnings.
--output -o
Output format.
--query
JMESPath query string. See http://jmespath.org/ for more information and

examples.
--subscription
Name or ID of subscription. You can configure the default subscription using az

account set -s NAME_OR_ID .
--verbose
Increase logging verbosity. Use --debug for full debug logs.

Terms and concepts used when tracking
work items in Azure Boards
Article • 06/27/2023
2018
The Microsoft Agile glossary is a short dictionary of terms used in tracking work using
Azure Boards. More terms are defined in the following articles:
Kanban key concepts

Sprints and Scrum key concepts
Agile methods
A family of engineering best processes with a goal of enabling rapid delivery of high-
quality software and a business approach that aligns development with customer needs
and company goals. In this paradigm, frequent inspection and adaptation are necessary,
with team work, self-organization, and accountability all critical to project success.
Agile tools
A suite of web-based tools used to track work and support Agile methodologies. Agile
tools support the core Agile methods—Scrum and Kanban—used by software
development teams today. Learn more: About Agile tools and Agile project
management.
Area path
Area paths are used to group work items by team, product, or feature area. Iteration
paths are used to group work into sprints, milestones, or other event-specific or time-
related periods. You can use area paths to define a hierarchy of paths. To learn more, see
Bugs
A type of work item that records a potential source of dissatisfaction with the product.
The common name of a work item type for tracking code defects. Each team can choose
how they want to manage bugs. Some teams like to track bugs along with requirements
on the backlog. Other teams like to track bugs as tasks performed in support of a
requirement. The bugs then appear on their Taskboard. Learn more: Manage bugs.
Categories
Groups one or more work item types to support flexible reporting, queries, and other
functions made available through Agile tools. Categories support the process
configuration used by the web portal backlog and taskboard pages. For example, you
can add custom work item types to the Requirements category and manage them using
the product backlog and Kanban boards. For more information, see Use categories to
group work item types.
Collections
A collection is a container for a number of projects in Azure DevOps. A default collection
is created when you sign up with Azure DevOps Services or install Team Foundation
Server. Within Azure DevOps Services, a collection corresponds to an organization. For
on-premises TFS deployments, you can add and manage collections to specify the
logical and physical resources available to the projects within the collection.
Learn more: About projects and scaling your organization, Manage organizations or
Manage project collections in Team Foundation Server.
Dashboards
Dashboards are user-configurable interactive signboards that provide real-time
information. Dashboards are associated with a team and display configurable widgets to
show information. To learn more, see Add and manage dashboards.
Discussion
Area within a work item form that supports adding and reviewing comments made
about the work being performed. This way, you capture all comments within the work
item rather than maintaining a long email thread. Within the discussion section, you can
use the @mention control to notify another team member about the discussion. Simply
type @ and their name.
Learn more: Work item form controls.
Favorites
Tagging an object as a favorite is a method used to support quick navigation by yourself
or other team members. You can tag work item queries and build definitions as personal
and team favorites. Other objects you can tag as a favorite for yourself only include
code branches, delivery plans, test plans, and teams or projects. To learn more, see Set
personal or team favorites.
Fields
Fields support tracking a piece of information about the work to perform. Values you
assign to a field are stored in the work tracking data store that you can query and
generate charts to view status and trends. Your project contains 100 or more data fields.
You update data by modifying the data field within a work item. Each work item is
associated with a work item type (WIT), and the data you can track corresponds to the
fields assigned to the WIT. For a definition of each predefined field, see Work item field
index.
Follow
Tagging specific work items or pull requests to follow them is a method used to receive
email updates about changes that are made to them. To learn more, see Follow a work
item or pull request.
Global lists
Defines a list of menu items or picklist items that are shared across WITs and projects
within a project collection. Global lists help to minimize the work that is required to
update lists. You can define global lists within WITs that you upload with your process
template. Learn more: Manage global lists for work item types. (Only supported for
Hosted XML and On-premises XML process models)
Global workflow
Specifies both work item fields and global lists that multiple projects and types of work
items can share. Learn more: Manage global workflow (Only supported for On-premises
XML process model).
Hidden types categories
Specifies the set of work item types that you don't want users to create manually. By
default this set includes:
Code Review Request and Code Review Response

Feedback Request and Feedback Response
Shared Steps and Shared Parameter
Test Plan and Test Suite
You can use TFS Team Project Manager , an open-source client available from GitHub
to quickly determine which WITs belong to the Hidden Types Category.
Hosted XML process model

The Hosted XML process model provides support for customizing work tracking objects
and Agile tools for a project by modifying and importing a process template. This
process model is only available for select accounts hosted on the Azure Boards cloud
platform. For more information, see Hosted process model.
Issues or impediments
A type of work item that helps track unplanned activities. Resolving an issue or
impediment requires more work beyond what was scheduled based on actual
requirements. Using the issue (Agile or CMMI process) or impediment (Scrum process)
work item type helps you track and manage these issues until you can resolve and close
them. Learn more: Manage issues and impediments.

The Inheritance process model provides support for customizing work tracking objects
and Agile tools for a project through the user interface. This process model is only
available for accounts hosted on the Azure Boards cloud platform. Projects inherit the
customizations made to a process. For more information, see Inheritance process model.
Issue
Agile process: An issue is a type of work item that defines an item that you want to track
as it may impact the completion of other work. It's defined for the Agile process and
doesn't appear on any backlog or board. See Manage issues and impediments.
Basic process: An issue is a type of work item that defines some work or code defect
that needs to be tracked. It's defined for the Basic process and appears on the product
backlog and Issues Kanban board.
Iteration paths (aka sprints)

A time period, usually two to three weeks, used to group work items to be completed
during that time period. Sprints are used in Scrum methods to support sprint planning,
sprint burndown, and other Scrum processes. Iteration paths allow you to group work
into sprints, milestones, or other event-specific or time-related period. Learn more:
Kanban board
An interactive, electronic sign board that supports visualization of the flow of work from
concept to completion and lean methods. Azure DevOps provides a Kanban board for
each product and portfolio backlog. Learn more: Kanban overview and Kanban board
features and epics.
Links and link types

Links support defining relationships between work items and other objects—such as
commits, branches, pull requests, and more—using different link types. Learn more: Add
link to work items, Link work items to support traceability and manage dependencies
and Link types reference.

The On-premises XML process model provides support for customizing work tracking
objects and Agile tools for a project. With this model, you can update the XML definition
of work item types, the process configuration, categories, and more. You can also
update the attributes of fields. This process model is only available for on-premises
Azure DevOps. For more information, see On-premises process model.
Pick lists
A picklist specifies an enumerated set of values that appear within a drop-down menu in
a work item form. Values also appear in the Value column within the query editor. The
method you use to customize a picklist varies. It depends on the field and the process
model. For more information, see Customize work.
Plans (also known as delivery plans)

A plan is a configurable view that displays work from multiple teams and projects laid
out within a calendar based on each team's iterations. Each row in the view represents
the work from a team's product or portfolio backlog. Each card corresponds to a work
item, such as user story, feature, or epic. To learn more, see Review team delivery plans.
Portfolio backlog
An interactive list of work items, similar to the product backlog, that supports organizing
or grouping work under features, epics, or scenarios. Portfolio backlogs work similarly to
product backlogs in that you can prioritize work and view the tree hierarchy of work.
Learn more: Define features and epics.
Process
A process defines the building blocks of a work-tracking system. To customize a process,
you first create an inherited process from one of the default system processes, Agile,
Scrum, or CMMI. All projects that use the process see the changes you make. To learn
more, see About process customization and inherited processes.
Process configuration
Specifies the default configuration and functional capabilities that your teams can access
using the Agile tools. These web portal tools include the product backlog, sprint
backlogs, Kanban board, and taskboard. (Only supported for Hosted XML and On-
premises XML process models)
Process model
The work tracking customization method supported by your organization or collection.
One of three process models are supported, Inheritance and Hosted XML for Azure
Boards and On-premises XML for on-premises Azure DevOps. Learn more: Customize
your work tracking experience
Process template
Specifies an inter-related set of files that contain the XML definitions for tracking work
and defining the initial configuration of other functional areas. The system provides
three default process templates—Agile, Scrum, or CMMI. You can create a project and
then customize it, or customize a process template that you then use to create a project.
(Only supported for Hosted XML and On-premises XML process models)
Product backlog
An interactive list of work items that corresponds to a team's project plan or roadmap
for what the team plans to deliver. The product backlog supports prioritizing work,
forecasting work by sprints, and quickly linking work to portfolio backlog items. You can
define your backlog items and then manage their status using the Kanban board.
Each product backlog can be customized by a team. Learn more: Create your backlog.
Product backlog item (PBI)

teams plan to create. Product owners typically define and stack rank product backlog
items which are defined with the Scrum process. Learn more: Scrum process work item
types and workflow.
Projects
A project, which was previously known as a team project, provides a repository for
source code. A project provides a place where a group of people can plan, track
progress, and collaborate on building software solutions. A project is defined for an
Azure DevOps Services organization or within a TFS project collection. You can use it to
focus on those objects defined within the project. To learn more, see About projects and
scaling your organization.
Queries
Queries are used to find and list work items. Queries support managed searches, which
are used to triage work, versus ad-hoc searches, which are used to find a specific work
item. Flat-list queries also support status and trend charts. To learn more, see About
managed queries.
Remote linking
With remote linking, you can create link relationships between work items in one
organization to work items or other objects defined in another organization.
Organizations must be managed by the same Azure Active Directory. Learn more: Link
work items, Link to a remote work item.
Rollup
Rollup refers to the sum of Remaining Work, Story Points, or other numeric field of child
and descendent work items within a hierarchy. To add rollup columns to a product or
portfolio backlog, see Display rollup progress or totals.
Sprints (also known as iterations)

A sprint is a time period of usually two to three weeks that's used to group work items
to be completed during that time period. Sprints are used in Scrum methods to support
sprint planning, sprint burndown, and other Scrum processes. Sprints are defined via
iteration paths. To learn more, see About area and iteration paths (aka sprints).
Sprint backlog
An interactive list of work items that have been assigned to the same sprint or iteration
path for a team. The sprint backlog supports teams that use Scrum methodologies.
Learn more: Sprint planning.
Taskboard
A taskboard is an interactive board of work items that you can use to review and update
tasks defined for the sprint backlog. The taskboard supports teams that use Scrum
methodologies. To learn more, see Update and monitor your taskboard.
Teams
A team corresponds to a selected set of project members. With teams, organizations
can subcategorize work to better focus on all the work they track within a project. Each
team gets access to a suite of Agile tools. Teams can use these tools to work
autonomously and collaborate with other teams across the enterprise. Each team can
configure and customize each tool to meet their work requirements. To learn more, see
User story
teams plan to create. Product owners typically define and stack rank user stories. User
story is defined with the Agile process. Learn more: Agile process work item types and
workflow.
Widgets
Widgets display information and charts on dashboards. Many of them can be
configured. Many widgets display information available from one or more data stores or
charts created by the system. To learn more, see Widget catalog.
Work item types (WITs)

A WIT specifies the fields, workflow, and form used to track an item of work. Each WIT is
associated with more than 30 system fields and several more type-specific fields. You
use work items to plan and track the work required to develop your project. For an
overview of predefined WITs provided with the default processes, see About processes
and process templates.
Workflow
A workflow is an integral aspect of a work item. It's defined by its corresponding work
item type. The workflow determines the logical progression and regression of work
items. For the Agile process, it tracks the status of work as the work progresses from a
New or Active state to a Closed or Completed state. For the Basic process, all work item
types use the To Do, Doing, and Done states to track workflow status.
The workflow also specifies the values that appear in the State and Reason drop-down
menus. For more information, see Workflow states and state categories.
Related articles
Refine your backlog

Azure Devops Manual

Uploaded by

Copyright:

Available Formats

Azure Devops Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Azure Devops Manual

Uploaded by

Copyright:

Available Formats

Tell us about your PDF experience.

Azure Boards documentation

About Azure Boards

What is Azure Boards?

About work items

About default processes

Agile process workflow

Sign up for Azure Boards

Plan & track work

Get started as a Stakeholder

Plan your project

About Backlogs & Agile project management

Create your backlog

Define features & epics

Organize your backlog

Bulk add or modify work items (Excel)

Bulk add or modify work items (Web)

Kanban board quickstart

Kanban board overview

Customize your Kanban board

About Sprints & Scrum

Assign work to sprints

Monitor sprint burndown

List & manage work items

Create managed queries

Perform ad hoc searches

Remove, delete, or restore work items

Connect Azure Boards to GitHub

Link GitHub commits, pull requests, & issues to work items

Link work items to support traceability

Use work item templates

Add tags to work items

Azure Boards with Microsoft Teams

Configure & customize

About teams & Agile tools

Configure & customize Boards

Set area paths

Set iteration (sprint) paths

Add a custom field

Customize the workflow

Review team deliverables & plans

Implement Scaled Agile Framework®

Fix re-ordering & nesting issues

Set up your Backlogs & Boards

Work items quick reference

Query quick reference

Work item field index

Azure DevOps CLI

Use Azure Boards hubs

Azure Boards hubs UI

Benefits of using Azure Boards

Connect Azure Boards to GitHub

Implement Agile, Scrum, and Kanban processes

Capability Maturity Model Integration (CMMI) supports a framework for process

Create a branch from a requirement

Support independent, autonomous teams

If your team is committed to practicing Kanban or Scrum methods, see instead

Configure your teams

Best practice tips:

Configure your sprints