Link user stories, issues, bugs, and other work items

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013

You link work items to other work items to manage dependencies and see relationships within work. You can link work items within your project or to work items within another project in your organization. You use different link types to support different business objectives. You can also link work items to other objects such as builds, commits, versioned items, or network resources.

You link work items to other work items to manage dependencies and see relationships within work. You can link work items within your project or to work items within another project in your collection. You use different link types to support different business objectives. You can also link work items to other objects such as builds, commits, versioned items, or network resources.

In general, you use the following link types when linking work items to one another:

  • Use Parent/Child links to link work items that you want to group within a hierarchy
  • Use Predecessor/Successor or Affects/Affected by links to link work items that have dependencies
  • Use Duplicate/Duplicate of links to link work items that track the same code defect or work
  • Use Related to link work items with some level of relationship, but not that strong

You can add a link to a work item from within the work item form or from a backlog or query results list. From a backlog or query results list, you can select multiple work items and then link them to a new or existing work item. In general, use the bulk edit to update several work items to link to the same work item, either new or existing.

Use this article to learn how to:

  • Link one or more work items to an existing work item
  • Link one or more work items to a new work item that you add when linking
  • Add a link to a remote work item
  • Link several work items to a new git branch
  • Link work items to a build artifact
  • Find work items that you want to link to
  • Bulk modify link relationships
  • Link one or more work items to an existing work item
  • Link one or more work items to a new work item that you add when linking
  • Link several work items to a new git branch
  • Link work items to a build artifact
  • Find work items that you want to link to
  • Bulk modify link relationships

For a list of all link types and supported link relationships, see Linking, traceability, and managing dependencies.

Note

The following link relationships are restricted:

  • You can't assign a work item more than one parent using a parent/child or other tree topology link type.
  • You can't add links in such a way as to create a circular relationship.
  • You can't link more than 1,000 work item to a single work item.

Prerequisites

Backlogs are automatically created when you create a project or add a team. Each team has access to their own product, portfolio, and sprint backlogs as described in About teams and Agile tools.

  • You must connect to a project. If you don't have a project yet, create one.
  • You must be added to a project as a member of the Contributors or Project Administrators security group. To get added, Add users to a project or team.
  • To add or modify work items, you must be granted Stakeholder access or higher. For details, see About access levels.
  • 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 learn more, see Set permissions and access for work tracking.

Note

Users with Stakeholder access for a public project have full access to backlog and board features just like users with Basic access. For details, see About access levels.

  • You must connect to a project. If you don't have a project yet, create one.
  • You must be added to a project as a member of the Contributors or Project Administrators security group. To get added, Add users to a project or team.
  • To add or modify work items, you must be granted Stakeholder access or higher. For details, see About access levels.
  • 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 learn more, see Set permissions and access for work tracking.

 

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

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

  1. From the web portal, open a 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, and then choose Link to a new item… or Link to an existing item….

    Here we multi-select from the Queries page and choose Link to a new item….

    Screenshot of Query results page, multi-select items, open context menu, choose Link to a new work item, TFS-2017 version.

  1. From the web portal, open a 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, and then choose Link selected item(s) to a new work item… or Link to an existing item….

    Here we multi-select from the Queries page and choose Link selected item(s) to a new work item….

    Screenshot of Query results page, multi-select items, open context menu, choose Link to a new work item, TFS-2015 and eaqrlier versions

When you link work items, you select a link type. In general, use the following link types as indicated. To learn more about each link type, see Link type reference.

  • Use the Duplicate link type when two work items have been created that essentially capture the same information; close one of the work items and keep the other one active
  • Use the Parent/Child link types when you want to break down work items into smaller items—for example, break down features into stories, or stories into tasks
  • Use Predecessor-Successor link types when you want to track tasks that must be completed before others can be started; this link type is most often used when you plan work using Project
  • Use the Related link type when the work items being linked are at the same level—such as two user stories that define features that overlap one another—or to link work items that are defined in different projects or managed by different teams.

