Apply a rule to a work item field

Depending on a field’s data type, you can set various restrictions on what data can be entered into that field. You can specify values for a pick list (drop-down menu), set default values, clear entries, or restrict changes. With conditional rules, you can apply rules to a field based on dependencies between different fields’ values. You can also restrict who can modify a field or scope a rule to only apply to a group.

All of these rule elements can be defined within the FIELD definition of a work item type (WIT) definition, subject to some restrictions for System fields. And, with the exception of HELPTEXT, you can specify these rules to take affect during a workflow transition or as child elements within a FIELD (Global workflow) element.

You can define any combination of rules to a field, subject to the constraints as described in this topic.

Field rules are one component you have to customize work item tracking. To learn more, see Customize work tracking objects to support your team's processes.

For information on modifying fields or adding field rules to a WIT definition file, see Modify or add a field to support queries, reports, and workflow.

Help text

You can customize the help text or tooltip text that appears when a user points to a field that appears on a work item form. You can customize and localize the Help text for the same field that appears in different WITs and different team projects. Help text is restricted to 255 Unicode characters.

The following example shows the assignment of Help text to a custom Business Justification field:

<FIELD name=”Business Justification” refname="Fabrikam.BusinessJustification" type="String">
<HELPTEXT>Only required when you set the Urgencyfield to Need Immediately. </HELPTEXT>
</FIELD>

To provide users guidance that exceeds the 255 characters limit, see Provide help text, hyperlinks, or web content on a work item form.

Pick list rules

Pick list rules define the values that a user can or can’t choose for a String field. Values defined in a pick list appear on a work item form and the query editor. You can combine lists, and expand or contract lists. You can also use the for and not attributes to apply or ignore these rules, based on who is modifying the work item.

For examples of using pick lists, see Define pick lists.

Assign value rules

Assign value rules define runtime behavior and constraints, such as specifying default values, clearing fields, requiring fields to be defined, and more. You can apply or ignore these rules based on who is modifying the work item using the for and not attributes.

Clear, set a default, copy a value, or force values to match a pattern

These rules support setting defaults, copying values from one field to another, or enforcing a field value to match a prescribed pattern.

For the syntax structure and examples, see Define a default value or copy a value to a field.

Require, read-only, and restrict values assigned to a field

These rules specify restrictions on specifying or changing the value of a field.

For the syntax structure, see All FIELD XML elements reference.

Restrict who can create or modify a work item

You can control who can create or modify a work item by applying the VALIDUSER element to person-name fields. When you specify this element, you indicate which user or group of users can be assigned as a value for the field. You can set this element to support the optional group attribute, which requires that the person who is assigned to the field must be a direct or indirect member of the group that you specify. By default, all members of the Team Foundation Valid Users group can be specified in the field.

The VALIDUSER element is valid only for String field types. You can allow or restrict whether the rule applies to the user who is modifying the work item by specifying a user or group for the for or not attributes, respectively.

<VALIDUSER group="groupName" for="userName" not="userName" />

You can use the VALIDUSER rule only when you refer to person-name fields. The following system fields are examples of person-named fields:

• Activated By (System.ActivatedBy)

• Assigned To (System.AssignedTo)

• Authorized As (System.AuthorizedAs)

• Changed By (System.ChangedBy)

• Closed By (System.ClosedBy)

• Created By (System.CreatedBy)

In addition to the system fields, you can create a custom string field and use it as a person-named field. Also, you can synchronize custom person-named fields with Active Directory (specify syncnamechanges="true").

Work item fields do not distinguish between user identities in different domains. Therefore, "Fabrikam\ctsoapo" and "Contoso\ctsoapo" are treated as the same user when they are entered into a field that uses the VALIDUSER rule.

Conditional rules

Conditional rules let you specify when a set of rules will be applied to a parent field. You can set conditions based on whether another field is assigned (or not assigned) a specified value or when another field changes (or doesn’t change). You can include pick list and assign value rules within a conditional rule element.

You can specify multiple conditional rules per field. However, you can only specify a single driving field per conditional rule. You can’t nest conditional rules. For the syntax structure and examples, see Assign conditional-based values and rules.

Apply or ignore rules based on who is creating or modifying the work item

You can make a pick list or assign value rule to apply or not apply to a group of users by using the for or not attributes. Scope the rule to a group. To have the rule scoped to multiple groups, you must create a parent TFS group that includes the set of groups that you want to use.

