Link model elements and work items
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
Track tasks, test cases, bugs, requirements, issues, and other work related to your model by linking model elements in Visual Studio and work items in Team Foundation Server or Visual Studio Team Services. Attach documents to linked work items to associate them with model elements.
To see which versions of Visual Studio support this feature, see Version support for architecture and modeling tools.
Note
You must use Team Explorer to create and open links. Make sure your modeling project and diagrams are checked into version control so that others can open linked diagrams.
For example, you can link:
A user story work item and an activity diagram to show how to realize the story as a sequence of operations
A use case on a use case diagram and test case work items to make sure the use case is implemented correctly
An attribute in a class on a UML class diagram and a bug work item to show an error in the implementation of the attribute
A component on a component diagram and a task work item to track the component's development. Such a task is usually broken into smaller tasks
You can link work items to any element that you can select on modeling diagrams or in UML Model Explorer, like these items:
All elements in UML models, such as UML classes, lifelines, use cases, subsystems, activities, object nodes, components, interfaces
All relations in UML models, such as associations, generalizations, dependencies, flows, messages
Parts of elements, such as the attributes and operations of classes, the execution occurrences of lifelines, the input and output pins of activities, and the parts and ports of components
Layers and layer dependencies
Comments and comment links
Diagrams. To select a diagram, choose a blank part of the diagram.
Warning
You must already be connected to TFS Source Code Control (SCC) to create or link to a work item. If you try to open a connection to a different TFS SCC, Visual Studio closes the current solution automatically. Ensure that you are already connected to the appropriate SCC before attempting to create or link to a work item. In later releases of Visual Studio, the menu commands are not available if you are not connected to an SCC.
Connect to a team project
You must first connect to your team project to create, view, or remove links.
On the Team menu, choose Manage Connections to show the Team Explorer window.
If the correct project doesn't appear, in Team Explorer, choose Manage Connections and then choose Connect to Team Project. Then choose the correct projects, or server if necessary.
In Team Explorer, choose the project where you want to create, link, or view work items.
Link a model element to a new work item
Make sure you are connected to the TFS instance you want to use.
On the modeling diagram or in UML Model Explorer, open the shortcut menu for the model element.
Choose Create Work Item and the kind of work item that you want to create.
In the work item form, fill in the fields. Choose Save Work Item.
Visual Studio links the model element to the new work item. An icon appears on or near the model element.
Warning
You must already be connected to TFS Source Code Control (SCC) to create or link to a work item. If you try to open a connection to a different TFS SCC, Visual Studio closes the current solution automatically. Ensure that you are already connected to the appropriate SCC before attempting to create or link to a work item. In later releases of Visual Studio, the menu commands are not available if you are not connected to an SCC.
Link a model element to an existing work item
When you link model elements to work items, start from the model element, not from the work item.
Make sure you are connected to the TFS instance you want to use.
On the modeling diagram or in UML Model Explorer, open the shortcut menu for the model element. Choose Link to Work Item. Then select your project in the Project field.
Choose one or more work items to link to the model element by following one of these steps:
Choose a query in Saved Query.
Type the IDs of one or more work items, separated by spaces, in IDs.
Type a word or phrase in Title Contains.
Choose Find.
In the work item list, select the work item or work items that you want to link.
When you're done, the Work Items property of the model element shows a larger number than before. An icon also appears on or near the model element.
Warning
You must already be connected to TFS Source Code Control (SCC) to create or link to a work item. If you try to open a connection to a different TFS SCC, Visual Studio closes the current solution automatically. Ensure that you are already connected to the appropriate SCC before attempting to create or link to a work item. In later releases of Visual Studio, the menu commands are not available if you are not connected to an SCC.
View work items linked to a model element
In Team Explorer, make sure you're connected to the team project where the work items are linked to the model element.
On the modeling diagram or in UML Model Explorer, open the shortcut menu for the model element. Choose View Work Items to view the list of linked work items.
Note
Only work items from the currently connected server appear. If you don't see any work items, make sure you're connected to the correct server in Team Explorer.
View model elements linked to a work item
You can view modeling diagrams and elements that are linked to a work item in Visual Studio Team Services and in Team Foundation Server 2012 or later. For example, a work item might be linked to class models that show the design of new classes to be implemented.
In Team Explorer, make sure you're connected to the team project where the model elements are linked to the work item.
Note
You can only use Team Explorer, not Team Web Access, to view linked model elements. Make sure your workspace is mapped to the modeling project that contains the modeling diagrams or elements. If you don't have a workspace, you must create it. See Troubleshooting and Create and work with workspaces.
Open the work item, choose Links. Under Model Link, open the shortcut menu for the linked model element. Choose Open Linked Item.
Delete links between model elements and work items
Remove a linked work item by starting from the model element. This correctly removes the reciprocal link to that model element from the work item. Otherwise, if you start with the work item, the reciprocal link from the model element to the work item won't be deleted.
On the modeling diagram or in UML Model Explorer, open the shortcut menu for the model element.
Choose Remove Work Items.
- or -
Choose Properties, then Work Items where the number of linked work items appears.
In the Work Items property, choose the ellipsis button […].
Note
Only work items on the current server appear. If the list is empty, but the number of work items is not zero, make sure you are connected to the correct server in Team Explorer.
Under Remove Links to Work Items, clear the selected items that you want to unlink. Choose OK.
Troubleshooting
| Issue | Possible cause | Resolution |
|---|---|---|
| Can't find the model element that you want to link. | The element might be on a diagram in a modeling project that is in Team Foundation version control. You might not have a workspace that maps to the diagram. | Map your workspace to the modeling project and diagram. If you do not have a workspace, then you must create it. The error message that appears for this issue contains the path that you can use to map your workspace. See Create and work with workspaces. |
| Can't find the linked model element. | The linked element might be on a diagram that has been moved, renamed, or deleted. | 1. In the work item, delete the link to the model element. 2. Create a new link from the work item to the model element. |
| The work item doesn't have the linked model elements that you expect. | A work item shows a linked layer element only if the link was created from the work item. If your team does not use Team Foundation version control, the local path of the diagrams will be used to create the links. If the modeling project and its diagrams are in Team Foundation version control, all team members who can access the project can view linked elements in work items. | Try refreshing the work item. |
| Deleting a link to a model element from a work item doesn't delete the link from the model element to the work item. | Delete the link to the work item starting from the model element. |