Link validity

Linked data is only useful when semantic consistency exists between two artifacts and their relationship. In projects with large data sets, achieving and maintaining consistency across linked data can be challenging over time. You can use the link validity status to achieve consistency across artifacts and links as you make changes that propagate through linked data.

In regulated industries, show the relationships that someone confirmed as valid, such as requirements validated by test cases. List the relationships where validity status isn't defined so that someone can assess whether the relationship is valid.

Note: If you enabled configuration management in all your Engineering Lifecycle Management applications, enable link validity in both IBM Engineering Requirements Management DOORS® Next and IBM Engineering Test Management applications. Starting from 7.0.0 release suspicion profiles are no longer supported for DOORS Next projects that do not use configuration management. You must enable link validity in the DOORS Next application. In Engineering Test Management, use Suspect traceability for projects that do not use configuration management and enable link validity for projects that use configuration management.

Link validity information in Engineering Lifecycle Management applications:

The IBM Engineering Test Management (Engineering Test Management or QM) and IBM Engineering Requirements Management DOORS Next (DOORS Next or RM) applications provide two kinds of validity information about requirement and test artifacts:
  • Link validity status: The status of links between artifacts, which indicates whether the contents of two artifacts meet the intended meaning of the link between them. Link validity status is a property of a link.
  • Validity summary: A rollup of the status of all the relevant links for an artifact. The summary specifies whether you need to investigate specific relationships further and modify artifacts to achieve or restore the intended meaning of the link. Validity summary is a property of an artifact.

The IBM Engineering Workflow Management (Engineering Workflow Management or CCM) application source control management (SCM) feature provides link validity status information about SCM-controlled files only. Validity summary information is not available here.

The IBM Rhapsody® Model Manager (Rhapsody Model Manager or AM) application provides link validity status information only. Validity summary information is not available here.

Note: Link validity is not supported on the links to or between container types (such as DOORS Next collection and modules, and Engineering Test Management test plans), but is supported on the artifacts within the container types, such as requirements and test cases.
Read the following subtopics to know the details about link validity concepts and terminology, setting link validity status, and about using validity summary information in your project:

Link validity

The link validity indicates whether the meaning of a link is satisfied by the content of the two artifacts that are connected by the link. An artifact’s content is the set of fields and attributes (such as summary, description) that define its meaning. Artifact metadata, such as system-generated properties (creator, creation date, last modification date, priority), does not affect link validity status.

The validity of a link is assessed as shown: Contents of artifact version X + link type + contents of artifact version Y => [has a] validity status

What link validity is not

Link validity status does not assess whether the link must exist between two versions of artifacts, nor whether the correct link type exists between the artifacts. It is not a date-based check for changes to artifacts, nor is it a tool to compare changes in configurations or to see changes.

To see whether changes to artifacts make them incompatible and invalidate the link relationship between them, use the link validity status and validity summary information.

You cannot use validity to identify which artifacts are changed in a component because validity statements are reused across configurations. To identify which artifacts changed, or to see what the changes are, or to ensure that changes to an artifact make sense, compare the configurations in their Engineering Lifecycle Management application, such as comparing a stream to a baseline.

Link validity status options

The validity status of links between artifacts can have one of these color-coded values:
Suspect (gray icons)
The system sets links as suspect when they are new or unknown. A person must verify whether the contents of both artifacts satisfy the intended meaning of the link.

If you cannot determine that, leave the link as suspect and analyze it more later.

Valid (green icons)
Team members set this status when the contents of the two artifacts satisfy the meaning of the link that connects them. Consider a “validates” link between a test case and a requirement: if the test case validates the requirement, the relationship is valid.
Invalid (red icons)
Team members set this status when the contents of the two artifacts do not satisfy the intended meaning of the link that connects them. For example, you know that a test case no longer validates a requirement. Set the status to invalid, and later, you (or another member of your team) might change the test case (the downstream artifact) to make the link valid.

If the system cannot access the linked artifact to get validity status, or if the validity service is not responding, the validity status is Unknown. Sometimes it happens if artifacts are deleted. To solve the problem, contact your application or project area administrator, or follow the instructions on the page.

Consider a test case that validates a requirement. If you change the contents of either artifact, the status of the link becomes suspect. You must examine whether the contents of the two artifacts meet the intended meaning of the link (does that test case validate that requirement?), and likely set a new status for that link. The link validity status is updated automatically in the respective applications. However, the validity summary of each artifact differs.

