Link work items to objects

  • Article

TFS 2018

Work item links are associations between two work items, or a work item and another object, that describe their relationship. You can use work item links to track dependencies and related work for traceability, share information, manage complex projects that involve multiple teams or products, track code changes, tests, and more.

In this article learn how to do the following tasks:

Prerequisites

Prerequisite Description
Project Administrator or Contributor member You must be added to a project as a member of the Contributors or Project Administrators security group.
Stakeholder access To add or modify work items, you must be granted Stakeholder access or higher.
Contributor member or Allow perms on To view or modify work items, you must have your View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has this permission set to Allow. For more information, see Set permissions and access for work tracking.
Defined iterations To use the Planning pane, your team administrator must define iteration (sprint) paths and configure team iterations.

The following types of links help you manage the various relationships between work items and other objects.

Link type Column2
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
Work link type Links work items including select test case management work items

For more information about link types, including parent/child, related, predecessor-successor, and so on, see Link type reference/Work link types.

To link work items to various objects, do the following steps.

  1. From the web portal, open the work item that you want to link from, or create a new one.
  2. Select the Links tab, and then select Link to.
  3. In the Link type drop-down list, select the type of link that you want to create.
  4. In the Link to field, enter or select the object that you want to link to. Depending on the link type, you can enter or select the following objects. Select each object for more details.
  5. (Optional) Enter a comment to describe the link.
  6. Select OK to create the link.

Tip

There are other features that you can use to quickly link or change links that use the Parent/Child link type (some features are version-dependent, see the linked articles for details).

Do the following steps to add a link to another user story, epic, feature, bug, issue, or task from the web portal.

  1. Open the work item that you want to link to another work item.
  2. In the work item form, select the Related Work section.
  3. Select Add link, and then Existing item.
  4. In the Link type dropdown list, select the type of link you want to create (for example, Parent, Child, Related, and so on).
  5. In the Work item field, enter the ID of the work item you want to link to, then select OK. In the following example, we use the Related link type to link three items to the bug with ID of 400.

To link to multiple work items, enter their IDs separated by commas or spaces. If you don't know the IDs or you want to link to an item in a different project, select More actions. 6. (Optional) If you're working from the Query Results page, bulk save the work items you modified. When you work from a backlog, work items automatically get saved.

Screenshot of Query results page, multi-select items, bulk save modified work items, TFS-2018 and earlier versions.

  1. From the web portal, open a backlog or query results page, and multi-select the work items you want to add a link to.

  2. Open the … context menu of one of the selected work items, choose Add link, and then choose Existing item... or New item....

    In the following example, we multi-select from the product backlog and choose Existing item.... Screenshot of backlog context menu, Multi-select items in backlog, open context menu, choose Add link to an existing work item.

Do the following steps to link a work item to a new work item.

  1. Specify the link type, work item type, and title of the new work item. Select OK. A work item of the type you selected opens.

    Screenshot of Add link dialog, Link to new work item.

  2. Enter additional information and Save the work item.

    Screenshot of new work item Issue added.

  3. (Optional) If you're working from the Query Results page, bulk save the work items that you modified.

Do the following steps to link work items to objects defined in other Azure DevOps organizations. You can only do so if both organizations use the same Microsoft Entra ID to manage users.

  1. Choose from one of the following remote link types:

    • Consumes From/Produces For: When you want to track dependencies of work items that are defined in different organizations and managed by different teams.
    • Remote Related: When the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies.

  2. From the Add link dialog, select the link type, enter the URL of the remote work item, and then select OK.

    In the following example, we use the Remote Related link type to link to work item ID 350 that exists in the remotelinkingtest2 organization, RemoteLinking project. Screenshot of removing a work item link.

The link tab maintains a count of all links to the work item. The Remote Link Count field maintains a count of the number of links added to a work item that link to a work item defined in another project or organization.

The following example shows two remote links, indicated by the cloud icon, added to a user story.

Screenshot of User Story form, Link tab, showing two external links. ::: moniker-end

For more information, see Link to work items from pull requests, commits, and comments.

As you develop your software, you can capture which code changes and builds support the completion of a work item. This way, your team can understand what work was done or how a bug was fixed through the audit trail of changes to the code base.

The link types used to construct these links—as illustrated in the following image—are: Branch, Build, Changeset, Commit, Pull Request, and Versioned Item.

Screenshot of Artifact-to-artifact link types.

For more information, see LinksControlOptions elements, Development links control.

Tip

We recommend that you drive development from the work item at the time you create it. You can also add the work item ID when you create branches, commits, and pull requests. Git lets you link work items to commits by using the Commit link type. You can do so in the following ways.

  • Add work item IDs in Visual Studio Team Explorer before you commit your changes.
    Screenshot of Add work item ID or drag items before you commit your changes.
  • Use the git-commit command and include the work item ID in your comment. For example, apply this comment #35 Catch null exception to your commit. When you push the commit, the system creates a Commit link between the commit and work item #35.
  • Use the Development control, to drive your git development from the work item.

As shown in the following image, the Deployment control shows release information for two release stages those work items that have been linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards.

Screenshot of multiple environments that the release is targeting.

Deployment control

Work item forms provide two controls to show and quickly go to development objects. The Deployment control is described in this article, and the Development control is described in Drive Git development from a work item.

The Deployment control appears by default on the work item forms for User Story (Agile), Product Backlog Item (Scrum), Issue (Basic), Requirement (CMMI), Feature, Epic, Bug, Task, and Test Case work item types. It’s also automatically enabled for custom work item types that use the Inherited process. The Deployment control displays the release information for two stages of the release pipeline that's integrated with Azure Boards. This control only shows the work items that are linked to a Git commit or pull request for this pipeline. You can also gain visual insight into the status of a work item as it gets deployed to different release environments and quickly go to each release stage and run.

