Edit

Share via

Reference guide for link types

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Use different link types to manage relationships between work items and other artifacts, such as builds, commits, and pull requests. This article describes 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 have topological restrictions. Use the guidance in the following tables to choose a link type based on the queries and reports you plan to create. To learn more about topologies, see Link type topologies and restrictions.

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 labels, topology, and restrictions used when you construct links between work items. For example, the parent-child link type defines two labels: Parent and Child. The link type uses a tree topology and prevents circular references between work items.

Screenshot that shows a conceptual diagram of a work item link type.

A work item's Related Link Count equals 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) Screenshot that shows a conceptual diagram of the Affects link type. Screenshot that shows a conceptual diagram of the Affected by link type.

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 work items without creating closed loops. People typically use it to track change requests linked to requirements.

Restrictions and recommendations:

  • Link a change request to only one requirement using Affects. 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 when you plan to use Excel to modify or update work item data.

Child-Parent
Screenshot that shows a conceptual diagram of the Child link type.
Screenshot that shows a conceptual diagram of the Parent link type.

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 and one or more child items. Use it to organize work items within a hierarchy. You can 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 represent 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. We recommend this when you plan to use Excel to modify or update work item data.

Duplicate-Duplicate of Screenshot that shows a conceptual diagram of the Duplicate link type. Screenshot that shows a conceptual diagram of the Duplicate Of link type.

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 to track tasks, bugs, or other work items that duplicate 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. We recommend this when you plan to use Excel to modify or update work item data.

Referenced By-References
Screenshot that shows a conceptual diagram of the Referenced By link type. Screenshot that shows a conceptual diagram of the References link type.

Microsoft.VSTS.TestCase.
SharedParameterReferencedBy
Topology type: Dependency
Link category: Process-defined

Use this to link test cases to shared parameters and to support repeating a test with different data. Generally, you don't add this link type to a scoped links control.

Related
Screenshot that shows a conceptual diagram of the Related link type.

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

Use this nondirectional link to create relationships between work items. Use it to link work items at the same level (for example, two user stories that overlap). The Related link type creates simple relationships with few restrictions.

  • Relate work items that are at the same level.
  • Link work items 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
Screenshot that shows a conceptual diagram of the Successor dependency. Screenshot that shows a conceptual diagram of the Predecessor dependency.

System.LinkTypes.Dependency
Topology type: Dependency
Link category: System-defined
Choose Predecessor when linking to a work item that should complete before the current item. Choose Successor when linking to a work item that should complete after the current item.

Use this directional link to track tasks that must finish before others start. Linked tasks appear as predecessor-successor links in Azure Boards.

  • Track tasks that must be completed before others can begin.
  • Support one-to-many relationships.
  • Find predecessor and successor work items in a two-tiered direct-links query view.

Restrictions and recommendations:

  • An error appears when you attempt to create circular relationships.
  • Create predecessor-successor links only for work items within the same project when you plan to export to Excel. You can create predecessor-successor links across projects, but Excel export/import will only include items for the project that defines the query.

Tested by-Tests
Screenshot that shows a conceptual diagram of the Tested by link type. Screenshot that shows a conceptual diagram of the Tests link type.

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 PBIs. Use this to track test cases that validate user stories (Agile), PBIs (Scrum), or requirements (CMMI). For on-premises Azure DevOps, several SQL reports depend on these links. See Review team activities to support useful reports.

Test Case-Shared Steps
Screenshot that shows a conceptual diagram of Test Case to Shared Steps link. Screenshot that shows a conceptual diagram of Shared Steps to Test Case link.

Microsoft.VSTS.TestCase.
SharedStepReferencedBy
Topology type: Dependency
Link category: Process-defined

Use this to link test cases with shared steps. Share steps between test cases to avoid duplicating the same sequence of steps.

A hyperlink links a work item to any URL. The Hyperlink Count tracks the number of hyperlinks on a work item.

Screenshot that shows a conceptual diagram of a Hyperlink.

Link name

Tool supported

Artifact type

Usage

Hyperlink

Work item tracking

Hyperlink

Use this 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 types are system-defined and link work items to other objects stored within Azure DevOps. A work item's External Link Count equals the sum of all links defined with external link types.

Screenshot that shows a conceptual diagram of external link types.

Note

Use an external link type only to link to an Azure DevOps object. To link work items to objects outside Azure DevOps, use a hyperlink.

The following table describes the external link types you can choose when you add a link from a work item or test case.

The following table describes the external link types you can choose when adding a link from a work item or test case. You can also specify one of these link types to scope a links control using the ExternalLinksFilter XML element.

Link name

Tool supported

Artifact type

Usage

Security Alert

Advanced Security

Advanced Security

Used to link a work item to an Advanced Security alert.

Branch

Git

Branch

Use to link a work item to a branch.

Pipelines/Build

Build

Build

Use to link a work item to a build.

Changeset (or Fixed in Changeset)

VersionControl

Changeset

Use to link a work item to a changeset.

Commit (or Fixed in Commit)

Git

Commit

Use to link a work item to a commit.

Found in build

Pipelines/Build

Build

Use to link a work item to a build.

Integrated in build

Build

Build pipeline

Use to link a work item to a build.

Integrated in release environment

Release

Release pipeline

Use to link a release to a work item. The system creates this type when a user enables Report deployment status to Work for a release definition.

Pull Request

Git

PullRequestId

Use to link a work item to a pull request.

Result attachment

Test Management

TcmResultAttachment

Use 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

Use to link a work item to a file under Team Foundation version control (TFVC).

Storyboard

Requirements

Storyboard

Use to link a work item to a PowerPoint file or other file that contains storyboarding information on a network.

Tag

Git

Tag

Use to link a work item to a tag defined for a git commit or repository. For more, see Work from the Git command prompt.

Test Result

Test Management

TcmResult

Use 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

Use 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

Use to link a work item to a wiki page. Supported for TFS 2018.2 and later versions.

GitHub link types are system-defined and link work items to GitHub objects as shown here.

Screenshot that shows a conceptual diagram of GitHub link types.

Important

You can only link to GitHub artifacts for repositories connected to Azure Boards.

The following table describes the GitHub link types you can choose when adding a link from a work item.

Link name

Artifact type

Usage

GitHub Commit

GitHub repository commit

Use to link a work item to a GitHub commit.

GitHub Issue

GitHub repository issue

Use to link a work item to a GitHub issue.

GitHub Pull Request

GitHub repository pull request

Use to link a work item to a GitHub pull request.

Remote work link types support linking work items defined in different organizations, as long as the same Microsoft Entra ID manages those organizations (see Connect your organization to Microsoft Entra ID).

A work item's Remote Link Count equals the sum of all links defined with a remote work link type.

Name

Reference name

Usage

Consumes From-Produced For
(Dependency topology) Screenshot that shows a conceptual diagram of Consumes From topology. Screenshot that shows a conceptual diagram of Produced For topology.

System.LinkTypes.Remote.Dependency-Forward
System.LinkTypes.Remote.Dependency-Reverse
Topology type: Dependency
Link category: System-defined

Use this directional link to create dependencies between work items defined in different organizations, as long as the same Microsoft Entra ID manages them. People typically use this to track change requests linked to requirements across org boundaries.

Remote Related
Screenshot that shows a conceptual diagram of Remote Related topology.

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

Use this nondirectional link to relate work items defined in different organizations, as long as the same Microsoft Entra ID manages them.

Create custom link types, export and import link-type definitions, and delete, activate, deactivate, or reactivate custom link types. See:

You can list link types using supported command-line tools.

az boards work-item relation list-type

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. For details, 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.

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 is a list of 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

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 types. 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 workItemLink value 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.

Related content