Using the <WHEN>, <WHENNOT>, and <WHENCHANGED> Conditions

You can define rules that are run conditionally by using WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED elements. These rules define which elements are run when the defined clause is True. For example, you can create a dependent pick list to provide detailed security or custom behavior. The following is a simple example of the WHEN clause:

<FIELD . . . >

    <WHEN field="refname" 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 Field Reference Names.

Examples

Dependent Pick List

The following example demonstrates a dependent pick list in which the allowed values for Problem Type are limited, based on the value of ProblemCharacteristic:

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

Required Fields

The following example shows a change in required fields. In this scenario, when a bug is reported by a customer, a customer severity must be entered. If the bug was not reported by a customer, the customer severity is not required.

WHEN

<WHEN>

Example

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

Condition   Anything within this element is applicable as long as the field Customer Reported has a value and that value is true.

WHENNOT

<WHENNOT>

Example

<WHENNOT field="refname" value="yyy">
</WHENNOT>

Condition   Anything within this element is applicable as long as the field refname has a value but that value is not yyy.

WHENCHANGED

<WHENCHANGED>

Example

<FIELD refname="MyCorp.StateDate" name="Date Of Last State Change" type="DateTime">
    <WHENCHANGED field="MyCorp.State">
        <COPY from="clock" />
    </WHENCHANGED>
</FIELD>
<!-- 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>

Condition   Anything within this element is applicable when the field refname has been modified by the user.

WHENNOTCHANGED

<WHENNOTCHANGED>

Example

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

Condition   Anything within this element is applicable as long as the field refname has not been changed.

See Also

Concepts

Available Field Rules