Reporting on applications that have versioned type systems

You can manage incompatibilities in the type systems (custom attributes, types, links, enumerations) that IBM® Engineering Lifecycle Management applications support. At present, only IBM Engineering Requirements Management DOORS® Next has a versioned type system. If the type system in your application evolves over time and your data source is Lifecycle Query Engine scoped by a configuration, the reports might show inconsistencies such as multiple attributes with the same name, or attributes that no longer exist. These inconsistencies can create confusion while building reports. To prevent this problem, you can create a data source for a specific baseline or stream in Report Builder.

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 an administrator with Jazz administrative privileges or a report manager.
  • You must know the data source type, and depending on the type and vendor, the properties that are required to connect to it.
  • You should be familiar how the global configurations in a project area are related.

About this task

Points for consideration:
  • You should plan your custom types and attributes carefully so that they evolve consistently over time. By doing this, you can use Lifecycle Query Engine scoped by a configuration data source whenever required.
  • If your versioned type system has developed inconsistencies over time, you can create a configuration-scoped data source and use a global configuration that represents a useful milestone in the evolution of the type system.
  • Avoid creating too many active configuration-scoped data sources. Archive data sources that are no longer used for reporting or dashboard widgets because each data source consumes memory on the Report Builder server.
Example 1: A versioned type system

Before explaining how to create a configuration-scoped data source, it’s helpful to look at an example of how such changes might occur and their consequences. Suppose in the IBM Engineering Requirements Management DOORS Next (DOORS Next) application you have a global configuration SGC Production Stream that has contributions from three different streams (on the left).

Imagine that over time some changes were made to the artifacts in these DOORS Next streams in the context of their global streams. Eventually, three sets of changes were made, resulting in four global baselines (on the right). Typically, these baselines capture the state of an artifact and its attributes when it was created.

a global configuration having baselines

So, here is the related data in DOORS Next. For the global baseline SGC Production Stream (baseline 1), there is a corresponding local configuration in DOORS Next.

showing global configuration corresponding to a local configuration

You can use Manage Component Properties to check the artifact types and their possible attribute values

an image showing manage component properties

Suppose at this time you made changes to the Software Requirement artifact type, adding two new attributes: Color and Part number.

To see the possible values for these attributes, look on the Attributes Data Types tab. The Color attribute has possible values of red, green and blue. The Part number attribute is of the String data type, which can contain any text entered by a user.

Now you can see that DOORS Next recorded the version and state of these attributes and their types as a part of the local baseline as well as the global baseline. Each artifact can have values for these attribute types. This example reflects the versioned type system for the application. You can also view the state of any artifact at the time when that baseline was created.

Example 2: Evolution of the type system over time
Administrators might alter the type system for good business reasons, but the changes will affect reports. In the previous example, the administrator made changes to the attributes in the type system for SGC Production Stream (baseline 2).
Remember: You can select this configuration by switching the Configuration Context in the Current Configuration menu.

Two new values were added for the Color attribute, yellow and purple. A new attribute Part reference was created with the String data type. In addition, for the Software Requirement artifact type the Part number attribute was removed and Part reference was added.

Later, in the context of SGC Production Stream (baseline 3) the administrator made some other changes. They changed the values of the Color attribute, renaming purple to mauve with the same RDF URI (so that Report Builder recognizes this as the same value) and removed yellow.

Finally, they made further changes to the attributes in the context of SGC Production Stream (baseline 4). They deleted the existing Part number attribute from the Software Requirement artifact type and created a new attribute with the same name but without an RDF URI (to help Report Builder to recognize this as a different value).

This example depicts poor planning of the properties and enumeration values of the Software Requirement artifact type. It leads to a confused presentation of attributes when creating reports in Report Builder. Such evolution of the custom attributes results in inconsistent type definitions and overlapping of attributes.

In Report Builder, you can create reports for a specific global or local configuration by using the Lifecycle Query Engine scoped by a configuration as a data source. This data source is system generated and uses metamodels that merge the attributes across all versions of the type system (custom attributes, types, links, and enumerations). However, you might see multiple attributes with the same or similar names when you add conditions to the report, as shown in the following image.

image showing outdated attributes in report builder

Ideally, the type systems should be planned in such a way that they evolve into a compatible and consistent system that avoids any confusion when selecting attributes for conditions in reporting.

However, for those type systems that have not been or cannot be planned, Report Builder includes an important feature that can help users to build efficient reports.

Example 3: Reports using configuration-scoped data sources

When you create a configuration-scoped data source scoped to the global baseline SGC Production Stream (baseline 1), then in the reports section, you'll see only the types and attributes specific to SGC Production Stream (baseline 1). Similarly, you can create data sources scoped to SGC Production Stream (baseline 2), or SGC Production Stream (baseline 3), or SGC Production Stream (baseline 4). The result is a clear representation of types and attributes when adding conditions to a report, as shown in the following image.

attributes after scoping to configurations

Creating a configuration-scoped data source

About this task

