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.


  1. Choose data.
  2. Format results.
  3. Name and share the report.
  4. Run the report.

Step 1. Choose data


  1. Open Report Builder.

    Go to https://server_name:port/rs, and click Build. Contact your application administrator if the page doesn't open.

  2. 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 Edit 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.
  3. 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.

  4. 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.

  5. 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 Shows an unlocked 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:
    Shows the Status radio button and Valid check box selected
    Show only link validity status set by you:
    Shows the Modified By and Current User radio buttons selected
    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.
    For the Validated by relationship, shows the Relationship menu set to Required and Link validity menu set 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 Edit 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.


  • 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.
    Shows the columns you can add for link validity 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 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 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


  1. Give your report a name and a description. The description helps other team members find your report if it is public.
  2. 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.
  3. 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.
  4. 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.
  5. Click Add owner.
    Your report can have multiple owners who can modify the report, and assign other owners.
  6. 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.