Reference guide for link types used in Azure DevOps and Azure Boards
TFS 2017 | TFS 2015 | TFS 2013
You can use different link types to manage the various relationships between work items and other artifacts, like builds, commits, pull requests, and more.
You can link work items to other work items or artifacts using the following link types.
- Work link types: links work items including select test case management work items
- Hyperlink: connects a work item to any URL or network share
- External link types: connects a work item to an external object, such as a code object, build, or storyboard.
A specific field maintains a count of links for each of these link types, such as Related Link Count, Hyperlink Count, and External Link Count.
Link types you use to link work items are subject to certain restrictions based on their topology. Use the guidance provided in the following tables to choose which link type to use based on the types of queries and reports you'll want to create. To learn more about the different topologies, see Link type topologies and restrictions.
Work link types
Work link types are system-defined, process-defined, or user-defined (custom). The links listed in the following table are system defined.
Each work 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. The link type also supports a hierarchical or tree topology, and prevents circular references from being created between work items.
A work item's Related Link Count corresponds to the sum of all links defined with a work link type.
The following table describes the work item link types you can specify to scope a links control using the WorkItemLinksFilter XML element.
Name
Reference name
Usage
Affects-Affected by (CMMI only) 
Microsoft.VSTS.Common.Affects-Forward
Microsoft.VSTS.Common.Affects-Reverse
Topology type: Dependency
Link category: Process-defined
Use this directional link to create links between any set of work items, but not ones that would create closed loops. Typically used to track change requests made to requirements.
Restrictions and recommendations:
You can link a change request to only one requirement using Affects. You can link requirements to as many child change requests as needed using Affected by.
Only use Affects-Affected by links to link work items in the same project. This action is recommended if you plan to use Excel or Project to modify or update work item data.
Child-Parent
System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse
Topology type: Tree
Link category: System-defined
Use this directional link to create one-to-many relationships between a single parent to one or more child items. 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 Taskboard.
Typical uses include:
- Maintain task summary relationships. Parent-child links are created for summary tasks and their subordinate tasks.
- Link tasks to PBIs, user stories, or requirements. Supports Backlog Overview, Stories Overview, and Requirements Overview reports.
Restrictions and recommendations:
- Use Excel to bulk edit both work items and parent-child links. See Bulk add or modify work items with Excel.
- A work item can have only one Parent. A parent work item can have many children.
- Only use parent-child links to link work items in the same project. This action is recommended if you plan to use Excel to modify or update work item data.
Duplicate-Duplicate of 1
System.LinkTypes.Duplicate-Forward
System.LinkTypes.Duplicate-Reverse
Topology type: Tree
Link category: System-defined
Use this directional link to create one-to-many relationships between a single parent to one or more child items. Use to track tasks, bugs, or other work items that are duplicates of one another.
Restrictions and recommendations:
- A work item can have only one Duplicate.
- Only use Duplicate or Duplicate Of links to link work items in the same project. This action is recommended if you plan to use Excel or Project to modify or update work item data.
Referenced By-References
Microsoft.VSTS.TestCase.
SharedParameterReferencedBy
Topology type: Dependency
Link category: Process-defined
Use to link test cases to shared parameters. 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. To learn more, see Repeat a test with different data.
Related
System.LinkTypes.Related
Topology type: Network
Link category: System-defined
Use this non-directional link to create links between any set of work items. 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.
- Relate work items that are at the same level, such as two user stories that define features that overlap one another.
- Link work items that are defined in different projects and managed by different teams.
- Find and view work items and their related work items in a two-tiered view.
- Create simple relationships with few restrictions.
Successor-Predecessor
System.LinkTypes.Dependency
Topology type: Dependency
Link category: System-defined
Choose Predecessor link type when linking to a work item that should be completed before the work item you're linking from. Choose Successor link type when linking to a work item that should be completed after to the work item you're linking from.
Use this directional link to create links between any set of work items, but not ones that would create closed loops. Use to track tasks that must be completed before others can be started. When you plan work using Microsoft Project, linked tasks are represented as predecessor-successor links in Azure Boards. Typically used to track work that must be completed before beginning work on predecessor items.
- 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.
- Supports one-to-many relationships.
- Find and view predecessor work items and their successor work items in a two-tiered, direct links query view.
Restrictions and recommendations:-
- An error appears when you attempt to create links that define circular relationships.
- Create predecessor-successor links only to work items that are within the same project. You can create predecessor-successor links between work items that are defined in different projects. However, if you export a query to Excel or Project, only those work items that are defined for the project for which the query is defined are imported.
Tested by-Tests
Microsoft.VSTS.Common.TestedBy-Forward
Microsoft.VSTS.Common.TestedBy-Reverse
Topology type: Dependency
Link category: Process-defined
Link test cases to work items, such as bugs, user stories, requirements, and product backlog items. 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. For on-premises Azure DevOps, there are several SQL reports that depend on these links. See Review team activities to support useful reports.
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. To learn more, see Share steps between test cases.
Note
- Available from TFS 2017 and later versions.
Hyperlink link type
There's one link type that tracks the number of hyperlinks—Hyperlink Count—added to a work item. A hyperlink can link a work item to any URL.
Link name
Tool supported
Artifact type
Usage
Hyperlink
Work item tracking
Hyperlink
Used to link a work item to a URL. Workitem Hyperlink is the name of this link type in the Artifact Link Types API.
External link types
External link types are system-defined link types that support linking work items to other objects stored within Azure DevOps as shown in the following image. A work item's External Link Count corresponds to the sum of all links defined with an external link type.
Note
You can only use an external link type to link to an Azure DevOps object. To link work items to other objects outside of Azure DevOps, you can use the Hyperlink link type.
The following table describes the external link types you can choose when adding a link type from a work item or test case. Also, you can use specify one of these link types to scope a links control using the ExternalLinksFilter XML element.
Link name
Tool supported
Artifact type
Usage
Branch
Git
Branch
Used to link a work item to a branch.
Pipelines/Build
Build
Build
Used to link a work item to a build.
Changeset (or Fixed in Changeset)
VersionControl
Changeset
Used to link a work item to a changeset.
Commit (or Fixed in Commit)
Git
Commit
Used to link a work item to a commit.
Found in build
Pipelines/Build
Build
Used to link a work item to a build.
Integrated in build
Build
Build pipeline
Used to link a work item to a build.
Integrated in release environment
Release
Release pipeline
Used to link a release to a work item. The system creates a link of this type when a user enables the Report deployment status to Work option for a release definition. To learn how to set this option, see Release pipelines, How do I integrate and report release status?
Pull Request
Git
PullRequestId
Used to link a work item to a pull request.
Result attachment
Test Management
TcmResultAttachment
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 Test or Microsoft Test Manager.
Source Code File<
VersionControl
LatestItemVersion
Used to link a work item to a file under Team Foundation version control (TFVC).
Storyboard
Requirements
Storyboard
Used to link a work item to a PowerPoint file or other file that contains story boarding information on a network.
Tag
Git
Tag
Used to link a work item to a tag that's been defined for a git commit or git repository. For more information, see Work from the Git command prompt for more information.
Test Result
Test Management
TcmResult
Used to link a work item to a test result. These links appear when you associate a work item with a test result from Test or Microsoft Test Manager.
Versioned item
VersionControl
LatestItemVersion
Used to link a work item to a file or changeset defined within a TFVC repository. Source Code File is the name of this link type in the Artifact Link Types API.
Wiki
Wiki
Wiki
Used to link a work item to a wiki page. Supported for TFS 2018.2 and later versions.
Custom link types
You can create custom link types; export and import definitions of link types; and delete, activate, deactivate, and reactivate types of links. See the following articles:
List link types
To get a list of link types, you can use one of the supported command-line tools.
witadmin listlinktypes
You can list link types supported for your project collection using the witadmin listlinktypes command-line tool or the Work Item Relation Types - List REST API command.
Here we list the link types for the fabrikam-sever default collection:
C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin listlinktypes /collection:http://fabrikam-server/DefaultCollection
Reference Name: Microsoft.VSTS.TestCase.SharedParameterReferencedBy
Names: Referenced By, References
Topology: Dependency
Is Active: True
Reference Name: Microsoft.VSTS.Common.TestedBy
Names: Tested By, Tests
Topology: Dependency
Is Active: True
Reference Name: Microsoft.VSTS.TestCase.SharedStepReferencedBy
Names: Test Case, Shared Steps
Topology: Dependency
Is Active: True
Reference Name: System.LinkTypes.Duplicate
Names: Duplicate, Duplicate Of
Topology: Tree
Is Active: True
Reference Name: System.LinkTypes.Dependency
Names: Successor, Predecessor
Topology: Dependency
Is Active: True
Reference Name: System.LinkTypes.Hierarchy
Names: Child, Parent
Topology: Tree
Is Active: True
Reference Name: System.LinkTypes.Related
Name: Related
Topology: Network
Is Active: True
Link type attributes
The following table provides descriptions for each of the link type attributes returned by Azure Boards CLI or the REST API.
Attribute
Description
Names, name
Specifies the friendly name assigned to the link type(s). Directional links are defined in pairs, therefore include a forward and reverse name.
Reference name, referenceName
Specifies the name assigned to the link type or link type pair.
acyclic
Indicates whether the link type allows or (true) or restricts (false) circular relationships. For example, tree type links restrict circular relationships. For more information, see LinkTypes elements reference.
directional
Indicates whether the link type is directional (true) or not (false). Directional link types are defined in pairs with a forward and reverse component. For more information, see LinkTypes elements reference.
editable
Indicates whether the link type is editable (true) or not (false). You can only add and edit custom link types for on-premises deployments using witadmin Manage link type command-line tool. System link types always have editable=false.
Is Active, enabled
Indicates whether the link type is active (true) or not (false). You can only custom link types for on-premises deployments using the witadmin Manage link type command-line tool.
isForward
Indicates whether the link type specifies the forward link (true) or not (False) within a link type pair.
oppositeEndReferenceName
Specifies the reference name of the link type that defines the link in the opposite direction of a link type pair.
remote
Indicates whether the link type supports linking to a remore work item (true) or not (False). Link types with remote=false require that the target work item resides in the same organization or collection as the origin work item.
singleTarget
Indicates whether the link type allows for more than one target (false) or is restricted to a single target (true).
topology
Specifies the topology type—dependency, network, and tree`. For descriptions, see Link type topologies and restrictions.
usage
Specifies the usage type—resourceLink or workItemLink. The workItemLinkvalue indicates a link type that links two work items. TheresourceLink` value indicates a link type used to link a work item to a resource, such as a URL or attachment.
url
Lists the attributes of the link type in json format.