SA12:IBM Reporting Supportpac for WebSphere Service Registry and Repository

The IBM Reporting Supportpac allows users to create customised and detailed reports of the contents of their WebSphere Service Registry and Repository, by making use of the powerful, Eclipse-based BIRT tooling. Once installed, this package provides authors of BIRT reports with the ability to execute property queries against WSRR. The information returned by those queries can be used by BIRT to generate detailed reporting charts in a number of formats, including HTML, PDF and Excel. Once written, the reports can then be deployed into Tivoli Common Reporting, allowing users to view and generate reports from within a web browser.

The Supportpac consists of the following:

Table of contents

Pre-requisite software

The minimum software requirement for this SupportPac is WebSphere Service Registry and Repository version 6.1.

To generate reports you will also need a copy of Eclipse, along with the necessary BIRT plug-ins. Information about BIRT can be found at the official site, here.

Installation instructions

WSRR Reporting Plug-Ins

Installation into Eclipse

This version of the WSRR eclipse plugin will install into Eclipse >= 3.1; e.g. RSA7.0.
  1. Select Help->>Software Updates->->Find and Install....
  2. Choose Search for new features to install. Click Next.
  3. Select the New Archived Site... button.
  4. Choose the update site zip using the dialog that appears.
  5. Check the newly added update site location in the main Install dialog. Click Next.
  6. Check the com.ibm.serviceregistry.reporting.feature. Click Next.
  7. Accept the License if you agree to the terms and conditions. Click Next.
  8. Install the WSRR eclipse plugin into your preferred 'Available site'. Click Next.
  9. Click Install.
  10. Restart the workbench to initialise the new feature and plugin.

Installation into TCR

See the section on Using Tivoli Common Reporting, below.

Using the WSRR Data Sources and Data Sets to create Reports

Reports for WSRR should be created in the usual manner as any other BIRT report. The key difference for WSRR reports is that a WSRR-specific data source is used to configure access to information from WSRR, and two WSRR-specific data sets are supplied to provide two different ways of retrieving that information. The two different data set types, "named property query" and "free form graph query", will be discussed separately, below.

Configuring the WSRR Data Source in Eclipse

To create a WSRR data source for your reports perform the following steps:

  1. In Eclipse, go to the Report Design perspective.
  2. Create a new report, or open an existing report.
  3. Right-click on Data Sources and select New Data Source.
  4. Select IBM WSRR Data Source, provide it with a name if you wish, and click Next.
  5. In the Required settings section you should provide the necessary information for connecting to your WSRR instance.
  6. If your WSRR instance is running with security enabled, check the box to indicate this, and fill in the remaining connection properties appropriately. Note that both sections must be filled in whilst creating and using reports in Eclipse. The section headed 'Security settings needed by Eclipse only' can only be ignored if you are creating a data set purely for use with Tivoli Common Reporting (see below).
  7. Click Finish.

Using the Named Property Query Dataset

Configuring WSRR for Reporting with Named Property Queries

Since the Named Property Query dataset retrieves information via stored named property queries, property queries must first be defined within WSRR. The actual queries that will be defined will be specific to the information that you wish to use in generating reports (see Creating the Sample Property Query for an example). In general, though, the following steps should be followed:

  1. Go to the IBM WebSphere Service Registry and Repository console.
  2. Expand Queries and click on Query Wizard.
  3. Choose the type of entity you wish to query from the drop-down list, and click Next.
  4. Enter the properties you wish to query on, and click Next.
  5. In the Summary page, click Finish if you are happy with the query. This will take you to a list of results for the search.
  6. Finally provide the query with a name, and click Save.
The query will now be available for use as a WSRR data source when you create reports.

Also be aware that if you have added any extra properties to the entities upon which you're querying, that these extra properties will not, by default, be returned by executing the query. Thus, if you wish to include the values for these additional attributes in your reports, then you must make the following changes to your saved property query:

  1. Go to the IBM WebSphere Service Registry and Repository console.
  2. Expand My Service Registry and click either My Saved Searches or All Saved Searches.
  3. Select the saved query that you're interested in by clicking on its name.
  4. Under Additional Properties click Edit Properties.
  5. Click Add Property.
  6. In the Name field, enter any value to represent this new property. In the Value field, enter the name of the attribute you want the query to return.
  7. Click OK.

When you next run the query the results returned will now also contain the values for the attribute that was just specified. Note however that these additional attribute values will not be displayed in the standard WSRR UI.

Creating a Named Property Query Data Set in Eclipse

Named property query data sets will be created from the named property queries that have already been defined and saved within WSRR (as described above). To create this type of data set, perform the following steps:

  1. In Eclipse, go to the Report Design perspective.
  2. Right-click on Data Sets and select New Data Set.
  3. Provide the new data set with a name if you wish.
  4. In the Data Source dropdown list select the WSRR data source that you created previously.
  5. In the Data Set Type dropdown list select 'IBM WSRR Named Property Query Data Set'.
  6. Click Next.
  7. From the list presented, select the property query that you wish to use to provide information to your reports, and click Finish.
  8. BIRT will then take you to the data set dialog pane, from which you can inspect the values that you'll be able to use in your reports, as usual.

You can now proceed to create a BIRT report based upon the values returned by the named property query. For information on creating reports using BIRT, see the BIRT tutorial documentation, here.

Using the Free Form Graph Query Dataset

Unlike the named property query dataset, this dataset requires no additional configuration on the server side, since it allows you to define queries directly in the dataset. So when using the free form graph query dataset you can immediately define the dataset itself, as described below.

Creating a Free Form Graph Query Data Set in Eclipse

  1. In Eclipse, go to the Report Design perspective.
  2. Right-click on Data Sets and select New Data Set.
  3. Provide the new data set with a name if you wish.
  4. In the Data Source dropdown list select the WSRR data source that you created previously.
  5. In the Data Set Type dropdown list select 'IBM WSRR Free Form Graph Query Data Set'.
  6. Click Next.
  7. In the top field simply enter the XPath query that you wish to use to retrive the data for your report.
  8. In the field below that you can enter the name of any user-defined properties that you wish to have returned by the query. User-defined properties are not returned by default and so must be listed in this field.
  9. Check or un-check the options for the information that you want your dataset to contain. Depending on the type of report that you're building, you may sometimes not want to consider some of these.
  10. Cick Finish.
  11. BIRT will then take you to the data set dialog pane, from which you can inspect the values that you'll be able to use in your reports, as usual.

Using Input Parameters with a Free Form Graph Query Data Set in Eclipse

The free form graph query data set type also supports the use of input parameters. Input parameters are used to provide input to the XPath queries that are used by the dataset, and can thus be used to chain datasets (and thus queries) together.

Input parameters are defined within the query strings using the following notation: 

{parameter name}

For example, if we were to search for all generic objects with a specific bsrURI, we would build the following query: 

//GenericObject[@bsrURI={my_input_param}]

There is no limit on the number of input parameters used in a query, and input parameters may be re-used in the same string. To provide values to the input parameters use the standard BIRT techniques.

Using Tivoli Common Reporting

The IBM Reporting Supportpac for WebSphere Service Registry and Repository is supplied with sample reports which can be deployed into the Tivoli Common Reporting product, available from the Supportpac website.

Installing

Extract the Tivoli Common Reporting archive into a temporary directory. Run the launchpad and follow the instructions.

Configuring for use with WSRR

In order for reports run within TCR to be able to retrieve information from WSRR, you must install the WSRR plug-ins into TCR. To do this, perform the following steps:

  1. Stop Tivoli Common Reporting, if it's running.
  2. Open up the WSRR_Reporting_ArchiveSite zip file.
  3. Extract the com.ibm.serviceregistry.reporting.runtime_1.2.0.jar JAR file from the zip file.
  4. Copy that JAR file into the following directory: 
     <TCR Install Root>\lib\birt-runtime-2_2_1\ReportEngine\plugins
  5. Restart TCR.

Deploying a Report into TCR

