2011 December » ALM Adventures

TF201001: Cannot change topology for a link type

Dec 302011

TF201001 is an error you can get when working with custom link types, and is time-consuming and disruptive to resolve, so merits discussion.

First, some background… before TFS 2010 you could link work items together, but couldn’t specify what their relationship was. In TFS 2010 you can do that, because there are different link types to choose from including parent/child, successor/predecessor and related. As you may guess from the names, each of these link types has rules that define how they can be used, called a topology. For example:

Parent/child uses a tree topology – meaning that relationships must be one-to-many and cannot be circular. So a child can only have one parent (only in the field of computing could that statement pass without bemusement).
Successor/predecessor uses a dependency topology – meaning that relationships are many-to-many but cannot be circular, and the direction determines what name is given to the link.
Related uses a network topology – meaning that anything goes, including circular relationships, and the link has the same name regardless of direction. It indicates that work items have something in common without saying exactly what that is.

You can use the link types that come with TFS 2010 to define richer relationships between work items, but you can also create new custom link types.

You define a custom link type in an XML file like so:


<?xml version="1.0" encoding="utf-8"?>
<LinkTypes>
 <LinkType ReferenceName="MyCo.LinkTypes.Releases" ForwardName="Releases" ReverseName="Released By" Topology="Tree" />
</LinkTypes>

And upload it into TFS using witadmin:


witadmin importlinktype /collection:http://myserver:8080/tfs/DefaultCollection /f:"LinkType_Releases.xml"

This particular link type was created so TFS could be used to track complex configuration changes, linked together under a new Release work item type. The thinking at its creation was that one work item could only be linked to one Release, so the Tree topology was the right choice. It later turned out that under some circumstances one work item could be included in multiple Releases – which is prohibited by the one-to-many rule of the Tree topology.

So the logical decision is to modify the custom link type to the Dependency topology, which (sadly) results in:

TF212018: Work item tracking schema validation error: TF201001: Cannot change topology for a link type MyCo.LinkTypes.Releases, it has already been defined.

Ouch! Even though I want a less restrictive topology, TFS prohibits the change. There is no simple way to get around this – getting the change in place requires a tedious workaround such as:

Rename the existing link type
Create a new corrected link type
Change all of the work items using the old link type to the new link type
Delete the old link type

I can understand that changing a link type to a more restrictive topology could invalidate existing links, so it makes sense to prohibit that change, but why not allow a change to a less restrictive topology – which cannot possibly cause that problem?

I’m guessing that Microsoft either didn’t think of this scenario, or thought it too rare to accommodate. Either way, the lesson is that custom link type topologies should be chosen with great care and, if in doubt, choose the one that is less restrictive!

Process Template Customisation – Look Before You Leap

No Responses »

Dec 112011

There are circumstances when you might want to make changes to the TFS process template, such as creating a new work item type (WIT). Technically, process template changes are often straightforward. However the main considerations to be wary of are not technical, they are about process and project management – so don’t make changes just because you can!

Before leaping in, ask yourself the following:

Are we using the right process template?

Using a different process template could give you what you need in a simple and well-proven package. This requires you to create a new Team Project, because you can’t change the process template for an existing team project. (Although you could get away with it if you haven’t used Work Items yet, by importing Work Item Type Definitions etc.)

For example, the CMMI template comes with Risk and Review WITs, along with detailed guidance on how to use them for risk management and code reviews respectively. By the way (and contrary to popular belief) the CMMI process template does not preclude you from using Agile methodologies, you can absolutely do Agile (and Scrum) with the CMMI template – we do. (Although it does lack some resources available from the Agile and Scrum templates such as iteration planning workbooks). Work item fields belong to the Project Collection, not Team Projects, so whichever template you adopt you can easily add fields you like from other templates.

Do you understand your process template?

There is very detailed MSDN guidance on each template here:

It may be some time since you last read the guidance, or you may have skipped it completely, so take time and understand how the templates are intended to be used. This may sound like preaching, when you just want to make a change, but it’s not unusual for a team to make an (apparently) must-have modification only to realise later that their needs were already met – they just hadn’t realised it. You could even end up reversing you change once you understand the template properly – a situation I have seen several times.

Is it you who needs to change?

The TFS work items system defines and tracks the day-to-day software development process for your team, so it’s crucial to use it well. Any team could adopt TFS and carry on working exactly the way they did before – using, abusing or ignoring the system as required to get their work done the old way they are used to.

It’s easy to think along lines like “TFS needs to change to fit the way we work” but make sure you don’t miss out on process improvements by changing the way you work instead. Question why you work the way you do and don’t accept that it’s right without some detached evaluation first. Some working practices are laid down diligently to meet the needs and technology available at that point in time, while others spring up in reaction to particular problems, or develop organically. Requirements, technology and the work you do can change quickly, and the process that was right even just a couple of years ago may not be right now. Don’t be afraid to adapt yourself rather than your technology – the default template may define a better process than the one you have now.

Does the naming fit?

Language is far from precise, and trying to distil complex concepts into one or two words is extremely difficult. For example, the CMMI state workflow of Proposed/Active/Resolved/Closed is simple, but can be a huge source of confusion – does Active mean someone is working on it or that just that the work is ready to be worked on? Does Resolved mean the work has been completely finished (a valid interpretation by the dictionary definition) or just that it has been implemented and we need to verify it?

Likewise, words such as “issue” can be vastly overused and the Issue work item type could mean almost anything, rather than the blocker or impediment it is intended to be.

Before making wholesale changes, consider if a simple renaming could meet your needs. You can rename almost anything in TFS process templates – fields, work item types, layout labels, states, transitions etc.

But if it does need to change…

Then absolutely change it!

The message here isn’t “never change the process template”, it’s “understand it, then make changes in the right place”. There are many valid reasons to change the process template, and you should never be held back by a template that isn’t working for you.