This post relates to the Team Foundation Server Scrum for Team System process template event service. It assumes that you have a basic understanding of TFS work items and their fields.
In my last post I gave you an overview of the SfTS event service. Here I pick up the story again and look at the Transition service rules.
The event service code is written with extensibility in mind using the Microsoft Extensibility Framework. Out of the box it comes with two flavours of work item changed event processors; Transition and Aggregation. Both services have a set of rules that are defined in XML configuration files. The MEF plug-in assemblies and the controlling rules files can be found under the SfTS v3 installed web service folder on the TFS AT.
- Default Installation Plug-in Folder:
C:\Program Files\Scrum for Team System\Services\3.0\Plugins
- Default Installation Rules Folder:
C:\Program Files\Scrum for Team System\Services\3.0\Rules
The Transition Service
The transition service handles work item field changes from one value to another. Transition rules can be set to either update the source work item or work items linked to the source item.
Example Transition Rule
Scenario: In our SfTS project, we have a “Product Backlog Item” which links to several “Sprint Backlog Tasks” using the “Scrum.ImplementedBy” link type. When all the linked SBTs are set to a state of “Deleted” we want the Transition Service to automatically set the PBI to “Deleted”.
Here is sample of a XML transition rule that will apply our desired functionality:
<TransitionRule>
<WorkItemTypeName
source="Sprint Backlog Task"
target="Product Backlog Item" />
<Transition
field="System.State"
from="*"
to="Deleted" />
<LinkType target="LinkedItem">Scrum.ImplementedBy</LinkType>
<ChangeNote>All tasks have been deleted</ChangeNote>
<EligibleTargetStates>
<State>In Progress</State>
<State>Done</State>
</EligibleTargetStates>
<Replacements>
<Replacement
targetfield="System.State"
type="Specified"
decimalplaces="0"
>Deleted</Replacement>
</Replacements>
<SiblingConditions>
<SiblingCondition
comparison="All"
field="System.State"
value="Deleted"
siblingtype="Sprint Backlog Task"
link="Scrum.ImplementedBy">
<ExcludedStates>
<State>Ignored</State>
</ExcludedStates>
</SiblingCondition>
</SiblingConditions>
</TransitionRule>
Note: This isn’t a real rule that exists in the SfTS solution, its just an example.
Transition Rule Components Breakdown
So let’s break down the example rule to see what all the bits do.
- Transition rule:
<TransitionRule>
- The container for the rule specification.
- Work Item Type Name:
<WorkItemTypeName source="Sprint Backlog Task" target="Product Backlog Item" />
- Source. The type of the changed work item to match. The sample rule will match a source work item of type “Sprint Backlog Task”.
- Target. The type of linked work item to update. the sample will target work items of type “Product Backlog Item”.
- Transition:
<Transition field="System.State" from="*" to="Deleted" />
- Field. The name of the source work item field to monitor for changes.
- From. The previous field value. The sample rule uses the wildcard “*” character, this means that any previous value will match the rule.
- To. The new field value. The “to” value of the sample transition is set to “Deleted”. This means that this rule will only match work items that have a new “System.State” value of “Deleted”.
- Link Type:
<LinkType target="LinkedItem">Scrum.ImplementedBy</LinkType>
- Target. The work item to target. This value can be either “Self” or “LinkedItem”.
- The work item linkage type name. This is the type of linkage between the source and target work items.
- Change Note:
<ChangeNote>All tasks have been deleted</ChangeNote>
- The note to be written to any updated work items change history.
- Eligible Target States:
<EligibleTargetStates>
<State>In Progress</State>
<State>Done</State>
</EligibleTargetStates>
- A list of target work item states that are eligible to match this rule. This example will only target work items that are in a state of either “In Progress” or “Done”.
- Replacements Collection:
<Replacements>
- This contains a collection of replacement specifications. A single rule can contain multiple replacements and update multiple fields on the target work item.
- Replacement:
<Replacement targetfield="System.State" type="Specified" decimalplaces="0">Deleted</Replacement>
- Target Field. The field on the target work item to update.
- Type. The replacement value specification type. This can be either “Specified” or “Expression”.
- Decimal places. Used when specifying an expression to limit the precision of the returned value.
- Node content. The replacement value. If the type is “Specified” then the value is used as is. A type of “Expression” means that the value represents a calculation expression. More on expressions below.
- Sibling Conditions:
<SiblingConditions>
- A collection of Sibling condition specifications. More on siblings below.
- Sibling Condition:
<SiblingCondition comparison="All" field="System.State" value="Deleted" siblingtype="Sprint Backlog Task" link="Scrum.ImplementedBy">
<ExcludedStates>
<State>Ignored</State>
</ExcludedStates>
</SiblingCondition>
- Comparison. Specifies which sibling items to consider. This can be either “All” or “Any”.
- Field. The field on the sibling item to compare. The sample rules specifies that the “System.State” field value should be examined.
- Value. The field value to be matched. The sample rule checks for a value of "Deleted".
- Sibling Type. The sibling work item type of the. Example: "Sprint Backlog Task".
- Link. The work item linkage between the target and sibling work items. Example: "Scrum.ImplementedBy"
- Excluded states. A list of sibling work item states to ignore from the condition test.
Replacement expressions
The replacement component of the transition rule can specify two types of replacement value; Specified or Expression. “Specified” indicates that the value is used “as is” and “Expression” means that the value is interpreted as an expression.
Expressions allow you to specify a field name or a simple mathematical formula. Formulas can use the add, subtract, multiple and divide operator symbols (+, –, *, /) and the operand values can be either numerical or work item field names.
Expression Examples:
- Scrum.BusinessValue / Microsoft.VSTS.Scheduling.StoryPoints
This expression divides the “Scrum.BusinessValue” field value by the “Microsoft.VSTS.Scheduling.StoryPoints” field value.
Note: When using mathematical expressions, only fields with a “Double” data type can be specified.
- System.IterationPath
This expression returns the value of the “System.IterationPath” field.
- Scrum.BusinessValue * 2.5 / 100
The above expression returns the “Scrum.BusinessValue” field multipled by 2.5 and divided by 100.
Note: Calculations are made in left to right operand pair sequence. So the above example will be the result of “Scrum.BuinessValue” multiplied by 2.5 that is then divided by 100.
Siblings
Transition rules can include a collection of “Sibling” conditions. Siblings are work items that share a common linked target work item. For example in our “Make PBI Deleted” scenario, we specify that all work item Sibs of type “Sprint Backlog Item” that are linked to the target PBI with by a “Scrum.ImplementedBy” linkage, must also be in a state of “Deleted”. From the PBI point of view, this means that all my linked SBTs must be in a state of “Deleted” before this rule can be applied.
You can add multiple sibling conditions that can the reference any work item type linked by any linkage type.
Sibling conditions also allow you to set a list of sibling states that exclude work items from comparison. This is useful in order to handle scenarios where some work items should be ignored.
Links
Next time I will delve into the Transition sister service; the Aggregation service.