Library > Articles >

Getting started with reporting by using Lifecycle Query Engine data sources in 7.x versions

Jazz Reporting Service team 
Last updated: 5 September 2023
Build basis: IBM Jazz Reporting Service 7.0 and later versions


You can use the Report Builder in the Jazz Reporting Service to create and run reports about artifacts across projects or versioned data in configurations. Using indexed data from the Lifecycle Query Engine (LQE) data sources, you can, for example:

  • Create a multi-project report that shows test cases, the requirements that they validate, and related defects.
  • Run this report, scoping the results by choosing a configuration (stream or baseline).

Learn how to set up your environment and understand some of the limitations when you use either the LQE or LQE scoped by a Configuration data source.

Consider the limitations described here before you use LQE data sources for production reports.

If you are interested only in document-style reports, you can export Report Builder reports as IBM® Engineering Lifecycle Optimization – Publishing (PUB) templates to make document authoring easier. For example:

  • Create the documents required for a Bill of Materials (BOM) for a product: lists of requirements, and test cases and their status when a product was delivered.
  • Provide a document-style report to someone who cannot access IBM® Engineering Lifecycle Management (ELM) dashboard.

Contents

What’s new

See the complete Jazz Reporting Service New and Noteworthy list on the Jazz.net Download pages, for example Version 7.0.2.

For administrators

Getting started

Before you can report on artifacts from the LQE-based data sources, you must activate and enable configuration management in the IBM® Engineering Requirements Management DOORS Next (DN) and IBM® Engineering Test Management (ETM) applications. These steps are not required for IBM® Engineering Workflow Management (EWM). EWM does not send information about versioned artifacts to LQE. Be sure to follow the steps in the Interactive Upgrade Guide in IBM Knowledge Center.

After you enable configuration management for the first time in your solution, you must also establish a connection to the data sources.

Enabling configuration management in your ELM tools

  1. Upgrade all IBM® Engineering Lifecycle Management (ELM) and JRS applications to 7.0 or later versions. Report Builder cannot use the version 6.0 metadata that was published to LQE by the ELM applications.
  2. Enable configuration management in the ETM and DN applications:
    1. Get an activation key.
    2. Set the activation key for the ETM and DN applications. Go to the corresponding administration page:
      https://server:port/application_context_root/admin
      For the ETM and DN applications, enter the key under Advanced Properties, in the Local Versioning Component field; then, click Save. Other ELM applications’ Jazz Team Server also have this advanced property, but you add the key to the property only in the ETM and DN applications.
  3. For each ETM and DN project area that uses configurations, enable the feature on the Configuration Management page.
    The system archives the project’s data in the data warehouse. The project now sends data only to LQE as described in Choosing an LQE-based data source.
  4. Click Explore Project and if no artifacts are available, create some for the project. The initial configuration and its versioned resources are published to LQE.

Connecting to LQE data sources

You must establish a connection to the LQE data sources before users can build reports and use them on their dashboard. In a browser window, open the Setup page at https://server:port/rs/setup and click Connect to data sources.

Complete this step for each LQE data source that you add.

Additional resources

To learn more about how Report Builder and the LQE data source process metadata from applications and data sources, see A look inside LQE and Report Builder on Jazz.net. The article explains what you see in the Report Builder user interface and generated report queries.

Choosing an LQE-based data source

Before you enable configuration management in ETM and DN project areas, their information is sent to both the ELM data warehouse and LQE. After you enable configuration management in these project areas, they stop sending feeds to the ELM data warehouse, which archives their data. From that point on, those project areas send the configuration management data to the lifecycle index and is accessed by using the LQE application.

IBM® Engineering Lifecycle Optimization – Engineering Insights (ENI) can use Report Builder to report on data in the LQE scoped by a Configuration data source.

IBM® Engineering Workflow Management (EWM) does not support configuration-enabled projects areas, so it does not publish any versioned resources to LQE. All EWM data in LQE is compatible with all configurations.

