Author name

Tue, 11 Aug 2015

5 min read

Getting started with reporting on configurations (in technology preview)

Kevin Cornell, IBM
Last updated: June 29, 2015
Build basis: Jazz Reporting Service 6.0

You can use the Report Builder in the Jazz Reporting Service to create reports on versioned data in configurations. This article explains how to set up your environment and helps you understand some of the related limitations when you use Lifecycle Query Engine (LQE) as your data source. You can also do limited reporting on configurations using Rational Publishing Engine.

Use LQE to report on configurations and artifacts across different tools
Configuration management setup
- Enabling configuration management in CLM
- Enabling reporting on configurations in JRS
Reporting on configurations in JRS
Report Builder hints and limitations
Known Report Builder issues and work arounds
Related links

Use LQE to report on configurations and artifacts across different tools

To report on configurations that contain versioned artifacts, you must use Lifecycle Query Engine using Configurations as the data source for Report Builder; the Rational data warehouse does not support configurations.

In Report Builder 6.0, support for LQE-based reports is in technology preview. The metadata in LQE that is required by the Report Builder to create reports is incomplete, and not adequate for some reports. LQE also does not yet provide project-area-level access control. However, the following data does exist:

Configurations and versioned artifacts in Rational Quality Manager (RQM)
Artifacts from the initial stream of Doors Next Generation (DNG) configurations
Artifacts from projects that are not configuration-enabled

Report Builder 6.0 does not provide ready-to-use reports for any data source that uses either LQE or LQE using configurations. You must create your own reports from scratch.

Configuration management setup

Before you can do any reporting on versioned artifacts, you must enable configuration management in your CLM tools, and then enable reporting.

Enabling configuration management in your CLM tools

Both DNG and RQM support configuration management, but the administrator must first get an activation key. See Enabling configuration management in CLM 6.0 applications.
To set the activation key for each DNG and RQM application, go to the corresponding administration page.
```
.../<app>/admin
```
In each case, enter the key under Advanced Properties, in the Local Versioning Component field, and save.
Enable configuration management for each DNG and RQM project area on the Configuration Management page.
After you enable configuration management for a project area, its information is no longer sent to the data warehouse. Data is now sent to the LQE data source. For details, see No support for configurations in the data warehouse.
Click Explore Project and if there are no artifacts, create some. The initial configuration and its versioned resources are published to LQE.

Enabling reporting on configurations in JRS

After at least one RQM project area is enabled for configurations, when you click Connect to Data Sources in the Report Builder Admin page, you see two LQE data sources:

A Lifecycle Query Engine data source (including all the data), at https://<host:port>/lqe/sparql
Use this data source if the RQM projects are not enabled for configurations. If you use the Lifecycle Query Engine using Configurations data source, you won’t get any results.
A Lifecycle Query Engine using Configurations data source, at https://<host:port>/lqe/sparql-variable-config

If the projects are enabled for configurations, you must use this data source to get the proper versions of the artifacts. If you use the LQE data source, the result list might be very large and wrong because the property values defined in all versions of the resources are extracted, and all combinations of those values appear in the results.

If you do not see the data sources or results that you expect after you enable configuration management, or if you get an error connecting to the LQE with configurations data source, try to figure out the reason.

Make sure a project administrator has correctly configured the TRS feeds. For details, see Tracked Resource Set (TRS) feeds in LQE 6.0.

You must be a report manager to complete these steps:

Go to the Report Builder Admin page and make sure you are a report manager.
You cannot create any configuration-aware reports until at least one application publishes a TRS feed for a configuration of versioned artifacts. This means that, during the initial setup, Report Builder only creates the LQE data source. To add the LQE using Configurations data source, on the Admin page, click Connect to data sources.
The data sources are rediscovered, configuration data is automatically detected, and the LQE using Configurations data source is added.
Report Builder hides all LQE-based data sources until you activate the technology preview license. On the Data Sources page, click Activate Technology Preview and read the license information.
Set the LQE permissions so that Report Builder can query the LQE artifacts. For more information, see Managing user access to data sources in Lifecycle Query Engine.

Reporting on configurations

To create reports across configurations, in Report Builder, click Build and change the data source to LQE using Configurations.
Select the artifact type to report on.
LQE handles artifacts from each CLM application differently. The artifact section in Report Builder shows the base OSLC types. When you expand one, you can see the set of project-specific artifact types. To create a cross-project report, select the OSLC type, but not any of its derived types.

