Getting started with reporting by using Lifecycle Query Engine data sources in version 6.0.3

Catherine Trinkwon, Information Developer, with contributions from the Jazz Reporting Service team at Persistent Systems Ltd.
Last updated: 15 June 2018
Build basis: IBM Jazz Reporting Service version 6.0.3

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. You can include designs from Design Manager by editing the SPARQL query in the Advanced section of Report Builder.
• 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 using Configurations 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 Rational Publishing Engine 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 a CLM dashboard.

Contents

• What’s new
• For administrators:
  • What’s new
  • Getting started
  • Enabling configuration management in your CLM tools
• Choosing an LQE-based data source
• Using reports from version 6.0 and earlier
• Reporting on current data
• Reporting on metrics and historical trends
• Running cross-project reports
• Details of Report Builder capabilities:
  • Tracked resource set (TRS) feeds in LQE 6.0.3
  • Synchronizing project membership information
  • Choosing an artifact type
  • Creating traceability relationships
  • Identifying equivalent but conflicting properties in merged shapes
  • Identifying equivalent properties across projects in an application
  • Reporting on edited links
• Report Builder limitations
  • LQE scoped by a Configuration data source
  • DOORS Next Generation

---

What’s new

Simplification of the LQE artifact type hierarchy: In the Choose an artifact section, the quality management group lists all the Rational Quality Manager artifact types. If you are using multiple quality management tools, the artifact types are grouped by tool.

Although only one Requirements Management product (DOORS Next Generation) publishes requirement types, artifact types are grouped under Requirement and Requirement Collection because each of these types is extended by multiple DNG artifact types.

Artifacts and attributes now available for reporting

• Complex custom attributes now available for reporting: Work Item, Iteration, Timeline, Release, Category, Contributor, Project Area, and Team Area.

  Some of these attributes correspond to an existing artifact type (such as Work Item, Iteration, Timeline, and Release) and are now available as traceability links from Work Item. The name of the link includes the name of the attribute and the word “(Custom)” in the appropriate locale. All the other complex attributes (Category, Contributor, Project Area, and Team Area) are available as additional attributes of work items.

• Report on components or configurations (baselines and streams): You can now report on components, baselines, streams, and global configurations. Components and configurations themselves are not versioned, so you must use the Lifecycle Query Engine data source and not the LQE scoped by a Configuration data source.
• New “type” property for Requirement and Requirement Collection types: The type enumeration attribute was added so that you can report on multiple requirement types.

Support for components

In DNG and RQM, a configuration-enabled project area can have multiple components that logically organize its artifacts. Each component can have multiple configurations (streams and baselines) to organize the different versions of the component’s artifacts.

In configuration-enabled projects, artifacts now have an extra property indicating what component of the project area they belong to. Likewise, every configuration also has an associated component. Therefore, to report on artifacts in specific configurations of components, you must select the LQE scoped by a Configuration data source.

In Report Builder, the artifact type property that indicates its component is shown as an enumeration attribute, and not as a relationship property. When you build your report, you can add conditions to restrict the artifacts that are returned in a report about specific components. Although the configuration you choose when you run a report indirectly restricts the components, a global configuration can include multiple local configurations from the same tool and thus multiple components. When you add a condition for the “component” attribute, the possible values are shown in a two-level hierarchy of project areas and their components.

In addition to conditions, you can add a “component” column to a table report. In this case only the component name is shown and not the project name.

In the configuration picker on the Run report page, the four-level hierarchy (project, component, stream, and baseline) keeps the configurations organized. In addition, you’ll always see a “component” dynamic filter and many times a “project” filter. Both the project and component filters are loosely connected to the configuration picker.

• If you don’t select anything in either the project or component filter, the configuration picker shows all projects, all components in those projects, and all streams (and baselines) associated with each component.
• If you select one or more values in the project filter, only components for those projects are listed in the component filter and configuration picker.
• If you select values in the component filter, only those components are shown in the configuration picker along with their streams.

Detecting multiple versions of an artifact

A local configuration of a component has only one version of each artifact. An artifact is uniquely defined by its URI (concept URI) and not by its name. When child streams or baseline configurations are created, each such configuration can link to a different version of the same artifact.

