Introduction
In DOORS Next, links are essential for establishing traceability by creating associations, relationships, and dependencies between requirements. We will explain basic concepts and show multiple ways to create links between artifacts. Finally, we will cover the importance of traceability in requirement management and explain how links are used to trace the impact of a change in a project. This is the first article in a series. To learn more check out our next articles - Link Constrains and Link By Attribute.
Note: In scenarios we will be working with modules from one of the DOORS default templates - Automated Meter Reader, but the examples are not content-specific and you can use any modules to follow the scenarios analogously.
Basics of Links in DOORS Next
Links are one of the most important parts of any project. They are used to establish and represent relationships between artifacts. The primary use of links in DOORS Next is to create associations, , and dependencies between requirements.
Project templates tend to have an extensive list of predefined link types. Link types are used to define and customize the relationships between artifacts. Project administrators can modify and update templates by creating custom link types, or they can create new templates from scratch based on their specific project needs. You can view and create the link types for a project or component on the Link Types page - click on the Administration menu (gear icon) in the upper right corner, and select “Manage component properties”*, then click on Manage Project Properties > Link Types.
*Note: If configuration management is not enabled for your project, select “Manage Project Properties”.
Below we have chosen a few of the often-used link types and their description for illustration:
Link Type Name | Relationship labels | Description |
|---|---|---|
Satisfaction | Satisfies / | A requirement satisfies a higher level requirement. This relationship captures how the different levels of requirements are elaborated. For example: Vision is satisfied by stakeholder requirements and those are satisfied by system requirements. |
Embeds | Embeds / | Tracks a containment relationship between Requirements Management artifacts. These types of relationships occur when performing operations such as 'Insert Artifact' and 'Insert Image' for a Text artifact. |
Validated By | Validates / | Captures the relationship between a Requirements Management artifact and a Quality Management item that validates the implementation of the requirement artifact e.g. a Test Case. |
A relationship between artifacts is directional. This direction is represented by different label names as well as by the color and direction of the arrow associated with the label. Take a look at the example below:
1.) Links Types displayed in "create link" selection
Satisfies, Link To, and Embeds represent outgoing direction, which is displayed by red directional arrows to the right.
Satisfied by, Link From, and Embedded in represent incoming direction, which is displayed by orange directional arrows to the left.
Satisfies, Link To, and Embeds represent outgoing direction, which is displayed by red directional arrows to the right.
Satisfied by, Link From, and Embedded in represent incoming direction, which is displayed by orange directional arrows to the left.
Link direction can be also used for filtering purposes. Navigate to the right sidebar, unpack the “Artifact links” section and click on the filter link icon. Next, navigate to Link Type and you will be presented with the option to show only outgoing or incoming links to filter artifacts by the direction of their associated links.
2.) Filtering the links based on direction
Traceability
Extremely useful result of establishing a relationship between artifacts is the ability to trace the impact of a change in a project of any scale and at any stage of the development cycle. This helps to assess the impact and cost of the proposed change, as well as alert contributing teams of the potential impact of the implemented change on their linked artifacts.
Below is a simple scenario to demonstrate traceability in requirements management.
In this example, the user is making changes to the requirement by increasing the supported mission type from 2 to 3 hours. This change automatically marks associated links as suspects, as this change may have an impact on downstream requirements. Below you can observe the change from the module view as well as from the link explorer view.
3.) Change in Link Validity
4.) Links explorer view
Suspect links are information for teams working on the project, that implemented change may have an impact on downstream requirements. Now is it about use-case and business process, who is allowed to change link validity, and mark, that change did/did not impact linked requirements.
5.) Changing Link Validity
Another use case necessary to deliver the right solution is being able to determine if all requirements are satisfied by linked lower-level artifacts - for example, if every stakeholder requirement is satisfied by system requirements.
The simple example below describes how to create a filter to determine which stakeholder requirements are not satisfied by other types of requirements eg. system requirements.
Step 1 - Navigate to the upper right corner and click on create filter icon
6.) Add Filter
Step 2 - Create two filters.
- Filter only stakeholder requirements (omitting all other artifacts such as headings, information,... ). To do this choose an attribute “Artifact type” and select “Stakeholder requirement”
- Filter only those requirements, that are satisfied, by creating filter for link type, choosing “Satisfied by” and leaving value to “exists”
7.) Defining filtering condition for Artifact Type
8.) Defining filtering condition for Link Type
Step 3 - Observe the result - In our project, there is only one stakeholder requirement that is satisfied.
9.) Filtered View
Step 4 - Change the value of the link type from “exists” to “does not exist”. This way we will filter all stakeholders requirements that are not satisfied yet. To do so navigate to the “edit filter” pencil icon, do not change the link type, change only the value from “exists” to “does not exist” and click apply.
10.) Edit Filter
11.) Changing the Filter
Step 5 - Observe the result - in our project, there are tens of stakeholder requirement, that are not satisfied.
12.) Filtered View after change
Observe the whole process in the animation below.
13.) Animation of creating and editing the Filter
Use softacus extension for easier graphical representation
To simplify the process to a few clicks you can use our extension Module Link Statistics that will show you a quick pie chart overview of the link types of artifacts in a module based on artifact type and link type.
There are only 3 simple steps.
- Choose artifact type - in our example “Stakeholder requirement”
- Choose link type - in our example “Satisfied”
- Click on “Create Chart”
As you can see, this chart presents the same information that was provided with the views we created.
14.) Module Link Statistics showcase
By hovering the mouse over parts of the graph we can see how many requirements were/were not linked so far.
Use softacus extension for easier graphical representation
There are multiple ways to link artifacts. To demonstrate the possibilities we will use a short scenario. The simple task is to create a link between two artifacts informing that stakeholders requirement #78428 is satisfied by system requirement #78635. In the next section, we will cover each of the options.
Option 1 and 2 - Drag & Drop link between windows
First two options to create links between two artifacts use simple drag and drop between artifacts in separate tabs. In our experience, it is the most simple, and safe way to create links, as there is very little room for user errors. In our example, we have System Requirements Specification opened in the first window and Stakeholder Requirements Specification opened in the second window.
Step 1 - Find the artifact you would like to link to and click on the dots on its left side.
15.) Select an Artifact
Step 2 - Drag the artifact to the second window
16.) Switch the tab
Step 3 - Navigate to the artifact you would like to create a link to (in our example #78428), find the chain symbol in the “Satisfies” column, and release the artifact
17.) Drop the Artifact in link column
Observe the whole process in the animation below.
18.) Drag and drop for link creation - animation
Option 2 - Drag & Drop link between side-by-side windows
The second (arguably better) option is fairly similar and is excellent for anyone with a larger display. In this option, we use side-by-side windows to drag and drop artifacts between them.
Note - if you have both artifacts in the same module, you can toggle open windows using the steps below, otherwise you have to do it manually.
19.) Open Artifacts side-by-side
Steps to link artifacts are the same as in the first example:
Step 1 - Find the artifact you would like to link to and click on the dots on its left side.
Step 2 - Drag the artifact to the second window
Step 3 - Navigate to the artifact you would like to create a link to (in our example #78428), find the chain symbol in the “Satisfies” column, and release the artifact
Observe the whole process on the animation below.
20.) Side-by-side drag and drop - animation
Option 3 - Copy and Paste
Third excellent option is to copy the artifact and paste it as a link.
Step 1 - Select the first artifact (in our case 78635) and copy it either by using ctrl+c or by steps in the example below.
Step 2 - Navigate to the artifact (in our example 78428) you would like to create a link to, click on the pencil icon and select “Paste as a link”
Observe the whole process on the animation below.
21.) Copy and paste - animation
Option 4,5 and 6 - 3 Options to Add the Link Manually
Next three options use a little less user-friendly process, that may be error-prone, due to the end-user mistakes. We will point out the weak spot in the example below.
Option 4 - Add a link by clicking on the pencil icon in the “satisfies” column. Please bear in mind, that we can also start in the “satisfied by” column in second module as well as it may be any other type of link for different use-case and artifacts relationships.
Step 1 - Click on the pencil icon in Satisfies column for artifact 78635 and select “Add a link”
22.) Add Link option
Step 2 - From this step onward, the process is the same for all three options (4,5,6) -
Click on modules and select module with stakeholder requirements specification.
23.) Switch the context
Caution! - THIS IS THE STEP THAT IS PRONE TO USER ERRORS.
A majority of use cases are using module artifact to module artifact linking. However - in the option “What to look in”, the Folders option is chosen by default. Not being aware of this may lead to choosing the link to the base artifact instead of the module artifact and creating an immediate problem, or (even worse) hard-to-identify problems later down the line.
Step 3 - Find the artifact you want to create a link to (in our example 78428) either by searching for it manually or by using the filter.
24.) Select the Artifact from Module
Step 4 - Double click on the artifact, or select it and click OK.
Observe the whole process in the animation below.
25.) Add Link manually - animation
Option 5 - Add a link by clicking on the artifact setting icon, selecting add link to Artifact, and selecting “Satisfies”. After that follow steps 2,3, and 4 from option 4.
26.) Add Link manually from view
Option 6 - Add a link by selecting “Artifact links” in the right pane, clicking on the chain icon, and selecting “Satisfies”. After that follow steps 2,3, and 4 from option 4.
27.) Add Link manually from right pane
Changing Base/Module Links
Before we continue to the next option we would like to cover the scenario, where we find out that the links we made were in the wrong context - instead of creating module links (link between module artifacts), we used base links (link to the base artifact), or vice versa. The other use case may be, that you changed the way you are working with links and you need to change the context of already created links.
To simplify that process, Softacus developed a Link Switcher widget, which converts the context of artifacts links in a very short time. With just a few clicks you can convert each link in the module, or select up to two hundred links for conversion. Learn more about this extension at https://softacus.com/extension-articles/doors/link-switcher
As a simple example, imagine, you made a mistake in step 2 from the previous options and instead of module links, you created base links. We demonstrate how the link switcher can help change the link type in a few clicks. All you need to do is:
- Select what link type you want to convert - in our example “Satisfies”
- Select if you would like to convert link to module link or base link -in our example, we will select “To module” to change base links to module links.
- Select what artifacts you would like to include - if nothing is selected, all base “Satisfies” links will be converted to the module links.
- Click convert
28.) Link Switcher showcase
As you can see, both links were successfully converted without the need for any other action.
To demonstrate the ability to choose the artifacts for conversion, we did another conversion where only artifact 78635 was selected.
29.) Link Switcher showcase - result
As shown in the examples above, with the Softacus extension and its ability to convert thousands of links at once, it is extremely easy to change the link context. The most important thing, however, is knowledge about link contexts, their usage, and their consistent usage across the project modules.
Option 7 - Creating External Links
The last option describes the ability to create external links. External links associate requirements in a DOORS database with an entity or resource that is outside the current DOORS database. To create an external link to the web, choose any of options 4,5, and 6 to add a link, and in the “Where to link to” section select “The web”. Next, create a link label that will be displayed to the user and enter the URL.
30.) Select the web option
31.) Created external link
Softacus Services
We, in Softacus, are experts when it comes to consulting and service delivery of IBM software products and solutions in your business. We help our clients to improve visibility and transparency when licensing and managing commercial software, providing measurable value while increasing efficiency and accountability and we are providing services in different areas (see Softacus Services).
IBM ELM extensions developed by Softacus are free of charge for the customers who ordered IBM ELM licenses via Softacus or for the customers who ordered any of our services. If you are interested in any of our IBM ELM extensions, you found a bug or you have any enhancement request, please let us know at info@softacus.com.
Related and Referenced Topics
Blog Articles:
Basics of Links and Link Types in IBM DOORS Next Generation - learn the basics about the linking and link types in IBM DOORS Next.
Link By Attribute Feature in IBM DOORS Next - the article explains how to use the "Link by attribute" function to automatically create, update, or delete one or more links between artifacts based on values in the attributes of the artifact.
Link Constraints in IBM DOORS Next - learn how to create link constraints in requirements management to ensure coherence and consistency in your project and how to prevent user errors and inconsistencies when creating links between requirements.
Softacus Widgets:
Link Switcher - widget developed by Softacus, that converts the context of artifacts links in a very short time.
Module Link Statistics - extension that provides users with a quick overview of the amount of the links in specific link types in a module.
Link Type Change- extension developed by Softacus designed to enhance the functionality of DOORS Next Generation by allowing users to manipulate the direction of a link or convert it to another type of link.
Links Builder- extension that allows the users to create a link between two artifacts in DOORS Next Generation according to the certain rules.
Link by Foreign Attribute - this extension allows users to create links between artifacts in the selected module(s), based on the attributes values.
Show Attributes of Linked Artifacts - this extension shows the attributes and links of the artifact that is currently selected.