Which LQE data source to use?

  • LQE data source:
    • Report on ETM and DN project areas that are not configuration-enabled.
      After an administrator activates configuration management, each project must be enabled individually. Therefore, some projects are enabled, and others are probably not enabled.
      In the Limit scope section, select only non-enabled projects. If you select a mix of projects, or select only configuration-enabled projects, your report is meaningless. See this example.
    • Report across all configurations in an ETM or DN configuration-enabled project area. Your report contains information about all the versions of the selected artifact in those configurations.
      Consider this scenario: an enabled project area represents a product, and each stream in the project area represents a release. You can report on some aspect of the product, such as requirements not implemented, across all the releases. To get the same information by using the LQE scoped by a Configuration data source, you run the report on each stream and then manually collate the results.
      Your report results might be huge with unexpected results because the property values come from all versions of each artifact, and all combinations of those values are shown. See this example.
  • LQE scoped by a Configuration data source:
    • Report on artifacts in ETM or DN configuration-enabled project areas. When you run the report, you must choose a configuration. You must choose a global configuration if your report contains traceability relationships between these artifacts:
      • DN artifacts across DN components
      • DN and ETM artifacts
    • Report on a global configuration itself (not the artifacts in the configurations that it references). Use a SPARQL query in the Advanced section.

Use the data warehouse if you have thousands of active users, or have more than 5 million resources in the projects to report on, or need to report on some artifacts types or project elements. To help you decide whether to use the data warehouse or not, see Choosing the right data source for Report Builder in IBM Knowledge Center.

Remember, the data warehouse does not contain information about configuration-enabled projects.

Using reports from version 6.0 and earlier

  • You must re-create all existing reports that are created in Report Builder version 6.0 that use LQE or LQE scoped by a Configuration (previously called LQE using Configurations) data sources because this capability was a technical preview feature in that version.
  • Existing Report Builder reports for the data warehouse might work in 7.0 and later versions.
  • Re-create manual Report Builder reports with custom SPARQL queries if they no longer generate the results that you expect.
  • SPARQL queries created in IBM® Engineering Lifecycle Optimization – Engineering Insights (ENI) might continue to work if the corresponding metadata assumptions are still true. For example, a query that assumes that artifacts have back-link properties does not work because back links are no longer created and links in the “reverse” direction are not stored.

Reporting on current data

As you build your report, your choices are shown in the My Choices pane on the right side of the page. To change your choices:

  • Click the heading near the top of the page and go to the section to change.
  • In the My Choices pane, click the pencil Edit beside the section to change.
Next, follow the procedure explained in Reporting on data in configurations.

What to do next

  • To see your report in the list of other reports, click All Reports or My Reports.
  • To further edit your report, click a pencil in the My Choices pane at the right. Click Save to save your changes.
  • You can export your report to a spreadsheet, IBM® Engineering Lifecycle Optimization – Publishing (PUB), Microsoft® Word, PDF, and HTML files. You can also export a report graph to an image file.

Before you report on historical trends, you must configure LQE to collect metrics. For details, see Collecting metrics for historical trends in IBM Knowledge Center. Then, you can report on metrics and historical trends by following the procedure in Reporting on metrics and historical trends across projects, also in IBM Knowledge Center.

Remember these points when you configure LQE to collect metrics:

  • Collecting data can be resource-intensive. Schedule the task to run when the server is not heavily used.
  • To avoid performance issues, select only the configurations you want to focus on.
    If you collect historical metrics from all the data, you end up running resource-intensive data collection jobs for each configuration.
  • Metric collection is not automatically enabled for new configurations; you must add new configurations to existing tasks.
  • If you don’t select any configuration, or if you don’t use configurations, the task collects metrics from all data.

When you use an LQE data source, some of the metrics are different than their equivalent in the data warehouse.

  • Change Management:
    –Work item creation and Work item closure gather data only about work items that were closed or created on the previous day
    –Work item totals collects data for the following dimensions: Project Area, Work Item Type, Iteration, Status, Filed Against.
    If you use the data warehouse, this metric included data for additional dimensions: Team Area, Found In, Severity, Priority, Creator.
  • DOORS Next application:
    Custom attributes, such as Status or Difficulty, are not included in the metrics.
  • General differences:
    To run a trend report against a configuration, you must configure LQE to gather metrics for that configuration. Metrics are not gathered by default.

