Linking artifacts in different projects or components

A link represents a relationship between artifacts. Link relationships are directional and indicated by an icon. Link types help you define and customize the linking relationships between artifacts. Each link type has an outgoing and an incoming role. You can create links between artifacts in different projects on the same server or on different servers. If you enable configuration management, you can create links between artifacts in different components.

Cross-project or cross-component linking is automatically enabled for system-defined link types. However, if link constraints are set the cross-project and cross-component linking is governed by the link constraint rules.

To enable cross-project or cross-component linking for a custom link type, a URI must be defined for the link type. For example, https://hostname.com/domain/myLabel. Define the same link type with the same URI for the projects or components that you want to link. To create link from both ends, see Creating RDF vocabulary documents and assigning URIs. If configuration management is enabled, the user must be working in a global configuration context. If you enable cross-project or cross-component linking in only one project or component, but not in other projects or components, you can create the link only from the project or component where the link is defined. This is because the link direction for a cross-project or cross-component link determines where the link is stored. Cross-project or cross-component links are stored in the source artifact's project or component area. The outgoing role represents the source of the link. If you use link constraints, you must define equivalent URIs for the requirement types.

When viewed in the context of a local baseline, rich hovers for links to artifacts outside that baseline say that the artifact cannot be found in configuration. The Links sidebar section shows the links' information.

To create links across projects that reside on different servers:
  • The Link Index Provider application must be installed and registered with the Jazz® Team Server.
  • If you are using a topology with multiple Jazz Team Server instances, you must set up bidirectional friend relationships between the IBM® Engineering Requirements Management DOORS® Next servers, and between Link Index Provider and any DOORS Next servers that are running on a different Jazz Team Server than Link Index Provider.
  • The data source for all DOORS Next servers must be added to Link Index Provider.
  • All participating project areas must be enabled for configuration management.
  • The user must be working in a global configuration context.
  • Project areas that link to each other must be associated with the Related Requirements association on the Overview page for project area administration.
Note: If the projects on remote servers are not displayed in the linking dialog box, you might need to create a URL allowlist entry for the common Jazz Team Serverserver, which handles the authentication of Engineering Lifecycle Management application servers.
When you enable cross-server linking between projects:
  • You can view, create, modify, and delete cross-server links in both grid columns and the Links pane in the sidebar.
  • When you hover over a cross-server link, information is displayed about the artifact at the other end of the link.
  • You can use a drag-and-drop operation to create cross-server links.
  • The reports that are generated when you export comma-separated value (CSV) files and spreadsheet files contain the cross-server links.
  • Link validity is fully supported for cross-server links.
Note: When creating links between two different DOORS Next servers, drag and drop supports only the creation of outgoing cross-server links.

For a cross-project or cross-component link, the link direction determines where the link is stored. Cross-project or cross-component links are stored in the source artifact's project or component area. The Outgoing role represents the source of the link.

For the following operations, when you create cross-project or cross-component links for artifacts, both Outgoing and Incoming roles are available. The links are stored according to the role selected:
  • Import CSV
  • Link By Attribute
  • Duplicate Artifact
In the following cases, when you create a cross-project or cross-component links for artifacts, links are always stored in the source or component, so only Outgoing roles are available:
  • When you create a cross-component link to an artifact in a baseline component, the new link cannot be stored in the baseline component.
  • When you create a link to the web, the new link is stored in IBM Engineering Requirements Management DOORS Next.
  • When you create a cross-component or cross-project link by using a link type that is only defined in one of the projects or components that are involved in the link, the new link must be stored in the project or component that defines the link type.
  • When you Clone from Component only Outgoing links are cloned and stored in the source artifact.
  • When you Copy from Component only Outgoing links are copied and stored in the source artifact.

Link direction and change sets

Links are always stored on the outgoing side of the link. When you create a cross-project or cross-component, depending on where the link is stored, messages that are related to change sets might be displayed and the available link types might be filtered to show only the outgoing link types. The following conditions apply:
  • If the other component that is involved in the link requires that all changes occur in changes sets, but a change set does not exist, the list of available link types is filtered to show only outgoing link types.
  • If the other component that is involved in the link is using a change set, a warning message is displayed that explains that you must deliver the other component's change set after the link is created.
  • If the specified link type is incoming, and you switch the component to one for which a change set is required but does not exist, an error is displayed and the list of available link types is filtered to show only the outgoing link types.

Editing existing cross-project or cross-component links

If you are editing existing cross-project or cross-component links and change the direction of the link type from outgoing to incoming or the reverse, the storage location of the link changes since cross-project and cross-component links are stored in the project or component of the source, or outgoing, artifact. When the direction of a link is changed, it is deleted from the project or component where it is stored and it is created in the project or component of the source, or outgoing, artifact. Since editing a link can change where the link is stored, the following conditions apply when editing a cross-component or a cross-project link if change sets are active:
  • If the link is incoming from an artifact in a component for which change sets are required, and no change sets exist, an error message is displayed that explains why you cannot edit that link.
  • If the link is outgoing to an artifact in a component from which change sets are required, and no change sets exist, the list of available link types is filtered to show only outgoing links. A warning message is displayed that explains why you cannot specify an incoming link type.
  • If you change an outgoing link to an incoming link, and the link originates in a component that is in a change set, a warning message is displayed that explains that you must deliver the change set to see the changes to the link.
  • If you edit an incoming link, and the link originates in a component that is in a change set, a warning message is displayed that explains that you must deliver that change set to see the changes to the link.