Link type reference

Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

Different link types are used to manage the different relationships that you can make among work items or between work items and other artifacts, such as 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.

  • 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
  • GitHub link types: 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.

  • 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 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), supports a hierarchical or tree topology, and prevents circular references from being created between work items.

Work item link types, conceptual image

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.

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)

Affects link type image Affected by link type image

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
Child link type image
Parent link type image

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

Typical uses include:

  • Create a work breakdown structure (WBS). See Schedule tasks and assign resources using Microsoft Project.

  • Map backlog items to portfolio backlog items. Mapping items automatically creates parent-child links between the items. To learn about mapping, see Organize your backlog.

  • 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 or Project to modify or update work item data.

Duplicate-Duplicate of 1
Duplicate link type image Duplicate of link type image

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 which are duplicates of one another.

Restrictions and recommendations:

  • A work item can have only one Duplicate.

  • Only use Duplicate/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
Tested by link type image Tests link type image

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
Related link type image

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
Duplicate link type image Duplicate of link type image

System.LinkTypes.Dependency

Topology type: Dependency
Link category: System-defined

Choose Predecessor link type when linking to a work item that should be completed prior to the work item you are linking from. Choose Successor link type when linking to a work item that should be completed after to the work item you are 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 prior to 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
Tested by link type image Tests link type image

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 TFS, there are several SQL reports that depend on these links. See Review team activities to support useful reports

Test Case-Shared Steps
Tested by link type image Tests link type image

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.

Notes:

  1. Available from TFS 2017 and later versions.

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

Hyperlink, conceptual image

Link name Tool supported Artifact type Usage
Hyperlink Work item tracking Hyperlink Used to link a work item to a URL. Note that Workitem Hyperlink is the name of this link type in the Artifact Link Types API.

External link types are system-defined link types. They support linking work items to other objects as shown in the following image. A work item's External Link Count corresponds to the sum of all links defined with a external link type.

External link types, conceptual image

The following table describes the external link types you can choose when adding 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 use specify one of these link types to scope a links control using the ExternalLinksFilter XML element.

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.
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 Build Build Used to link a work item to a build.
Integrated in build Build Build Used to link a work item to a build.
Pull Request Git PullRequestId Used to link a work item to a pull request.
Model Link ArchitectureTools ModelLink (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.
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 on a network. See Storyboard your ideas using PowerPoint for details.
Storyboard Requirements Storyboard Used to link a work item to a file on a network. See Storyboard your ideas using PowerPoint for details.
Tag Git 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 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. Note that 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 are system-defined link types. They support linking work items to GitHub objects as shown in the following image.

GitHub link types, conceptual image

GitHub link types, conceptual image

Important

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

Important

You can only link to GitHub artifacts whose repositories you have connected to Azure Boards. To create that connection, see Install and configure the Azure Boards app for GitHub. To learn more about linking to GitHub artifacts, see Link GitHub commits and pull requests 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.
Link name Artifact type Usage
GitHub Commit GitHub repository commit Used to link a work item to a GitHub commit.
GitHub Pull Request GitHub repository pull request Used to link a work item to a GitHub pull request.

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.

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)

Consumes From topology image Produced For topology image

Microsoft.VSTS.Common.ProducedFor.Forward
Microsoft.VSTS.Common.ConsumesFrom.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
Remote Related topology image

System.LinkTypes.RemoteRelated

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.

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 topics: