Reference guide for link types
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
You can use different link types to manage the various relationships between work items and other artifacts, like builds, commits, pull requests, and more. In this article, we describe the following link types.
- Work link type: Links work items including select test case management work items
- Hyperlink: Connects a work item to any URL or network share
- External link type: Connects a work item to an external object, such as a code object, build, or wiki page
- Remote work link type: Connects work items that are defined in different organizations
- GitHub link type: Connects a work item to a GitHub repository commit, issue, or pull request.
A specific field maintains a count of links for the first four link types, such as Related Link Count, Hyperlink Count, External Link Count, and Remote Link Count.
- Work link type: links work items including select test case management work items
- Hyperlink: connects a work item to any URL or network share
- External link type: connects a work item to an external object, such as a code object, build, or wiki page
- GitHub link type: connects a work item to a GitHub repository commit or pull request.
A specific field maintains a count of links for the first three link types, such as Related Link Count, Hyperlink Count, and External Link Count.
Link types 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 want to create. To learn more about the different topologies, see Link type topologies and restrictions.
Work link type
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. We recommend this action if you plan to use Excel 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
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 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.
Related
System.LinkTypes.Related
Topology type: Network
Link category: System-defined
Use this nondirectional 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. Linked tasks are represented as predecessor-successor links in Azure Boards.
- Track tasks that must be completed before others can be started.
- 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. But, if you export a query to Excel, only those work items defined for the project for which the query is defined get 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. Share steps between test cases to avoid having to create multiple entries of the same sequence of steps.
Hyperlink
A hyperlink can link a work item to any URL. The Hyperlink Count tracks the number of hyperlinks to a work item.
Link name
Tool supported
Artifact type
Usage
Hyperlink
Work item tracking
Hyperlink
Used to link a work item to a URL. Work item Hyperlink is the name of this link type in the Artifact Link Types API.
External link type
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, use a hyperlink.
The following table describes the external link types you can choose when you add a link type from a work item or test case.
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 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.
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 defined for a git commit or git repository. For more information, see Work from the Git command prompt.
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.
GitHub link type
GitHub link types are system-defined and support linking work items to GitHub objects as shown in the following image.
Important
You can only link to GitHub artifacts with repositories connected to Azure Boards.
The following table describes the GitHub link types you can choose when adding a link type from a work item.
Link name
Artifact type
Usage
GitHub Commit
GitHub repository commit
Used to link a work item to a GitHub commit.
GitHub Issue
GitHub repository issue
Used to link a work item to a GitHub issue.
GitHub Pull Request
GitHub repository pull request
Used to link a work item to a GitHub pull request.
Remote work link type
Remote work link types are system-defined link types that support linking work items defined in different organizations, as long as the same Microsoft Entra ID manages them as described in Connect your organization to Microsoft Entra ID.
A work item's Remote Link Count corresponds to the sum of all links defined with a remote work link type.
Name
Reference name
Usage
Consumes From-Produced For
(Dependency topology)
System.LinkTypes.Remote.Dependency-Forward
System.LinkTypes.Remote.Dependency-Reverse
Topology type: Dependency
Link category: System-defined
Use this directional link to create links between work items that have dependencies and are defined in different organizations, as long as the same Microsoft Entra ID manages them. Typically used to track change requests made to requirements.
Remote Related
System.LinkTypes.Remote.Related
Topology type: Network
Link category: System-defined
Use this nondirectional link to create links between work items defined in different organizations, as long as the same Microsoft Entra ID manage them.
Custom link type
You can create a custom link type; 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.
az boards work-item relation list-type
You can list link types supported by your organization with the az boards work-item relation list-type command or the Work Item Relation Types - List REST API command. To get started, see Get started with Azure DevOps CLI.
az boards work-item relation list-type [--org]
Optional parameters
- org: Azure DevOps organization URL. You can configure the default organization using
az devops configure -d organization=ORG_URL
. Required if not configured as default or picked up usinggit config
. Example:--org https://dev.azure.com/MyOrganizationName/
.
Example
The following command lists the work item link types in table format that are defined for the fabrikam organization.
az boards work-item relation list-type --org fabrikam --output table
Name ReferenceName Enabled Usage
-------------------- ----------------------------------------------------------- --------- ------------
Produces For System.LinkTypes.Remote.Dependency-Forward True workItemLink
Consumes From System.LinkTypes.Remote.Dependency-Reverse True workItemLink
Duplicate System.LinkTypes.Duplicate-Forward True workItemLink
Duplicate Of System.LinkTypes.Duplicate-Reverse True workItemLink
Referenced By Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Forward True workItemLink
References Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Reverse True workItemLink
Tested By Microsoft.VSTS.Common.TestedBy-Forward True workItemLink
Tests Microsoft.VSTS.Common.TestedBy-Reverse True workItemLink
Test Case Microsoft.VSTS.TestCase.SharedStepReferencedBy-Forward True workItemLink
Shared Steps Microsoft.VSTS.TestCase.SharedStepReferencedBy-Reverse True workItemLink
Successor System.LinkTypes.Dependency-Forward True workItemLink
Predecessor System.LinkTypes.Dependency-Reverse True workItemLink
Child System.LinkTypes.Hierarchy-Forward True workItemLink
Parent System.LinkTypes.Hierarchy-Reverse True workItemLink
Related System.LinkTypes.Related True workItemLink
Remote Related System.LinkTypes.Remote.Related True workItemLink
Attached File AttachedFile True resourceLink
Hyperlink Hyperlink True resourceLink
Artifact Link ArtifactLink True resourceLink
The default json format provides additional information about the attributes defined for the link types. For example, the information for the link types Produces For and Consumes From are listed as follows.
{
"attributes": {
"acyclic": true,
"directional": true,
"editable": false,
"enabled": true,
"isForward": true,
"oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Reverse",
"remote": true,
"singleTarget": true,
"topology": "dependency",
"usage": "workItemLink"
},
"name": "Produces For",
"referenceName": "System.LinkTypes.Remote.Dependency-Forward",
"url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Forward"
},
{
"attributes": {
"acyclic": true,
"directional": true,
"editable": false,
"enabled": true,
"isForward": false,
"oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Forward",
"remote": true,
"singleTarget": true,
"topology": "dependency",
"usage": "workItemLink"
},
"name": "Consumes From",
"referenceName": "System.LinkTypes.Remote.Dependency-Reverse",
"url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Reverse"
},
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 get 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 use 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 remote 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. The
resourceLink` 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.