Running cross-project reports

When you run your report, you see only the artifacts that you have access to.

Assume you created a cross-project report to show ETM test cases and the DN requirements that they validate.

The results depend on whether you’re reporting on a specific configuration or across projects that are not enabled for configurations.

For more information, see Reporting across projects and Reporting on data in configurations in IBM Knowledge Center.

Reporting on versioned artifacts from a specific configuration

  • Data source: The report must use the LQE scoped by a Configuration data source.
  • Traceability: You must know which configurations return results based on the traceability relationships and conditions that are defined in the report. For example, if you’re reporting on specific projects, you don’t get results if the configurations are not in the report’s scope.
  • Global configuration: Because the report includes artifacts from different lifecycle tools, ensure that the configurations from those tools are in a global configuration.
    When you run the report, in the Filters > Choose a Configuration section, select the global configuration that contains the local configurations to report on. If you run the report against a local configuration only, you can’t see any results.

Reporting on projects that are not enabled for configurations

  • Data source: You must select the LQE data source.
  • Mixed environment: If you work in an environment that has projects that are enabled for configurations and ones that are not, limit the scope of the report by selecting specific projects that are not enabled. Don’t try to report across them. Otherwise, the report results show all the combinations of all the property values for an artifact; the values are extracted from the multiple versions of that artifact in a configuration-enabled project. 
    Example:
    • In Stream_1, an artifact has these properties and values: state=draft and priority=low.
    • In Stream_2: state=approved and priority=high.

    Instead of two entries in the report results, there are four entries (cross product of the property values):
    • state=draft priority=low
    • state=draft priority=high
    • state=approved priority=low
    • state=approved priority=high

Details of Report Builder capabilities

TRS feeds in LQE

