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

The following is a wee snippet of the code that sends the work item information to the server:

/* first, create the ClientService object.
Path must be explicitly specified because another ClientService exists in the Microsoft.TeamFoundation.WorkItemTracking.Server namespace (and you don't want that one). */

Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService clientService = new Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService();

clientService.Url = http://your_server:8080/WorkItemTracking/v1.0/ClientService.asmx;

try
{
// send the package to the server for processing.
clientService.Update(Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService.NewRequestId(), insertWorkItem.DocumentElement, outputXmlElement, metadataTHE, databaseStamp, metadataRowSets);
}
catch
{
/* Update will fail if the xml is formatted incorrectly, or if filling any of the fields on the server fails. If the Update fails, the WI will not have been saved on the server side, no data is entered. */
}

Note: This method will allow you to upload work items that are not entirely correct; for example, you may upload a work item of state “Closed” but not have uploaded a “Closed By” and “Closed Date” value. The VSTS UI will inform you of this when you view the WI through Team Explorer.

insertWorkItem is an XmlDocument formatted as described in Part 3. This xml package contains the "guts" of the work item.

metadataTHE is an array of type MetadataTableHaveEntry, which can be found in the Microsoft.TeamFoundation.WorkItemTracking.Proxy namespace. This array must be populated with the TableName and RowVersion information returned from a call to Enum.GetNames(typeof(Microsoft.TeamFoundation.WorkItemTracking.Server.MetadataTable))

outputXmlElement is an XmlElement, databaseStamp is a string, and metadataRowSets is an interface IMetadataRowSets found in the Microsoft.TeamFoundation.WorkItemTracking.Proxy namespace. These parameters should hold no value, as they are returned by the Update function call.

.oO(in the next part, more detailed information on the required XML package insertWorkItem...)

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
Microsoft.TeamFoundation.WorkItemTracking.Server.dll
Microsoft.TeamFoundation.WorkItemTracking.Server.Dataaccesslayer.dll
Microsoft.TeamFoundation.WorkItemTracking.Server.DataServices.dll

(from the VSTS SDKs)
C:\Program Files\Visual Studio 2005 SDK\\VisualStudioTeamSystemIntegration\Work Item Tracking
Microsoft.TeamFoundation.WorkItemTracking.Proxy.dll

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:
http://your_vsts_server_name:8080/WorkItemTracking/v1.0/ClientService.asmx

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