Link validity data representation

Based on the conditions, the link validity data can be represented in one of the following ways:
Case-1: The link has no link validity resource.
The link is implicitly suspect.
Case-2: The link has a link validity resource, but its status is Unknown.
The link is explicitly suspect.
Case-3: The link has a link validity resource, and its status is Valid.
The link is explicitly valid.
Case-4: The link has a link validity resource, and its status is Invalid.
The link is explicitly invalid.
Note: The type of links that are described in case-1 and case-2 are represented as Suspect in the Engineering Lifecycle Management domain applications.

Link validity and container types

Container types include DOORS Next modules and collections, and Engineering Test Management test plans.
Note: Link validity is not supported on the links to or between container types, but is supported on the artifacts within the container types, such as requirements and test cases.

Links (symmetric and asymmetric) and artifacts (upstream and downstream)

A link type can be asymmetric or symmetric. If a link type is asymmetric, the artifact on one side of the link is normally created or modified first, and then the artifact on the other side of the link is created or modified in response to the creation or modification of the first artifact. The artifact that is created first is called upstream artifact, and the artifact that is created later is called downstream artifact.

For an asymmetric link type, the downstream artifact is the source artifact (where the link is stored), and the upstream artifact is the target artifact (the artifact that is referenced by the link).

Validity summary information

Use the validity summary to see which artifacts to examine and possibly modify. The validity summary rolls up the validity status of all the relevant artifact links:
  • Asymmetric links: A change to either artifact affects the validity summary of the downstream artifact.
  • Symmetric links: A change to either artifact affects the validity summary of both artifacts.

The validity summary shows you at a glance the status of all the links to relevant artifacts so you know which downstream artifacts you must examine to verify intended meaning of a link.

The definitions of upstream and downstream follow the development process: requirements are developed first, followed by models and designs (not shown here), and then tests. In the following examples, only requirements and tests are shown:
  • Requirements are upstream of models, designs, and tests.
  • Tests are downstream of requirements, models, and designs.

Requirements are considered symmetric to each other. For example, stakeholder requirements are symmetric to system requirements: a change to either artifact affects the validity status of the link between them.

Using requirements and tests as an example, the following simple example shows symmetric links and upstream and downstream artifacts:

The directions (symmetric, upstream, and downstream) affect only the calculation of the validity summary for artifacts, not the validity status of individual links.

The following applications support validity summary information. The link validity status of the following types of links contributes to an artifact’s validity summary:
  • Engineering Test Management application: Validates (links from test cases to requirements; does not apply to steps in test scripts).
  • DOORS Next application: Link To, Link From, Elaborates, Satisfies, Traced By Architecture Element, or a link to another DOORS Next artifact that has a custom link type. Validated By (links to downstream test cases) links are ignored in validity summary calculations.
The following applications support link validity status only and do not support validity summary information:
  • Rhapsody Model Manager application: You can set link validity status on any link between an Rhapsody Model Manager and DOORS Next or Engineering Test Management artifact. The link types can include Derives From and Validated By.
  • Engineering Workflow Management application:
    • You can link files in Engineering Workflow Management source control to DOORS Next requirements or Engineering Test Management test scripts, and set link validity status on these links by using "Implements" link type.
    • You can link work items to other Engineering Lifecycle Management artifacts, but because work items are not versioned, you cannot set the link validity status on the link. For example, you can create an “Implements” link type from a work item to a requirement, but no link validity status icon is shown on either end of the link in the respective Engineering Lifecycle Management application.
Note: No validity status icon is shown on external links or on links to other applications that do not support link validity.
Using requirements and test cases as an example: The status of links to downstream artifacts (test cases) does not affect the validity summary of upstream artifacts (requirements), as shown in the following image. As you can see from the validity icons (see the key), for example, a suspect link between a requirement and a test does not affect the validity summary of the requirement; it affects the validity summary of the test case. You must examine the downstream artifact and either restore validity by changing the downstream artifact or flagging the link as invalid and doing the work later.
Upstream and downstream, with validity summary icons
Key to the icons is as shown in the diagram:
Key to link validity icons

Validity summary options

You do not change a validity summary; you change only the status of the individual links that contribute to it, which in turn can affect the summary. Summary icons are the same colors as for link validity.

