Link validity

Linked data is only useful when there is semantic consistency between two artifacts and the relationship between them. 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.
The Quality Management (QM) and Requirements Management (RM) applications provide two kinds of validity information about requirement and test artifacts:
  • Link validity: The status of links between artifacts, which indicates whether the contents of two artifacts meet the intended meaning of the link between them.
  • 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.

The Change and Configuration Management (CCM) application source control management (SCM) feature provides link validity information about SCM-controlled files only. Validity summary information is not available.

The Architecture Management (AM) and Design Management (DM) applications provide link validity information only. Validity summary information is not available.

To watch a YouTube video that describes link validity, see Achieving consistency across linked data by using link validity. Although this video was created in version 6.0.1, the feature is similar in this IBM® Engineering Lifecycle Management (ELM) version.

Link validity

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

Here is how the validity of a link is assessed: 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 should 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 have changed in a component because validity statements are reused across configurations. To identify which artifacts changed, to see what the changes are, or to ensure that changes to an artifact make sense, compare the configurations in their ELM 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 this happens if artifacts have been 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. The validity summary of each artifact, however, differs.

Note about container types: Container types include RM modules and collections, and QM test plans.

The system updates the validity status of links to or between container types when one of their attributes change.

The system does not update the validity status of links container types in the following scenarios:
  • Artifacts change in the container type, such as a requirement is renamed in a module
  • Artifacts in the container type are added, reordered, or removed
Because the status of all links is affected by a single invalid or suspect link in the container, these changes are not useful for containers, so the status is not updated.

Validity summary and link direction

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:
  • Links to upstream artifacts
  • Symmetric links, which go in both directions. A change to either artifact affects the link validity status.

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 a link’s intended meaning.

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 contribute to an artifact’s validity summary:
  • QM application: Validates (links from test cases to requirements; does not apply to steps in test scripts).
  • RM application: Link To, Link From, Elaborates, Satisfies, Traced By Architecture Element, or a link to another RM artifact that has a custom link type. Validated by (links to downstream test cases) links are ignored in validity summary calculations.
Note:
  • AM application: You can set link validity status on any link between an AM and RM artifact.
  • CCM application:
    • You can link files in CCM source control to RM requirements or QM test scripts, and set validity status on these links.
    • You can link work items to other ELM artifacts, but because work items are not versioned, you cannot set the validity status on the link. For example, you can create an “implements” link from a work item to a requirement, but no link validity status icon is shown on either end of the link in the respective ELM application.
  • DM application: You can link only to IBM Engineering Requirements Management DOORS® Next (DOORS Next) requirements, and set validity status on these links.
  • 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

Here's a key to the icons 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, but have a square around them.

The summary can have three possible statuses, determined in this 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 should be verified, but there are no invalid or undetermined links.
  • 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 there are. Or, because invalid links mean someone has verified that a relationship is not semantically consistent, you might want to examine these relationships first, and then address suspect items. Suspect relationships might still be consistent; it’s just that the system has 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 has just verified that all the artifacts and the links between them all meet their intended meaning.

Here's a key to the icons 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 their link’s intended meaning. The Suspect validity summary for either of the artifacts indicates that someone should 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 should 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 the validity summary of the test cases is still Suspect . If you use the QM 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 RM 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 there is an invalid link to a requirement (upstream artifact).
    Note: In the RM 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 QM application you set the link validity status to Valid . All the validity summaries are valid, which tells you there are no more artifacts to examine.

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 tells you there are no more artifacts to examine.

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 working in the other configuration invokes an operation that refreshes the page (for example, Save).

Team members 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, there would be different versions of some of the artifacts across configurations, 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 RM 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 RM 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 you choose in a change set is applied when you deliver changes to the stream. Consider these 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 you set in the change set is applied to the stream when you deliver the change set, as long as you don’t have to merge your changes with those from another change set that was also delivered.

If you had to merge your changes and therefore modified the content of the requirement artifact, the link between the requirements is set to Suspect and someone must examine it.

Test case approval and automatic link validation

In the QM 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 details, 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 ELM applications. When an application or project area administrator enables it for the first time in the project areas, links between artifacts will likely be 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 details, see Reporting on link validity status in ELM projects.

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.


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