Managing data sources for Report Builder

Edit online

As an administrator with Jazz administrative privileges, or a report manager, you can add and edit Report Builder data sources. For example, you can update the password that is required to connect to a data source, or specify a new location for a data source as part of balancing workload among servers in a distributed environment.

Before you begin

  • Report Builder must be installed and registered as an application with Jazz Team Server.
  • If you are using Report Builder with IBM® Engineering Lifecycle Optimization - Engineering Insights, Lifecycle Query Engine (LQE) must be installed and registered as an application with Jazz Team Server.
  • The Java™ Database Connectivity (JDBC) driver for your database type must be installed as part of the Report Builder installation.
  • You must have Jazz administrative privileges or be a report manager.

About this task

Data sources identify the location of the data stores that are used by queries.
Important: Lifecycle Query Engine is the data source for reporting on projects with or without configurations; however, there are considerations. For details, see Getting started with reporting by using Lifecycle Query Engine data sources on Jazz.net.

Remember, after you enable configuration management for the first time in either an RM or QM project area, a Report Builder administrator must refresh the data sources list. See the Connecting to data sources section.

Connecting to data sources

Edit online

After a data source is added, after you enable configuration management for the first time, or immediately after the installation of Report Builder, an administrator must establish a connection to it before users can use reports on their dashboard.

Before you begin

A data source must exist, and you must know the password.

About this task

There are three scenarios for connecting to data sources:
  • Immediately after installing and configuring Report Builder

    An administrator with Jazz administrative privileges must connect to the data source that was installed as part of IBM Engineering Lifecycle Management that uses Report Builder.

  • After enabling configuration management for the first time

    After you enable configuration management for the first time in your solution (in any requirements management or quality management project area), wait for the TRS feeds to refresh LQE; by default, this occurs every 60 seconds. The LQE scoped by a configuration data source, which you use to report on data in configurations, is available only after the first project that you enable publishes a configuration. For details about TRS feeds and refresh rates, see the related topic about managing LQE data sources.

  • After adding subsequent data sources

    After an administrator or a report manager adds a data source, they must also establish a connection to it.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. Click Connect to data sources.
  3. Optional: To view or edit the data source properties, click the Administration icon Gear icon for administration on the product banner and select Data Sources or click Data Sources in the Connect to data sources pane.

Results

The Setup page confirms that Report Builder can communicate with the data source. You can now import queries and select report managers. Report managers can then add and edit data sources.

Adding data sources

Edit online

If Report Builder does not have a data source, an administrator with Jazz administrative privileges or a report manager can add one.

Before you begin

You must know the data source type, and depending on the type and vendor, the properties that are required to connect to it.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. Click the Administration icon Gear icon for administration on the product banner and select Data Sources or click Data Sources in the Connect to data sources pane.
  3. Click Create a Data Source.
  4. Enter the data source name, description, type, and required properties; then, click Save.

Results

The data source is listed on the Data Sources page. You must connect to the data source, as described in Connecting to data sources.

Adding data sources for configurations

Edit online

Inconsistent type definitions across project areas make reports difficult to reuse and can produce unexpected results, such as duplicate attributes. To prevent this scenario, you can create a data source based on a specific configuration to ensure that a specific version of the type system (custom attributes, types, links, enumerations) is used for reporting. When building and running reports, team members see only the types from the configuration for the data source.

When team members build reports that use a configuration-specific data source, the type definitions in that configuration are used for fetching report results.

Note: Create these data sources sparingly. Even when not in use, they consume resources (disk storage, memory) for tasks such as refreshing each data source's type system model. Consider sharing one type system for all teams. For details, see these related topics:

Before you begin

  • On the Data Sources page, ensure that at least one Lifecycle Query Engine scoped by a configuration data source exists.
  • You must be familiar how the global configurations in a project area are related.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. Click the Administration icon Gear icon for administration on the product banner and select Data Sources or click Data Sources in the Connect to data sources pane.
  3. In the list of data sources, click a Lifecycle Query Engine scoped by a configuration data source.
  4. In the Advanced section, click Create a configuration-scoped data source.
  5. Follow the prompts to choose the configuration to report on, and click Choose.
  6. Configure the remaining data source properties to suit the needs of your project.
  7. Click Save.

Results

The data source is listed on the Data Sources page. You must connect to the data source, as described in Connecting to data sources.

When team members build reports based on this data source, they'll see only the types that belong to the configuration that you choose. To ensure accurate results when they run reports, they must choose a configuration that is related to the configuration that the data source is based on. For example, if the data source was created by using the Engine_v2.0_Baseline1 baseline, when they run their report they must choose a configuration that can be traced back to Engine_v2.0_Baseline1.

Team members can group reports by data source on the My Reports and All Reports pages by choosing the Group by data source option from the list on the toolbar.

Editing data sources

Edit online

In general, do not edit data sources because it can have implications for data collection jobs and reports. If you must change a data source property, ensure that you understand other corresponding changes that you must make.

Before you begin

You must be connected to a data source. You must be an administrator with Jazz administrative privileges or a report manager.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. Click the Administration icon Gear icon for administration on the product banner and select Data Sources or click Data Sources in the Connect to data sources pane.
  3. In the Actions column near the data source, click Actions, and select the action to complete.
  4. If you edit any of the data source properties, click Save.
  5. Return to the Setup page, and click Connect to data source to ensure that the connection is established.