• Make a field required only for a specified group:

  Use for to apply a rule to a group. This example requires any user in the Junior Analysts group to complete the Second Approver field.

  <FIELD name="Second Approver">
  <REQUIRED for="Example1\Junior Analysts"/>
  </FIELD>
  

• Restrict modification of a field to a group of users:

  Use not to exclude a group from a rule. This example defines the Triage Description field as read-only for everyone except those users in the Triage Committee group.

  <FIELD name="Triage Description">
  <READONLY not="[Project]\Triage Committee" />
  </FIELD>
  

• Make a field required for some users and not for others:

  Use a combination of for and not to simultaneously apply a rule to some and not for others. This example defines Severity as a required field for users in the Project Members group, but not for those in the Project Admins group.

  <FIELD name="Severity">
  <REQUIRED for="[Project]\Project Members" not="[Global]\Project Admins"/>
  </FIELD>
  

  Because Deny takes precedence over Allow, if a user is in both groups, the "not" statement would be enforced, and the field would not be required.

Use tokens to reference groups

When you restrict a rule to a group, you must indicate the domain or scope of the group. For some values, you can use tokens.

Person-name fields can accept values that reference both users and groups. Field attributes, for and not, apply to groups. You can use the following tokens when specifying values for these items.

• Scope to a team project – [Project] :

  The [Project] token is used to specify a group that is defined for a team project. This could correspond to a team, built-in TFS group, such as the [Project]\Contributors group, a custom TFS group you create at the project level, or a Windows group that you added to a TFS group. For example:

  • Team: [Project]\Fabrikam Team

    When you create a team, a TFS group is created that contains the members assigned to the team.

  • Team project group: [Project]\Contributors

  • Windows group added to a team project: [Project]\ Triage Committee

  Tip: You can view a list of valid groups by opening the Security page in the Team Web Access (TWA) administration context.

• Scope to a project collection – [CollectionName]:

  Use [CollectionName] to reference a collection-scoped TFS group, such as the Project Collection Administrators group or a Windows group you add to a collection. For example:

  <FIELD name="Title">
  <READONLY for="[DefaultCollection]\Project Collection Valid Users"/>
  </FIELD>
  

• Scope to a server instance – [GLOBAL]:

  Use the [GLOBAL] token to reference a server-scoped TFS group, such as a built-in group or a Windows group you add to a server-level group. For example:

  <FIELD name="Title">
  <READONLY for="[Global]\Team Foundation Valid Users"/>
  </FIELD>
  

• Specify a domain qualified account or group:

  Domain-qualified account name, such as the one shown in the following example, can be used to reference a domain user or group. Note that some rules only support groups and do not support referencing domain users.

  <LISTITEM value="FABRIKAM\Christie Church’s Direct Reports"/>
  

All users and groups must be qualified by one of these tokens. For example, the following XML isn’t valid because it doesn’t qualify the specified group with a valid token.

<FIELD name="Title">
<READONLY for="Dev Team"/>
</FIELD>

Q & A

Q: What rules can be applied to System fields?

A: System fields have Sytem.Name reference names, for example System.Title and System.State. TFS restricts customization of these fields, except for these instances:

• HELPTEXT rule can be assigned to all fields.

• READONLY rule can be assigned to the State and Reason fields.

• Most rules can be assigned to the Title, Assigned To, Description or Changed By System fields.

Q: How can I avoid validation errors on person-name fields?

A: To avoid validation errors that would otherwise occur when members leave the team and are no longer registered as project contributors, include the ALLOWEXISTINGVALUE element for the Assigned To field.

<FIELD name="Assigned To" refname="System.AssignedTo" type="String" syncnamechanges="true" reportable="dimension">
   <HELPTEXT>The user who is working on this work item</HELPTEXT>
   <ALLOWEXISTINGVALUE />
   <VALIDUSER />
   <ALLOWEDVALUES expanditems="true" filteritems="excludegroups">
      <LISTITEM value="Active" />
      <LISTITEM value="[project]\Contributors" />
   </ALLOWEDVALUES>
   <DEFAULT from="field" field="System.CreatedBy" />
</FIELD>

Q: Is there a way to define a multi-select pick list?

A: This feature isn’t natively supported, However, you might be able to adapt source code provided in this CodePlex project: Custom Controls for TFS Work Item Tracking.

Q: How do I modify the State and Reason fields?

A: The State and Reason fields are defined within the WORKFLOW section of the WIT definition. You can specify most field rules to apply to a field during a change of state, selection of a reason, or for a specific transition. To learn more, see Change the workflow for a work item type.

Q: Where should I apply a field rule?

