Change the workflow for a work item type

Last Update: 4/20/2017

Team Services (Hosted XML) | TFS 2017 | TFS 2015 | TFS 2013

IMPORTANT

This topic applies to team project customization for Hosted XML and On-premises XML process models. For the Inheritance process model, see Customize a process.

For an overview of process models, see Customize your work tracking experience.

You can change the workflow for a work item type (WIT) to support your business and team processes. WITs support tracking all types of work─requirements, tasks, code defects─to support software development.

The workflow determines the logical progression and regression of work that team members will perform. It also specifies the values that appear in the drop-down menus for the State and Reason fields. For an overview of the default workflow states supported in the default process templates, see Choose a process.

Workflow for Product Backlog Item (Scrum process template)

Product backlog item workflow, Scrum process

NOTE

This topic describes how to customize a workflow state. If instead, you want to change the State assigned to a specific work item, see one of the following topics: Add work items, Update work status, Kanban board, Track work in progress, or Task board, Update task status. You can also perform a bulk update of the State for many work items.

For information about build definition workflows, see Get started with CI/CD.

Update the XML definition for a WIT

If you are new to WIT customization, note the following:

Workflow design guidelines

You define the workflow by first identifying the states and the valid transitions between them. The WORKFLOW section of the WIT definition specifies the valid states, transitions, reasons for the transitions, and optional actions that will be performed when a team member changes the state of a work item.

In general, you associate each state with a team member role and a task that a person in that role must perform to process the work item before changing its state. Transitions define the valid progressions and regressions between states. Reasons identify why a team member changes a work item from one state to another, and actions support automation of the transition of a work item at a point in the workflow.

For example, the State is set to New when a tester opens a new bug that is based on the default Agile process. The developer changes the State to Active when fixing the bug, and once fixed, the developer changes its state to Resolved and sets the value of the Reason field to Fixed. After verifying the fix, the tester changes the state of the bug to Closed and the Reason field changes to Verified. If the tester determined that the developer had not fixed the bug, the tester would change the state of the bug to Active and specify the Reason as Not Fixed or Test Failed.

As you design or modify a workflow, consider the following guidelines:

  • Use the STATE element to define a unique state for each team member role that will take a specific action on a work item. The more states you define, the more transitions you must define. Regardless of the sequence in which you define the states, they are listed in alphanumeric order in the drop-down menu for the State field.

    If you add a state to a work item type that appears on the backlog or board pages in the web portal, you must also map the state to a state category. To learn more, review Workflow states and state categories.

  • Use the TRANSITION element to define a transition for each valid progression and regression from one state to another.

    At a minimum, you must define one transition for each state, and the transition from the null state to the initial state.

    You can define only one transition from unassigned (null) to the initial state. When you save a new work item, it is automatically assigned to the initial state.

    When a team member changes the state of a work item, that change triggers the transition and the actions that you define to be performed for the selected state and the transition. Users can specify only those states that are valid based on the transitions that you define for the current state. In addition, an ACTION element, which is a child element of TRANSITION, can change the state of a work item.

  • For each transition, you define a default reason by using the DEFAULTREASON element. You can define as many optional reasons as you want by using the REASON element. These values appear in the drop-down menu of the Reason field.

  • You can specify rules that will be applied when the work item changes state, when it transitions, or when a user selects a specific reason. Many of these rules supplement the conditional rules that you can apply when you define the fields in the FIELDS section under the WORKITEMTYPE definition. For more information, see Update fields during a workflow change later in this topic.

  • The names that you assign to states and reasons are case insensitive.

    The drop-down menus for the State and Reason fields within the work item form or query editor display the values assigned in the WORKFLOW section of the work item type.

Workflow diagram and code example

The following code example shows the WORKFLOW for the Bug WIT definition for the Agile process template. This example defines three states and five transitions. The STATE elements specify the Active, Resolved, and Closed states. All possible combinations for progression and regression transitions are defined for the three states, except one. The transition from Closed to Resolved is not defined. Therefore, team members cannot resolve a work item of this type if the work item is closed.

This example doesn't list all the elements for DEFAULTREASON, REASON, ACTION, and FIELD.

**Example Workflow State Diagram – Agile Bug WIT **

Bug workflow states, Agile process template

<WORKFLOW>
 <STATES>
    <STATE value="Active">
      <FIELDS> . . . </FIELDS>
    </STATE>
    <STATE value="Resolved">
     <FIELDS> . . . </FIELDS>
    </STATE>
    <STATE value="Closed">
     <FIELDS> . . . </FIELDS>
    </STATE>
 </STATES>
 <TRANSITIONS>
    <TRANSITION from="" to="Active">
       <REASONS>
          <REASON value="Build Failure" />
           <DEFAULTREASON value="New" />
       </REASONS>
       <FIELDS> . . . </FIELDS>
    </TRANSITION>
    <TRANSITION from="Active" to="Resolved">
     <ACTIONS> . . . </ACTIONS>
     <REASONS> . . . </REASONS>
    </TRANSITION>
    <TRANSITION from="Resolved" to="Active">
       <REASONS> . . . </REASONS>
    </TRANSITION>
    <TRANSITION from="Resolved" to="Closed">
       <REASONS>
          <DEFAULTREASON value="Verified" />
       </REASONS>
     <FIELDS> . . . </FIELDS>
    </TRANSITION>
    <TRANSITION from="Closed" to="Active">
       <REASONS>
          <REASON value="Reactivated" />
          <DEFAULTREASON value="Regression" />
       </REASONS>
     <FIELDS> . . . </FIELDS>
    </TRANSITION>
 </TRANSITIONS>
 </WORKFLOW>

