Managing data sources

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.

Following are the tasks that are related to data sources:

Viewing data sources

View list of all available data sources, including default, active, and archived data sources.

About this task

Data sources identify the location of the data stores that are used by queries.

Procedure

  1. Click Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources along with some information about each data source. You can resize and customize the columns in the data source table listing to meet your needs.
    Column name Description
    Server Displays the root name of the server and the URL.
    Name Displays the name of the data source and the name that is shown in the URL.
    Last refresh Displays the date and time and status of the last type system model refresh.
    Connection status Indicates if the data source is connected.
    State The data sources can have two states, Active or Archived. When a data source is set as default, it is indicated by 'Active (default)' in the State column.
    Type A data source can be one of three types: Complete, Configuration scoped, and Type scoped.

    Complete - This type of data source is recommended to be used only for artifacts that are not versioned - work items, components, and so on.

    Configuration scoped - This type of data source is recommended to be used for reporting on artifacts that are versioned - for example, it is part of a local or global configuration. This is because the same artifact might have multiple versions. If you do not use configuration that is scoped and you use the Complete data source, then all versions are considered as part of the report. As a result you get a cross product of all properties for each artifact, and it does not work.

    Type scoped or Type filtered- This type of data source is for customers that cannot create a common type system and have incompatibilities in them. This situation makes it hard and confusing for their team level reports to be created. The reason is because a type and attribute values might have differences but still have the same name.

  3. Click the name of a data source to view configuration details specific to that data source. You can also perform some actions from the data source configuration page.
  4. Click the More actions icon corresponding to the data source listed in the Data sources panel.
    • When the data source status is Active, and connection status is displaying as Connected, you can Set as default, Test connection, Refresh, Edit, Archive, or Delete.
    • When the status is Archived, there is no connection status and you can either Restore a data source, or Delete it.

Connecting to data sources

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.

About this task

You might connect to a data source in the following three scenarios:
  • 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 refresh action 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.

To discover and connect to a data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. If there are no data sources displayed, click Discover and connect data sources or Connect to search for a data source and connect to it. If the user tries to connect to a data warehouse server, then the user might be prompted to enter a password for the data warehouse.
  4. An Additional information requested dialog window is displayed, where the user needs to enter the Database password. If you do not have the password, click Skip and return to connect to the data source again when you have the password.
    Note: If you choose to skip the data warehouse data source, only that data source is skipped and rest of the LQE data sources will be discovered and connected.
  5. Else, if you have the password, enter it and click Connect. A success notification is displayed informing the user that the data source was successfully connected. Its status is also shown in the data sources table listing as connected.

Results

The 'connected' status of the data source on the Data source table listing page confirms that Report Builder can communicate with that data source. You can now import queries and select report managers. Report managers can then add and edit data sources.

Adding data sources

If Report Builder does not have a data source, an administrator with Jazz administrative privileges or a report manager can add one. Be sure to know the data source type and depending upon the type, and vendor, the properties that are required to connect to it.

About this task

To add data sources, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. Click + in the toolbar to create a data source.
  4. A Create data source form is displayed where you can specify a data source name, select the data source type and enter connection properties.
  5. After you have entered the required connection properties, click Test connection to verify whether a connection is being established with the data source. Once the data source is successfully connected, a green icon gets displayed.
  6. Click Create to create the new data source. A success notification appears informing you that the data source was successfully created.

Editing data sources

It is recommended that you 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.

About this task

To Edit an existing data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. For an existing data source, click Edit for the corresponding data source in the table listing or click the respective data source name in the data source list to edit the configuration properties. The data source configuration properties page is displayed.
  4. Modify the data source name, description, or any other properties; then, click Save to apply the updates.
    Note: The value for Data source type can be set only at time of creating a data source and cannot be edited.
  5. Click Refresh type system.

Adding data sources for configurations

Before you begin

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

About this task

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 and so on) 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:
To create type scoped data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. Identify the LQE or LQE configuration scoped data source that you want to use as the basis for the new type scoped data source. Click the More actions icon and click Create type scoped data source.
  4. A dialog displays where you select the configuration thy you want to use. To select the configuration you must first specify a domain, project area, and component (optional), and configuration, in order to filter the list of available configurations.
  5. Click Continue. The Create data source page is displayed. The fields for Name, Description, and URL are pre-populated depending upon the configuration that is selected by you in the previous dialog.
    Note: The Data source type field cannot be edited. By default, once the type scoped data source is created, the Require a configuration to run report check box is in selected state and disabled.
  6. Click Create. A success notification informs that the data source was successfully created. The Create data source page now gets displayed in edit mode. A new section for Change configuration gets displayed, where you can change the configuration to report on a more recent type definition scheme.