A new attribute called “Count artifact versions” has been added to all artifact types in Report Builder. Use this attribute only for reports that use the LQE scoped by a Configuration data source. Because of how this version count is computed, you cannot add a condition for this attribute. You must use the Add attribute columns button. However, when the attribute of an artifact type is added as a column to a report, the resulting count indicates how many versions of the artifact instance exist in the configuration that is used to run the report. In most cases, the count will be “1”, indicating a single version of the artifact. A larger count indicates component skew.

To find all artifacts with multiple versions, add the Count artifact versions attribute, and make it the first column used for sorting, in descending order. When the report is run, all the artifacts with multiple versions are listed at the top of the report results.

Reporting on historical trends

You can now create historical trend reports from an LQE data source. Before you build the report, an LQE administrator must enable metric collection.

The workflow for creating a historical trend report against an LQE data source is the same as for a Rational Data Warehouse data source. Select the trend to report on, choose the date range to run the report against, and format the resulting graph. Currently, the set of trends available is a subset of the trends available for the data warehouse. After you select one or more trends you can configure the graph in the same way as trends using the Data Warehouse data source.

Reporting on artifacts from Design Manager web client and Rhapsody Design Manager

Reporting on model information from Rational Rhapsody Design Management is in technology preview. If the preview is not enabled by your administrator, you can report on DM artifacts by writing SPARQL queries in the Advanced section of Report Builder. If you are the administrator, read about enabling the technology preview in this topic.

In Report Builder, create a report about any artifact type. Then, replace the generated query text in that report with your custom SPARQL query.

Editing SPARQL queries: To report on some items, you must edit the query text (including SPARQL code) in a report. Before you begin, check whether query editing access is restricted for the data source that you use.

To check permissions:

1. In Report Builder, go to the Data Sources page at https://server:port/rs/endpoint, and click a data source name.
2. If query editing is restricted to report managers, only they can make the changes in the Advanced section.

To manually edit a SPARQL query:

1. Use Report Builder to create your report. For guidance about which LQE data source to select, see Choosing an LQE-based data source.
2. Name and save your report.
3. Return to the Format Results page. In the Advanced section, click Edit and OK to disable the Report Builder interface.
   If you cannot click the Edit Query button, ask your report manager to do the rest of these steps.
4. Edit the query: remove all references to the original artifact type, and replace the existing query text with SPARQL code to access the item you want to report on.
5. Validate the query.
   Important: If you manually edit and save the query text in the Advanced section, you can only use the Report Builder interface to add query parameters and columns to the report. You can no longer modify the traceability links.
6. Save and run the report.

---

For administrators

What’s new

Administrators can now configure LQE to collect data metrics that can be used to create historical trend reports. Metric collection is not automatically enabled. You must configure and schedule tasks to collect data. To learn how to create and schedule data collection tasks, read the product documentation.

Getting started

Before you can report on artifacts from the LQE-based data sources, you must activate and enable configuration management in the RM and QM applications. These steps are not required for Design Manager or RTC: Design Manager uses configurations but you don’t need to enable them, and RTC does not send information about versioned artifacts to LQE. Be sure to follow the steps in the Interactive Upgrade Guide.

Enabling configuration management in your CLM tools

1. Upgrade all Rational solution for Collaborative Lifecycle Management (CLM) and JRS applications to version 6.0.3. Report Builder cannot use the version 6.0 metadata that was published to LQE by the CLM applications.
2. Enable configuration management in QM and RM:
   1. Get an activation key. See Enabling configurations in CLM applications (v6.0.3).
   2. Set the activation key for the QM and RM applications. Go to the corresponding administration page:
      https://server:port/application_context_root/admin
      For the RM and QM applications, enter the key under Advanced Properties, in the Local Versioning Component field; then, click Save. Other CLM applications Jazz Team Server also have this advanced property, but you add the key to the property only in the QM and RM applications.
   3. For each QM and RM project area that will use 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.
3. Click Explore Project and if there are no artifacts, create some for the project. The initial configuration and its versioned resources are published to LQE.

