Reporting on link validity status in Report Builder

Reporting on link validity status in Report Builder can show you which artifacts meet the intended meaning of their link. For example, you might need to create a report to show completeness of requirements and the test cases that are known to validate them. You can also generate reports to show which links have an invalid status or no validity status so you know which artifacts to examine, and possibly change to restore validity.

Before you begin

Ensure that you are familiar with the concepts and examples described in Link validity, especially the meaning of upstream and downstream artifacts in the context of link validity.
To display information about the artifact on either end of the link, you must have access to the project area that contains the artifact. Otherwise, your report will contain only the artifact's URI.
An administrator must enable link validity in the IBM Engineering Lifecycle Management (ELM) project areas whose artifacts you're reporting on. For details, see Enabling link validity in AM, QM, and RM project areas.

Note: If you enabled configuration management in all your ELM applications, enable link validity in both IBM Engineering Requirements Management DOORS® Next (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 DOORS Next application. In IBM Engineering Test Management, you can report on link validity only in project areas that are enabled for configurations.
If your report does not return link validity information, ask a Lifecycle Query Engine (LQE) administrator to assign this permission to read data in the JTS Link Validity Resources (TRS 2.0) data group.

About this task

In this topic, you create a report that shows requirements, the test cases that validate them, and link validity status information.

Step 1. Choose data

Procedure

Open Report Builder.

Go to https://server_name:port/rs, and click Build. Contact your application administrator if the page doesn't open.
Choose a report type.
- Select Current Data (table or graph) to report on the latest information about artifacts in and across projects.
- Click the pencil icon to select the LQE data source depending on what you want to report on: a specific configuration or all configurations.
  - Lifecycle Query Engine to report on artifacts from DOORS Next project areas that aren't enabled for configurations.
  - Lifecycle Query Engine scoped by a configuration to report on versioned artifacts in a specific configuration.
  If only one data source is defined, it is selected by default. To decide what data source to choose, see Choosing the right data source.
- DOORS Next: For projects that are not enabled for configurations, you can report on link validity information only between DOORS Next artifacts. To do this, select the Lifecycle Query Engine data source.
Limit the scope.

Choose the projects that contain the artifact types to report on and click Continue. For example, to report on requirements and the test cases that validate them, choose Requirements Management (RM) and Quality Management (QM) projects. If you don't select any projects, the report includes all projects you can access.

Note: In ELM applications, to work with links across applications, you must work in a global configuration context. However, to report on links across applications, you select projects that contain the artifacts you report on. You do not select a Global Configuration Management (GCM) project area because you are not reporting on a global configuration. When you run a report that includes links between artifacts from different applications, you must choose a global configuration.

Continuing with the example, you select RM and QM project areas because you are reporting on those artifacts and their links.

The list shows the projects that you can access in the data source that you selected. If your projects are not in the list, see the administrator who created the data sources for Report Builder.

Some artifact types are project-specific. Go to step 4 to select the artifact type, then return here, and select List only the projects that contain the artifact for your report.
Choose an artifact.

You might have to expand some artifacts to make a choice; if you don't expand the artifact, and select it, all of its types are included in the results.

If you select an artifact type that is project-specific, you can return to the Limit the scope section, and select List only the projects that contain the artifact for your report.

Tip: To report on requirements from specific modules, click Requirement, and select the types. You specify the requirement collections or modules later.

Continuing with the example, choose Requirement and click Continue.

Trace relationships between artifacts and choose whether to include link validity status.

Click Add a relationship. For each artifact type, you see all the existing relationships. Continuing with the example, click Add a relationship > Validated By and click OK. The trace relationship looks like this:

Report Builder trace relationship showing a requirement, Validated By relationship arrow, and QM test case

Note: Some custom link types are not shown in the list of existing relationships: for example, custom link types from artifacts that do not own the link. For more information, contact your administrator, or see Getting started with reporting by using Lifecycle Query Engine data sources on Jazz.net.

You can also select multiple relationships between two artifacts of the same type, as shown in the following example:

Multiple traceability links between two requirements.

Tip: When you name and share your report, include the traceability link names so that team members can find your report easily. For example, "Engine (Sport) 2.0 Requirements Validated By Test Cases".

To trace multiple relationships from one artifact, or to add source artifacts, select the check box, click Add an artifact, and build the next trace relationship.

Tracing multiple relationships and adding source artifacts

You can set conditions for each relationship that you trace. For tips and details about building complex trace relationships, see these resources:

To remove the last relationship from the right of an artifact, click Back. To remove an artifact or relationship and all the items to the right, click the X beside the item name.

Tip: To change the name of an artifact in the traceability box, double-click its name and type the new one. For example, if you want your report to refer to tests instead of QM Test Cases, double-click the QM Test Case box in the traceability diagram, and type Tests. Changing the name in the traceability diagram makes it clearer to your team members, especially if your report uses custom artifact types or custom links.

Next, choose options from the Relationship and Link validity menus. Use the following table to help you decide which options to choose.

Relationship	Link Validity	Results
Required	Ignore	Shows source and target artifacts that have the selected relationship. Ignores the link validity status on the relationship. Example: Shows requirements and the test cases that validate them, and doesn’t examine whether a link validity status is assigned.
Required	Optional	Shows source and target artifacts that have the selected relationship, whether a link validity status is assigned or not. For example, you might choose this combination to show all statuses (valid, invalid, or unknown), if a status is assigned. If the status is unassigned, it appears empty. In Report Builder, a link is suspect if it does not have a validity status or has the validity status 'unknown'. When you set Link validity to Optional, add conditions carefully, otherwise report results can be misleading. For example, add a condition to filter by valid or invalid status. Items that don’t match the condition are shown as empty cells, and you cannot distinguish if the status is unknown or just doesn’t match the condition. Instead, consider setting the Link validity menu to Required and add conditions. Example 1: Show the artifacts whose relationship is set to Valid Add the Status column to the report and add a condition for Status is Valid. When you run the report, the Status column shows Valid links. Empty cells can represent either links with no status or links whose status is not valid (invalid or unknown). Example 2: Show links whose validity status you set Add the Status column to the report, and add a condition for the Validated By link where Modified By is set to Current User. When you run the report, you see the status of the links that you set. In this scenario, blank rows do not equal links with no validity status; they equal rows whose link validity was set by someone else.
Required	Required	Shows source and target artifacts that have the selected relationship where the relationship is assigned a validity status of valid, invalid, or unknown. Typically, this is the most common combination for reporting on link validity. To filter by validity status (valid, invalid, or unknown), add a condition. You can also create conditions to filter by who set the validity status, and when it was last modified. You might also add columns to show the filter results. For example, add a Status column to show the validity status of a link. For details, see step 2.
Required	Does not exist	Shows source objects and target artifacts that have the specified relationship but no link validity status is set on the relationship. Example: Shows requirements validated by test cases where no validity status exists. You might use these results as a "to-do" list of relationships that a subject matter expert must assess as valid or invalid.
Optional	Ignore	Shows source artifacts whether they have the selected relationship to the target artifact. Ignores link validity status even if it exists. Example: Shows requirements from the scope that you choose, whether they have test cases that validate them. Validity status is ignored.
Optional	Optional	Shows source objects whether they have the specified relationship to the target resource or not, or whether the relationship has a link validity status assigned or not. Example: Shows requirements whether they have test cases that validate them and whether a link validity status is assigned to the Validated By link.

After you build the artifact relationships, click Continue.

Set conditions.
You can set conditions for these items:
- Any attribute of the artifact type that you selected
- Any relationship type that supports link validity
- Any attribute of the related artifact types in your traceability paths
If you want to add conditions related to link validity status, for best results, set the Link validity menu to Required in the Trace relationships section.
To further refine the content of your report, specify conditions.
1. Click Add condition.
2. From the list, select an artifact or relationship type.
3. Choose the attribute that you want to specify a condition for, and select the values to return the artifacts you want.
4. To keep the window open for adding other conditions, click Add. Otherwise, click Add and Close.
5. Optional: Change the lock to control whether people can or must supply a value for the condition when they run the report.
Examples of conditions you might set to report on link validity:

Show only links whose validity status is Valid:

Show only link validity status set by you:

Reporting on links with no validity information: Remember, instead of setting a condition, in the Trace relationships section, set the Relationship menu to Required and the Link validity menu to Does not exist.

You can set a condition to return data only for specific components. You must select an application-specific artifact type (such as QM Test Case, or System Requirement). These artifact types contain a Component attribute that you can choose, and then select the component to report on. The Component attribute is not available if you select a global artifact type (typically the expandable top-level artifact type in the Choose an artifact section) or types from projects that aren't enabled for configurations.
- To edit a condition, click the pencil icon beside it.
- To create logical groups of conditions, select them, and click Group.
- To create nested groups of conditions, use the grouping buttons or drag conditions to existing groups.
- To reorder conditions, drag them into position.
- To remove conditions, select them, and click Remove.
After you create your conditions, click Continue.

Step 2. Format results

Your report already has some columns, including columns for the attributes you created conditions for.

Procedure

Add attribute columns: Select the artifact type from the drop-down list, and the attributes to add to the report. Then click Add.
Continuing with the example, you might add columns to show link validity status information.
- Last modification: Understand the last time the link validity was assessed.
- Status: Add this if your report is designed to show all statuses (valid, invalid, or unknown).
- Modified By: Discover which team members set validity status so that you can follow up with them if more information is needed.
Add calculated value columns: Add columns that show calculations such as averages, sums, or counts.
1. Select the artifact type.
2. Select the calculation to show.
3. Select the attribute for your calculation.
4. To add other calculated values, click Add. Otherwise click Add and Close.
Add custom expression columns if you are a report manager, and if your data source is configured to allow report managers to edit queries: To show the data in the form that you need, you can use attributes and functions to build custom expressions.
1. Select the artifact type from the drop-down list.
2. Add attributes (and functions if needed) one by one by selecting one and clicking Add.
3. Modify the expression in the Custom expression field.
  
  For LQE, you can pick a frequently used function from the Choose functions list to help you choose the functions quickly without worrying about the syntax of the query language. If you add one of these functions to the custom expression, you must replace the placeholder text. In the custom expression, position the cursor at the placeholder text, choose an attribute, and click Add; then, delete the placeholder text.
4. If your custom expression includes a function or an aggregate expression, select the Contains an aggregate expression check box .
  
  Note: Aggregate expressions calculate a single value based on a set of values such as SUM, COUNT, AVG. Each database vendor has its own set of aggregate expressions. Check the vendor documentation.
5. Optional: Specify how to display the values. You can use the default String.
6. Validate your expression.
7. Click Add to include the column in the report.
Format columns.
- Change the column name: Type in the Column Label field.
- Arrange columns: Click the drag handle beside the column label, and drag it to another location, or use the controls in the Actions column.
- Adjust the column width: Click the column boundary in the table layout at the top, and drag it into position.
- Sort columns: Select the sort method from the Sort Type list. You can sort more than one column. To change the sort order, edit the number.
- Color-code your report: Click in the Color section to configure rules for highlighting specific data in your report. You can add multiple coloring conditions. If several conditions target the same cells in your report, prioritize them:
  - Within the same column: Drag a condition to adjust its priority. In a list, the priority increases from top to bottom. The first condition is met first. The last condition (at the bottom) can override the first one, so it has the highest priority.
  - Across all columns in your report: Use the Priority field to define the sequence to apply your conditions in. Enter a value from 1 (highest) to 9 (lowest). To give a condition the lowest priority, leave the Priority field empty.
- Combine consecutive columns: Enter the same column label for equivalent attributes that are grouped in one condition. Using the risk status example from Set conditions, for each instance of the attribute (Risk Status in RM, Risk Status in QM, and so on), set the column label to Risk Status. When you run the report, one Risk Status column shows data from all the projects.
  Important: If the consecutive columns contain calculations, the labels are combined in the report that you export, but not on the Run Reports page.
- Remove columns: Use the controls in the Actions column.

Step 3. Name and share the report

Procedure

Give your report a name and a description. The description helps other team members find your report if it is public.
Tag your report to make it easy to find, or to group it with related reports. Each tag becomes a category on the All Reports and My Reports pages.
Specify how to publish the report:
- Public (publish to catalog): The report is in the Report Builder catalog. Team members can add the report as a widget to their Jazz® dashboards.
- Private (publish to catalog and visible only to creator and owners): The report is in the Report Builder catalog. Only the report creator and owners can add the report to a dashboard and see it. Other users see the widget, but they cannot run the report.
- Private (visible only to me): The report is available only on the My Reports page.
Specify whether the default visualization for your report is a table or a graph. For example, if you select Graph, but then run the report to generate a table, the next time you run the report, the results are shown again in a graph.
Click Add owner.
Your report can have multiple owners who can modify the report, and assign other owners.
Click Save, and click Continue.

Step 4. Run the report

To see the complete report, click Run report. Provide values for all required parameters or filters.

About this task

Continuing with the example, you must choose a global configuration when you run the report because it includes links between artifacts from different applications.

If you were reporting on link validity status for relationships between artifacts in the same application, you could choose a configuration from that same application. For example, to report on link validity status for links between requirements, you could choose an RM configuration.

If you choose an LQE-based data source in step 2 and Report Builder reports don’t show the artifacts that you expect, show artifacts more than once, or show a different number of artifacts than application views, ask an application administrator to validate the TRS feeds for the application. See Validating TRS feeds and the LQE index.