Working with Link Types

You use a link type to define the link labels, topology type, and restrictions that are used when links between work items are constructed. For example, the parent-child link type defines two labels (Parent and Child), supports a hierarchical or tree topology, and prevents circular references from being created between work items.

To customize or create a link type, you import an XML file to the team project collection that contains the definition for the link type. Link types are added to the set of link types that are defined for the collection. Existing link types are overwritten with the new information based on the reference name that you specify.

Topic Contents

• Syntax Structure

• Requirements for Link Types

• System Defined Link Types

• Link Types Defined by MSF Process Templates

• Link Restrictions and Topologies

• Link Type Schema Definition

Syntax Structure

You can define additional link types by adding them to the link types that are defined for a team project collection. You can define valid link types for use in your process based on the structure that the link type definition schema provides. A link type is defined by the following XML syntax in the link types XML file:

<LinkTypes>
   <LinkType ReferenceName="LinkTypeName" ForwardName="ForwardName" ReverseName="ReverseName" Topology="TopologyType" />
</LinkTypes>

The descriptions in the following table apply to the previous syntax:

Link directionality is determined by the assignments made to the ForwardName and ReverseName attributes. If you create a custom link and assign the same name to the forward and reverse names, you should set the link type to Network because it is the only non-directional topology.

Requirements for Link Types

LINKTYPES is a set of LINKTYPE elements that are stored and used by a team project collection.

Each link type has a reference name and two optional friendly names, or name labels, which must be unique within the project collection. Each link type name must meet the following requirements:

• Names can have up to 254 Unicode characters.

• Names must not be empty.

• Names cannot have leading or trailing white spaces.

• Names cannot contain backslash (\) characters.

• Names cannot contain two consecutive white spaces.

System Defined Link Types

The following table summarizes the link types that are defined by the system. These link types should not be overwritten or modified in any way.

Link Types Defined by MSF Process Templates

The following table lists the link types that are created when you create a team project by using a Microsoft Solutions Framework (MSF) process template. These link types are specifically designed to support interaction with tracking work items in Team Foundation and Microsoft Test Manager.

Each of the link types listed earlier in this topic are added to the team project collection when you use an MSF process template to create a team project. Link type definition files are defined in the WorkItem Tracking\LinkTypes folder of the Template.zip file. The following definition for the Microsoft.VSTS.Common.TestedBy link type is defined in the TestedBy.xml file:

<?xml version="1.0" encoding="utf-8"?>
<LinkTypes>
   <LinkType ReferenceName="Microsoft.VSTS.Common.TestedBy" ForwardName="Tested By" ReverseName="Tests" Topology="Dependency" />
</LinkTypes>

When you create the team project by using the corresponding process template, the link type definition is imported into the project collection.

Link Restrictions and Topologies

The topology that is assigned to a link type determines the restrictions that are added for its usage. In the following table, you can view the different topology types:

Topology type	Illustration
Network: You can use network links to create basic relationships between work items that are non-restrictive. The link is the same at both end points. Circular relationships are allowed. Example usage: Use a network link, such as Related, to record a relationship between two features that might share dependencies.
Directed Network: You can use directed network links to create relationships between work items that indicate directionality. The link name is different at the end points. Circular relationships are allowed. Example usage: Use a directed network link to record a relationship between two features that might share dependencies and which you want to distinguish from each other in some way.
Dependency: You can use dependency links to create relationships between work items that have directionality and to restrict circular relationships. The link name is different at the end points. In the illustration, you cannot create a dependent link to a work item that contains dependent link relationships to the same work items. Example usage: Use a dependency link to record the features that must be completed to deliver a user requirement.
Tree: You can use tree links to create multi-level hierarchical relationships among work items. Tree links support multi-level hierarchical views, have directionality, and restrict circular relationships. The link name is different at the end points. Tree links are the only type of link that is supported by the Tree of Work Items query. In the illustration, you cannot assign two parents to a child. Example usage: Use a tree link to record tasks and subtasks from your team that must be completed to deliver a feature.

Link Types Schema Definition

The following code lists the schema definition for link types:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema 
  id="WorkItemLinkTypeDefinition" 
  elementFormDefault="unqualified" 
  attributeFormDefault="unqualified" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  targetNamespace="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/WorkItemLinkTypeDefinition.xsd" 
  xmlns="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/WorkItemLinkTypeDefinition.xsd" 
  xmlns:mstns="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/WorkItemLinkTypeDefinition.xsd" 
  xmlns:typelib="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/typelib"
  version="1.0">
   <xs:import namespace="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/typelib"/>
  <xs:simpleType name="TopologyTypes">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Network" />
      <xs:enumeration value="DirectedNetwork" />
      <xs:enumeration value="Dependency" />
      <xs:enumeration value="Tree" />
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="LinkTypeType">
    <xs:attribute name="ReferenceName" type="typelib:ReferenceName" use="required" />
    <xs:attribute name="Topology" type="TopologyTypes" use="optional" />
    <xs:attribute name="ForwardName" type="typelib:FriendlyName" use="optional" />
    <xs:attribute name="ReverseName" type="typelib:FriendlyName" use="optional" />
  </xs:complexType>
  <xs:complexType name="LinkTypesType">
    <xs:sequence>
       <xs:element name="LinkType" type="LinkTypeType" minOccurs="1" maxOccurs="unbounded" />
      </xs:sequence>
      </xs:complexType>
   <xs:element name="LinkTypes" type="LinkTypesType" />
</xs:schema>

See Also

Concepts

What's New in Tracking Work Items

Choosing Link Types to Effectively Track Your Project

Determining the Scope of Your Customization Requirements

Customizing Project Tracking Data, Forms, Workflow, and Other Objects

Other Resources

Creating Relationships Between Work Items and Other Resources

Grouping Work Item Types into Categories