---

Choosing an LQE-based data source

Before you enable configuration management in RM and Quality Management (QM) project areas, their information is sent to both the CLM data warehouse and LQE. After you enable configuration management in these project areas, they stop sending feeds to the CLM 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 Rational Engineering Lifecycle Manager can use Report Builder to report on data in the LQE scoped by a Configuration data source.

RTC does not support configuration-enabled projects areas, so it does not publish any versioned resources to LQE. All RTC data in LQE is compatible with all configurations.

Which LQE data source to use?

• LQE data source:
  
  • Report on RM and QM projects 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 will be meaningless. See this example.
  • Report across all configurations in an RM or QM configuration-enabled project area. Your report will contain information about all the versions of the selected artifact in those configurations.
    Consider this scenario: an enabled project represents a product, and each stream in the project 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 very large 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 RM or QM 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:
    • RM artifacts across RM components
    • RM and QM artifacts
    • RM and QM artifacts to DM artifacts
  • Report on a global configuration itself (not the artifacts in the configurations that it references). Use a SPARQL query in the Advanced section.
  • Report on model information that is managed by Design Manager. Use a SPARQL query. If you are not in a production environment, you can report on Rhapsody DM data by enabling the technology preview.

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 this topic in the product documentation.

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

---

Using reports from version 6.0 and earlier

• You must recreate all existing reports created in Report Builder version 6.0 that use LQE or LQE using Configurations data sources, because this capability was a technical preview feature in that version.
• Existing Report Builder reports for the data warehouse should still work in version 6.0.3.
• Recreate manual Report Builder reports with custom SPARQL queries if they no longer generate the results that you expect.
• SPARQL queries created in Rational Engineering Lifecycle Manager should continue to work if the corresponding metadata assumptions are still true. For example, a query that assumes that artifacts have back-link properties will not work, because back links are no longer created and links in the “reverse” direction are not stored.
  • Practitioners, see Cross-project links
  • Administrators, see Links across project areas in configuration

---

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 beside the section to change.

Procedure

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

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 or to Rational Publishing Engine as a document-style report. You can also export a report graph to an image file.

Step 1. Choose data

1. Open Report Builder at https://host:port/rs, and click Build.
2. Choose a report type.
   1. Select Current Data (table or graph) to report on the latest information about artifacts in and across projects.
   2. Select the LQE data source for what you want to report on: one configuration or all configurations. Click the pencil to select a different data source. To help you decide which data source to select, see Choosing an LQE-based data source.
3. Limit the scope.
   Choose the project to report on and click Continue. If you don’t select any projects, the report includes all projects you can access.
   
   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.
   
   The projects that you select affect the artifact types that you will see in the Choose an artifact and Trace artifact relationships sections. For example, if you don’t select a QM project, you cannot report on QM artifacts, and you cannot create traceability relationships that include QM artifacts (for example, a report that shows requirements and the test cases that validate them).
   
   • For Lifecycle Query Engine, only projects that are not enabled for configurations are listed. If you select List all projects when reporting on configurations themselves, configuration-enabled projects are included in the list. To limit the configuration results, select specific projects. Reporting on a mix of configuration-enabled and non-enabled projects might generate invalid results because there might be several versions of the same artifact.
   • For Lifecycle Query Engine scoped by a Configuration, only configuration-enabled projects are listed. When you run the report, you must choose a configuration.

   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.

   You must know which RM and QM projects are configuration-enabled. Select only one type (enabled or not enabled projects). This constraint does not apply to RTC projects, which are compatible with either type of RM and QM project.
   For example, to show related work items, select the correct RTC projects even though they are not configuration-enabled; otherwise, you cannot add the relationship to the work items in the Trace artifact relationships section.

   If don’t see the project that you want, see the administrator who created the data sources for Report Builder.

4. Choose an artifact.

   Select an artifact or specific types, and click Continue. 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.

   The top-level artifact types correspond to OSLC types. Nested artifact types correspond to merged artifact types from one application. If you select an OSLC type, your report might contain results from any application that publishes that type.

   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.

   For details, see “Choosing an artifact type” later in this article.

   Tip: To report on requirements in Requirements Management modules, click Requirement > Use Case Specification, and in the next step, define a Uses trace relationship between the Use Case Specification and Requirement artifact types. For details, see Modules later in this article.

