Assign conditional-based values and rules

Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013

You can define rules that are run conditionally by using the WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED elements. You use these rules to define which elements are run when the defined clause is True. You can define conditions that are based on what value is assigned to a specific field or whether a user modifies a specific field. For example, you can create a dependent pick list to provide detailed security or custom behavior.

Field conditions are additional elements that you list inside a FIELD (Definition) element or the FIELD (Workflow) element. For more information about these elements, see FIELD (Definition) element reference and FIELD (Workflow).

The following code is a simple example of the WHEN clause:

<FIELD  . . .  > 
<WHEN field="referenceName" value="yyy">  
</FIELD>

This clause means that anything within this FIELD element is applicable as long as the field refname has the value "yyy". The field must be a valid field reference name. For more information, see Naming conventions for work item tracking objects.

Note

The value attribute is case-insensitive. Therefore, if the field reference name holds "YYY", matches include the values "yyy" and "YYY".

Syntax structure for conditional elements

The following table describes conditional rules that you can specify as child elements of the FIELD (Definition) element or FIELD (Workflow) element. These elements accept one or more of the following attributes:

• field: A string that describes the field. Must contain 1 to 255 characters.
• value: When the specified field has this value, the rules in the WHEN and WHENNOT elements are applied to the current field.

Element and syntax

Description

WHEN

<WHEN field="fieldReferenceName" value="value">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHEN>

Specifies one or more rules to apply to the current field when another field has a specific value. The parent element defines the current field.

When the specified field has the specified value, the rules in this element are applied to the current field.

WHENNOT

<WHENNOT field="fieldReferenceName" value="value">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHENNOT>

Specifies a condition under which to apply one or more rules to the current field. The rules apply to the current field when the value of another field changes. The parent element defines the current field.

When the specified field does not contain the specified value, the rules in this element are applied to the current field.

WHENCHANGED

<WHENCHANGED field="fieldReferenceName" >
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>  
</WHENCHANGED>

Specifies a condition under which to apply one or more rules to the current field. The rules apply to the current field when the value of another field is changed in a revision to a work item. The parent element defines the current field.

WHENNOTCHANGED

<WHENNOTCHANGED field="fieldReferenceName">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>  
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHENNOTCHANGED>

Specifies a condition under which to apply one or more rules to the current field. The rules apply to the current field when the value of another field is not changed in a revision to a work item. The parent element defines the current field.

The following table describes how each optional, conditional-based rule is applied to the parent field when the conditional clause that you specify by using a WHEN, WHENNOT, WHENCHANGED, or WHENNOTCHANGED element is true. For more information, see Rules and rule evaluation.

Element	Description
ALLOWEDVALUES	The parent field must have a value that comes from the specified list of values.
ALLOWEXISTINGVALUE	The value of the parent field that already exists will be allowed, even if it violates other rules. This element is not applicable if the value of the parent field is changed.
CANNOTLOSEVALUE	Users can change the value of the parent field to NULL, but they cannot change it to any other value.
COPY	The value of a third field is automatically copied into the parent field. You specify the third field in the COPY element.
DEFAULT	This element specifies the default value of the parent field.
EMPTY	The parent field must not contain a value.
FROZEN	The parent field is frozen. When a field is frozen, you can change its value to NULL, but you cannot change it to any other value.
MATCH	The value of the parent field must match the pattern that you specify.
NOTSAMEAS	The value of the parent field cannot match the value of a third field. You specify the third field in the NOTSAMEAS element.
PROHIBITEDVALUES	The parent field cannot contain any values in the enumerated list.
READONLY	The parent field is read-only.
REQUIRED	The parent field must contain a value that is not NULL.
SERVERDEFAULT	The parent field takes its value from the specified server component. The valid server components are clock, which is the time when the work item is updated, and currentuser, which is the identity of the user who updated the work item.
SUGGESTEDVALUES	The enumerated list contains suggested values for the parent field.
VALIDUSER	Only the users whom you specify can modify the parent field.

Define a dependent required field

You can specify that a field is required only when another field contains a specific value. In the following example, when a customer reports a bug, a customer severity must be specified. If the bug was not reported by a customer, a customer severity is not required.

<FIELD refname="MyCorp.Severity" name="Customer Severity" type="String">  
       <ALLOWEDVALUES>  
           <LISTITEM value="Blocking" />  
           <LISTITEM value="Major" />  
           <LISTITEM value="Minor" />  
       </ALLOWEDVALUES>  
       <WHEN field="MyCorp.CustomerReported" value="true">  
           <REQUIRED />  
       </WHEN>  
</FIELD>  

Define a conditional pick list

The following example demonstrates a conditional pick list in which the allowed values for the Problem Type field are limited, based on whether the value of the ProblemCharacteristic field is set to Documentation.

<FIELD refname="MyCorp.ProblemType" name="Problem Type" type="String">  
       <WHEN field="MyCorp.ProblemCharacteristic" value="Documentation">  
           <ALLOWEDVALUES>  
               <LISTITEM value="Spelling Error" />  
               <LISTITEM value="Bad Format" />  
               <LISTITEM value="Missing Info" />  
           </ALLOWEDVALUES>  
       </WHEN>  
</FIELD>  

Define a field when the user changes another field (WHENCHANGED)

In the following example, when a user changes the value of the MyCorp.State field, the MyCorp.StateDate field is set to the current date and time, as the server clock shows.

<FIELD refname="MyCorp.StateDate" name="Date Of Last State Change" type="DateTime">  
       <WHENCHANGED field="MyCorp.State">  
           <COPY from="clock" />  
       </WHENCHANGED>  
</FIELD>   

In the following example, when a user changes the value of the MyCorp.State field, the value of the MyCorp.Status field is cleared.

<!-- Clear the status field whenever someone changes the state -->  
<FIELD refname="MyCorp.Status" name="Status" type="String">  
       <WHENCHANGED field="MyCorp.State">  
           <COPY from="value" value="">  
       </WHENCHANGED>  
</FIELD>  

Define a field value based on a user not modifying a field (WHENNOTCHANGED)

In the following example, when a user does not change the value of the MyCorp.State field, the MyCorp.StateDate field becomes read-only.

<FIELD refname="MyCorp.StateDate" name="Date Of Last State Change" type="DateTime">  
<!-- Make the StateDate field read-only when the State field is not changed -->  
       <WHENNOTCHANGED field="MyCorp.State">  
           <READONLY />  
       </WHENNOTCHANGED>  
</FIELD>  

Related articles

• Rules and rule evaluation