Reference guide for link types used in Azure DevOps and Azure Boards

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

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 wiki page
• Remote work link types: connects work items that are defined in different organizations
• GitHub link types: 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.

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.

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

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.

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.

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.

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 types

GitHub link types are system-defined link types. They support linking work items to GitHub objects as shown in the following image.

Important

You can only link to GitHub artifacts whose repositories you have connected to Azure Boards. To create that connection, see Connect Azure Boards to GitHub. To learn more about linking to GitHub artifacts, see Link GitHub commits, pull requests, and issues to work items.

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 types

Remote work link types are system-defined link types that support linking work items defined in different organizations. Organizations must be managed by the same Azure Active Directory as described in Connect your organization to Azure Active Directory.

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. Organizations must be managed by the same Azure Active Directory. Typically used to track change requests made to requirements.

Remote Related

System.LinkTypes.Remote.Related
Topology type: Network
Link category: System-defined

Use this non-directional link to create links between work items defined in different organizations. Organizations must be managed by the same Azure Active Directory.

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 using git 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. For other formats, see Output formats for Azure CLI commands.

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 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.

Related articles

• Link work items to track dependencies
• Add link to multiple work items
• Query FAQs
• Track dependencies using Delivery Plans
• Use mapping to link backlog items to features and epics
• Bulk modify links using Excel
• Link type topologies and restrictions
• Artifact Link Types API