Link work items to support traceability

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.

Track related work and dependencies

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 Link type element reference.

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

Add a link

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 controls, restrictions, and field reference.

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

Links control tab in work item form (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 Team Web Access, to create links or attach files.

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

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

Link or change parent-child links between work items

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

• To link backlog items to portfolio backlog items, use the mapping pane. See Work with portfolio backlogs

• To create and link tasks to backlog items, use the sprint backlog page. See Work in sprints

• To indent (), outdent (), and change the tree hierarchy, use a tree query in Team Explorer.

  Or, to add or delete work items or change the link structure, you can use Excel or Project. See Bulk add or modify work items with Excel and Create your backlog and tasks using Project.

Track work performed when submitting code updates

You should 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. To learn how, see Manage and commit your changes.

Share information through links or attachments

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

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

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.

Q & A

Q: Can I change the link type of an existing link?

A: Yes. 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.

Q: Can I create a work item that is automatically linked?

A: Yes. You can add a work item that is automatically linked from the links control toolbar. Click New. Or, you can use the context menu from a query results list.

Q: Can I add a custom link type?

A: Yes. 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].

Q: Can I change the controls and columns on a links tab?

A: Yes. You edit the FORM section of the work item type. See Modify or add a custom work item type (WIT) and LinksControlOptions Elements.

Q: How do I query for linked work items?

A: 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.

Q: How do I link test cases, shared steps, and test results?

A: 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.

Q: How do I link work items to my architecture diagrams?

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

Q: Can I increase the size of attachments that TFS will accept?

A: Yes. 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