All WORKFLOW XML elements reference
Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013
You can use the information in this topic as a quick reference to all the elements and main attributes that control the workflow for a type of work item. You specify these elements in the WORKFLOW element container, which is the second major section of the definition of a work item type. You use the STATES and TRANSITIONS child elements to define the different states that a user can specify for a type of work item and which transitions are allowed between states. For more information about how to define these elements, see Change the workflow
To modify the workflow, you modify the definition for a work item type. See Modify or add a custom work item type.
WORKFLOW example
The following example shows the overall structure of the WORKFLOW element. You specify all the states to which a user can first assign a work item type within a STATES container. Next, you specify all the transitions that are allowed from one state to another. Each state corresponds to a STATE element, and each transition corresponds to a TRANSITION element. Within each STATES and TRANSITIONS container element, you can define the states and transitions in any sequence that you want.
For each transition, you specify a set of reasons for changing the state of the work item, including a default reason. You can assign values for each state, transition, or reason, and you can place conditions on the values of one or more fields by using the FIELD (Workflow) element. In addition, you can trigger an action to occur during a transition by specifying the ACTION element.
<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>
Syntax structure
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. For more information, see Change the workflow.
Element
Description and syntax
Required?
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="NameOfAction" />
For more information, see Automate field assignments based on State, Transition, or Reason
Optional
ACTIONS
Defines a collection of ACTION elements.
<ACTIONS>
<ACTION>. . . </ACTION>
</ACTIONS>
Optional
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
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>
For more information, see FIELD (Workflow) element reference.
Optional
FIELDS
Specifies a collection of FIELD elements.
<FIELDS>
<FIELD . . . </FIELD>
</FIELDS>
Optional
REASON
Defines an additional explanation for why a team member changed the state of a work item.
<REASON value="NameOfReason">
<FIELDS>. . . </FIELDS>
</REASON>
Optional
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>
STATE
Defines a valid state for the work item type. This element 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="NameOfState">
<FIELDS>. . . </FIELDS>
</STATE>
Required
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
TRANSITION
Specifies a valid progression or regression from one state to another for work items of a particular type.
<TRANSITION from="NameOfStartingState"
to="NameOfEndingState"
for="UserOrGroupName"
not="UserOrGroupName">
<ACTIONS>. . . </ACTIONS>
<REASONS>. . . </REASONS>
<FIELDS>. . . </FIELDS>
</TRANSITION>
For more information, see TRANSITION element.
Required
TRANSITIONS
Specifies a collection of TRANSITION elements.
<TRANSITIONS>
<TRANSITION>. . . </TRANSITION>
</TRANSITIONS>
Required
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