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

Uploading through the Web Service requires sending an xml package through the Client Service that contains all the work item information. The xml package mentioned last post in insertWorkItem has the following format:

<Package Product=http://your_server:8080/WorkItemTracking/v1.0/ClientService.asmx DisableNotifications=”True” xmlns=””>
  <InsertWorkItem ObjectType=”WorkItem” BypassRules=”True”>
    <ComputedColumns>
      <ComputedColumn Column=”System.RevisedDate”>
    </ComputedColumns>
    <Columns>
      <Column Column=”System.WorkItemType”>
        <Value>Bug</Value>
      </Column>
      <Column Column=”System.AreaId”>
        <Value>40</Value>
      </Column>
      <Column Column=”System.CreatedBy” Type=”String"/>
    </Columns>
    <InsertText FieldName=”Microsoft.VSTS.CMMI.Analysis” FieldDisplayName=”Analysis”>text goes here </InsertText>
  </InsertWorkItem>
</Package>

Column values for System.WorkItemType and System.AreaId are absolutely required for web service update. These relate the work item to the database. Team Project is specified through the System.Area field, and not through the System.TeamProject field (not required). All other Column entries require a Type to accompany the field name.

Fields of type HTML or PlainText must be entered into parameters instead of through . Fields of type String have a character limit of 255.

The most valuable (from a migration-perspective) part of this xml package, and really the only reason to use the Web Service method instead of the OM to upload, is the BypassRules attribute. Setting this attribute value to True allows the State/Reason/Transition rules to be bypassed, as well as allowing values such as Created By/Date, Resolved By/Date, Closed By/Date to be programmatically set.

Note: Microsoft could release a new version of their WIT Web Service at any point in time and change the format of the Package document. This (and previous) posts are to provide an outline of the methodology for web service uploading of work items.

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...)

Stuff in the pipe for Team Foundation Server

Brian Harry has a post highlighting what's in the upcoming SP1 for TFS in Stuff in the pipe for Team Foundation Server. My favourite enhancement is excerpted below:

"WIT Custom Control support - This is a cool new feature. It is a mechanism by which people can design work item forms that host custom controls. The data behind the controls can either be persisted in WIT fields or elsewhere. I'm hoping people go crazy with it and build some awesome custom controls."

This was one feature I really, really missed in the RTM version.

Taken for a ride.

Which two well-known Canadian Visual Studio public speakers were taken for a ride last week?

Hint: You can see them at Tech Ed this week, one of them at a book signing.

TFS Licensing

When you buy an MSDN Premium (or formerly Universal) subscription, you get development licenses for a wide range of MS servers. These server licenses are only good for development and testing purposes, not for production use. The idea is that if you are developing a solution using these servers, you don't need to run out and purchase a full blown license for the server. This is a great idea to help keep costs down and promote MS Server based solutions.

The exception to the above is the Team Foundation Server. With the Premium subscription, you get a license to use a limited 5 user version of the server (Note: the limitation is on the number of users, not the functionality of the server) for what I would argue is production use. In other words, you can use the Version Control, Work Items and other features as if you bought the full server (as long as you stay within the 5 user limit). This is significantly different than the licensing for all of the other servers included with the Premium subscription.

So, what do you do if you want a server to develop and test the customisations that you are doing to your full-blown production TFS server? Well, if you have more than 5 developers or you want to test a solution with more than 5 users (including performing load testing), you need to buy a copy of the retail TFS server! That's right, no special development server license is available, you need to either use the 5 user edition or buy a full server license. Granted, the server isn't that expensive and you should already have the client licenses (Team Foundation Explorer), but it really would be nice to have a development licensed server.

Microsoft, are you listening?

Source Control: Where in TFS did my solution go?

I just spend 15 minutes frustrated at my computer because VSTS kept automatically checking my source into the wrong project. All the information on the Net said, “right click on the solution, click Add to Source Control, select the project you want to add it to, and voila, instant version control!” That’s just great, except that I wasn’t being given the option to check my code into a specific project; the source just flew somewhere out of my control. So I figured, hunt down the source files, delete them, try again. When I found out which project my source was being saved in and deleted the files, I found myself present with no source control options for my solution at all. After unbinding the files (see last paragraph), I was able to try to check them into source control again. Same problem occured once more.

It turns out that at some point in time my base directory (lets call it D:/) had managed to become mapped to this other VSTS project. Thus, any and all projects that resided somewhere on my D: drive which needed to be added to source control, would automatically go there. So if you’re trying to add to source control and files are being saved not in the project you expect, check for that condition first.

Under Source Control Explorer, select Workspaces… from the Workspace pulldown menu, then Edit -> Working Folders, select the one that lists the base directory under Local Folder, and hit Remove.

Another useful thing I stumbled across in my quest for the holy grail of source control… the Change Source Control button, home of the Unbind option. To reveal it, go to View -> Toolbars and select the Source Control – Team Foundation option. On the new toolbar that appears, the Change Source Control button is the yellow-gold one that vaguely looks like two cylinders on the left. When you open it up, it lists your active solution and projects, and presents you with the option to Unbind your source if it is currently resident in source control. You still have to manually delete the files that were previously checked into the wrong project though.

-me.