Archiving data sources

Edit online

Over time, you might create many data sources for specific configurations so that teams can generate consistent reports based on the type systems of those configurations. However, you might use only a subset of these data sources at a time. Data source type system model is computed and stored in memory. To free up storage and memory, you can archive the data sources that teams no longer run reports against. You can restore archived data sources later if you need them.

Before you begin

  • You must be an administrator with Jazz administrative privileges or a report manager.
  • Ensure that no frequently run reports and dashboard widgets use this data source.

Procedure

  1. In a browser window, open the Data sources page at https://server:port/rs/endpoint.
  2. Click the Actions menu near the data source name and click Edit the data source.
  3. Click Archive and follow the prompts.

Results

After you archive a data source:
  • It gets removed from the list on the Data Sources page.
  • Team members can no longer build or run reports on an archived data source. Reports that use it are no longer shown on the My reports and All reports pages.
  • Dashboard widgets that are based on reports for this data source cannot run. Team members can remove affected widgets from dashboards.

What to do next

To show archived data sources in the list on the Data Sources page, select the Show archived data sources checkbox. For details about restoring data sources, see Restoring data sources.

Restoring data sources

Edit online

Restoring a data source takes a few minutes. You might restore a data source for regulatory purposes or to re-create an environment to address a product recall.

Before you begin

You must be an administrator with Jazz administrative privileges or a report manager.

Procedure

  1. In a browser window, open the Data sources page at https://server:port/rs/endpoint.
  2. Select the Show archived data sources checkbox.
  3. Click the Actions menu near the data source name to restore and click Edit the data source.
  4. Click Restore.
  5. If the data source is based on a specific configuration, you must refresh its type system model. Click Refresh.

Results

After you restore a data source:
  • It shows in the list on the Data Sources page.
  • Reports that use this data source are restored to the All Reports and My Reports pages.

Refreshing the type system model

Edit online

For each reporting data source, Report Builder generates a memory-based type system model hierarchy: a collection of closely related meta-types, based on the type URIs. Report Builder loads the type system models when you open the report editor, using the cached type system model to populate the user interface (for example, the entries and domain groupings in the Choose an Artifact section), and to generate the queries for the report.

About this task

Report Builder generates and caches the reporting type system model, refreshing it on a defined schedule. When applications publish modified type system model to the data warehouse or LQE that affects the type system model, these changes might require a type system model refresh. To refresh the reporting type system model:

Procedure

  1. Open Report Builder (https://server_name:port/rs/endpoint) .
  2. Click the data source that you want to refresh, for example the data warehouse.
  3. Click Refresh.
    A message confirms that the refresh is complete. See Refreshing the type system model for more details about changes that require a type system model refresh.
    Note: The Refresh button is not enabled for the Lifecycle Query Engine scoped by a configuration data source, as it depends on the Lifecycle Query Engine data source's type system model. It is enabled only for the Lifecycle Query Engine data source that contains the type system model. You can use the navigation icon Browser icon with arrow for navigation on the Lifecycle Query Engine scoped by a configuration > Data source page to go to the Lifecycle Query Engine > Data source page for refreshing the type system model. You cannot delete the Lifecycle Query Engine data source if there are associated configuration scoped data sources.

Preventing unauthorized queries against the data warehouse data source

Edit online

To prevent queries against tables that do not contain report data, create a user ID that has limited access in the database application. Then, in Report Builder, specify that database user in the connection information for the data warehouse.

Before you begin

  • This task applies only if your database application requires a database user ID and password to connect to the data warehouse. If you are not sure, on the Data Sources page, select the database vendor and see the sample value for the Data source location field.
  • You must be an administrator with Jazz administrative privileges or a report manager.
  • The data warehouse must be installed.

About this task

Note: This information applies only to the data warehouse. Access to LQE data sources is determined by project area membership, so team members cannot query tables that are related to projects they don't belong to. See the related topic for details.

If an administrator has not restricted the manual editing of queries, team members can edit the generated SQL or SPARQL queries in the Advanced section of the Report Builder interface. To prevent queries against tables that do not contain report data, use a database user ID that has access only to the data warehouse tables and views, and any custom tables for your reports.

You do not have to change the user ID and password on the Data Warehouse Connection page in the JTS administration section because other IBM Engineering Lifecycle Management (ELM) applications do not provide a way for team members to edit queries.

To further restrict unauthorized queries, limit manual query editing to report managers. See the related topic.

Procedure

  1. Complete these steps in the database application that contains the data warehouse tables:
    1. Create a user ID.
    2. Grant that user ID access read access to these items:
      • Tables and views in these schemas: RICALM, RIDW, and RIODS
      • Custom tables that contain information that your teams report on
  2. In Report Builder, go to the Data Sources page at https://server:port/rs/endpoint, and click the data warehouse link.
  3. Change the following fields to use the ID and password that you careted in step 1:
    1. Data source location: Change the user ID. The format of this field depends on the database vendor.
    2. Data source password: Specify the new password.
  4. Optional: To ensure that only report managers can manually edit the SQL or SPARQL queries that generate the report, select Restrict query editing to report managers.
    Enabling this option changes which sections of the Report Builder interface that you can use. See the related topic for details.

Results

Report Builder can now access only those tables that the database user ID can access. Team members can report only on data in those tables.

If you change the privileges of that ID in the database application, no extra steps are required to update Report Builder.