Accessing TFS work item tags via the API

With TFS 2012.2 Microsoft have added tags to work items. These provide a great way to add custom information to work items without the need to customise the process template to add custom fields. This is important for users of the hosted http://tfs.visualstudio.com as this does not, at this time, allow any process customisation.

It is easy to add tags to any work item via the TFS web client, just press the Add.. button and either select an existing tag or add a new one. In the following PBI work item example I have added two tags, Tag1 and Tag2.

However, the problem with tags, at present, is that they can only be used as filters within the result of a work item query in the web client, as shown below.

They are not available inside work item queries and are not published to the TFS warehouse/cube for reporting purposes. Hopefully these limitations will be addressed in the future, but not today.

Given all this, I was recently asked by a client if they could use tags to mark PBI work items scheduled for a given release with a view to using this information to produce release notes. Obviously given the current limitations this cannot be done via work item queries or reporting, but you can use the TFS 2012.2 API to do this easily in .NET or Java.

The tags are stored as a ; separated list in a string field property. In C# there is a property in the API to get the tags …

using System;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.WorkItemTracking.Client;
using System.Linq;

namespace BlackMarble
{
    public class TFSDemo
    {
        public static string[] GetTagsForWorkItem(Uri tfsUri, int workItemId)
        {
            // get a reference to the team project collection
            using (var projectCollection = TfsTeamProjectCollectionFactory.GetTeamProjectCollection(tfsUri))
            {
                // get a reference to the work item tracking service
                var workItemStore = projectCollection.GetService();

                // and get the work item
                var wi = workItemStore.GetWorkItem(workItemId);
                return wi.Tags.Split(’;’);
            }
        }
    }
}

but in Java you have to get the field yourself …

import java.net.URI;
import java.net.URISyntaxException;

import com.microsoft.tfs.core.TFSTeamProjectCollection;
import com.microsoft.tfs.core.clients.workitem.WorkItem;
import com.microsoft.tfs.core.clients.workitem.WorkItemClient;
import com.microsoft.tfs.core.httpclient.Credentials;
import com.microsoft.tfs.core.httpclient.DefaultNTCredentials;

public class TFSDemo {
    
      public static String[] GetTagsForWorkItem(URI tfsUri, int workItemId) 
      {
          // get a reference to the team project collection
          Credentials credentials = new DefaultNTCredentials();
         
          TFSTeamProjectCollection projectCollection = new TFSTeamProjectCollection(tfsUri, credentials);
         
          // get a reference to the work item tracking service
          WorkItemClient wic = projectCollection.getWorkItemClient();
         
          // get the work item and return the tags
          WorkItem wi = wic.getWorkItemByID(workItemId);
         
          // there is no method for the tags, but can pull it out of the fields
          return wi.getFields().getField(“Tags”).getValue().toString().split(";");
      }

}
        

Given these methods it is possible to write a tool that can select matching work items. Thus allowing you generate any output you require.

Update 14 May 2013

Just had confirmed that at present there is no API to write tags, I had not tried, I only need a read only solution. Keep an eye open for future releases of the SDKs to get a write call method.