The summary can have three possible statuses that are determined in the following order:
  • Invalid : At least one relevant artifact link is invalid, even if other links are suspect or valid.
    Note: In an artifact view, you must add the link type column to the table in the view before you can set link validity. Hover over the validity summary to determine which columns to add.
  • Suspect : At least one relevant artifact link is suspect and must be verified, but no invalid or undetermined links exist.
  • Valid : All the associated artifact links that affect this artifact are valid.
Note: If you see a validity summary status of “Undetermined”, the system doesn't have enough information to determine the status of at least one link. If the problem persists, tell your project area administrator.

To resolve links, use an approach that is appropriate for your situation. You might want to first inspect all the suspect values to see how many invalid values are there. Or, because invalid links mean that someone verified that a relationship is not semantically consistent, you might want to examine such relationships first, and then address suspect items. Suspect relationships might still be consistent; it’s just that the system detected changes that you must verify.

Example 1. Modifying a stakeholder requirement

You start off with five artifacts in a simple scenario. A system requirement elaborates two stakeholder requirements, and is verified by two test cases.

Consider that someone verified that all the artifacts and the links between them all meet their intended meaning.
Key to the icons is as shown in the diagram:
Key to link validity icons
Step 1. You discover that you must change the description of Stakeholder requirement A v1. When you change the requirement, a new version is created, Stakeholder requirement A v2. After you save your changes, your situation looks like this:

The system sets the link to and from Stakeholder requirement A v2 as Suspect because it can no longer verify that the contents of the Stakeholder requirement A v2 and other relevant artifacts (in this case, the system requirement) meet the intended meaning of their link. The Suspect validity summary for either of the artifacts indicates that someone must verify whether the contents of the artifacts on both ends of the link satisfy the intended meaning of the link. In this case, verify that System requirement M v1 elaborates Stakeholder requirement A v2.

Step 2. In this case, you decide that the system requirement no longer elaborates Stakeholder requirement A v2, so you set the status of the link to Invalid . Because the links are symmetric, the validity summary for both artifacts is now Invalid :
Step 3. To restore validity between Stakeholder requirement A v2 and the System requirement M v1, you decide to change the system requirement. As soon as you do that, a new version of the system requirement is created, System requirement M v2. The system sets the link validity status of the links to this artifact to Suspect:

Step 4. The new artifact content in System requirement M v2 affects the validity status of links to the stakeholder requirements and the test cases. Since the stakeholder requirements are fixed, start by examining whether the System requirement M v2 still elaborates the stakeholder requirements.

You decide that the System requirement M v2 now validates Stakeholder requirement A v2, so you set that link to Valid , which changes the validity summary Stakeholder requirement A v2 to Valid . The validity summary for System requirement M v2 is still Suspect because the link to Stakeholder requirement B v1 is still Suspect .

Step 5. Because you still have a suspect link as a result of changing the system requirement, you must confirm that System requirement M v2 still elaborates Stakeholder requirement B v1. You confirm that it does and set the link validity status to Valid . The validity summary for Stakeholder requirement B v1 now becomes Valid because the relevant link to it is Valid .

The validity summary for System requirement M v2 is also Valid because its relevant links are all valid. Notice that the validity summary of System requirement M v2 is not affected by the validity status of the links to the test cases: validity summary is not affected by the link status to downstream artifacts.
Step 6. Notice that the validity summary of the test cases is still Suspect . If you use the Engineering Test Management application, you see that the validity summary of the test cases shows that the link to System requirement M v2 is Suspect . You need to look at each test case and System requirement M v2.
  • You see that Test case X v1 still validates System requirement M v2, so you set the link as Valid . The validity summary for that test case becomes Valid because all links to requirements (upstream artifacts) are valid.
    Note: In the DOORS Next application, the status of the link is also updated to Valid .
  • You see that Test case Y v1 does not validate System requirement M v2, so you set the link as Invalid . The validity summary for this test case becomes Invalid because an invalid link to a requirement (upstream artifact) exists.
    Note: In the DOORS Next application, the status of the link is also updated to Invalid .
