TFS 2010: Overview of Workitems linking – Use and Custom Link Type Creation

Posted by: Subodh Sohoni , on 6/26/2009, in Category VSTS & TFS (Azure DevOps)
Views: 79075
Abstract: Hierarchical workitems is one of the most fascinating concepts introduced with TFS 2010.
TFS 2010: Overview of Workitems linking – Use and Custom Link Type Creation
Hierarchical workitems is one of the most fascinating concepts introduced with TFS 2010. In the earlier versions we could link workitms to other workitmes but those links were at one level, sort of peer to peer. With those links we could not create a tree structure or view dependency of one workitem over other. In one of my earlier articles I delved into creating the links programmatically and set their relation to parent – child - Spawn tasks to implement newly added ‘Requirement’ or ‘User Story’ in Team Foundation Server (TFS) 2010.
In this article we will probe into various dimensions that workitem linking has and will create custom link types to suite our requirement. Parent – child is not the only link types supported by TFS 2010. In fact, TFS 2010 provides a framework for creating link types and usually the process templates will provide the link types. We can use the same framework to create our custom link types. Let us first check that framework out.
First part of the framework is the topologies that can be present with the link structures. Topology of the linking defines their rules and restrictions. A selected topology may force the user to provide a direction or allow circular referencing etc. Following topologies are defined in TFS 2010:
1.    Network: It allows relations that are non-directional and circular referencing is allowed. I will select this topology for defining a link type which will used to create links between peers. For example if I want to link a ‘User Story: A user authenticates using login form’ to another ‘User Story: User views the pages for which access is provided to that user’ to indicate that both of them will be necessary to implement security, I will use Network topology. I will probably name that link as ‘Sibling of’.
2.    Directional Network:  This type of topology allows for circular referencing but it is directional. It forces a direction from source workitem to target worksite. This is better readable than Network topology links. For example we can have a label of ‘References’ on the first user story and ‘Referenced by’ to the second user story. For the other link between the same workitems, the labels will reverse.
3.    Dependency: As the name suggests it indicates a dependency between two workitems. This link is directional and to obvious reason does not support circular referencing. Extending the same example we can say that ‘User Story: User views the pages for which access is provided to that user’ ‘Depend upon’ ‘User Story: A user authenticates using login form’. Unless the user is authenticated the authorization will not happen. Another example is ‘Requirement: User should be shown only the pages for which that user has access permissions’ ‘Depends Upon’ the ‘Task: Create pages for authenticating the user and check authorization’.
4.    Tree: This is the topology which is responsible for the hierarchical view of the structure. The type of link which creates relationship mentioned earlier – Parent – Child uses this topology. It is directional, does not allow circular referencing and puts some additional constraints like ‘a child may not have multiple parents’.
Second part of the framework is the definition of link type. Let us take the case of ‘User Story’ -> ‘Tasks’ which was used in the earlier articles, - Spawn tasks to implement newly added ‘Requirement’ or ‘User Story’ in Team Foundation Server (TFS) 2010 and TFS 2010 - WorkItems Linking and Automation Workflow implementation for Closing Linked Workitems .
The ‘User Story’ is implemented by the ‘Tasks’ and there can be multiple ‘Tasks’ that will be required to implement a ‘User Story’. A natural constraint will be that a ‘Task’ cannot be used to implement multiple ‘User Stories’ obviously because it will create conflicts of priority and estimation. We can see that so far the topology of ‘Dependency’ best suites our condition. We may require sub-tasks to implement the tasks. Tasks and Sub-Tasks may also have the same link and in such case the ‘Tree’ topology will be more appropriate. Although we can choose any one for the example, I am going with ‘Tree’ for this case.
Let us now see which other details we have to provide to create a link type.
We have to provide:
Reference Name: This is very similar to the definition of field in the workitem where we provide a fully qualified name as RefName so that will be used internally. I will give my link type the Reference Name: ‘Subodh.Sohoni.Implementation’.
Forward name: This is the name with which created link will be known as on the source side. I will use ‘Implemented By’ as the ForwardName for this link type.
Reverse Name: This is the name with which created link will be known as on the target side. I will use ‘Implementes’ as the ReverseName for this link type.
The XML that is needed to be created for this link type definition is:
<?xml version="1.0" encoding="utf-8"?>
   <LinkType ReferenceName="Subodh.Sohoni.Implementation" ForwardName="Implemented By" ReverseName="Implements" Topology="Tree" />
