Link work items to support traceability and manage dependencies

Last Update: 11/18/2016

Team Services | TFS 2017 | TFS 2015 | Previous versions

By linking work items and other objects, you can track related work, dependencies, and changes made over time. As the following illustration shows, specific link types are used to track specific work items and actions.

Feature availability: Additional link types are supported when you connect to Visual Studio Team Services over those available with on-premises Team Foundation Server (TFS).

Supported Link Types

There are four system link types used to link work items to each other: two tree topology, one dependency topology, and one network as indicated in the table. Tree topology links support nested hierarchies, tree queries, and several reports. Dependent links support tracking tasks that must be completed before others can be started. And, the Related link type supports connecting work items that are at the same level.

Use the guidance provided in the following table to choose which link type to use based on the types of queries and reports you'll want to create. To learn more about link type restrictions and topologies, see LinksControlOptions elements.

Link type Usage
Affects-Affected by (Tree topology, CMMI only)
  • 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 team project. This action is recommended if you plan to use Excel or Project to modify or update work item data.

Child-Parent (Tree topology)
  • 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. Go here to learn about mapping.

  • 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 team project. This action is recommended if you plan to use Excel or Project to modify or update work item data.

Duplicate-Duplicate of (Tree topology)
  • Track tasks or bugs that have been created 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 team project. This action is recommended if you plan to use Excel or Project to modify or update work item data.

Predecessor-Successor (Dependency topology)
  • 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.

  • Support 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 team 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 team project for which the query is defined are imported into the Team Foundation client.

Related (Network topology)
  • 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 team 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.

You can create links between work items by using one of the links control tabs within a work item form. Some work item types have three or more links control tabs. Each tab is designed to support specific types of links and restricts the types of link relationships made. See Link and attachment queries.

Links control tab in work item form (Team Explorer/Visual Studio) Work item form link toolbar controls

Links control tab in work item form (Team Explorer/Eclipse)

Link control options (Team Explorer, Eclipse)

You can create links from within a work item form, from a work item that appears in a list of query results, in Microsoft Excel, or in Microsoft Project. You can also use any of the client programs for Team Foundation, such as Team Explorer and the web portal, to create links or attach files.

Also, you can use the context menu in the web portal or Team Explorer.

Link a work item to an existing work item (Team Explorer) Link to an existing work item

These features let you quickly link or change links that use the parent-child link type:

Track work performed when submitting code updates

You can link your changes to your work items so that your team can understand what work was done or how a bug was fixed.

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 are automatically linked to your changes.

Git lets you link work items to commits by using the Commit link type. You can do this in several ways:

  • Drive your git development from the work item (Team Services)
  • In Team Explorer, add work item IDs before you commit your changes
    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, you 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.

From the Links or All Links tab, you can select the Hyperlink link type to add a hyperlink from a work item to a Web page or a document on a Web site.

To help track a work item, use the Attachments tabto attach a file with supplemental information to the work item. For example, you can attach a screen image that illustrates a problem, a line of code in a text file, a log, an e-mail thread, or a product feature's specification.

Attachment control toolbar

Attach files to a work item

From the Storyboards tab, you can link storyboards that you created using PowerPoint Storyboarding or other application. By default, this links control is added to those item types used to defined requirements, user stories, or features. When you make changes to a linked storyboard, the work item continues to link to the file with the latest changes.

Storyboards tab and links control

Storyboard links control

By linking the storyboard to a work item, you provide your team access to the shared file where they can add their comments. For more information, see Storyboard your ideas using PowerPoint.

You can use Team Explorer, Excel, or Project to edit the link type of an existing link. You can only edit one link at a time.

Create a work item that is automatically linked

You can add a work item that is automatically linked from the links control toolbar. Click Add New Linked Work Item icon New. Or, you can use the context menu from a query results list.

The link types, Tested and Tested By are used to link test cases to work items, and Test Case and Shared Steps are used to link Shared steps to test cases. Using Microsoft Test Manager, you can create test cases and test plans which define and manage these associations. Also, Test Manager creates and manages the associations of test results to test cases and test plans. See Share steps between test cases.

Create shared steps

By specifying the Model link type, you can link a work item to a diagram created using Visual Studio Ultimate. This lets you track tasks, test cases, bugs, requirements, issues, or other kinds of work that are associated with specific parts of your model. Or, you can link a model element to a work item. See Link model elements and work items.

Link Model elements to work items Open linked model element from a work item

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. You can search for work items that not only meet criteria for field values but also that are linked to other work items with specific types of links. This kind of query displays a primary set of work items, which meet the field criteria, and a secondary set, which are linked to items in the primary set.

See Query for work items.

Supported customizations (TFS)

If you connect to an on-premises TFS, you can create custom link types; export and import definitions of link types; and delete, activate, deactivate, and reactivate types of links.

See Link type element reference and Manage link types (witadmin).

If you connect to an on-premises TFS. You edit the FORM section of the work item type. See Add or modify or add a work item type and LinksControlOptions (web) elements.

Increase the size of attachments that TFS will accept

By default, Team Foundation Server (TFS) limits the size of work item attachments to 4 MB. For on-premises deployments, you can increase this limit to up to 2GB. See Change the maximum attachment size for work items.