Changing configuration of a data source

You can change the configuration of an existing type scoped data source to report on a more recent type definition scheme.

About this task

To edit the configuration for a type scoped data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. Click Edit for the corresponding type scoped data source in the table listing or click the respective data source name in the data source list to edit the configuration properties. The Data source configuration properties page is displayed.
  4. In the Change configuration section, click the Choose configuration button.
  5. A dialog displays where you select the configuration that you want to use. To select the configuration you must first specify a domain, project area, component (optional), and configuration, in order to filter the list of available configurations.
  6. Click Continue to return to the data sources properties page. The fields for Name, Description, and URL are automatically updated based on your configuration selections.
  7. Click Save. A success notification informs that the data source was successfully updated.

Deleting an existing data source

You can delete a data source that might or might not be default, and has no reports that are associated with it, or delete data source with reports that are associated with it or delete a data source that has dependent data sources.

About this task

To delete an existing data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. In the data source table listing, click More actions for the corresponding item and select Delete from the options listed.
  4. A dialog window is displayed informing the user that the data source will be deleted permanently. If the data source that you are deleting is the default, the dialog allows you to select a different default data source.
  5. Click Delete to complete the delete data source action. The data source table listing is refreshed with the new default data source. A success notification is also displayed on the page, which informs you that the previous default data source was deleted and that the default data source was updated.
    Note:
    • If there are reports associated with a data source that you attempt to delete, then a dialog window informs you that the data source cannot be deleted. Delete the reports first and then try deleting the data source again.
    • If you attempt to delete a data source that has one or more dependent data sources, then a dialog window informs you that the data source cannot be deleted. Delete the dependent data sources first and then try deleting the data source again.
  6. Optional: Click Undo in the success notification, if you want to revert the delete action. If you click Undo the delete action for a data source that was set as default, then the Undo action also reverts the settings of the default data source.

Archiving an existing data source

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. 

About this task

To archive an existing data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. In the data source table listing, click More actions for the corresponding item and select Archive from the options listed or click the data source name and then click Archive on the Edit data source page.
  4. A dialog window is displayed informing the user that the data source will no longer be available for building or running reports and dashboard widgets that use the data source. If the data source that you are archiving is the one that is the default, the dialog allows you to select a different default data source.
  5. Click Archive to complete the archiving data source action. The data source table listing is refreshed with the new default data source, and the previous one is marked as archived. A success notification is also displayed on the page, which informs you that the previous default data source was archived and that the default data source was updated.

Restoring a data source

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.

About this task

To restore an archived data source, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. In the data source table listing, click More actions for the corresponding item and select Restore from the options listed or click the data source name and then click Restore on the Edit data source page. A success notification informs you that the data source was restored, and in the data source table listing it again shows the state as active instead of archived.

Refreshing the type system model

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

Note: Data sources that are scoped to a configuration share a type system model with the data source they are based on. You only need to initiate the type system model refresh from one of the data sources. Doing so will refresh all the related data sources.
To refresh a type system model, complete the following steps:

Procedure

  1. Click the Administration icon in the main menu bar of the Report Builder new user experience page. This action takes you to the Administration settings page.
  2. Click Data sources to view a list of all available data sources.
  3. In the data source table listing, click More actions for the corresponding item and select Refresh type system from the options that are listed or click the data source name and then click Refresh type system on the Edit data source page. A Refresh type system dialog window is displayed informing you that the refresh action might take some time and the shared type system model gets refreshed.
  4. Click Refresh type system to confirm the type system refresh action. The refresh status displays Refreshing until it is completed.
    • If the data source shares a type system model with other data sources, the refresh status appears for all of them.
    • You cannot start another refresh on this data source or any dependent data sources until this refresh completes.
  5. Once the refresh action is successful, it displays a success notification and the latest successful refresh date and time. If the refresh action failed, you can view more details in the data source configuration page, along with the date and time of the last successful refresh.