Step 7. To restore validity between Test case Y v1 and System requirement M v2, you change the downstream artifact, which is the test case. Now you have a new version of the test case, Test case Y v2. The system sets the link between it and System requirement M v2 as Suspect. Because the test case is downstream, its validity summary is affected by the suspect link, and is therefore set as Suspect . The validity summary of System requirement M v2 does not change because link validity status to test cases is not considered, upstream artifacts are not affected by changes to link validity status to downstream artifacts.
You know now that Test case Y v2 validates System requirement M v2, so in the Engineering Test Management application you set the link validity status to Valid . All the validity summaries are valid, which means that no more artifacts are pending for examination.

Example 2. Changing a test case

Continuing with the previous example, later in the release, you want to improve Test case X v1 by reducing the number of steps.

Step 1. Your changes automatically generate a new version of the test case, Test case X v2, and the system sets the link between it and System requirement M v2 to Suspect. The validity summary for Test case X v2 becomes Suspect as a result of the suspect link.
Step 2. You confirm that Test case X v2 validates System requirement M v2, so you set the link to Valid. Now that all links to Test Case X v2 are valid, the validity summary automatically changes to Valid . All the validity summaries are valid, which means that no more artifacts are pending for examination.

Example 3. Reuse of link validity in other configurations

When you set a link validity status in one configuration, the status is refreshed in any other configurations that contain the same two artifacts with that same content and link type between them. The status is refreshed when someone who is working in the other configuration starts an operation that refreshes the page (for example, Save).

Team members who are working in other streams that contain those versions of artifacts and their links know that the artifacts in their configuration satisfy the meanings of those links, without having to analyze them.

Continuing with the previous scenario, you create a baseline and a maintenance stream. For simplicity, this diagram uses the same artifacts as the other examples. In reality, different versions of some of the artifacts across configurations would exist, and only the links that share versions would share link status.

Other examples of how link validity is shared

Link validity status is also shared across configurations in the following ways:
  • When you set the validity of a link in a global configuration, the status is shared with local streams that have the contents.
  • When you set link validity in a local stream, the status is shared with global configurations that use the stream.
  • When you set link validity in a baseline, the status is shared with the same contents in predecessor or successor streams. You can revert to a known good baseline and set the validity status there.
  • When you set link validity in a stream, the status is shared with predecessor or successor baselines.
In any of these examples, if the contents of artifacts revert to a previous known state, the previous known status is applied and reused as described in the preceding list.

Validity and global configurations

When you work in a global configuration context, you can set the status of links to different artifact types in other applications. For example, you can create links to, and set the validity status of, links between requirements and test cases.

In the DOORS Next application, when you work in a change set in a personal stream, you can add and remove links to other artifacts, such as test cases. If you are not working in a global configuration, you can link only to other requirements.

However, if you are working in an DOORS Next configuration, you can see only links to requirement artifacts.

To see your configuration context at any time, click the Current Configuration menu on the toolbar and see the Configuration Context information.

Validity and change sets

The link status that you choose in a change set is applied when you deliver changes to the stream. Consider the following high-level steps of using a change set to update a system requirement that elaborates a stakeholder requirement.
  1. Create a change set.

    Change the system requirement so it satisfies a stakeholder requirement, which creates a new version of the system requirement.

  2. In the change set, set the link status between the system requirement and the stakeholder requirement.
  3. Deliver your changes.
  4. The stream now has the same content and link status as what was in your change set.

The link validity status that you set in the change set is applied to the stream when you deliver the change set, only if you must not merge your changes with the changes from another change set that was also delivered. If you had to merge your changes and the content of the requirement artifact got modified, the link between the requirements is set to Suspect and someone must examine it.

Test case approval and automatic link validation

In the Engineering Test Management application, an administrator can set the system to automatically set links to requirements to Valid when you complete a test case review and approve it. For more information, see the related topic about enabling link validity.

Enabling link validity later in a release

Link validity information is always tracked, whether you show it in the Engineering Lifecycle Management applications. When an application or project area administrator enables it for the first time in the project areas, links between artifacts are labeled as suspect because no one ever marked them otherwise. However, some cross-project links might be already set as valid or invalid someone set the status in other applications.

Reporting on link validity

Different applications support different methods for reporting on link validity information. For more information, see Reporting on link validity status in Report Builder.

Exceptions to changing only the downstream artifact to restore intended meaning

Typically, you change the downstream artifact so that artifacts in a linked relationship meet the intended meaning of the link that connects them. However, if a performance test case fails, you might request a change to the requirement to specify a different performance outcome. Then, change the test case so that it validates that requirement, and the intended meaning of the link is satisfied and the test case passes.