5. Optional: Trace artifact relationships.

   Explore how your artifacts are linked to other artifacts from the same, or from other lifecycle tools. Click Add a relationship. For each artifact type, you see all the existing relationships. Pick one, and click OK.

   Note:

   • Reporting on requirements in modules: if you chose Requirement > Use Case Specification in the previous step, define a Uses trace relationship between the Use Case Specification and Requirement artifact types, as shown in Modules.
   • 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 details, see DOORS Next Generation limitations.

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

   Example: To show that a requirement is validated by a test case, click Add a relationship, and under QM Test Case, select Validated by. To also list the work items associated with the test cases, click Add a relationship > Related Change Request and click OK. To specify what type of related change request to add, select Work Item and click OK. In the Set conditions section, you can further define the relationships.
   

   Tip: When you name and share your report, include the traceability link names so that team members can find your report easily.

   From one artifact, you can trace multiple relationships to other artifacts, and show all the results in the same report. Choose how to combine the results:

   • Merge: The results are shown in the same rows.
   • Append: The report shows the results for each traceability relationship. All the source artifacts are in the same column.
   • Append in new columns: To count the source artifact relationships separately, append the results in different columns.

   
   

   For each relationship that you trace, you can set conditions. For step-by-step instructions on how to build this type of report, read the Tutorial.

   Example: Trace how features are linked to work items, test cases, and child requirements, and see all the relationships in a single table.

   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 X beside the item name.

   To change the name of an artifact in the traceability box, double-click its name and type the new one. 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. For example, if you want your report to refer to related defects instead of change requests, double-click Change Requests in the traceability diagram, and type Defects.

   After you build the artifact relationships, click Continue.

6. Set conditions.

   Set conditions to further refine your report and further identify relationships among artifacts.

   You can set conditions for any attribute of the artifact type that you selected, and any attribute of the related artifact types in your traceability paths.

   For example, to show that a requirement is validated by a test case, select the Validated by relationship under QM Test Case. Then, set a condition to focus only on approved test cases. For the artifact type QM Test Case, choose the attribute Has Workflow State, and set the value to Approved.

   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.

   Tip: If you add the Component attribute as a column but do not add a condition for it, when you run your report you can select a component to filter the results that you see.

   1. Click Add condition and select an artifact type.
   2. Choose the attribute that you want to specify a condition for, and select the values to return the artifacts you want.
   3. Click Add to keep the window open so that you can add other conditions. Otherwise, click Add and Close.
   4. Optional: Change the lock to control whether people can or must supply a value for the condition when they run the report.
   
   

   Sometimes several projects use the same custom attribute, and although the attribute has the same name across the projects, its ID is different in each project. To report on this attribute, add a condition for each project. Then, to consolidate them in your report, group the attributes by using an OR condition.

   You can assign the same RDF URI to custom attributes that are used in multiple projects. For details, see Identifying equivalent properties across projects in an application.

   Example: Each project you report on has a risk status attribute, and it means the same to each project. Select this attribute for all the projects; then, group the attributes, and add an OR condition between them. To show the results in one column, instead of one column for each project, see the “Show the report as a table” section in this topic.

   • To edit a condition, click the pencil icon beside it.
   • To create logical groups of consecutive conditions, select them, and click Group.
   • To remove conditions, select them, and click Remove.
   
   After you create your conditions, click Continue.

Step 2. Format results

1. Choose whether to show the report as a table or a graph.
2. Click Refresh to see a subset of the data for your report. To see all the results, you must run the report.

For details, see this help topic.

Step 3. Name and share the report

1. Give your report a name and a description. The description is important to help other team members find your report if it is public.
   Note: You might include the traceability link names that you built in the Trace artifact relationships section, so that team members can find your report easily.
2. Tag your report to make it easier 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 and visible to everyone): 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 creator and owners): 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 owners. 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.