Determine the number and types of states

You determine the number and types of valid states based on the number of distinct logical states in which you want the work items of that type to exist. Also, if different team members perform different actions, then you can consider defining a state based on a member role. Each state corresponds to an action that a team member must perform on the work item to move it to the next state. For each state, you should define the specific actions and the team members who are allowed to perform those actions.

The following table provides an example of four states that are defined to track the progress of a feature and the valid users who must perform the indicated actions:

State Valid user Action to perform
Proposed Project manager Anyone can create a feature work item. However, only project managers can approve or disapprove the work item. If a project manager approves a feature, the project manager changes the status of the work item to Active; otherwise, a team member closes it.
Active Development lead The development lead oversees the development of the feature. When the feature is completed, the development lead changes the status of the feature work item to Review.
Review Project manager The project manager reviews the feature that the team implemented and changes the status of the work item to Closed if the implementation is satisfactory.
Closed Project manager No additional action is expected to occur on work items that are closed. These items remain in the database for archival and reporting purposes.
NOTE

All states appear in alphabetical order in the list on the form for a work item of a particular type, regardless of the sequence in which you specify them.

Define transitions

You control the states to and from which team members can change a work item if you define the valid state progressions and regressions. If you do not define a transition from one state to another state, team members cannot change a work item of a particular type from a particular state to another particular state.

The following table defines the valid transitions for each of the four states that were described earlier in this topic, together with the default reason for each.

State Transition to state Default reason
Proposed Active (progression) Approved for development
Closed (progression) Not approved
Active Review (progression) Acceptance criteria met
Review Closed (progression) Feature complete
Active (regression) Does not meet requirements
Closed Proposed (regression) Reconsider for approval
Active (regression) Closed in error

You can restrict who is allowed to make a transition from one state to another by using the for and not attributes of the TRANSITION element. As the following example shows, testers can reopen a bug but developers cannot.

<TRANSITION from="Closed" to="Active"  
     for="[Project]\Testers"  
      not="[Project]\Developers">  
    . . .  
</TRANSITION>  

Specify the reasons

When a team member changes the State field, that user can retain the default reason for that transition or specify a different reason if you define additional options. You must use the DEFAULTREASON element to specify one and only one default reason. You should specify additional reasons only if they help the team track or report data.

For example, a developer can specify one of the following reasons when they resolve a bug: Fixed (Default), Deferred, Duplicate, As Designed, Cannot Reproduce, or Obsolete. Each reason specifies a particular action for the tester to perform with regard to the bug.

NOTE

All reasons appear in alphabetical order in the list on the work form for work items of a particular type, regardless of the sequence in which you specify the REASON elements.

The following example shows the elements that define the reasons why a member of the team might resolve a bug:

<TRANSITION from="Active" to="Resolved">  
   . . .  
   <REASONS>  
      <DEFAULTREASON value="Fixed"/>  
      <REASON value="Deferred"/>  
      <REASON value="Duplicate"/>  
      <REASON value="As Designed"/>  
      <REASON value="Unable to Reproduce"/>  
      <REASON value="Obsolete"/>  
   </REASONS>  
   . . .  
</TRANSITION>  

Specify actions

In general, team members change the state of a work item by specifying a different value for the State field and then saving the work item. However, you can also define an ACTION element that automatically changes the state of a work item when that transition occurs. As the following example shows, you can specify that bug work items should be resolved automatically if they are associated with files that a developer checks into version control:

<TRANSITION from="Active" to="Resolved">  
   <ACTIONS>  
   <ACTION value="Microsoft.VSTS.Actions.Checkin"/>  
   </ACTIONS>  
. . .  
</TRANSITION>  

You can use the ACTION element to automatically change the state of work items of a particular type when events occur elsewhere in Microsoft Visual Studio Application Lifecycle Management or outside Visual Studio Application Lifecycle Management (for example, from a tool that tracks calls). For more information, see ACTION.

Update a field during a workflow change

You can define rules that update fields whenever the following events occur:

  • Assign a field rule under STATE when you want the rule to apply for all transitions to and reasons for entering that state.

  • Assign a field rule under TRANSITION when you want the rule to apply for that transition and all reasons for making that transition.

  • Assign a field rule under DEFAULTREASON or REASON when you want the rules to apply only for that specific reason.

    If a field should always contain the same value, you define the rule under the FIELD element that defines that field. To learn more about rule usage, see Apply a field rule.

    You should try to minimize the number of conditions that you define for any one type of work item. With each conditional rule that you add, you increase the complexity of the validation process that occurs every time that a team member saves a work item. Complex rule sets might increase the time that is required to save the work item.

    The following examples show some of the rules that are applied to system fields in the process template for MSF Agile Software Development.

Change the value of a field when the state changes

When the value of the State field for a work item is set to Active and the work item is saved, the values of the Activated By and Assigned To fields are automatically set to the name of the current user. That user must be a member of the Team Foundation Server Valid Users group. The value of the Activated Date field is also set automatically. The following example shows the elements that enforce this rule:

<STATE value="Active">  
<FIELDS>  
   <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">  
      <COPY from="currentuser"/>  
      <VALIDUSER/>  
      <REQUIRED/>  
   </FIELD>  
   <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">  
      <SERVERDEFAULT from="clock"/></FIELD>  
   <FIELD refname="System.AssignedTo">  
      <DEFAULT from="currentuser"/>  
   </FIELD>  
. . .  
</FIELDS>  
</STATE>  

Clear the value of a field when the value of another field changes

When the value of the State field for a work item is set to Active and the work item is saved, the Closed Date and Closed By fields are automatically set to null and made read-only if you use the EMPTY element, as the following example shows.

<STATE value="Active">  
   <FIELDS>  
. . .  
      <FIELD refname="Microsoft.VSTS.Common.ClosedDate"><EMPTY/></FIELD>  
      <FIELD refname="Microsoft.VSTS.Common.ClosedBy"><EMPTY/></FIELD>  
   </FIELDS>  
</STATE>  

Define a field based on the contents of another field

When the value of the State field for a work item changes to Resolved and the work item is saved, the value of the Resolved Reason field is set to the value that the user specified in the Reason field. The following example shows the elements that enforce this rule:

<STATE value="Resolved">  
   <FIELDS>  
. . .  
      <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">  
         <COPY from="field" field="System.Reason"/>  
      </FIELD>  
   </FIELDS>  
</STATE>  

Workflow elements and state categories

All workflows consist of states, transitions, and reasons. A transition supports forward and backward movement among two states. When you add a custom state, the system automatically adds transitions from the custom state to all other inherited states (except for Removed).

Each state belongs to a state category (previously referred to as a metastate). State categories support the Agile tool backlog and board views. If you change or add a state for a WIT that belongs to the Requirements, Task, or Bug categories, you need to update the ProcessConfiguration definition. For details, see ProcessConfiguration.

Workflow states

Workflow states define how a work item progresses from first activation or creation to closed or complete. For example, the four main states defined for the Agile process User Story define a progression of four states, from New, Active, Resolved, to Closed. A fifth state, Removed, also exists to support removing a work item from appearing on the backlog.

The natural progressions and regressions of the user story, product backlog item, and requirement WITs are as shown.

User Story (Agile)

User Story workflow states, Agile process

Product backlog item (Scrum)

Product backlog item workflow states, Scrum process template

Requirement (CMMI)

Requirement workflow states, CMMI process

State categories

State categories, on the other hand, determine how the Agile planning tools treat each workflow state. The state categories used by the backlogs and boards are Proposed, In Progress, and Complete.

Here's how the default, inherited states map to the state categories for all three system processes plus test case management WITs. The workflow states for Test Case, Test Design, and Test Suite are the same across all three system processes.

Categories Agile Scrum CMMI Test WITs
Proposed: Assign to states associated with newly added work items that should appear on the backlog. The first column on the Kanban or task board maps to a Proposed state. New New
Approved
To Do (Task)
Proposed
Design (Test Case)
In Progress: Assign to states that represent active work. Work items assigned to states mapped to this category will appear in the backlog (unless you choose to hide them) and make up the middle columns on the Kanban boards. Active
Resolved (Epic, Feature, User Story)
Committed
Open (Impediment)
Active
Resolved (Epic, Feature, Requirement, Task)
Active (Test Plan)
In Planning (Test Suite)
In Progress (Test Suite)
Ready (Test Case)
Resolved: Assign to states that represent a solution has been implemented, but are not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. Resolved (Bug) n/a Resolved (Bug, Issue, Review, Risk) n/a
Completed: Assigned to states that represent work has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. Closed
Done
Closed
Closed (Test Case)
Completed (Test Suite)
Inactive (Test Plan)
Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. Removed Removed n/a n/a

When to add a State versus a Kanban column

Both States and Kanban columns are used to track the status of work. Workflow states are shared across a team project while Kanban columns are shared within a team. Only project collection admins can add custom states, while team admins can add Kanban columns.

Add custom states when you want all teams to track the status according to the business workflow adopted by the organization. By customizing the process, you automatically customize the team projects and WITs that reference that process.

Also, by adding custom states to support those workflow states that several teams want to track, you avoid the confusion that can arise when team's create a query based on a Kanban column. 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 work around is to formalize the columns by adding custom states which can be shared across teams.

Tool support

You can change the workflow or view the workflow state diagram that you are defining by using the Process Editor, available for TFS 2015 and earlier versions. You install it from Microsoft Visual Studio Team Foundation Server 2015 Power Tools.

You can support your users to visualize the workflow by installing the State Model Visualization extension from the Visual Studio Marketplace. This tool supports both TFS and Team Services.