Linking Items Internally or Externally

This procedure describes how to link two items, either internally in the same server configuration, or linking between two items located on different server configurations, called external linking.

In StarTeam, an item is a file, change request, requirement, task, or topic. A link is a connection between two folders, two items, or a folder and an item on the same server, or on two different servers (called External Links).

Creating links can be quite useful. For example, linking a file to a change request allows you to mark it as fixed when you check in the edited file. By linking files to the requirements document that the files fulfill, you can easily refer to or update the document.

You can create several links at the same time if you want to link several items of the same type to one particular item. For example, you might wish to link several change requests to a single file. To accomplish this, you can create links using the Folder Tree menu, component menu, context menu, or Link button on the toolbar.

Note: When you create external links between items on different server configurations, both server configurations need to be opened in the StarTeam Cross-Platform Client to be able to create or view the external links. Also, to create external links, you must have the access rights to the generic external link access rights, such as create, see, modify, delete.

Begin the link process by doing one of the following:
- Open the server configuration and view which contains the items you want to link. If you want to link two items on different server configurations, open both server configurations and views in the StarTeam Cross-Platform Client.
- Select a folder from the folder tree or in the upper pane on the Folder tab.
- Click a component tab in the upper pane, such as File, Change Request, Requirement, Topic, or Task, and select one or more items.
Note: You cannot link two folders to each other with the method described in this procedure.
Right-click the selected item(s) on the component tab and choose Links > Create Link . The Links menu is also available on the component menu that corresponds with the selected component tab.

This action changes the mouse pointer and displays it as a knotted rope.

Note: If you initially select an item from the upper pane, you can also use the Link button on the toolbar. However, this button is disabled if you start the link with a folder.
Select the folder or item(s) for the end of the link in the project on the other StarTeam Server. This can be:
- A StarTeam folder (if you have not already selected a folder).
- One or more other files.
- One or more change requests or change packages.
- One or more requirements.
- One or more topics/responses.
- One or more tasks/subtasks.
To locate all items, you may need to switch to a different component tab or use the All Descendants button on the toolbar.
Click Folder Tree > Links > Complete Links or click the Link button again on the toolbar.

This button is disabled if you are linking an item to a folder.
Verify that the links exist by doing one of the following:
- Select a linked item, then click the Link tab on the lower pane to view the links for the item.
- Right-click a linked folder, then choose Properties to display the Folder Properties dialog box. Click the Link tab to view the link. (The Link tab will not appear in this dialog box if you do not have access rights to view links.)

You can also view a link by selecting either of its ends. The end you select, whether a folder or an item, is called the source. The other end of the link is called the target and is listed in the Item Type column on the Link pane.

Tip: If you change your mind about creating a link after you have started to create it, but before you have finished completing it, you can select Links > Cancel Link on the Folder Tree menu, the component menu, or the context menu. If you are using the Link button on the toolbar, press ESC.

Note: External links can also be created using drag-drop. With both views open, select the source item, press CTRL + SHIFT, then drag-drop it on the target item.