To export your report results, click Export near the upper right. You can export your results to a spreadsheet, to Rational Publishing Engine as a document-style report, or export a report graph to an image file. See the links to help topics at the end of this article.

---

Reporting on metrics and historical trends

Before you report you historical trends, you must configure LQE to collect metrics. Then you can report on metrics and historical trends by following the procedure in this help topic.

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.
   
• Requirements Management:
  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 have created a cross-project report to show QM test cases and the RM 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.

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 will return results based on the traceability relationships and conditions defined in the report. For example, if you’re reporting on specific projects, you won’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 will not see any results.
• Hierarchy: Configurations are shown hierarchically:
  

  You can see these levels in the image:

  • Components: A configuration-enabled project area can have multiple components that logically organize its resources. Each component can have multiple configurations that contain the different versions of the component’s artifacts.
  • Streams: Global streams and local streams that are not associated with a global stream.
    To reduce clutter, local streams that belong to a global configuration are not shown, unless those streams have baselines.
    For example, you cannot select the “Config Banking (RM) Initial Stream” stream, but you can expand it to see its baselines and select one to report against.
  • Baselines (nested): All baselines created from the preceding stream.
  
  

  Streams that do not publish project information to LQE are shown at the bottom of the hierarchy (none shown in the preceding image).

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 4 (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 version 6.0.3

TRS feeds: If you add a TRS feed for an application that is registered with a different Jazz Team Server (JTS), all user URIs in the artifacts refer to the user registry in that other JTS 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 Rational Jazz Team Server data source permissions. This includes all JTS 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.3, 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 (TRS 2.0 for DOORS Next Generation Process Resources, TRS 2.0 for GC Process Resources, 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 10 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 a CLM application, you might change this interval to 1 minute so that the new project members can see the information 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 Generation requirements, your report might also return Requirement artifacts published by the Design Management (DM) application. Report Builder does not support DM types at this time. To exclude DM requirements from your report results and report only on DOORS Next Generation requirements, select the nested Requirement type, and in the Limit scope section, select only DOORS Next Generation 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 QM project area Proj1 defines an artifact shape type QM Test Case and QM 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 Requirements Management:

• Most DOORS Next Generation merged shape types are shown under both Requirement and Requirement Collection.
• If a specific merged type is shown in both places, it 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 RM 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:
   • RM application: Click Administration menu > Manage Component Properties > Artifact Types.
   • QM 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 should 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.

Reporting on edited links

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

Artifacts from DM applications: This information is available in the LQE, but you cannot access it in the Report Builder interface. You must create SPARQL queries to report on artifacts from Rhapsody Design Manager or the Design Manager web client. If you are not in a production environment, and the administrator enabled the technology preview, you can report on Rhapsody design data by using the Report Builder interface.

Artifact types and information you cannot report on with Report Builder: Neither the data warehouse nor the LQE contain the following information. Instead, use the dashboard widgets for the specific CLM application.

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

Artifacts from DOORS: Reporting on DOORS (DOORS Web Access) artifact types is not supported at this time. If an LQE TRS feed exists for the DOORS application, you might see the corresponding artifact types on the Choose data page in the Choose artifact > Requirements Management section, but reporting on them is not supported.

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 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 only add 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 now 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. See editing queries for details.

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 you want from all configurations.

Link validity: Using the Report Builder interface to report about link validity is not supported at this time. You must write SPARQL queries to access this information. See editing queries for details. 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 saving 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, as well as 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 Generation limitations

Components: When you create a component, use a template to populate it. 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 you will clone from.
• If you manually set up the component structure later (by importing a type system), the data is not published to LQE, and you can’t use Report Builder to report on that component or its versioned artifacts.

Modules: To report on requirements in modules:

1. In the Choose an artifact section, click Requirement > Use case specification.
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).
These are the names that you see in Report Builder. The names in parentheses, (), are the link types in DOORS Next Generation. 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

In your Report Builder report, for the following link types in DOORS Next Generation, you can define traceability links that start with the source of the link (the first link type listed in each pair). To create an equivalent report that starts with the target of the link, you must add SPARQL code to the query in the Advanced section of your report:

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

---

© Copyright IBM Corporation 2017