TRS feeds: If you add a TRS feed for an application that is registered with a different Jazz Team Server, all user URIs in the artifacts refer to the user registry in that other Jazz Team Server application. Therefore, you must also add the feed from the other server (https://host:port/jts/trsUsers).

Permissions: Ensure that the data source permissions are assigned correctly:

  • Assign the Report Builder functional user (jrs_user) to the Lifecycle Query Engine Index data source permissions.
  • Assign the Everyone group to the Jazz Team Server data source permissions. This group includes all Jazz Team Server user TRS feeds that are added manually.
  • In version 6.0, the Everyone group was manually added to the Lifecycle Query Engine Index top-level LQE entry on the Data Groups page. In version 6.0.6, you must remove this Everyone group from this entry.

Project access: To see the access for each project, look at the application’s Process feed (DOORS Next Process Resources (TRS 2.0), GCM Process Resources (TRS 2.0), and so on).

Synchronizing project membership information

Project membership updates: You might not see updated project membership information immediately in Report Builder. The system refreshes LQE with project membership information every 15 minutes. To change this default interval, go to the Advanced Properties tab of the LQE application and click the Show Internal link.

Example: Before you add members to a project in an ELM application, you might change this interval to 1 minute so that the new project members can see the information that they need in Report Builder sooner.

After LQE refreshes, change the interval back to its previous or default value.

Choosing an artifact type

Top-level and nested artifact types: The top-level artifact types correspond to OSLC types. Nested artifact types are merged artifact types from one application.

If you select a top-level (OSLC) type, you might see unexpected results in your report if multiple applications publish that type of artifact to LQE.

Example: If you choose the OSLC Requirement type to find all DOORS Next requirements, your report might also return Requirement artifacts that are published by the EWM application. To exclude EWM related artifacts from your report results and report only on DOORS Next requirements, select the nested Requirement type, and in the Limit scope section, select only DOORS Next projects.

Combined artifact types: Merged (non-OSLC) artifact types are combined based on their name.

  • If two project areas in an application define semantically different types but use the same type name, Report Builder assumes they are equivalent.

    Example: If ETM project area Proj1 defines an artifact shape type QM Test Case and ETM Proj2 defines a QM Test Case that has different properties, the hierarchy in the Choose artifact section shows only one QM Test Case type.

  • If you select a merged type for your report, it shows resources from both projects, which might include unexpected results.

To avoid this problem, in the Limit scope section, select only the projects that contain the type that you want to report on.

Differences in the DN application:

  • DOORS Next merged shape types are shown under both Requirement and Requirement Collection.
  • In DOORS Next, a type can be used for both a collection and a regular artifact. A specific merged type shown in both places is the exact same type. The generated report does not infer which hierarchy you chose it from. The system examines all the artifacts that correspond to that merged type, whether the underlying artifact type is Requirement or Requirement Collection.

Creating traceability relationships

In the Trace artifact relationships section, the list of target shape types is shown hierarchically. If you choose an OSLC type, such as Requirement, the report results include all the Requirement types published to LQE that satisfy the traceability relationship, project scope, and conditions that you define.

Identifying equivalent but conflicting properties in merged shapes

Conflicting properties: Conflicts among properties can occur when the system (LQE + Report Builder) merges project-specific artifact shapes. These conflicts are indicated by a question mark  in the Add Attributes to the Report section of Report Builder.

Visual cue: Hover over the question mark  to identify and select the correct property (attribute). The tooltip typically includes the project name and indicates the reason for the conflict.

Effect on cross-project reports: If you add a property that has a conflict, your report might return unexpected results. These properties prevent cross-project reporting. The report results for that type are limited to the resources in the corresponding project.

Identifying equivalent properties across projects in an application

Different projects might use different names for an equivalent property. For example, in DN projects, a Feature in Project1 might use a property called Priority, and in Project2 that same property might be called Urgency.

Report Builder considers properties as equivalent when you specify the same RDF URI in the projects that use it.

  1. Complete one of the following steps:
    • DN application: Click Administration menu > Manage Component Properties > Artifact Types.
    • ETM application: Click Administration menu > Manage Project Properties > Custom Attributes.
  2. For an artifact type, specify the RDF URI for that property and then click Save.
  3. Repeat for each project that uses that property.

If the property is an enumeration, in each project where the values are equivalent, you must also specify an RDF URI for each value in the enumeration.

For details, see Best Practice: Enable Users to Specify URIs for Custom Attributes and Values on Jazz.net.

After a link is edited, Report Builder reports show the new link version regardless of whether the link direction or type was changed. For example, if you change a link of type Link to a Synonym link, the updated link is shown in reports that show requirements that are related through the Synonym link type.

Report Builder limitations

General limitations

You can report on DM artifacts in these ways:

  • By creating SPARQL queries in the Advanced section of Report Builder.
  • By using IBM® Engineering Lifecycle Optimization – Publishing (PUB).


Artifact types and information you cannot report on with Report Builder: The data warehouse and the LQE does not contain the following information. Instead, use the dashboard widgets for the specific ELM application.

      • EWM: Plan resources, work item comments and complexity
      • DOORS Next: Change set information; review or module hierarchy information; tags

Attributes with the same name: Sometimes a set of projects uses the same custom attribute, even if the attribute has a different name across the projects in an application. Across projects, when you specify the same RDF URI for the attribute, Report Builder shows only one instance of it. If the attribute has a different name across projects, Report Builder shows the first attribute name that it discovers. For example: Project1 might have an attribute called Priority; Project2 might have an attribute called Urgency, and both attributes have the same RDF URI. In Report Builder, the attribute might be listed by either name.

Editing SPARQL queries: To report on some types of artifacts or project elements, you must manually edit the query for your report in the Advanced section of Report Builder (for example, to add SPARQL code). After you save your changes, you can add only query parameters and columns to that report in Report Builder. You can no longer modify the links in Trace artifact relationships section.

Reporting about configurations: You can report on global configurations by using the Report Builder interface. To report on data about local configurations themselves, you must write SPARQL queries in the Advanced section of Report Builder. Use the LQE scoped by a Configuration data source for your report.

For example, to find out which local configurations refer to a specific requirement, create a Report Builder report about requirements, and replace the generated query with a custom SPARQL query that extracts data from the configurations directly.

Otherwise, Report Builder exposes configurations only in the Choose a Configuration menu when you run a report that uses the LQE scoped by a Configuration data source. Because you can pick only one configuration from this menu, the query that Report Builder generates cannot find the information that you want from all configurations.

Link validity: Using the Report Builder interface to report about link validity is not supported at present. You must write SPARQL queries to access this information. In the LQE application, you must have permission to read data in the TRS 2.0 for Link Validity Resources data group. If your report does not return link validity information, ask an application or project administrator to grant you this permission.

Translation: When you create a report that uses an LQE-based data source, the types and property names that you see in Report Builder are extracted from metadata that is published to the LQE by the lifecycle tools. Typically, this metadata contains only English names.

LQE scoped by a Configuration data source limitations

Manually created data sources: If you manually create LQE data sources in Report Builder, you must create the (all-data) LQE data source first, and then create the configuration aware LQE data source. Be sure to check the option to require configurations before you save the data source. After you save a data source, you cannot change this option.

Reports on configurations: Reports that are run against a configuration have access to all versioned artifacts in that configuration, and all non-versioned artifacts.

Errors when no configuration is defined: When Report Builder runs a query on the Lifecycle Query Engine scoped by a Configuration data source, a configuration must be defined in the request, or LQE generates an error. If Report Builder detects this situation, the query is redirected to the normal (all data) LQE data source, but the results might not be correct.

Both LQE data sources: Typical queries that must be redirected to the normal (all-data) LQE data source include queries to obtain the metadata for the data source and queries to find the available configurations. Therefore, Report Builder cannot create and run an LQE configuration-based report unless both LQE data sources are defined.

DOORS Next limitations

Change sets: Reporting on change sets is not supported at present. They are not published to LQE.
Components: When you create a component, consider using a template to populate it if a suitable template exists. By doing so, the component data is published to LQE and you can use Report Builder to report on the component and its versioned artifacts.

  • If you know you need to clone artifacts into your new component, select a template whose type system matches the component that you want to clone from.

If no suitable template exists to populate the component, ask your project administrator to create one to suit the project needs, or determine whether this new component is necessary.

Modules: Modules are represented in LQE as OSLC collections. To distinguish between modules and requirements collections, use different artifact types for each when you create them in the DN application. When you build your report, the artifact type that you choose determines whether you are reporting on modules or collections. For example, if you choose the modules-specific shape named “Use Case Module”, the report shows only requirements that belong to modules of type Use Case Module.


To report on requirements in modules:

  1. In the Choose an artifact section, click Requirement > Use Case Module.
  2. In the Trace artifact relationships section, define this relationship:

Traceability and link types: If two artifacts are connected by using any of the following OSLC link types, you can create a traceability report (starting with either artifact A or artifact B).
Following are the names that you see in Report Builder. The names in parentheses, (), are the link types in DOORS Next. For details, see the help topic about link types in requirements projects.

  • Affected By
  • Artifact Term Reference
  • Constrained By
  • Decomposed By (Parent Of, Child Of)
  • Elaborated By
  • Embeds (Embeds, Embedded In)
  • Extraction (Extracted, Extracted From)
  • Implemented By
  • Link (Link To, Link From)
  • References
  • Specified By
  • Synonym
  • Tracked By
  • Uses
  • Validated By

Some link types are bidirectional. In your Report Builder report, for the following link types in DOORS Next, you can define traceability links that start with the source of the link (the first link type that is listed in each pair). 

  • Elaborates, Elaborated By
  • Specifies, Specified By
  • Satisfies, Satisfaction

To create an equivalent report that starts with the target of the link, you might need to edit the generated SPARQL query in the Advanced section of your report to reverse the subject and object of the link.

 

© Copyright IBM Corporation 2020

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.
Feedback
Was this information helpful? Yes No 0 people rated this as helpful.