Before we move ahead with the case, let us see which other link types are defined by TFS and MSF:
Link types that are defined by the system.
Forward Name
Reverse Name
Link type reference name
Link Types Defined by MSF Process Templates
Forward Name
Reverse Name
Link type reference name
Tested By
Test Case
Shared Steps
Now that our definition of the link type is ready, let us import it in the team project. We should create an XML file which will contain the Link Type Definition. I created a file C:\Users\TFSSETUP\Documents\Visual Studio 10\Templates\ImplementationLinkType.xml and typed in the definition tags in it and saved it. Now we have to import that Link Type Definition in the TFS. We open the Visual Studio 10 command prompt and use the command line utility named WitAdmin.exe to import the Link Type. The command to be given is:
WitAdmin.exe /s http://tfs2010Beta1:8080/tfs /f “C:\Users\TFSSETUP\Documents\Visual Studio 10\Templates\ImplementationLinkType.xml”
We can now test that our link type is imported in TFS. We can create a ‘User Story’ or a ‘Requirement’ depending upon the process template that was selected and open the ‘Other Links’ tab. In the drop down of the link type to create we can seed both the labels are appearing that is ‘Implemented By’ and ‘Implements’. We have no control to avoid ‘Implements’ being shown.
What we can do is spawn workitems as shown in my earlier article, Spawn tasks to implement newly added ‘Requirement’ or ‘User Story’ in Team Foundation Server (TFS) 2010. The code may change now to incorporate the new link type instead of the plain Parent – Child that we had used.
foreach (string task in tasks)
    WorkItem wi = new WorkItem(WITCollection["Task"]);
    wi.Title = eventDoc.DocumentElement.SelectSingleNode("//StringFields/Field[Name='Title']/NewValue").InnerText + task;
    wi.Fields["System.AssignedTo"].Value = eventDoc.DocumentElement.SelectSingleNode("//StringFields/Field[Name='Assigned To']/NewValue").InnerText;
    WorkItemLinkTypeEnd linkTypeEnd = WIStore.WorkItemLinkTypes.LinkTypeEnds["Implemented By"];
    wi.Links.Add(new RelatedLink(linkTypeEnd, Int32.Parse(eventDoc.DocumentElement.SelectSingleNode("//IntegerFields/Field[Name='ID']/NewValue").InnerText)));
For Each task As String In tasks
      Dim wi As New WorkItem(WITCollection("Task"))
      wi.Title = eventDoc.DocumentElement.SelectSingleNode("//StringFields/Field[Name='Title']/NewValue").InnerText & task
      wi.Fields("System.AssignedTo").Value = eventDoc.DocumentElement.SelectSingleNode("//StringFields/Field[Name='Assigned To']/NewValue").InnerText
      Dim linkTypeEnd As WorkItemLinkTypeEnd = WIStore.WorkItemLinkTypes.LinkTypeEnds("Implemented By")
      wi.Links.Add(New RelatedLink(linkTypeEnd, Int32.Parse(eventDoc.DocumentElement.SelectSingleNode("//IntegerFields/Field[Name='ID']/NewValue").InnerText)))
Next task
This will create tasks to implement ‘Requirement’ or ‘User Story’ and create the links of the type Implementation with label ‘Implemented By’ on the side of ‘Requirement’ and ‘Implements’ on the side of tasks.
Summary: In this article we have taken an overview of internals of workitem linking and created a custom link to suite our business requirement.
If you liked the article,  Subscribe to the RSS Feed or Subscribe Via Email
Subodh Sohoni is MCTS - Microsoft Team Foundation Server - Configuration and Development and also is a Microsoft Certified Trainer(MCT) since 2004. Subodh works as VP, Technology with SEED Infotech Ltd

This article has been editorially reviewed by Suprotim Agarwal.

Absolutely Awesome Book on C# and .NET

C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.

We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).

Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.

Click here to Explore the Table of Contents or Download Sample Chapters!

What Others Are Reading!
Was this article worth reading? Share it with fellow developers too. Thanks!
Share on LinkedIn
Share on Google+


Subodh is a Trainer and consultant on Azure DevOps and Scrum. He has an experience of over 33 years in team management, training, consulting, sales, production, software development and deployment. He is an engineer from Pune University and has done his post-graduation from IIT, Madras. He is a Microsoft Most Valuable Professional (MVP) - Developer Technologies (Azure DevOps), Microsoft Certified Trainer (MCT), Microsoft Certified Azure DevOps Engineer Expert, Professional Scrum Developer and Professional Scrum Master (II). He has conducted more than 300 corporate trainings on Microsoft technologies in India, USA, Malaysia, Australia, New Zealand, Singapore, UAE, Philippines and Sri Lanka. He has also completed over 50 consulting assignments - some of which included entire Azure DevOps implementation for the organizations.

He has authored more than 85 tutorials on Azure DevOps, Scrum, TFS and VS ALM which are published on is a regular speaker at Microsoft events including Partner Leadership Conclave.You can connect with him on LinkedIn .

Page copy protected against web site content infringement 	by Copyscape

Feedback - Leave us some adulation, criticism and everything in between!
Comment posted by damian on Wednesday, August 11, 2010 6:32 AM
The command to import link type should be: "witadmin importlinktype /collection:http://server:8080/tfs/MyCollection /f:Links.xml"
Comment posted by Laetitia on Wednesday, April 18, 2012 4:11 AM

I currently have 5000 test cases to trace to around 1200 requirements.
These test cases have already been imported in TFS, as well as the requirements.
Therefore I have 5000 work items types test cases and 1200 work item type requirements.

I currently manage the traceability of test case to requirement in an excel spreadsheet.

I need to find a way to create the links in TFS automatically, and not by using the manual step "link to" and entering the ID of the work item to be linked to.

Is there any way to do that? I tried to use "test case migrator plus", but it did not work at all...

Thanks for your support
Comment posted by Subodh Sohoni on Thursday, April 19, 2012 11:00 AM
Hi Laetitia,
You will need to write a utility (program) for that. It should read from your Excel Worksheet the links and then create same links in TFS. First part of the program should use VSTO to read cells of Excel and the later part should use TFS APIs as I have shown.
If you send a sample of your worksheet then I will be able to provide you the code. My email address is subodh[attherate]ssgsonline[dot]com