The Tivoli Common Reporting user guides contain detailed information on deploying BIRT reports into TCR, in particular in the 'Creating Reports and Report Packages' section of the 'Tivoli Common Reporting Development and Style Guide' (as found in the 'tcr_style_guide.pdf' file), and in the 'Importing and exporting report packages' section of the 'Tivoli Common Reporting User's Guide' (as found in the 'tcr_users_guide.pdf' file).

However, to summarise that information, in order to allow a WSRR report to be deployed into TCR you must perform the following steps:

  1. Create your report, or set of WSRR reports, ensuring that all the data sources and data sets are correctly defined.
  2. Zip up your reports into a zip file, named using the conventions stated in the TCR documentation. Note that, unless your reports explicitly use them, you do not need to add the extra directories and files that are detailed in the TCR documentation.
  3. Log onto the Tivoli Common Reporting console.
  4. From the navigation tree, expand Tivoli Common Reporting and select Work with Reports.
  5. From the Navigation in the right hand pane, select the Report Sets node.
  6. Right click and select Import Report Package from the pop up menu.
  7. From the Import Report Package dialog, click the Browse button.
  8. From the resulting File Upload dialog, find the zip file containing your project.
  9. Click the Import button.

You should now be able to view and execute your imported reports, as described below.

Running a Report

To run a report that has been deployed into TCR, perform the following steps:

  1. Log onto the Tivoli Common Reporting console.
  2. From the navigation tree, expand Tivoli Common Reporting and select Work with Reports.
  3. From the Navigation in the right hand pane, expand the Report Sets node until you find your report set.
  4. From the Reports tab, click either the HTML or PDF option next to the report that you wish to generate. The report will then be generated and displayed in your browser.

Configuring TCR for use in a Secure Environment

As stated above (in Configuring the WSRR Data Source in Eclipse), in order for a WSRR report to be able to communicate with a secure WSRR instance, the data source for that report must be configured with the necessary security settings.

However, once the report is deployed into TCR, some of those settings are no longer used. The only data source settings that need to be correct are those contained within the section marked 'Security settings for use in Eclipse and Tivoli Common Reporting'. Certificates and other authentication settings for the secure connection between TCR and WSRR are managed by TCR itself.

In order to allow TCR to communicate with WSRR, you must have all the necessary security settings and shared certificates. TCR uses an IBM WebSphere Application Server-like interface to administer security, so simply configure TCR as you have your secure WAS environment, and then share the necessary certificates between the two servers to enable secure communications.

For further information on configuring WAS, see the IBM Information Center. (For example, see: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tsec_ssladdsignercert.html).

Using the Sample Reports

Sample reports are supplied for both types of dataset provided by this supportPac. Instructions on using both are supplied below.

Using the Named Property Query Sample Report

The named property query sample report can be found in the 'WSRR_sample_port_status.rptdesign' file in the 'samples' directory within the 'WSRR_Reporting_ArchiveSite' zip file.

The sample reports on the status of WSDL ports for any installed services, using an example (and highly simplified) means of detailing the current usage level of a WSDL port.

The sample does not come configured with any data sources, so before you can use the report, you must follow the instructions given in the following sections. Since the report also reports on WSDL documents and their port objects, you must therefore also have some WSDL documents imported into your WSRR instance, in order to provide "WSDL Port" objects to report on. Instructions for setting up your WSRR instance appropriately are also listed below.

Creating the Sample Property Query

The supplied sample requires a particular named property query to exist to provide information to the report. As well as creating the query, it also needs to be set to return the correct properties as results. So to create the necessary query, and set it up correctly, perform the following steps:

  1. Go to the IBM WebSphere Service Registry and Repository console.
  2. Expand Queries and click on Query Wizard.
  3. From the drop-down list select WSDL Ports, and click Next.
  4. In the Name field, enter "*".
  5. In the Property name field, enter "availability".
  6. Click Next.
  7. In the Summary page, click Finish.
  8. In the Name field enter "getWSDLPortAvailability".
  9. Click Save.
  10. In the navigation frame to the left, expand My Service Registry, and select either My Saved Searches or All Saved Searches.
  11. Click on getWSDLPortAvailability.
  12. Click on Edit Properties.
  13. Click Add Property.
  14. In the Name field enter any value to identify the type of property being returned - for this example enter "pAvailability".
  15. In the "Value" field enter the name of the property that you wish to have returned - in this case "availability".
  16. Click OK.

In order for the query to return any results, though, you must have some data for it to find. In this case, the "WSDL Ports" in your WSRR must contain an "availability" field. To this, first of all ensure that your WSRR contains WSDLs that have defined ports. Then, for each WSDL you want included in your report, perform the following steps:

  1. Go to the IBM WebSphere Service Registry and Repository console.
  2. Expand Service Metadata, expand WSDL, and click on Ports.
  3. Select the port you wish to appear in the query results by clicking on its name.
  4. Click on Edit Properties.
  5. Click on Add Property.
  6. In the Name field enter "availability".
  7. In the Value field you must provide a status. The sample report will report on ports that have an availability of either "red", "amber" or "green". So enter either "red", "amber" or "green" as a value.
  8. Click on OK.

In order to provide the report with more than one document to report on, you should repeat the above steps for multiple WSDL documents and ports.

Deploying the Sample Report into Eclipse

It is necessary to deploy the sample report into Eclipse before deploying into Tivoli Common Reporting, since the report does not come shipped with any data sources defined. So these steps are essential whether or not you intend to run reports from within Eclipse.

First of all, you will need to configure the data source for the report. To do so, perform the following steps:

  1. Extract the 'WSRR_sample_port_status.rptdesign' file from the zip and import it into your Eclipse workspace.
  2. Go to the Report Design perspective.
  3. Right-click on Data Sources and select New Data Source.
  4. Select IBM WSRR Data Source, and leave it with the default name of "Data Source".
  5. In the Required settings section you should provide the necessary information for connecting to your WSRR instance, including any necessary security settings.
  6. Click Finish.

Next you will need to create the necessary data sets for the report. To do so, perform the following steps:

  1. Go to the Report Design perspective.
  2. Right-click on Data Sets and select New Data Set.
  3. Leave the new data set with the default name of "Data Set".
  4. In the Data Source dropdown list select the WSRR data source that you created previously.
  5. In the Data Set Type dropdown list select 'IBM WSRR Named Property Query Data Set'.
  6. Click Next.
  7. From the list presented, select the "getWSDLPortAvailability" query that you defined previously, and click Finish.
  8. BIRT will then take you to the data set dialog pane. Select 'Preview Results' to ensure that the query that you defined is working correctly and returning data as expected.

Once the data set has been defined, you will be able to run the report and see it generate the pie-chart that shows service availability.

Using the Free Form Graph Query Sample Report

The free form graph query sample report can be found in the 'WSRR_sample_wsdls_and_xsds.rptdesign' file in the 'samples' directory within the 'WSRR_Reporting_ArchiveSite' zip file.

The sample report produces a basic table list all WSDL documents in a WSRR instance, along with all the XSD documents that are imported or included from those XSD documents. Whilst this is a fairly simplistic report, the techniques used do illustrate how free form graph query datasets can be used and chained together. Note should be taken of the use of nested tables, and how the data bindings from one table are used to feed into a nested table, thus allowing parameters to be passed between datasets.

Whilst this sample does come configured with datasets and a partially-configured datasource, it does not come with any data against which the report can be run. This must be created manually, as described below.

Creating the Sample Data

Since the report simply lists WSDL and associated XSD documents, the only set up to be done in terms of creating sample data is to ensure that your WSRR instance contains WSDL documents, and that some of those documents have imported or included XSD documents, and that those XSD documents are also present in the WSRR instance.

Deploying the Sample Report into Eclipse

