Links between artifacts

Edit online

A link represents a relationship between artifacts. Links are mechanisms for referring to related information. You create some links manually. Other links are created automatically when you complete certain tasks. There are different properties for trace links, content links, links to base artifacts, and links in modules.

Trace links and content links

You can create links from an artifact or from content within the artifact to another artifact or to a URL. All links must indicate whether they are stored locally or externally. Links are created automatically when you embed one artifact within another. For example, links are created when you embed an artifact in a text document, add a part to a sketch, or embed a sketch in a storyboard.

Tip: You can also create links by dragging an artifact and dropping it on the link icon of another artifact, as shown here:

Content links are simple hyperlinks between content within an artifact or to another artifact. You can create a content link from a text string in a textual artifact to an artifact in the repository or to a URL. You can create multiple content links from a graphical element in a diagram, sketch, part, or storyboard to other artifacts or to URLs. You do not designate a traceability type for content links and the link is included in the content only.

When you create a link from content within an artifact, such as a range of text or a diagram element, you can assign a link type that defines a traceability relationship for the link. In addition to basic hyperlink behavior, the trace link type can convey relationships such as dependency, origin, derivation, implementation, or validation. Each trace link has a label that defines its traceability relationship type. Trace link types are based on the Open Services for Lifecycle Collaboration (OSLC) specification. Project administrators can also create custom link types to meet the needs of a particular project and organization.

Restriction:

You cannot create a link if another link to the same target with the same link type exists. However, you can create multiple content-based links. For example, you can create a link from a document to a term multiple times or embed an image in a document multiple times.
You cannot create links to external lifecycle applications from elements in graphical artifacts, such as business process diagrams, use case diagrams, and sketches. For example, when you create Implemented By links to work items that are in a Change and Configuration Management (CCM) project, you can link from the graphical artifact, which contains the entire diagram, but not from elements in the diagram.
This restriction also applies to links from Requirement Management (RM) graphical elements to artifacts in the Quality Management (QM) and in requirements management applications that are not part of the IBM® Engineering Lifecycle Management (ELM).

To create traceability for elements in graphical artifacts, link an element to an artifact in your project that describes the activity for that element, and then link that artifact to a work item, test case, design object, or requirement in an external lifecycle application.

If you designate a traceability relationship for a link, a matching trace link is displayed in the Links section of the artifact sidebar. You can also display and filter artifacts that contain trace links on the Artifacts page and in dashboard widgets. Trace links and the relationships that they represent are also visible in the artifact summary when you hover over a link that includes traceability. When you click the Show More link, you can see the link information.

Trace links help to manage and monitor the status of requirements and their related artifacts, such as parent and child requirements, development work items, or test cases.

You can use Link types to define and customize the linking relationships between artifacts. Link relationships are directional. When link types are displayed in the user interface, icons indicate the direction of the link type. For more information, see Creating link types for requirements projects.

Content links have no matching trace link in the artifact sidebar or on the Artifacts page or dashboard. They provide simple hyperlinks within an artifact without adding nonessential link information in the sidebar and project pages.

You can add a matching trace link to an existing content link, or remove it. When you delete a matching trace link, the content link remains in the artifact content. If you delete a rich-text content link that has a matching trace link, the trace link is deleted when you save the artifact. If you delete a content link from a graphical element in a diagram, the trace link is not affected.

If you create a link in the Links section of an artifact sidebar, you are creating a trace link for the artifact and must designate a traceability link type. These trace links are independent of any specific content in the artifact editor; they represent the entire artifact.

Trace links that are associated with a content link are displayed in the Links section with the Content link Content link icon icon. When you view the artifact that contains the content link and you click the icon, the content link is highlighted in the artifact editor.

You can track changes to linked artifacts by using link validity.

Links to base artifacts and artifacts in modules

Artifacts can be created and managed in a project independently from a module. They are called base artifacts. Base artifacts can also be used in one or more modules. You can link base artifacts with other base artifacts or with artifacts in the context of a module. Links to and from base artifacts are available in all modules in which those artifacts are used. A blue icon over the artifact type icon indicates linking with a base artifact screen cap indicating the base artifact

. Links that are created in the context of modules are only available in those modules. If you create links to or from base artifacts, those links are available in every module that the base artifacts are used in. For more information about how to create links, see Linking between artifacts in modules.

Linking between projects after enabling configuration management

To work with links across project areas, team members must work in the context of a global configuration. For an overview of cross project linking, see Cross-project links to versioned artifacts.

Deleting artifacts that have links

How a link between two artifacts is impacted when one artifact is deleted? When you delete an artifact that contains links:

If the artifacts are in the same project or component area, the deleted artifact is automatically removed as a link from the artifact it is linked to or linked from. In other words, incoming and outgoing links are updated to reflect the deletion.
If the artifacts are in different project or component areas, it is deleted only if it is an outgoing link for the artifact that is being deleted. If the link is an incoming link, it appears as an outgoing link for the artifact, but the link's target artifact do not work as the artifact is deleted.

Example 1: A and B are two artifacts that are created within the same project or component area. A and B are linked to each other.

If Artifact A is deleted, the link is deleted and it no longer appears as an incoming link for Artifact B.
If Artifact B is deleted, the link is deleted and it no longer appears as an outgoing link for Artifact A.

Example 2: A and B are two artifacts that are created in different project or component areas. A and B are linked to each other.

If Artifact A is deleted, the link is deleted, since it is an outgoing link, and it no longer appears as an incoming link for Artifact B.
If Artifact B is deleted, the link is not deleted, since it is an incoming link, and the link still appears as an outgoing link for Artifact A. But the link's target is not accessible, since Artifact B is deleted.

Sorting and filtering links

You can sort, group, or filter links by using the Links section of the artifact sidebar.

You can sort the artifacts by name, type, ID, or last modified date by clicking the Sort Links icon. You can also group the artifact links by relationship, component or project, last modification date, or link direction. The following image shows the sort and group options for artifact links: Sorting or grouping Links

Note: The Requirements Management (RM) application does not manage artifacts that are associated with Open Services for Lifecycle Collaboration (OSLC) and external. When you sort these types of links, the following rules apply to each sorting option:

Sort by Artifact Name: The full OSLC or external link label is used, which might or might not start with an artifact name.
Sort by Artifact Type: An external link is used as the artifact type name.
Sort by Artifact ID: The full OSLC or external link label is used, which might or might not start with an ID.
Sort by Date Last Modified: The last modified date of the link is used instead of the modified date of the linked artifact.

Additionally, you can filter artifacts by link type, artifact type, or project or component, by clicking the Filter Links icon. You can filter artifact links by link type, artifact type, or component or project. The following image shows the filter options for artifact links: