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 that have been defined within 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:
- WSRR Reporting Designer Plug-In
- WSRR Report Runtime Plug-In
- A sample report
Table of contents
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.
This version of the WSRR eclipse plugin will install into Eclipse >= 3.1;
e.g. RSA7.0.
- Select Help->>Software Updates->->Find and Install....
- Choose Search for new features to install. Click Next.
- Select the New Archived Site... button.
- Choose the update site zip using the dialog that appears.
- Check the newly added update site location in the main Install
dialog. Click Next.
- Check the com.ibm.serviceregistry.reporting.feature. Click
Next.
- Accept the License if you agree to the terms and conditions. Click
Next.
- Install the WSRR eclipse plugin into your preferred 'Available site'.
Click Next.
- Click Install.
- Restart the workbench to initialise the new feature and plugin.
See the section on Using Tivoli Common Reporting, below.
Reports for WSRR should be created in the usual manner as any other BIRT report.
The key difference is that reports for BIRT use a specific type of data source
for providing information to the report. WSRR provides information to data
sources by way of stored named property queries.
Since the WSRR reporting plug-in 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:
- Go to the IBM WebSphere Service Registry and Repository console.
- Expand Queries and click on Query Wizard.
- Choose the type of entity you wish to query from the drop-down list, and
click Next.
- Enter the properties you wish to query on, and click Next.
- 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.
- 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:
- Go to the IBM WebSphere Service Registry and Repository console.
- Expand My Service Registry and click either My Saved
Searches or All Saved Searches.
- Select the saved query that you're interested in by clicking on its name.
- Under Additional Properties click Edit Properties.
- Click Add Property.
- 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.
- 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.
With the property queries defined within WSRR, the next step is to create a new
data source for your reports. To do this perform the following steps:
- In Eclipse, go to the Report Design perspective.
- Create a new report, or open an existing report.
- Right-click on Data Sources and select New Data
Source.
- Select IBM WSRR Data Source, provide it with a name if you
wish, and click Next.
- In the Required settings section you should provide the
necessary information for connecting to your WSRR instance.
- 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).
- Click Finish.
Once a WSRR Data Source has been created, you can create data sets for use in
your reports. These data sets will be created from the named property queries
that have already been defined and saved within WSRR (as described above). To create a data set, perform the following
steps:
- In Eclipse, go to the Report Design perspective.
- Right-click on Data Sets and select New Data
Set.
- Provide the new data set with a name if you wish.
- In the Data Source dropdown list select the WSRR data source
that you created previously.
- In the Data Set Type dropdown list select 'IBM WSRR Named
Property Query Data Set'.
- Click Next.
- From the list presented, select the property query that you wish to
use to provide information to your reports, and click
Finish.
- 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 saved property query. For information on creating reports using BIRT, see
the BIRT tutorial documentation, here.
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.
Extract the Tivoli Common Reporting archive into a temporary directory. Run the launchpad and follow the instructions.
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:
- Stop Tivoli Common Reporting, if it's running.
- Open up the WSRR_Reporting_ArchiveSite zip file.
- Extract the com.ibm.serviceregistry.reporting.runtime_1.1.0.jar
JAR file from the zip file.
- Copy that JAR file into the following directory:
<TCR Install Root>\lib\birt-runtime-2_2_1\ReportEngine\plugins
- Restart 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:
- Create your report, or set of WSRR reports, ensuring that all the data
sources and data sets are correctly defined.
- 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.
- Log onto the Tivoli Common Reporting console.
- From the navigation tree, expand Tivoli Common Reporting and
select Work with Reports.
- From the Navigation in the right hand pane, select the Report Sets node.
- Right click and select Import Report Package from the pop up menu.
- From the Import Report Package dialog, click the Browse button.
- From the resulting File Upload dialog, find the zip file containing your
project.
- Click the Import button.
You should now be able to view and execute your imported reports, as described
below.
To run a report that has been deployed into TCR, perform the following steps:
- Log onto the Tivoli Common Reporting console.
- From the navigation tree, expand Tivoli Common Reporting
and select Work with Reports.
- From the Navigation in the right hand pane, expand the Report
Sets node until you find your report set.
- 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.
As stated above (in Configuring the WSSR 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).
The sample report can be found in the 'wssr_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.
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:
- Go to the IBM WebSphere Service Registry and Repository console.
- Expand Queries and click on Query Wizard.
- From the drop-down list select WSDL Ports, and click
Next.
- In the Name field, enter "*".
- In the Property name field, enter "availability".
- Click Next.
- In the Summary page, click Finish.
- In the Name field enter "getWSDLPortAvailability".
- Click Save.
- In the navigation frame to the left, expand My Service Registry,
and select either My Saved Searches or All Saved
Searches.
- Click on getWSDLPortAvailability.
- Click on Edit Properties.
- Click Add Property.
- In the Name field enter any value to identify the type of
property being returned - for this example enter "pAvailability".
- In the "Value" field enter the name of the property that you wish
to have returned - in this case "availability".
- 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:
- Go to the IBM WebSphere Service Registry and Repository console.
- Expand Service Metadata, expand WSDL, and click on
Ports.
- Select the port you wish to appear in the query results by clicking on
its name.
- Click on Edit Properties.
- Click on Add Property.
- In the Name field enter "availability".
- 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.
- 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.
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:
- Extract the 'wssr_sample_port_status.rptdesign' file from the zip
and import it into your Eclipse workspace.
- Go to the Report Design perspective.
- Right-click on Data Sources and select New Data
Source.
- Select IBM WSRR Data Source, and leave it with the default
name of "Data Source".
- In the Required settings section you should provide the
necessary information for connecting to your WSRR instance, including
any necessary security settings.
- Click Finish.
Next you will need to create the necessary data sets for the report. To do so,
perform the following steps:
- Go to the Report Design perspective.
- Right-click on Data Sets and select New Data
Set.
- Leave the new data set with the default name of "Data Set".
- In the Data Source dropdown list select the WSRR data source
that you created previously.
- In the Data Set Type dropdown list select 'IBM WSRR Named
Property Query Data Set'.
- Click Next.
- From the list presented, select the "getWSDLPortAvailability"
query that you defined previously, and click Finish.
- 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.
Once the sample report has been configured with the necessary data sources in
Eclipse (as described above), it may be deployed to and run in TCR. To load the
sample into TCR, perform the following steps:
- Place the 'wssr_sample_port_status.rptdesign' report file into a
directory, zip that directory up into a zip file, and give that zip file
the name 'WSRR_Samples.zip'.
- Log onto the Tivoli Common Reporting console.
- From the navigation tree, expand Tivoli Common Reporting and
select Work with Reports.
- From the Navigation in the right hand pane, select the Report Sets node.
- Right click and select Import Report Package from the pop up menu.
- From the Import Report Package dialog, click the Browse button.
- From the resulting File Upload dialog, find the 'WSRR_Samples.zip' file
that was just created.
- Click the Import button.
Once the report has been deployed, it can be viewed and run from within TCR by
performing the following steps:
- Log onto the Tivoli Common Reporting console.
- From the navigation tree, expand Tivoli Common Reporting
and select Work with Reports.
- From the Navigation in the right hand pane, expand the Report
Sets node until you find the "WSRR_Samples" report set.
- 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.
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.
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"
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.
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 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.