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 that are 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 contains only the artifact's URI.
  • An administrator must enable link validity in the IBM Engineering Lifecycle Management project areas whose artifacts you're reporting on. For more information, see Enabling link validity in project areas.
    Note: If you enabled configuration management in all your Engineering Lifecycle Management 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. 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 (Lifecycle Query Engine) administrator to assign one of the following permissions to read data in the JTS Link Validity Resources (TRS 2.0) data group.
    • Add the Everyone group to the JTS Link Validity Resources (TRS2.0) data group.
    • Set specific users to the JTS Link Validity Resources (TRS2.0) data group.
    • Create a group with specific users and add the group to the JTS Link Validity Resources (TRS2.0) data group.
    For more information about assigning user permissions, see Managing user access to data sources in Lifecycle Query Engine.

About this task

You create a report that shows the requirements, the test cases that validate them, and link validity status information.

Procedure

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

Choose data

Procedure

  1. Open Report Builder.

    Go to https://server_name:port/rs, and click Build. If the page does not open, contact your application administrator.

  2. Choose a report type.
    • Select Current Data (table or graph) to report on the current information about artifacts in and across projects.
    • Click the Edit icon Edit to select the Lifecycle Query Engine data source. Select the data source for 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, and 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.

    Note: In Engineering Lifecycle Management 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 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 Engineering Requirements Management DOORS Next and Engineering Test Management 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.

    For example, to report on requirements and the test cases that validate them, choose IBM DOORS Next and Engineering Test Management projects. If you do not select any projects, the report includes all projects that you can access.
  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 that are 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 suspect links

    For querying for the suspect links, the report needs to explicitly include the following traceability paths:

    Link validity: Required with condition status= Unknown.
    1. To include this path, goto Report Builder > Create report > Trace relationships and add artifacts section.
    2. In this section, create links from the story artifact type to the related work items. Click Add a relationship and under Work Item, select Children and Related. Click OK. Select Work Item and click OK.
    3. Set the Link validity to Required.
    4. From the Set condition section, click Add condition and set Attributes of to Validates Requirement [Type: Link validity].
    5. From the Choose an attribute column, select the status attribute.
    6. From the Choose values column, apply the condition Status isUnknown
    Link validity: Does not exists.
    1. To include this path, goto Report Builder > Trace relationships and add artifacts section.
    2. In this section, create links from the story artifact type to the related work items. Click Add a relationship and under Work Item, select Children and Related. Click OK. Select Work Item and click OK.
    3. Set the Link validity to Does not exists.

    After you create your conditions, click Continue.

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 list, and that the link validity attributes to add to the report.
  • Select Select all checkbox if you want to select all the listed attributes and then click Add.
  • 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 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 checkbox .
      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 next to 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, 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 first to last. The first condition is met first. The last condition 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.

Name and share the report

Procedure

  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. To improve the performance of reports that do not the need the up-to-date data, set the Result timeout in seconds field. The report displays data at the configured time. Caching is implemented for the last report result to quickly display it on dashboard, reducing the load on Lifecycle Query Engine caused by automatically triggered query executions by each dashboard refresh.
  6. Click Add owner.
    Your report can have multiple owners who can modify the report, and assign other owners.
  7. Click Save, and click Continue.

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 are reporting on link validity status for relationships between artifacts in the same application, choose a configuration from the same application. For example, to report on link validity status for links between requirements, choose an Engineering Requirements Management DOORS Next configuration.

If you choose an Lifecycle Query Engine-based data source in step 2 and Report Builder reports, perform one of the following actions:
  • Do not show the artifacts that you expect.
  • Show artifacts more than once.
  • Show a different number of artifacts than application views.
  • Ask an application administrator to validate the TRS feeds for the application.

For more information, see Validating TRS feeds and the LQE index.

For more information, watch the following video: