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 have enabled 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. You should also define the same link type with the same URI for the projects or components that you want to link to, see Creating RDF vocabulary documents and assigning URIs. If you only enable cross-project or cross-component linking in one project or component, but not other projects or components, you will only be able to create the link from the project or component where the link is defined. If you use link constraints, you must define equivalent URIs for the requirement types.

To create links across projects that reside on different servers:
  • The Link Index Provider (LDX) 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 setup bidirectional friend relationships between the Requirements Management (RM) servers, and between LDX and any RM servers that are running on a different Jazz Team Server than LDX.
  • The data source for all RM servers must be added to LDX.
  • All participating project areas must be enabled for configuration management.
  • The user must be working in a global configuration context.
  • Project areas that will link to each other must be associated with the Related Requirements association on the Overview page for project area administration.
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.

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 as per 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 will always be stored in the source 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 (DOORS Next).
  • When you create a cross-component or cross-project link using a link type that is only defined in one of the projects or components 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 will be stored, messages 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 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 involved in the link is currently 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 you change the direction of the link type from outgoing to incoming, or from incoming to outgoing, 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 will be deleted from the project or component where it is currently stored and it will be 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 exists, 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 exists, 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.

Utilities to change links and repair incorrectly stored links

  • Link swapper tool: Changes the direction of an existing custom link type into a new link type that you specify.
  • Link storage tool: Ensures that cross-component links are stored in the component with the outgoing endpoint of the link.
You can download these utilities from DOORS Next wiki.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki