Designing the Workflow

You design the workflow for a work item type to support your business and team processes. The workflow determines the logical progression of tasks that will be performed and by whom. You define the workflow by first identifying the states and the valid transitions between them. The WORKFLOW section of the definition for the work item type defines 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. For more information about type definitions, see High-Level Structure of a Work Item Type.

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 field is set to Active when a tester creates a bug that is based on the process template for Microsoft Solutions Framework (MSF) for Agile Software Development v4.2. After fixing the bug, 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 leaves the value of the Reason field as Fixed. 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 Resolution Denied or Test Failed.

Note

You can create and modify the definitions for types of work items and other objects to track work items by using Process Template Editor, which is a power tool for Visual Studio. This tool is not supported. For more information, see the following page on the Microsoft website: Visual Studio Team System 2008 Team Foundation Server Power Tools - October 2008 Release.

In this topic

• Workflow Design Guidelines

• Workflow Diagram and Code Example

• All Workflow Elements

• Determining the Number and Types of States

• Defining the Transitions

  • Specifying the Reasons

  • Specifying Actions

• Updating a Field

  • Changing the Value of a Field When the State Changes

  • Clearing the Value of a Field When the Value of Another Field Changes

  • Defining a Field Based on the Contents of Another Field

• Viewing the Workflow State Diagram

Workflow Design Guidelines

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

• By using the STATE element, you 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 State list.

• By using the TRANSITION element, you 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.

• For each transition, you must define a default reason by using the DEFAULTREASON element. You can define as many optional reasons as you want by using the REASON element.

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

• You can define conditional rules to any field 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 Updating Fields During State Changes, Transitions, or Reasons later in this topic.

• 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 may increase the time that is required to save the work item.

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

Workflow Diagram and Code Example

The following table shows the WORKFLOW section of the definition for a work item type that tracks code defects, and the workflow state diagram that it defines. This example defines three states, six transitions, and nine reasons. 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.

Note

The example does not list the elements for DEFAULTREASON, REASON, ACTION, and FIELD.

<WORKFLOW> <STATES>   <STATE value="Active">     <FIELDS> . . . </FIELDS>   </STATE>   <STATE value="Resolved">     <FIELDS> . . . </FIELDS>   </STATE>   <STATE value="Closed" /> </STATES> <TRANSITIONS>   <TRANSITION from="" to="Active">     <REASONS>       <DEFAULTREASON value="New" />     </REASONS>     <FIELDS> . . . </FIELDS>   </TRANSITION>   <TRANSITION from="Active" to="Resolved">     <REASONS> . . . </REASONS>     <FIELDS> . . . </FIELDS>     < ACTIONS > . . . </ ACTIONS > </TRANSITION> <TRANSITION from="Resolved" to="Closed">     <REASONS> . . . </REASONS>     <FIELDS> . . . </FIELDS>     < ACTIONS > . . . </ ACTIONS > </TRANSITION> <TRANSITION from="Resolved" to="Active">     <REASONS> . . . </REASONS>     <FIELDS> . . . </FIELDS> </TRANSITION> <TRANSITION from="Active" to="Closed ">     <REASONS> . . . </REASONS>     <FIELDS> . . . </FIELDS> </TRANSITION> <TRANSITION from="Closed" to="Active">     <REASONS> . . . </REASONS>     <FIELDS> . . . </FIELDS> </TRANSITION> </TRANSITIONS> </WORKFLOW>

Example Workflow State Diagram

All Workflow Elements

By using the elements that the following table describes, you can specify to which states a team member can set a work item of a particular type. In the WORKFLOW section of the definition, you define states first, and then you define transitions.