You can avoid confusion caused by inconsistent evolution of types in versioned type systems, currently in DOORS Next. The Report Builder administrator can create data sources based on a specific configuration inside the Lifecycle Query Engine scoped by a configuration. Such data sources are known as configuration-scoped data sources, and they ensure that a specific version of the type system is used for reporting. When you build reports for the versioned type systems using these data sources, you can see only the types and attributes that are scoped to the chosen configuration for the data source.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. On the Connect to data sources pane, click on Data Sources.
  3. From the list of data sources, click Lifecycle Query Engine scoped by a configuration data source.
  4. Expand the Advanced section, and click Create a Data Source for a Configuration.
  5. Follow the prompts to choose the appropriate project area and configuration to report on, and click Accept.
  6. Configure the remaining data source properties to suit the needs of your project, and click Save.

Results

In the background, Report Builder creates new metamodels for this data source, which takes some time. To check the status of this data source, you can periodically refresh the browser window. When the Metamodels status section appears on that page after the Data source properties section, this new data source is now ready to use for reports.

Important:

Ensure that while running your reports, you must either choose the same configuration that was used for scoping the data source or a configuration that is related to the one picked for scoping the data source. For example, the configuration that is used for your report execution can be a stream whereas your configuration-scoped data source might use a baseline that is created from that stream.

What to do next

You can now use this data source for creating your configuration-scoped reports using Report Builder.

Archiving and restoring

About this task

Each active data source consumes memory on the Report Builder server. Creating configuration-scoped data sources can increase the memory consumption on the server. It is likely that over time the data sources that are scoped to baselines are seldom used.

Reports can be deleted, but you must first delete all the reports that use that data source. Some organizations might need to keep these reports for regulatory or compliance purposes, so they cannot delete these reports. Even so, if you try to delete a configuration-scoped data source without deleting the reports that use this data source, you get an error because a report might use this data source.

image showing error message when trying to delete configuration-scoped data sources

Instead of deleting, you can archive a data source.

To archive a configuration-scoped data source, see Archiving data sources.

To restore a configuration-scoped data source, see Restoring data sources.

Refreshing the metamodels

About this task

Configuration-scoped data sources are not refreshed automatically, unlike the other data sources that are automatically refreshed every 12 hours by default. For more information, see Refreshing the metamodel.

If a configuration-scoped data source uses a baseline as its scope, the metamodel might not need to be refreshed frequently. You might need to refresh if any types (versioned or non-versioned) were changed during tracking or planning of the IBM Engineering Lifecycle Management (ELM) applications. If this data source configuration uses a stream, and a DOORS Next type system for that stream has changed, or the types in IBM Engineering Workflow Management have changed, then the Report Builder administrator must manually refresh that configuration-scoped data source so that the metamodels reflect those changes in their type systems.

Note: Manually refresh if the configuration-scoped data source is scoped to a stream or whenever the non-versioned types have changed in an application.

Procedure

  1. Open Report Builder (https://server_name:port/rs/endpoint) .
  2. Click the Data Sources link in the product banner.
  3. Click the data source that you want to refresh, for example the data warehouse.
  4. Click Refresh.
    A message Successfully updated the metamodel for this data source confirms that the refresh is complete. See Refreshing the metamodel for more details about changes that require a metamodel refresh.

What to do next

You can check when the last successful refresh happened in the Metamodels status section.

Changing the configuration

About this task

A Report Builder administrator can change the configuration used for a configuration-scoped data source. However, you must take care to choose a configuration that’s compatible with the existing reports using that data source. In general, you should choose a configuration of the same component. Choosing an inappropriate configuration could break reports created for that data source.

Tip: You can choose a configuration of the same component.

Procedure

  1. In a browser window, open the Setup page at https://server:port/rs/setup
  2. On the Connect to data sources pane, click Data Sources.
  3. Click the data source that you want to associate with a different configuration.
  4. In the Data source configuration change section, click Choose configuration.
  5. Select the project area and the configuration to report on, and click Accept.
  6. Click Save

Results

The configuration-scoped data source will be scoped to the selected configuration.
Important: When you have changed the configuration used by a configuration-scoped data source, ensure that all the reports using that data source are compatible with the new one. You can do this by validating the reports.

Validating reports

About this task

It’s possible that changing the configuration might break existing reports that are linked to the specific configuration-scoped data source. The Report Builder administrator must validate all the reports that are linked to the data source. Report Builder checks whether the data source of each report was changed and if the artifact types are still available in the new data source. If there is a problem, you can go back and select the original configuration or manually modify any broken report by referring to the appropriate types and attributes that exist for the modified data source.

Procedure

  1. Open Report Builder.
  2. Go to https://server:port/rs/setup. On the My Reports or All Reports page, group the reports by data source by selecting the Group by data source option from the list on the toolbar.
  3. Select all reports that are linked to the data source for which you changed the configuration scope.
  4. Click Validate.

    validate button

Results

You’ll see a green check mark green check mark beside all the report names that are valid. Changing the configuration didn’t break those reports.