From the Add link dialog, select the link type, enter a work item ID, and then choose OK.

For example, here we use the Related link type to link three items to the bug with ID of 400.

Add link dialog, web portal, to an existing work item.

To link to multiple work items, you can use inline add which finds work items based on your recent activity or keyword searches. Simply select one or more of the work items displayed automatically based on your recent activity, or enter a keyword. Keyword searches will display work items based on work items that include that keyword in their title.

Note

You need to add each link one at a time. (You can no longer enter their IDs separated by commas or spaces.) To quickly find work items of interest, you can also use work item search.

To view the work items selected for linking, you can choose the .

Add link dialog to an existing work item

Screenshot of backlog context menu, choose Add link to an existing work item, TFS-2018 and previous versions.

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, you can choose the … context menu to open a dialogue that will support you in choosing work items based on IDs, a query, or title keyword.

If you are working from the Query Results page, you'll need to bulk save the work items you've modified. When you work from a backlog, work items are automatically saved.

Screenshot of Query results page, save bulk modified items.

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

Here, we have selected to add a link to the selected work items.

  1. Specify the link type, work item type, and title of the new work item. Choose OK.

    Add link dialog, Link to a new work item, TFS-2018 and later versions.

    Add link dialog, Link to a new work item, TFS-2017 and earlier versions.

  2. A work item of the type selected opens. Enter additional information and save the work item.

    Screenshot of new work item Issue added.

  3. If you are working from the Query Results page, you'll need to bulk save the work items you've modified as shown in the previous procedure.

You can link work items to objects defined in other Azure DevOps organizations as long as both organizations use the same Azure Active Directory to manage users.

Choose from one of the following two remote link types supported.

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

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

For example, here we use the Remote Related link type to link to work item ID 350 that exists in the remotelinkingtest2 organization, RemoteLinking project.

Add link dialog, Add a link to an existing, remote work item.

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 image shows an example of two remote links, indicated by the cloud icon, added to a user story.

Screenshot of User Story form, Link tab, showing two external links.

You can add a new git branch and link them to existing work items at the same time.

From a backlog or query results page, multi-select the work items you want to link to a new git branch, choose the actions icon, and then New branch.... To learn more, see Link work items to Git development objects.

Screenshot of backlog, context menu, choose Link multiple backlog items to a git branch.

Screenshot of backlog, context menu, choose Link multiple backlog items to a git branch, TFS 2017 version.

You can link work items to existing builds from the Add link dialog.

  1. From the Add link dialog, choose one of the build link types—Build, Found in build, Integrated in build— and specify the build number.

    Add link dialog, build link type selected.

  2. If you don't know the build number—a combination of the pipeline and build name—you can search for it choosing the ... button and using the Find builds dialog.

    Note you can choose a different project within your organization to link to a build. With All selected, choose Find and then apply additional filters to narrow your search.

    Find builds dialog, Project filter available.

  3. Once you select a build, choose OK and then OK to save your changes and dismiss the dialogs.

  1. From the Add link dialog, choose one of the build link types—Build, Found in build, Integrated in build— and specify the build number.

    Add link dialog, build link type selected

  2. If you don't know the build number—a combination of the pipeline and build name—you can search for it choosing the ... button and using the Find builds dialog.

    With All selected, choose Find and then apply additional filters to narrow your search.

    Find builds dialog, link to a build within your project.

  3. Once you select a build, choose OK and then OK to save your changes and dismiss the dialogs.

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 are 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 Browse button (Visual Studio) to open the following dialog.

    Choose Linked work items

    If the work items are defined in another project, then first select the Project. Then, make your selections:

    • Query. Use this method when you have defined a query that you know contains the set or superset of the work items that you want.

    • IDs. Use this method 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. Use this method to find work items that have a common word or phrase in the title field. In the and type list, click the type of work item that you want to retrieve.

      Note

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

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

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

    • From the web portal: To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the Ctrl key.

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

Additional features you can use to quickly link or change links that use the parent-child link type (some features are version dependent, see the linked topic for details):