Element	Description and syntax	Required?	Schema reference
ACTION	Defines a text string that corresponds to an action to be performed when the system for tracking work items calls the WorkItem.GetNextState method to get the post-action state of the work item. <ACTION value="name of action" />	Optional	ACTION Element (Work Item Type Definition Schema)
ACTIONS	Defines a collection of ACTION elements. <ACTIONS>    <ACTION>. . . </ACTION> </ACTIONS>	Optional	ACTIONS Element (Work Item Type Definition Schema)
DEFAULTREASON	Defines the most common cause of a team member changing a work item from one particular state to another particular state. <DEFAULTREASON value="ValueOfDefaultReason">    <FIELDS>. . . </FIELDS> </DEFAULTREASON>	Required	DEFAULTREASON Element (Work Item Type Definition Schema)
FIELD	Specifies a field for a type of work item and the rules and conditions that will be applied to that field when a team member changes the state of a work item of that type and specifies a reason for the change. <FIELD refname="FieldReferenceName"> <ALLOWEDVALUES> . . . </ALLOWEDVALUES> <ALLOWEXISTINGVALUE /> <CANNOTLOSEVALUE /> <COPY /> <DEFAULT /> <EMPTY /> <FROZEN /> <MATCH /> <NOTSAMEAS /> <PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES> <READONLY /> <SERVERDEFAULT /> <SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES> <VALIDUSER /> <WHEN>> . . . </WHEN> <WHENNOT> . . . </WHENNOT> <WHENCHANGED> . . . </WHENCHANGED> <WHENNOTCHANGED> . . . </WHENNOTCHANGED> <FIELD>	Optional	FIELD Element (WORKFLOW)
FIELDS	Specifies a collection of FIELD elements. <FIELDS>    <FIELD . . . </FIELD> </FIELDS>	Optional	FIELDS Element (WORKFLOW)
REASON	Specifies a different explanation from DEFAULTREASON for why a team member changed the state of a work item. <REASON value="ValueOfReason">    <FIELDS>. . . </FIELDS> </REASON>	Optional	REASON Element (Work Item Type Definition Schema)
REASONS	A collection of one DEFAULTREASON and optional REASON elements that explain why a team member changed the state of a work item. <REASONS>    <DEFAULTREASON>. . . </DEFAULTREASON>    <REASON>. . . </REASON> </REASONS>		REASONS Element (Work Item Type Definition Schema)
STATE	Defines a valid state for the work item type and can contain a FIELDS element, which references rules and conditions that will be applied to a specific field when a team member changes the state of a work item of that type. <STATE value="NameOfTheState">   <FIELDS>. . . </FIELDS> </STATE>	Required	STATE Element (Work Item Type Definition Schema)
STATES	Specifies a collection of STATE elements that define the valid states to which a user can assign a work item of that type. <STATES>    <STATE>. . . </STATE> </STATES>	Required	STATES Element (Work Item Type Definition Schema)
TRANSITION	Specifies a valid progression or regression from one state to another state for the work item type. <TRANSITION from="NameOfStartingState"    to="NameOfEndingState"    for="UserOrGroupName"    not="UserOrGroupName">    <ACTIONS>. . . </ACTIONS>    <REASONS>. . . </REASONS>    <FIELDS>. . . </FIELDS> </TRANSITION>	Required	TRANSITION Element (Work Item Type Definition Schema)
TRANSITIONS	Specifies a collection of TRANSITION elements. <TRANSITIONS>     <TRANSITION>. . . </TRANSITION> </TRANSITIONS>	Required	TRANSITIONS Element (Work Item Type Definition Schema)
WORKFLOW	Specifies the collection of STATES and TRANSITIONS container elements that together define the workflow for the type of work item. <WORKFLOW>    <STATES>. . . </STATES>    <TRANSITIONS>. . . </TRANSITIONS> </WORKFLOW>	Required	WORKFLOW Element (Work Item Type Definition Schema)

Determining 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, 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.

Defining the 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 transition:

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>

Specifying 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>

Specifying 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 Visual Studio Team System or outside Visual Studio Team System (for example, from a tool that tracks calls). For more information, see Automating State Transitions.

Updating a Field

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

• The State field of a work item changes to a particular value, regardless of the previous value of that field, and the work item is saved. To create this type of rule, you define it under that value for the STATE element.

• The State field of a work item changes from a particular value to another particular value, and the work item is saved. To create this type of rule, you define it under the TRANSITION element that defines that type of change.

• The Reason field is set to a particular value, and the work item is saved. To define this type of rule, you define it under the DEFAULT REASON or REASON element that defines the appropriate value.

If a field should always contain the same value, you define the rule under the FIELD element that defines that field. For more information, see Defining Field Rules.

The following examples show some of the rules that control system fields in the process template for MSF Agile Software Development v4.2.

• Changing the Value of a Field When the State Changes

• Clearing the Value of a Field When the Value of Another Field Changes

• Defining a Field Based on the Contents of Another Field

Changing 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>

Clearing 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>

Defining 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>

Viewing the Workflow State Diagram

You can view the workflow definition of any type of work item if you use Team System Web Access to open the state diagram for any work item of that type. For more information, see How to: View State Diagrams for Work Item Types (Team System Web Access).

Tip

You can also view the workflow state diagram that you are defining by using the Process Template Editor, a power tool for Visual Studio. This tool is not supported. For more information, see the following page on the Microsoft website: Visual Studio Team System 2008 Team Foundation Server Power Tools - October 2008 Release.

See Also

Other Resources

Defining Work Item Workflow

Change History

Date	History	Reason
July 2010	Completely rewritten to provide more information, examples, and a summary of all WORKFLOW elements and attributes.	Customer feedback.