Agile workflow in Azure Boards

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

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 board to track progress by updating the status of those items.

Conceptual image of Agile process, work item types used to plan and track work.

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.

Screenshot of User Story work item form.

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.



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.

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.

The area of customer value addressed by the epic, feature, requirement, 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 customer value to support the business (Default)

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.

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.

A subjective rating of the relative uncertainty around the successful completion of a user story. Allowed values are:

  • 1 - High
  • 2 - Medium
  • 3 - Low

Capture comments in the Discussion section

Use the Discussion section to add and review comments made about the work being performed.

Screenshot showing the Discussion section within a work item form.

The rich text editor tool bar displays below the text entry area. It appears when you select each text box that supports text formatting.

Screenshot of Discussion section, Rich Text Editor toolbar.


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

Screenshot of Discussion section, at-mention drop-down menu.

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.

Screenshot of Discussion section, Edit, Delete actions.


Editing and deleting comments requires Azure DevOps Server 2019 Update 1 or later version.

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.


For on-premises Azure DevOps Server, you must configure an SMTP server for team members to receive notifications.

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.

Screenshot of Discussion control, Add reactions to a comment.

Save a comment without saving the work item


This feature is available starting in Azure DevOps Server 2022.1.

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.

Screenshot of Discussion section, save comment.


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.

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.

Screenshot of Bug work item form, 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
Conceptual image of User Story workflow states, Agile process. Conceptual image of Bug workflow states, Agile process. Conceptual image of Task workflow states, Agile process.

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 board or Taskboards

Teams can use the 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.

Screenshot of Track progress on the board.

You can customize the board to support more swimlanes or columns. For more information, see Customize your work tracking experience.

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.

Screenshot of Sprint backlog, add task.

Name the task and estimate the work it takes.

Screenshot of Agile task work item form.

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.



The amount of estimated 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.

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.

The amount of work spent implementing a task.

Select the type of activity this task represents when your team estimates sprint capacity by activity.

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.

Screenshot of Test plan web portal.

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.

Screenshot of test case form.

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.


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



Enter a description of 255 characters or less. You can always modify the title later.

Assign the work item to the team member responsible for performing the work.

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

Use the default first. Update it when you change state. Each State is associated with a default reason.

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.

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.

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.

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.

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.

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 or Customize the On-premises XML process model depending on the process model used by your project.

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.

Screenshot of Add work item from a New work item widget.

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.