A: When you want a rule to apply to a field throughout the life of the work item, specify it within the FIELD definition. For example, a field that is required for a bug that is new and active remains required until the bug is closed.

Otherwise, specify a rule to be evaluated only during a change in state. These rules are defined within the WORKFLOW section under the STATE, REASON, or TRANSITION elements. All rules, except for HELPTEXT, can be applied within a FIELD (Workflow) element.

Field rules are additive. That is, you can specify four sets of rules for the same field which will all be evaluated by the work item rule-engine.

• Work item type-specific rules apply regardless of the location of a work item in its state model. For example, a <REQUIRED /> rule performs the following check:

  "MyField Value" != NULL

• State-specific rules are scoped to a work item instance when it is in a certain state. A state-specific rule is enforced when the following condition is true:

  State field value == "MyState" && "MyField Value" != NULL

• Transition-specific rules that you specify for a specific transition are scoped to a work item that is undergoing a certain transition. These rules are enforced when the following conditions are true:

  State field value == "ToState"  &&

  "Previous State Before Edit/New" == "FromState"

  && "MyField Value" != NULL

• Reason-specific rules that you specify for a specific reason are scoped to a particular reason for a particular transition. They are processed when the following conditions are true:

  Reason field == "MyReason" &&

  State field value == "ToState"  &&

  "Previous State Before Edit/New" == "FromState" && "MyField Value" != NULL

The following example restricts modification of the customer severity field when the work item is in the Active state.

<STATE name="Active">
   <FIELDS>
      <FIELD refname="MyCorp.Severity" >
         <READONLY />
      </FIELD>
   </FIELDS>
</STATE>

Q: How are rules evaluated? What order is applied?

A: Rules are typically processed in the sequence in which they are listed. However, when you use the WHEN*, DEFAULT, and COPY elements, additional behaviors may apply.

You can gain some idea of how rules are evaluated when you apply multiple rules to a field. How rules are evaluated is not completely deterministic. This section describes the expected behavior and interactions when you are using the WHEN*, DEFAULT, and COPY rules.

The following steps show, in the correct sequence, the interactions that TFS performs and by the user of a work-item form. Only steps 1, 8, and 13 are performed by the user.

1. From a Team Foundation client─such as Visual Studio, Team Explorer, Team Web Access, or Team Explorer Everywhere─, a user creates a new work item or edits an existing work item.

2. Fill in field defaults. For all fields, use any DEFAULT rules that are outside WHEN* rules.

3. Copy field values. For all fields, use any COPY rules that are outside WHEN* clauses.

4. For all fields with a WHEN rule that matches, first do DEFAULT and then COPY rules inside.

5. For all fields with a WHENNOT rule that matches, first do DEFAULT and then COPY rules inside.

   TFS always processes WHEN rules before WHENNOT rules.

6. For all fields that have had their values changed since step 1 and that contain WHENCHANGED rules, first do DEFAULT and then COPY rules inside.

7. Allow the user to start editing.

8. The user changes a field value and then moves focus from the field.

9. Raise any WHEN rules for that field that match the new value.

10. Raise any WHENNOT rules for that field that match the new value.

11. Raise any WHENCHANGED rules for that field that match the new value.

12. Return editing ability to the user.

13. The user saves the changes to the database.

14. For all fields, perform SERVERDEFAULT operations that are defined for the field either directly or indirectly under a WHEN or a WHENNOT rule.

Q: How do keystroke entries in a form affect rule evaluation?

A: The system sets a new value for a field every time a user enters a keystroke within a field through the UI work item form. This means that a conditional rule can occur unexpectedly whenever the rule’s prerequisite conditions are met.

In the following XML example, SubStatus will be emptied as you type "Approved Again" into the Status field because the WHEN* rule occurs as soon as the user types the letter "e" in Approved, even if the intended final value is not "Approve". For this reason, think carefully when you are using conditional rules.

<FIELD refname="MyCorp.SubStatus" />
<WHEN field="MyCorp.Status" value="Approve" >
<EMPTY />
</WHEN>
</FIELD>

Q: How do I make a field hold a value that is the sum of two other fields?

A: This feature is not natively supported at this time.

Q: When would I define field rules using global workflow?

A: Use global workflow only when you are tasked with maintaining many fields with the same definitions and rules across multiple team projects. Similar to global lists, using global workflow can minimize the work required when you have to update field definitions. For more information, see Customize global workflow.

See Also

Concepts

All WITD XML elements reference

Other Resources

Modify or add a field to support queries, reports, and workflow