Screenshot of Work item form, Deployment control.

Work items associated with commits in the build show the status of the release. But, only work items within the same project get linked to where the release pipeline is defined.

Screenshot showing multiple environments that the release is targeting.

You can see the stages in real time when you open a work item.

Screenshot of Release Settings Stages.

To populate the Deployment control, do the following steps:

Note

The Deployment control requires configuration of a Classic release pipeline. It doesn't support linking to release stages defined for a YAML pipeline.

  1. Define a Classic release pipeline and set up the release stages as described in Define your multi-stage continuous deployment (CD) pipeline.
  2. Configure the pipeline as described in Configure pipelines to support work tracking, Report deployment status to Boards.
  3. Link work items to a commit or pull request in Azure Repos Git repository. For more information, see:
  4. Run the pipeline.

Team Foundation version control (TFVC) lets you link work items to version control changesets or versioned source code files by using the Changeset and Versioned Item link types. When you check in pending changes or use My Work to check in changes, work items automatically get linked to your changes.

Screenshot of Team Explorer, My Work, Pending Changes, check in.

Test-related link types link test case management work items to one another, or to other work items. From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. But, these objects aren't linked to each other through link types.

You can link work items to test cases using the Tested/Tested By link types. Use the same link controls you use to link work items to other work items as described earlier.

The following image shows the full set of link types that you can use with test management work item types. Most links between test management objects occur by executing a task from the Test pages or Microsoft Test Manager.

Screenshot of Link types used to link test objects.

For example, when you add Shared Steps to a Test Case, they automatically get linked using the Test Case/Shared Steps link types. For more information, see Share steps between test cases.

Screenshot of test work item form showing steps.

Screenshot of Insert Shared Steps dialog.

From Test you can add test plans, test suites, and test cases—which are linked, but not through a specific link type. Also, the test system creates and manages the associations of test results to test cases and test plans.

You can use a hyperlink or Storyboard link type to link a work item to a Web site, network share, or document located on a network share. Both of these link types are one-way links. To add these link types, use the same controls described earlier for linking work items.

When you use the storyboard link type, you differentiate the link to specify a storyboard or document that provides work item specifications. Use this link type to provide your team access to the shared file where they can add their comments.

Screenshot of Hyperlink or Storyboard link type to link a work item to a URL.

Azure DevOps provides several ways to view dependencies and track related work: • Query Editor: You can use the Query Editor to create custom queries that show all work items linked to a specific work item. • Backlogs and Boards: The Backlogs and Boards views show parent-child relationships between work items, allowing you to see dependencies at a glance. • Dependency Tracker: The Dependency Tracker is a Power BI report that provides a visual representation of dependencies between work items.

To view the list of all objects linked to a work item, do the following steps.

  1. Open the work item and select Links. The links tab indicates the count of all linked objects. Linked objects get grouped under their link type, with a count within each group.

Screenshot of Links tab with count of linked objects.

  1. (Optional) Expand or collapse each group, and sort within each group by State, Latest Update, or Comment by choosing the corresponding column title.

For example, the following Links tab shows a portion of the 64 linked objects for a work item.

Screenshot of Links tab with many linked objects.

Links prefaced with the exclamation mark indicate that the build, release, or other object is deleted. Due to retention policies, these objects automatically get deleted after a certain time period.

Query for linked work items

To filter items based on hierarchical links, use the Tree of work items query type. To filter items based on all link types, use Work items and direct links.

To find work items linked to other work items with specific link types, use a query that shows a primary and a secondary set of work items. The primary set meets the field criteria, and the secondary set is linked to the primary set. You can’t query for work items in releases, but you can query for work items with external links. Add more query filters to refine your search.

For query examples, see Link and attachment queries.

You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using Parent/Child or any other link type. You can only view the hierarchy through the Test > Test Plans page.

From the Add link dialog, you can open a secondary dialog to help you choose one or more work items to link to. If you're going to find and list work items to link to by using a saved query, first define the query that you want to use.

  1. From the Add link dialog, choose the … context menu or select Browse (Visual Studio) to open the following dialog.

Screenshot of linked work items.

If the work items are in another project, open that project and then, make your selections:

  • Query: When you defined a query that you know contains the set or superset of the work items that you want.
  • IDs: When you know the IDs of the work items that you want to link to. In the IDs box, type the IDs of the work items that you want to find, separated by commas or spaces.
  • Title contains: To find work items that have a common word or phrase in the title field. In the and type list, select the type of work item that you want to retrieve.

To minimize the time required to run the query, narrow the filter criteria of the search.

  1. Select the Find button. Only those work items defined for the selected project and specified work item type are listed. To sort on a column field, choose the column title.

  2. In the list of returned work items, select one or more work items.

    • From the web portal: Hold down the shift key to select several items in a sequence. Use the Ctrl key to select several nonsequential items.

    • From Visual Studio: Select each work item that should link to the current work item. You can also press the SHIFT key while clicking to select a range of work items, or press the CTRL key while clicking to select multiple work items.

Do the following steps to delete a work item link.

  1. Open the work item that has links, or select it from a query result.
  2. Select the Links tab to see the list of links.
  3. Select the link that you want to delete, and then select Remove link.
  4. Confirm that you want to delete the link.

Once a work item gets linked to a commit or pull request, it continues to appear as part of the release stages. For example, if you have a work item that didn't pass testing criteria, you might want to remove it from the builds and releases.

To remove the work item from participating in future builds and releases, delete the link to the most recent commit and pull request.

Next steps

Visualize related work and other objects. Download the Work item visualization extension, available from the Visual Studio Marketplace, Azure DevOps tab.