Sample custom rule scenarios

Article
06/30/2021

TFS 2017 | TFS 2015 | TFS 2013

This article provides examples of custom rule definitions. All custom rules are defined for a work item type. Examples are provided for On-premises XML process models.

Prior to adding custom rules, read Rules and rule evaluation and Add a rule to a work item type (Inheritance process).

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 an issue, the custom Customer Reported field is set to True, and the Severity field becomes required. If the issue isn't reported by a customer, a value for the Severity field isn't required.

You specify a WHEN rule statement for the field definition within the FIELDS section of the work item type definition.

<FIELDS>
   ...
   <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> 
   ...
</FIELDS>

Clear the value of a dependent field

The following example illustrates defining a custom rule to clear the value for Story Points when a change is made to the Start Date.

You specify a WHENCHANGED rule statement for the field definition within the FIELDS section of the work item type definition.

<FIELDS>
 ...
   <FIELD name="Story Points" refname="Microsoft.VSTS.Scheduling.StoryPoints" type="Double" reportable="measure" formula="sum">
       <HELPTEXT>The size of work estimated for implementing this user story</HELPTEXT>
       <WHENCHANGED field="Microsoft.VSTS.Scheduling.StartDate">  
           <EMPTY />  
       </WHENCHANGED>
   </FIELD>
   ...
</FIELDS>

Set a dependent field value

The following examples illustrate how to map the values of the Size field depending on the value selected for the custom field, Tee-Shirt Size field.

You specify the value of the Size field in the FIELDS section of the work item type definition. You use a series of WHEN rule statements to make the mapping, setting the value of the Size field using the COPY value="value" rule.

<FIELDS>
   ...
   <FIELD name="Tee-Shirt Size" refname="Fabrikam.TShirt.Size" type="String">
        <HELPTEXT>Estimate of overall size for work to be done; Small (2), Medium (6), Large (18), X-Large (30).</HELPTEXT>
        <ALLOWEDVALUES expanditems="true">
          <LISTITEM value="Large" />
          <LISTITEM value="Medium" />
          <LISTITEM value="Small" />
          <LISTITEM value="X-Large" />
        </ALLOWEDVALUES>
   </FIELD> 
   <FIELD name="Size" refname="Fabrikam.Size" type="Integer">
        <HELPTEXT>Integer estimate of overall size for work to be done; Automatically fill in based on Tee-Shirt Size. Allow any value.</HELPTEXT>
        <WHEN field="Fabrikam.TShirt.Size" value="Small">
          <COPY value="2" />
        </WHEN>
        <WHEN field="Fabrikam.TShirt.Size" value="Medium">
          <COPY value="6" />
        </WHEN>
        <WHEN field="Fabrikam.TShirt.Size" value="Large">
          <COPY value="18" />
        </WHEN>
        <WHEN field="Fabrikam.TShirt.Size" value="X-Large">
          <COPY value="30" />
        </WHEN>
   </FIELD>
   ...
 </FIELDS>

Require a field value upon State changes

The following example shows how you can require specification of the Remaining Work field when the task workflow State changes to Active.

On-premises XML process

When the value of the State field for a work item is set to Active and the work item is saved, the values of the Activated By and Assigned To fields are automatically set to the name of the current user. That user must be a member of the Team Foundation Server Valid Users group. The value of the Activated Date field is also set automatically. The following example shows the elements that enforce this rule:

<WORKFLOW>
. . .  
    <STATE value="Active">
        <FIELDS>
            <FIELD refname="Microsoft.VSTS.Scheduling.RemainingWork">
              <REQUIRED />
            </FIELD>
        </FIELDS>
    </STATE>
. . .  
</WORKFLOW>

Clear the value of a field upon close State

To automate clearing the Remaining Work field upon closing a task, define a custom rule as indicated.

<WORKFLOW>
. . .  
      <STATE value="Closed">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Scheduling.RemainingWork">
              <EMPTY />
            </FIELD>
          </FIELDS>
      </STATE>
