Assign Conditional-Based Values and Rules

  • Article

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 and FIELD (Workflow) Element.

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

In this topic

  • Syntax Structure for Conditional Elements

  • Defining a Dependent Required Field

  • Defining a Conditional Pick List

  • Defining a Field When the User Changes Another Field (WHENCHANGED)

  • Defining a Field Value Based on a User Not Modifying a Field (WHENNOTCHANGED)

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

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 Set Conditions on a Work Item Field.

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.

Back to top

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

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

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

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

See Also

Concepts

All FIELD XML Elements Reference

Other Resources

Set Conditions on a Work Item Field

Working with Field Rules