LinkTypes elements reference

Last Update: 3/7/2017

Team Services | TFS 2017 | TFS 2015 | TFS 2013

IMPORTANT

This topic provides a reference of link types defined for Team Services and TFS. For the On-premises XML process model, you can add custom link types. Custom link types are not supported for Hosted XML or Inheritance process models.

For an overview of process models and supported cusomizations, see Customize your work tracking experience.

You use different link types to form link relationships between different work item types (WITs). There are three categories of link types: system-defined, process-defined, and user-defined or custom. The link types defined in the default processes support link relationships among the test management WITs.

Each link type defines 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.

You can customize an existing link type or create a link type to meet your project tracking requirements. Before you start to add or modify a link type, you should assess the link types available and how they are used in your team project. See Manage dependencies, link work items. Links are added through the work item form, which contains the links control. See Link controls, restrictions, and fields.

NOTE

You cannot customize the system-defined link types that correspond to the Related, Parent-Child, and Successor-Predecessor links.

You may want to modify or create a link type for one of the following reasons:

  • Change the link labels that are used to match your team's naming conventions.
  • Add a link type to track a particular relationship that is unique to your team's process.

The link type is specified in a type definition XML file that you import to a team project collection. To customize or create a link type, use witadmin importlinktype to import the link type definition file to the project collection that hosts your team project. With the witadmin command-line tool, you can deactivate, delete, export, import, list, and reactivate link types. See Manage link types.

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:

Attribute Description
ReferenceName     Name of the link type. This name is used internally when you create a link between two work items.
ForwardName Name of the link at the source work item. This name appears when you add links to the source work item.
ReverseName Name of the link at the target work item. This name appears when a listing of the links at the target work item appears.
TopologyType Specifies the DirectedNetwork, Network, Tree, or Dependency topology. The first three topologies are directional, and you use them to define subordinate or sequential relationships. You use Network to define relationships between peers or where no implied subordination exists.

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

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.

Link types come in two flavors. Work item link types support creating relationships among work items. External link types support connecting a work item to an external object, such as a code object, build, or hyperlink. You can't create a custom link type that links to an external (non-work item) object.

Work item link types are system-defined, process-defined, or user-defined (custom). Most links are system defined. Each link type defines 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.

Work item link types, conceptual mapping

The following table lists the work item link types you can specify within the WorkItemLinksFilter element.

Link type Reference name Description
Affects
Affected By

Microsoft.VSTS.Common.Affects.Forward
Microsoft.VSTS.Common.Affects.Reverse

Topology type: Dependency
Link category: Process-defined

Use to track change requests to requirements. (CMMI process)
Duplicate
Duplicate Of 1

System.LinkTypes.Duplicate-Forward
System.LinkTypes.Duplicate-Reverse

Topology type: Tree
Link category: System-defined

Used to link duplicate work items.
Parent
Child

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse

Topology type: Tree
Link category: System-defined

Use to organize work item within a hierarchy. You can quickly create this hierarchy among backlog items using the mapping function or among backlog items and tasks using the sprint backlog or task board.
References
Referenced By

Microsoft.VSTS.TestCase.SharedParameterReferencedBy

Topology type: Dependency
Link category: Process-defined

Use to link Test Cases to Shared Parameters to support the ability to repeat a test with different data. In general, you wouldn't add this link type to a scoped links control.
Related

System.LinkTypes.Related

Topology type: Network
Link category: System-defined

Use to link work items that are at the same level, such as two user stories that define features that overlap one another. The Related link type creates simple relationships with few restrictions.
Successor
Predecessor

System.LinkTypes.Dependency

Topology type: Dependency
Link category: System-defined

Use to track tasks that must be completed before others can be started. When you plan work using Project, linked tasks are represented as predecessor-successor links in TFS.
Tested By
Tests

Microsoft.VSTS.Common.TestedBy-Forward
Microsoft.VSTS.Common.TestedBy-Reverse

Topology type: Dependency
Link category: Process-defined

Use to track test cases that test user stories (Agile), product backlog items (Scrum), or requirements (CMMI). Can also link to other work item types such as bugs, issues, or tasks.
Test Case
Shared Steps

Microsoft.VSTS.TestCase.SharedStepReferencedBy

Topology type: Dependency
Link category: Process-defined

Use to link test cases with shared steps. You share steps between test cases to avoid having to create multiple entries of the same sequence of steps.

Notes:

  1. Available only from Team Services and TFS 2017 and later versions.

What link type is used to link test cases to test suites and test suites to test plans?

Test related link types link test case management work items to one another, or to other work items. From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. However, these objects aren't linked to each other through link types.

Test-related link types, conceptual mapping

External link types are all system-defined and support linking work items to other objects as shown in the following image.

External link types, conceptual mapping

The following table describes the external link types you can specify to scope a links control using the ExternalLinksFilter element.

External link type Description
Branch Used to link a work item to a build.
Build Used to link a work item to a branch.
Fixed in Changeset Used to link a work item to a changeset.
Fixed in Commit Used to link a work item to a commit.
Hyperlink Used to link a work item to a URL.
Pull Request Used to link a work item to a pull request.
Model Link (Not supported within the web portal) Used to link a work item to a diagram—such as an Activity, Component, Layer, Use Case, or other diagram—stored within the system. You can link diagrams to work items only from the Visual Studio client. For details, see Link model element to work items.
Result attachment Used to link a work item to an attachment associated with a test result. These links appear when you associate a work item with a test result from the Test hub or Microsoft Test Manager.
Storyboard Used to link a work item to a file on a network. See Storyboard your ideas using PowerPoint for details.
Tag Used to link a work item to a tag that's been defined for a git commit or git repository. See Work from the Git command prompt for more information.
Test Result Used to link a work item to a test result. These links appear when you associate a work item with a test result from the Test hub or Microsoft Test Manager.
Versioned item Used to link a work item to a file or changeset defined within a TFVC repository.

The topology types described in the following table determine the restrictions placed on the usage of each link type.

Topology type Illustration

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.

Example usage: Use a dependency link to record the features that must be completed to deliver a user requirement. You can't create a dependent link between two work items that are linked to the same work items via dependent links.

Dependency topology

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.

Directed network topology

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.

Network topology

Tree: You can use tree links to create 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. With Parent/Child links, you can't 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 user story or backlog item. Or, map backlog items to features, and features to epics.

Tree topology

NOTE

Feature availability: Creating a custom link type is only supported for the On-premises XML process model. You can't add custom link types when you use the Hosted XML process model.

To create a custom link type, define the link type XML definition file according to the syntax provided earlier in this topic, and then import it using witadmin importlinktype. Each process-defined link type is associated with an XML definition file. These files are defined in the WorkItem Tracking\LinkTypes folder of the process set of files and folders.

For example, the following syntax defines the Microsoft.VSTS.Common.TestedBy link type provided via 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 or update a team project, the link type definitions defined for the reference process are imported into the project collection.

In addition to defining link types, you can customize the work item type definition to accept or prohibit specific links based on link type. You use the LinksControlOptions element to define the options that control what links can be added to a work item and to which work item types. Also, you can specify the default columns that you want to appear for the list of links in a work item. For more information, see Define link controls to restrict link relationships.

Using the web portal or Test Manager, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. However, these objects aren't linked to each other through link types.