. . .  
</WORKFLOW>

Restrict creation of work items by a group

A custom rule that restricts the transition to the Proposed state category of a work item type effectively disallows creation of work items of that type. By applying the rule to a specific group, you effectively disallow that group from creating work items of that type.

The following custom rule restricts the Fabrikam Review Team (for attribute) from creating work items by disallowing the transition to the New workflow state.

<WORKFLOW>
... 
<TRANSITION from=" " to="New"  
   for="[Project]\Developers" 
   not="[Project]\Fabrikam Review Team"  
   . . .  
</TRANSITION> 
...  
</WORKFLOW>

Restrict modification of work items by a group

For an Inheritance process, you can prevent users from modifying a work item by setting the deny permission for a group on an Area Path. For an On-premises XML process, you can place restrictions on each workflow state for a group that prevents them from saving the work item in any state.

The following custom rule restricts the Fabrikam Review Team (for attribute) from modifying user stories by disallowing all workflow states defined for the user story work item type. Because no workflow state is valid for the specific team, members of that team are prevented from saving the work item with any changes.

<WORKFLOW>
... 
 <STATE value="New">  
   not="[Project]\Fabrikam Review Team"  
</STATE>  
<STATE value="Active">  
   not="[Project]\Fabrikam Review Team"  
</STATE>  
<STATE value="Resolved">  
   not="[Project]\Fabrikam Review Team"  
</STATE>  
<STATE value="Closed">  
   not="[Project]\Fabrikam Review Team"  
</STATE>  
...  
</WORKFLOW>

Restrict state transitions

For inherited processes, any-to-any state transitions are automatically defined. This allows users to advanced the workflow state from new to completed, but also to move backwards in case that is needed. When defining custom rules to restrict a transition, keep in mind that if a user makes a mistake in updating the workflow, they may not be able to correct it. For example, they could update the status by moving a work item card to a later stage on the Kanban board, but not move it back.

Tip

Consider restricting a state transition for some but not all users. That way, if a user makes a mistake, they can ask another team member to reset the State value to bypass the restriction.

Before defining state transition rules, review Rules and rule evaluation, Auto-generated rules and How workflow states and state categories are used in Backlogs and Boards.

Restrict modification of closed work items

Depending on your business processes, you may want to prevent users from continuing to modify or update work items that have been closed or completed. You can add rules to work item types to prevent users from re-opening closed work items.

For on-premises deployments, you can add rules to a work item type to prevent re-opening after a work item has been closed. For example, the following workflow transition rules allow Testers to reopen a work item, but not members of the Developers group.

<WORKFLOW>
. . .  
<TRANSITION from="Closed" to="New"  
   for="[Project]\Testers"  
   not="[Project]\Developers" 
   . . .  
</TRANSITION 
<TRANSITION from="Closed" to="Active"  
   for="[Project]\Testers"  
   not="[Project]\Developers" 
   . . .  
</TRANSITION 
. . .  
</WORKFLOW>

Restrict modification of select fields based on a user or group

You can customize work item types to restrict who can modify a specific field for a work item type.

For the On-premises XML process model, you can customize work item types to support these restriction requests:

Restrict who can create or modify a work item
Restrict who can create specific work item types, such as Epics or Features

For example, you can restrict modification of work items by adding a rule to the work item type, usually within the WORKFLOW section.

You restrict access to work tracking objects in one of two ways:

Set a condition field rule, a condition-based field rule or a combination of the two that applies to a group. You can restrict changes from being made to a field by specifying a qualifying rule and making it apply for a specific group. Conditional rules can include CANNOTLOSEVALUE, EMPTY, FROZEN, NOTSAMEAS, READONLY, and REQUIRED elements.
By adding WITs to the Hidden Categories group, you can prevent the majority of project contributors from creating them. You can create a hyperlink to a template that opens the work item form and share that link with those team members who you do want to create them.