Add link to work items

Last Update: 3/29/2017

Team Services | TFS 2017 | TFS 2015

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.

For a list of all link types and supported link relationships, see Link work items to support traceability.

NOTE

The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to Team Services or your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned.

Work items are denoted with icons for Team Services and TFS 2017.2 and later versions. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.

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 work items to support traceability.

  • 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 team projects or managed by different teams.
  1. Select the link type, enter a work item ID, and then click OK.

    For example, here we use the Related link type to link three items to the bug with ID of 46. The image illustrates the target work item is the bug. (Click ▼ for the TFS web portal and the Visual Studio versions.

    TFS web portal, Add link dialog

    Visual Studio, Add link dialog

    Add link dialog

    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 team project, you can click the … context menu or Browse button (Visual Studio) to open a dialogue that will support you in choosing work items based on IDs, a query, or title keyword.

    (Team Services only) To view the work items selected for linking, you can click the info icon.

    Add link dialog, show the work items selected for linking

  2. If you are working from the Query Results page (web portal or Visual Studio), you'll need to bulk save the work items you've modified. Work items are automatically saved when you work from a backlog page.

    Query results page, multi-select items, bulk save modified work items

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

    Query results page, multi-select items, select Link to an existing work item

  2. A work item of the type selected opens. Specify any additional fields you want and then save it.

  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 step 2 of the previous procedure.

NOTE

Feature availability: The New branch… option is available from Team Services and the web portal for TFS 2017 and later versions.

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.

Query results page, multi-select items, select Link to a new work item

To learn more, see Link work items to Git development objects.

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, click 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 team 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 team 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):

To add fields or customize a work item form, see Customize your work tracking experience. The method you use depends on the process model that supports your team project.

For additional information, see:

Required permissions

To add, modify, or remove a link between work items, you must have permission to view both of the work items and to modify at least one of them. You must be a member of the Contributors group or have your View work items in this node, and your Edit work items in this node permissions set to Allow.