Wednesday, July 05, 2006

Work Item Migration via the WIT Web Service (Part 1/3)

The Work Item Object Model provides an excellent interface to programmatically create new work items. However, from a migration perspective, it fails miserably; primarily due to the “rules” that make VSTS work items so great. For example, you cannot use the OM to set values such as Created By and Created Date; they are automatically set to the current user and current DateTime. Nor can you set the State or Reason to anything other than the default initial value of “New” or “Proposed”, without repeatedly saving the work item and transitioning through the states according to your WI transition rules.

Obviously, if you are a developer trying to migrate work items from a legacy application to VSTS, this will not suit your needs, since your work items will have been created by a multitude of people, all in the past, and many of these work items are in a “closed” state. Luckily, there is a second method by which work items can be uploaded: the Work Item Tracking Web Service. Through the web service, there is a means to turn-off the rules that prohibit setting the following values at will: State, Reason, Created By/Date, Resolved By/Date, Closed By/Date.

Several class libraries are required that are not included with the developer install of VSTS, but are installed on the TFS machine, or through the SDK. Reference to these libraries is required. Their names and locations (on the TFS) are listed below:

C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\Web Services\WorkItemTracking\bin

(from the VSTS SDKs)
C:\Program Files\Visual Studio 2005 SDK\\VisualStudioTeamSystemIntegration\Work Item Tracking

Note: Uploading through the web service is dangerous, not very well documented, and not recommended. It should only be used in extreme/migration cases where the WI rules absolutely must be bypassed. Access to the webservice upload methods is only available to TFS users in the Service Account (ie: TFSSERVICE).

For a preliminary look at some of the functions available through the web service, you can visit:

.oO(in the next part, some code snippets...)

No comments: