TFS API: Work ItemHistory

One of the tasks I had while developing my own version of a Sprint Task Board was to note each work item’s “staleness”. This meant that for any Sprint Backlog task that was in a state of “In Progress” or “Ready for Test” I needed to know the last time its Work Remaining field had been updated.

The Team Foundation Server API provides an easy object model for iterating through a work item’s history. Each WorkItem has a Revisions collection that holds individual snap shots of the work item each time it was updated. The Revisions in the collection are in order or earliest to latest, but there is also a Rev property for each one that is the sequential order. Each Revision has a collection of Fields for each field, both the common system fields and any fields added from a custom process template. When you access an individual Field in the Revision you can see what the original value was (OriginalValue) versus what the value was changed to in the revision (Value). If the field was not changed the values are the same.

Since this is the very first time the work item was saved the OriginalValue property on all fields is null. The ChangedDate is the date we saved this particular revision and the RevisedDate is displayed as the maximum value of the DateTime type since this particular revision has not been revised yet. If we edit the work item on June 3rd the Revisions would look like this:

The RevisedDate for Revision 1 is set to the ChangedDate for Revision 2. The fields for Revision 2 now have their OriginalValues populated with the appropriate values from Revision 1.

So based on the examples above, if we want to know the last time a specific field was updated you would look for the “System.ChangedDate” field’s Value for the latest Revision where that field’s OriginalValue and Value properties are not equal. Here is a LINQ query that would accomplish this for the “Work Remaining” field (this field is an extended field that comes with the Conchango Agile Process Template).

One thing to remember when using the Work Item object model is its effect on performance. Not all fields are loaded initially so depending on how you access the WorkItemStore you may incur additional round trips to the server. This MSDN article does a good job of explaining how this works and what your options are to increase performance.