DNG and RQM use project-specific artifact types that extend the basic OSLC types, so you’ll see a separate “QM Test Case” listed for each RQM project area. Here are some details, and for more, see the Limitations on artifact types.
- When you expand the (OSLC) test case, you see a list of derived artifact types. You can only choose one because each entry is a distinct type. When you select one, the base OSLC type is unselected.
- When you expand a work item, you can choose from a list of known work item types, resulting in a generated condition in your report.
Optional: To set traceability links, select how your artifacts relate to those from other lifecycle tools. Click Add Relationship, select the relationship, and then click OK.
Remember that to report across projects or tools, you must use the OSLC types. If you don’t see the traceability relationships that you expect, see Cross-project links between artifacts.

For RTC and RQM projects, if you select requirements in the Traceability links, your report will not show any requirements, even if they exist. Report Builder warns you that results might be missed. To avoid this problem, don’t select any projects in the Limit scope section; instead, define a “Project Area” condition for the RTC and RQM artifact types and select the project you want.
In the Limit scope section, specify what projects to report on, and click Continue.
The list shows the projects that you can access in the data source that you selected. If the projects that you want are not in the list, see the administrator who created the data sources for Report Builder.

Your project area selection affects the artifacts that you can report on. For details, see Project area scoping.
From here on, create your report in the normal way. Set conditions to further refine the content, preview if you want, format as a graph or table, save and tag it, and share it. For details, see Reporting across projects with Report Builder.

Report Builder hints and limitations

No support for configurations in the data warehouse

The data warehouse schema does not support configuration management. When a project area in DNG or RQM is enabled for configurations, the artifacts for that project area are no longer updated in the data warehouse, and the existing project data in the data warehouse is marked as soft-deleted (archived). This operation cannot be undone.
In configuration-enabled DNG and RQM projects, any existing BIRT and RRDI reports are removed, since they do not work without the data warehouse data.
Reports that use the data warehouse data source do not return any results from project areas that use configurations.

LQE with configurations

Reports that are run using a configuration have access to all versioned artifacts in that configuration, as well as all non-versioned artifacts.
In 6.0, only RQM publishes configurations and versioned artifacts to LQE. DNG only publishes artifacts from the initial stream of a configuration-enabled DNG project area to LQE, but they are not versioned artifacts.
When a global configuration is created that associates configurations in DNG and RQM, that global configuration can be used in the Rational solution for Collaborative Lifecycle Management (CLM) tools. Although the global configuration is also published to LQE, it only contains references to the DNG and RQM configurations. Effectively, since DNG configurations are not published, the global configuration is the same as the associated RQM configuration.
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 saving the data source. After you save a data source, you cannot change this option.
When Report Builder runs a query on the LQE using Configurations data source, a configuration must be defined in the request, or LQE generates an error. If the Report Builder detects this situation, the query is redirected to the normal (all data) LQEdata source, but the results may not be correct.
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.

Tracked Resource Set (TRS) feeds in LQE 6.0

RTC and RQM define a second TRS feed for LQE to publish artifacts about processes, such as project area, team area, iteration, and timeline. During the upgrade, administrators must manually add these extra process TRS feeds. For more information, see Adding a process TRS as a data source.
In the main TRS feeds for RTC and RQM, the published data resources contain extra triples for the process resources, namely the project area. During an upgrade to LQE 6.0, administrators must index the RQM and RTC TRS feeds again.
RQM added a second TRS 2.0 feed, so instead of re-indexing the old RQM TRS 1.0 feed, the LQE administrator should remove the old feed and add the new one.

Artifact type limitations in 6.0

The Report Builder uses several types of metadata from LQE. Published vocabularies can define basic cross-project and cross-tool types, such as the OSLC types change request, test case, test plan, requirement, etc.

