This post relates to Team Foundation Server and the Scrum for Team System process template.
Previously I have described the Event Service and have taken a closer look at the Transition Service. In this instalment I’ll describe the Aggregation service and it’s configuration.
In order to enhance the features of TFS 2010, we have added a web service that subscribes to the TFS work item changed notification. This gives us the ability to update related work items when certain triggering events are detected. The TFS change notifications are queued into a central service controller which in turn distributes them to all the registered service processors. The default SfTS v3 installation gives you two service processors; Transition and Aggregation.
The Transition processor handles the actions that relate to single work item instances, while the Aggregation service handles updates that involve collections of work items. The aggregation service also offers an alternative linking method, inferred linkage by work item path. More about this below.
The Aggregation Service
Unsurprisingly, this service offers the ability to execute aggregated updates to work items. These updates can be either “Sum”, “Min”, “Max” or “Average”.
An excellent example of this service in action is the “Product Backlog Item” (PBI) Work Remaining value. PBIs describe a required feature of the project output. To break the feature requirement down into task actions, you create linked work items called “Sprint Backlog Tasks” (SBT). Each SBT is given a “Work Remaining” value that indicates the duration of effort remaining in order to complete the specified task. The aggregation service sums up the total of the linked SBTs and updates the PBI work remaining value. Each time any of the SBTs remaining duration is changed, the service will update the associated PBI.
When the service updates a work item, it also adds a description of the action to the work item history. The above example states that the sum of associated tasks work remaining has been applied.
In this manner, the aggregation services can update work items to show values based on other work items. This is not a feature of standard TFS, but one I like to think adds a great deal of depth to work item linkage.
Inferred Linking.
Because the aggregation of a work item value can potentially involve a large number of other work items, we have added an alternative way to specify linkage. Imagine that you want to roll up the total number of story points in a release. If you could only roll up linked work item values, you would have to directly link every PBI to the Release work item. A single release might contain hundreds of PBIs and maintaining all those links isn’t going to be fun task, even for a temp. To combat this, you can create aggregation rules that work by Inferred linkage.
The concept of inferred linkage is that you consider work item paths as an indication of a relationship. Looking at our “completed story points in this release” rule, we can say: “Rollup all PBI story Point values where the iteration path under this release”. No direct linkage is required to do this, so you can take an extra hour for lunch with the time you saved not adding hundreds of work item links (or get rid of the temp).
This is why it is very important to maintain the correct planning path structure in your SfTS v3 work items. If you alter the default path hierarchy (Project / Release / Work Stream / Sprint / Team Sprint), the inferred aggregation rules will not be able correctly ascertain the relationships. Of course you could update all the rules to work with your new path structure and you might want to bring back the temp to help out with the additional work load.
You can use both Iteration (planning) and Area (Feature) paths to indicate an inferred link.
What Changes Trigger an Update?
It’s not only the field values changing that can trigger the update service. The aggregated value can also be affected by changing work item linkages, paths and states. The service rule definitions also allow you to specify a list of excluded states. Moving a work item in or out of an excluded state will also trigger an update.
Triggers:
- The aggregated field value is changed.
- The work item state is change from or to an excluded state.
- The work item linkage is changed (direct links).
or
- The work item path value is changed (inferred links).
Where can I find the default Rule definitions?
The default installation location of the Aggregation rules file is located on the TFS AT at:
- C:\Program Files\Scrum for Team System\Services\3.0\Rules\AggregationRules.xml
What does A Rule look like?
Below are two examples of aggregation rules. The first rule describes the PBI work remaining calculation and the second shows the PBI story point roll up.
PBI work remaining (using direct links)
<AggregateRule type="Sum">
<WorkItemType source="Sprint Backlog Task" target="Product Backlog Item" />
<Link linktypename="Scrum.ImplementedBy" isforward="true" />
<Field source="Scrum.WorkRemaining" target="Scrum.WorkRemaining" />
<ChangeNote>Sum of associated task(s) work remaining applied.</ChangeNote>
<ExcludedSourceStates>
<State>Deleted</State>
</ExcludedSourceStates>
</AggregateRule>
Release Story Points (using inferred linkage)
<AggregateRule type="Sum">
<WorkItemType source="Product Backlog Item" target="Release" />
<InferredLink path="IterationPath" type="Partial" depth="2" />
<Field
source="Microsoft.VSTS.Scheduling.StoryPoints"
target="Scrum.PlannedVelocity"
/>
<ChangeNote>Sum of planned backlog item(s) points applied.</ChangeNote>
<ExcludedSourceStates>
<State>Deleted</State>
</ExcludedSourceStates>
</AggregateRule>
Rule Definition Breakdown
Let’s break the rule definition down into it’s component parts.
Aggregate Rule
The rule container element.
<AggregateRule type="Sum">
...
</AggregateRule>
Attributes:
- type – Describes the aggregation action. Possible values are “Sum”, “Min”, “Max” and “Average”.
Work Item Type
Defines the work item types involved in this rule.
<WorkItemType source="Product Backlog Item" target="Release" />
Attributes:
- source – The source work item type to be aggregated.
- target – The target work item type to be updated.
Link
Details the work item link type to be used in the aggregation.
Note: Aggregation rules must specify either a “Link” or an “Inferred Link” but not both.
<Link linktypename="Scrum.ImplementedBy" isforward="true" />
Attributes:
- linktypename – The linkage type name.
- isforward – Boolean value to indicate if the target work item is on the forward side of the link.
Inferred Link
This element describes the inferred link for this rule.
Note: Aggregation rules must specify either a “Link” or an “Inferred Link” but not both.
<InferredLink path="IterationPath" type="Partial" depth="2" />
Attributes:
- path – Details which work item path is going to be used to infer the relationship. This value can be either: “IterationPath” or “AreaPath”.
- type – Describes the type of path matching to use. This can be either “Partial” or “Complete”. Partial paths match to a specified depth and complete matches the entire path.
- depth – Used in conjunction with the “Partial” type to indicate the depth of path to match.
The example shows a depth of “2”. This means that only the “Project / Release” part of the iteration path will be matched between the target and source work items.
Field
This details which the the work item fields to use for this rule.
<Field source="Scrum.WorkRemaining" target="Scrum.WorkRemaining" />
Attributes:
- source - The field on the source work item to aggregate.
- target – The field on the target work item to update.
Change Note
The text to enter into the target work items history when a change is made.
<ChangeNote>Sum of associated task(s) work remaining applied.</ChangeNote>
Excluded Source States
A list of states that indicate a source work is ignored from aggregation.
<ExcludedSourceStates>
<State>Deleted</State>
</ExcludedSourceStates>
A Word of Warning!
When customising rules in either the Transition or Aggregation service, make sure you take extra care not to cause any circular references. If you set one rule to change a field value that in turn triggers another rule, that in turn triggers the original rule, that in turn triggers the other rule... Well I expect you get the picture. Take time to plan the relational updates between your work items and keep an eye out for circular rule references. Remember that an infinite loop might involve more than just two rules.
Handy Links
Regards,
Crispin Parker,
Senior Technical Consultant,
EMC Consulting.