It is necessary to deploy the sample report into Eclipse before deploying into Tivoli Common Reporting, since the report does not come shipped with the data source properly defined. So these steps are essential whether or not you intend to run reports from within Eclipse. The major change that will be needed to allow the sample report to work will be to edit the supplied data source so that it correctly points at a valid WSRR instance. To deploy the report and make these changes, perform the following steps:

  1. Extract the 'WSRR_sample_wsdls_and_xsds.rptdesign' file from the zip and import it into your Eclipse workspace.
  2. Go to the Report Design perspective.
  3. Expand Data Sources and open up the properties for the existing data source Data Source.
  4. Fill in the information necessary to connect to your WSRR instance.
  5. Click Finish.

Once the data source has been correctly configured, you should be able to preview the report in Eclipse and see a table containing a list of all WSDLs and their related XSDs in your WSRR instance.

Deploying the Sample Reports into Tivoli Common Reporting

Once the sample reports has been configured in Eclipse (as described above), they may be deployed to and run in TCR. To load one or both of the samples into TCR, perform the following steps:

  1. Place the 'WSRR_sample_port_status.rptdesign' and/or the 'WSRR_sample_wsdls_and_xsds.rptdesign' report file (as required) into a directory, zip that directory up into a zip file, and give that zip file the name 'WSRR_Samples.zip'.
  2. Log onto the Tivoli Common Reporting console.
  3. From the navigation tree, expand Tivoli Common Reporting and select Work with Reports.
  4. From the Navigation in the right hand pane, select the Report Sets node.
  5. Right click and select Import Report Package from the pop up menu.
  6. From the Import Report Package dialog, click the Browse button.
  7. From the resulting File Upload dialog, find the 'WSRR_Samples.zip' file that was just created.
  8. Click the Import button.

Once the reports have been deployed, they can be viewed and run from within TCR by performing the following steps:

  1. Log onto the Tivoli Common Reporting console.
  2. From the navigation tree, expand Tivoli Common Reporting and select Work with Reports.
  3. From the Navigation in the right hand pane, expand the Report Sets node until you find the "WSRR_Samples" report set.
  4. From the Reports tab, click either the HTML or PDF option next to the report that you wish to generate. The report will then be generated and displayed in your browser.

Running Batch Reports

The WSRR Reporting SupportPac does not directly provide batch supporting capabilities for generating reports. However, there are command line options in Tivoli Common Reporting that can be used for such a task.

Using Tivoli Common Reporting to Generate Batch Report Runs

Tivoli Common Reporting does, likewise, not directly provide the facility to run batch report generation tasks. However, it does provide a command line option for generating reports, and this can be used in custom-written scripts to run batch report generations.

The command line options for TCR are detailed in the 'Tivoli Common Reporting command reference' section of the 'Tivoli Common Reporting User's Guide' (as found in the 'tcr_users_guide.pdf' file). For batch report generation, though, the 'run' command should be used. To summarise, the following command syntax should be used: 

        trcmd -user username -password password -run -report "report set/report name"

Troubleshooting

Secure connection issues within Eclipse

It is important to note that, within Eclipse, you must only use one trust store and key store for all of the certificates that you use to connect to your remote WSRR instances. If also using the WSRR Eclipse Plugin, you must also configure that plug-in to use the same trust and key stores as the WSRR Reporting plug-in.

Also note that if you incorrectly specify the details for your trust and key stores, that any changes made to those credentials may not be picked up until the next time that Eclipse is started.

Access permissions for objects used in reports

It is necessary to have the correct permissions set up on the objects that your reports are querying in order for those reports to properly execute. Users who are executing reports should be granted 'retrieve' permissions on all objects that are being accessed by the queries, and should also be granted 'retrieve' access on objects of type 'PropertyQuery'.

PKCS12 trust stores and the Sun JVM

PKCS12 trust stores are not presently supported when used in conjunction with the Sun JVM. Although the UI prevents you from specifying a PKCS12 store when using the Sun JVM, it is possible to configure a report to use PKCS12 whilst running under the IBM and JVM, and then use that report under the Sun JVM. If you attempt to do this, an error will occur. Please use either JKS or JCEKS trust stores if you are running against the Sun JVM.

If you have already created a PKCS12 trust store, then this can be converted to a JKS or JCEKS store by using the "ikeyman" tool from WebSphere. More information on running and using this tool can be found here.