Some tools also publish vocabularies to define their own specific types, such as work item. Other tools, such as DNG and RQM, publish project-specific artifact types (OSLC resource shapes) that extend an OSLC type with additional properties (attributes and relationships) that are not defined by the underlying OSLC type. Report Builder uses this information to present the artifact types that you can report on.
RQM artifact types include the name of the corresponding project area so that the report author can tell which project they are associated with. Unfortunately, the names of the DNG artifact types don’t contain the project area name and can’t be distinguished from those in other DNG project areas. The artifact selection list in the Report Builder includes only one set of artifact types, which seems to correspond to the last DNG project area created. Therefore, you cannot report on requirements using a DNG artifact type if the resource resides in a different DNG project area. However, you can use the base OSLC requirement types.
RTC does not publish any project-specific artifact types to LQE. Report Builder uses a published RTC vocabulary that extends the base OSLC change request type, so you can report across RTC projects. However, you might encounter problems if you report on work items across different tools that publish change requests. The OSLC change request type is currently hidden in the Report Builder.
Report Builder hides many work item properties such as “filed against” because the data is missing in LQE. In a work item, the values for enumeration properties are URIs rather than readable values.
Some work item properties such as business value, impact, priority, risk, severity, and story points have possible values hard-coded in Report Builder, as they are defined in the Money-that-Matters sample project. If a different project template is used to create an RTC project area, or if the administrator assigns specific external URIs to the enumeration values, Report Builder cannot filter or display the enumeration value names, and displays the URIs.

Cross-project links (between artifacts)

For configuration-enabled projects, DNG only publishes artifacts for the initial configuration. You cannot create a report to find links between versioned artifacts in DNG and RQM or RTC if the DNG artifacts are in a child configuration. A DNG artifact in a child configuration that links to an RTC or RQM artifact is not included in the LQE index at all. Conversely, links from RTC and RQM artifacts to DNG artifacts in a child stream cannot be resolved because the DNG artifacts are not in the index.
Any cross-project reports that include DNG artifacts (requirements) are limited to a non-enabled project or the initial stream in a configuration-enabled DNG project. You can use any configuration in an RQM project when creating links between test artifacts and requirements, as long as a global configuration associates the RQM project configuration with the DNG project’s initial configuration.

Project area scoping

When you select a project-specific artifact type in Report Builder, the report results only include artifacts of that type. Since the artifact type is project-specific, your choice effectively limits the scope to the corresponding project area. To report across projects or tools, you must use the OSLC artifact types. Such reports are limited to the attributes and relationships defined by the OSLC types.
In 6.0, only RTC and RQM publish project area information to the LQE index. If you create a report that uses only artifact types for RTC and RQM, you can limit the scope of the report to those project areas in the Limit scope section of Report Builder. You cannot limit the scope by DNG project areas.

Known Report Builder issues and work arounds

Errors in SPARQL queries:
If the Report Builder generates a SPARQL query with a syntax error, the error message usually gives you the line number and column where the SPARQL syntax is incorrect.
In the Report Builder, on the Format results page, open the Advanced section in the editor and examine the generated query. You might be able to find the SPARQL statement that is causing the error and possibly alter your report definition to fix it. Do not try to fix this manually; go back to the report definition in the UI.
If you cannot fix the error, contact IBM Support or open a defect on Jazz.net and provide both the error message and the generated SPARQL query.
Missing relationships in traceability reports:
Some relationships might be missing when you try to create a traceability report.
With the removal of back links in 6.0, links are now one-way. To understand how links work between artifacts in different tools, see the diagram in this topic. A relationship property between two artifacts in LQE might contain only a reference (link) in the source artifact. The metadata for that source type includes the relationship property (to the target type), but the metadata for the target type does not contain a relationship property to the source type.
The Report Builder can identify such a property as a reversible relationship. For a reversible property, the Report Builder adds a relationship property into the metadata for the target type, where the target of that new property is the source type. Then the SPARQL query for the new relationship property discovers the reference to the target artifact in the source artifact. However, not all possible reversible relationship properties have been identified. In addition, the metadata for some target types might still define a relationship property to the source type (if the back link existed), but none of the corresponding target resources actually contain a value for that property.
Scalability issues with more than 50 RQM project areas:
Each RQM project area defines a set of project-specific artifact types. If you have more than about 50 RQM project areas and you try to create a traceability relationship with a target of a test artifact type, the server URI can be longer than most browsers permit. Usually when you select such a relationship, the UI shows a list of target types to choose from, but when the URI length is exceeded, you get an error and no list is shown. There is no known workaround.
Inability to modify a report on an RQM artifact type:
If you create a report using an RQM project-specific artifact type, and a condition is defined for a property of that type, you can run the report, but it cannot be edited or modified later. If you try to modify the report, you get an error indicating that a condition exists for an attribute that does not exist. There is no workaround.

About the author

Kevin Cornell is a member of the Rational Reporting Team within IBM in Ottawa. He can be contacted at kcornell@ca.ibm.com.

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?

1 person rated this as helpful.