Introduction

IBM® WebSphere® Service Registry and Repository (hereafter called Service Registry) features auditing and reporting capabilities when the IBM Audit SupportPac (SA03) and IBM Reporting SupportPac (SA12) plug-ins are installed and configured. When changes occur to metadata being stored in Service Registry through events of interest, data about these events is recorded in the back-end database. Service Registry uses database queries to report on these events, which are persisted to a database. Typical activities that lead to auditing are create, update, and delete actions on metadata entities, enabling or disabling the governance on metadata entities, and state transitions involving metadata entities. Service Registry records information such as event type, whether the event succeeded, event details, event date and time, user id responsible for event occurrence, the registry in which the event occurred, whether the event is correlated to other events, and details of objects involved in the event (such as object name, description, namespace, version, unique identification, and type). Service Registry features powerful search capabilities to search the registry for various types of entities using a subset of XPath 2.0 syntax, and search queries can be saved for reuse. Additionally, the information returned by these queries can be used to populate the detailed and customized report templates developed by powerful, Eclipse based Business Intelligence and Reporting Tools (BIRT). BIRT tools enable you to generate detailed reports with charts and graphs in multiple formats including HTML, PDF, Microsoft Excel, and so on. Users can view and generate reports using a browser by deploying the BIRT-developed reports into Tivoli Common Reporting runtime.

This article shows you how to perform the following audit-enabling steps:

• Set up software environment.
• Configure database for auditing.
• Configure WebSphere Application Server for auditing.
• Configure Service Registry for auditing.
• Configure Tivoli Common Reporting for auditing.
• Set up and exercise a use case to perform auditing in Service Registry.
• Generate audit reports using Tivoli Common Reporting.
• Generate audit reports using the command-line reporting tool.

The article also shows you how to perform the following report-enabling steps:

• Configure the WebSphere Integration Developer Eclipse workbench for reporting.
• Set up and exercise a use case to perform reporting in Service Registry.
• Set up reporting using the WebSphere Integration Developer Eclipse workbench.
• Generate reports using Tivoli Common Reporting.
• Generate reports using batch report runs.

Enable and perform auditing

Set up software environment

This article uses a laptop with the following software installed:

• Apache Derby database V10.1.3.2
• WebSphere Application Server Network Deployment V6.1.0.2
• WebSphere Service Registry and Repository V6.2.0.2 with SupportPacs SA03 and SA12 installed
• Tivoli Common Reporting V1.1.1
• WebSphere Integration Developer V6.2.0.2

For details, see software_environment.doc in the package that you can download at the bottom of the article. The README file for SA03 Audit SupportPac for Service Registry contains values for specific audit event types being logged to a database, database tables and table structure details to construct the SQL queries, and four sample reports that you can deploy to Tivoli Common Reporting with associated sample SQL.

Configure database for auditing

The SA03 Audit SupportPac supports DB2 UDB, DB2 on z/OS, Apache Derby, and Oracle for use as databases. To configure the database for auditing, do the following steps. For details, see DatabaseConfig.doc in the download package.

1. Create database and database tables.
   The Audit SupportPac plug-in provides Apache Derby database scripts to create a user-specified audit database, and the audit database tables AUDITEVENT and OBJECT. The scripts are located at WSRRHOME/Audit/scripts/sql/derby. The author customized the scripts to create a new database instance at C:\i\Derby_DBs\ with database name as AUDIT using a specified user name of admin and an indicated user password.
2. Create Apache Derby JDBC provider.
   Create an XA-compliant Derby JDBC provider.
3. Create data source authentication alias.
   Create an authentication alias to use to connect to the WSRR AUDIT data source.
4. Create Apache Derby JDBC data source.
   Create a JDBC data source pointing to the AUDIT database.
5. Test JDBC data source connection
   Perform a connection test to the WSRR AUDIT database and validate that the test succeeds.
6. Configure Apache Derby Network Server.
   Embedded Apache Derby databases restrict database access to one JVM at a time. Since the AUDIT database is accessed from both WebSphere Application Server hosting Service Registry, and from the Tivoli Common Reporting server, you need to configure the Apache Derby Network Server so that the AUDIT database is accessed by the WebSphere Application Server JVM and the Tivoli Common Server JVM using Apache Derby Network Client.

Configure WebSphere Application Server for auditing

The SA03 Auditing SupportPac comes with the WSRRAudit.ear J2EE application. Using the WebSphere Integrated Solutions Console, install the J2EE application into WebSphere Application Server and start it. For details, see WebSphereConfig.doc in the package that you can download at the bottom of the article.

Configure Service Registry for auditing

The SA03 Auditing SupportPac comes with the WSRRAuditPlugin.jar and WSRRAuditProperties.properties files. To configure Service Registry for auditing, do the following steps. For details see WSRRConfig.doc in the download package.

• Using the Service Registry Web UI Configuration perspective, load the WSRRAuditProperties.properties file into the Service Registry as a user configuration.
• Load WSRRAuditPlugin.jar into Service Registry as a plug-in JAR.
• Configure Notification properties in Service Registry to enable default notification functions to call com.ibm.sr.audit.SRAuditNotifier class for all document types and all governed objects.

Configure Tivoli Common Reporting for auditing

The SA03 Auditing SupportPac comes with a report package called ReportSamples.zip. This archive file contains four sample reports: audit_all.rptdesign, audit.bsruri.rptdesign, audit_userid.rptdesign, and audit_what.rptdesign. You can deploy these reports to Tivoli Common Reporting runtime. Once deployed and configured, these reports can be run by end users using a browser to generate reports in various formats, including HTML, PDF, Microsoft Excel, or Adobe PostScript. To configure Tivoli Common Reporting for auditing, do the following steps. For details, see TCRConfig.doc in the download package.

• Download Tivoli Common Reporting product package and install.
  You can download the Tivoli Common Reporting package from the SupportPac Web site. To install it, unzip the compressed archive file and run launchpad.exe on Windows, then follow the installation steps.
• Configure Tivoli Common Reporting runtime.
  This step requires applicable JDBC drivers to be located at the appropriate Tivoli Common Reporting install location on your file system in order for data sources to be connected by the Tivoli Common Reporting runtime. It connects to the AUDIT database on Apache Derby to populate reports with matching data, upon user requests for reports initiated through a browser. To do this configuration step, copy derbyclient.jar file from the Apache Derby install area on your file system to the Tivoli Common Reporting install location.
• Deploy the sample report package into Tivoli Common Reporting runtime.
  Import the sample report package into the Tivoli Common Reporting runtime using a browser.
• Configure data source attributes of reports.
  For each report deployed to the Tivoli Common Reporting runtime, configure the appropriate data source detain information to connect to the AUDIT database. The relevant details are user role, user id, user password, JDBC driver, JDBC URL, and JNDI name.
• Test each report configuration.
  Run each configured report to creating a snapshot report and verify that there are no errors in the Tivoli Common Reporting connection to the database to retrieve report data. Also verify that the generated reports can be viewed in various formats. It is OK to have reports with no data since this step mainly verifies the connection.

Set up and exercise a use case to perform auditing in Service Registry

You are now ready to set up a use case and use the Service Registry auditing capabilities. At this point the Service Registry instance has no artifacts or metadata – it is empty. To capture an audit trail that you can report on, do the following steps. For details, see UsecaseConfig.doc in the download package.

• Create new objects in Service Registry.
  Sign-on and select Service Documents => Load Documents. Populate Service Registry with SOA artifacts as a collection using a ZIP archive file, in order to generate an audit report after performing this initial load. The audit report is saved as Initial_Load_View.pdf.
• Update an existing object in Service Registry.
  Select Service Version RequestCreditReportServiceService, and specify the description field value to be RequestCreditReportServiceService by clicking Edit Properties. Save the update.
• Make an existing object governable.
  To enable governance on the Service Version RequestCreditReportServiceService collection of artifacts, first make sure that the Service Versions, Authoritative WSDLS, and Service Endpoints artifacts have classifications for Environment defined as Test. Specify the classifications for these related artifacts in order to make them governable and to perform state transitions by fulfilling the state transition validator constraints.
• Make a state transition on an existing object.
  To perform state transitions on a Service Versions set of artifacts – from Initiate Service Version Life Cycle, to Approve For Deployment, to Approve For Production -- involves two transitions.
• Remove governance on an existing object.
  Remove governance on a set of Service Versions artifacts.
• Delete existing objects.
  Delete a Service Versions artifact and all its related artifacts, which involves deleting Service Versions, Service Endpoints, ServiceBindings, Service Interfaces, and WSDL documents for the identified Service Versions artifact RequestCreditReportServiceService.
• Create a query and save.
  Create a query to retrieve all matching WSDL ports and save the query as BHAR_WSDL_PORT_Query.

Generate audit reports using Tivoli Common Reporting

To generate an audit report. do the initial load and the query creation and query saving step in the previous section, then use the Tivoli Common Reporting deployed report audit_all. The initial audit report is saved as Initial_Load_View.pdf and the subsequent audit report is saved as Final_Audit_View.pdf. For instructions on generating these reports using your browser to connect to the Tivoli Common Reporting runtime, see TCRConfig.doc in the download package.

Generate audit reports using the command-line reporting tool

The SA03 Auditing SupportPac supplied J2EE application ServiceRegistryAudit.ear features a command-line reporting tool that you can use from an unmanaged J2EE application client using the launchclient.bat script file. The ServiceRegistryAudit.ear J2EE application reporting tool submits the client query to the AUDIT database and returns the results to client in a comma separated value file (CSV). The reporting tool supports only the SQL WHERE clause in conditional SQL queries requested by unmanaged J2EE application clients. Report queries can include all audited events, and can qualify the matching data by using a WHERE clause involving an entity or user or events falling between certain dates. Report queries can feature WHERE clauses combined with AND keywords.

Clients can invoke the reporting tool using the following command:

launchClient ServiceRegistryAudit.ear <Report Query> <CSV File Name>

Since you want to get all of the audited events, run the following query:

c:\i\WID\pf\wps\bin\launchClient.bat c:\i\WSRR\SA03_Audit\Audit\ServiceRegistryAudit.ear
1=1 c:\temp\All_Audited_Events.csv

Enable and perform reporting

Configure the WebSphere Integration Developer Eclipse workbench for reporting

Download the SA12 SupportPac and save it to your file system. The SupportPac consists of a plug-in for the Eclipse workbench Report Designer, a second plug-in for the Tivoli Common Reporting runtime, and a sample report. From the WebSphere Integration Developer Resource Perspective, click Help => Software Updates to install the Report Designer plug-in into the Eclipse workbench. Tivoli Common Reporting V1.1.1 uses the Business Intelligence and Reporting Tool (BIRT) V2.2.1 engine, which requires a WebSphere Integration Developer Eclipse workbench that features compatible Report Designer and Report Runtime features. To use Tivoli Common Reporting, download the product from the SupportPac Web site, extract the archive file, run launchpad.exe, and follow the instructions. Then extract the SA12 SupportPac TCR Runtime plug-in com.ibm.serviceregistry.reporting.runtime_1.1.0.jar from the SupportPac archive file and copy it to TCR Install Root\lib\birt-runtime-2_2_1\ReportEngine\plugins\. If the Tivoli Common Reporting embedded WebSphere Application Server is running, recycle it for the configuration changes to take place. For details, see ReportingConfig.doc in the download package.

Set up and exercise a use case to perform reporting in Service Registry

In order to perform reporting, use the previously defined and saved WSDL Ports query named BHAR_WSDL_PORT_Query. This query retrieves all WSDL Ports defined in our Service Registry instance using the wildcard character * matching policy.

Set up reporting using the WebSphere Integration Developer Eclipse workbench

To perform reporting using the WebSphere Integration Developer workbench, first define a project named My Report Design Project in the Report Design Perspective and import the sample report into this project. Then define the data source and data set attributes for the report, and perform Preview Results to make sure your Service Registry saved query executed successfully and the retrieved results are used to generate the report. For details, see ReportingConfig.doc in the download package.

Generate reports using Tivoli Common Reporting

Once the BHAR_WSDL_PORT_Query report has been tested successfully in the WebSphere Integration Developer workbench, export the report to a file directory and zip up the directory. Then you are ready to deploy the BHAR_WSDL_PORT_Query report into the Tivoli Common Reporting runtime, using the same steps you used previously to deploy the four audit reports into the Tivoli Common Reporting runtime, as described above.

Generate reports using batch report runs

The SA12 Reporting SupportPac does not support generating reports in a batch mode, but relies instead on the Tivoli Common Reporting command-line options interface, which lets you write custom scripts to generate batch reports. A typical Tivoli Common Reporting command-line invocation has the following syntax:

trcmd -user username -password password -run -report <report set/report name>

Use the following command to generate the reports, using scripting mode. For details, see TCRBatchReportRun.doc in the download package.

(C:\>c:\i\TCR\tcr\bin\trcmd.bat -user tcradmin -password tcradmin -list -reports) 
/TivoliProducts/TCR/Overview 
/WebSphereServiceRegistryandRepository/AuditReports/audit_bsruri
/WebSphereServiceRegistryandRepository/AuditReports/audit_userid
/WebSphereServiceRegistryandRepository/AuditReports/audit_what
/WebSphereServiceRegistryandRepository/AuditReports/audit_all
(C:\>c:\i\TCR\tcr\bin\trcmd.bat -user tcradmin -password tcradmin -run -report 
    /WebSphereServiceRegistryandRepository/AuditReports/audit_all) 

Conclusion

Congratulations, you have learned how to use WebSphere Service Registry and Repository SA03 and SA12 SupportPacs in order to enable auditing and reporting.

Acknowledgements

The author would like to thank Martin Rowe and David Seager of the WebSphere Service Registry and Repository Development Team at the IBM Hursley Software Lab in the UK, for their technical contributions to this article. The author is equally grateful for editing help from Sujatha Perepa, Software Information Technology Architect (SWITA) at the IBM Federal Division in Washington D.C.

Back to top

Download

Information about download methods

Resources

• WebSphere Service Registry and Repository product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere Service Registry and Repository V6.0 information center
  A single Web portal to all WebSphere Service Registry and Repository documentation, with conceptual, task, and reference information to help you install, configure, and use the product.
  
  
• WebSphere Service Registry and Repository V6.2 information center
  A single Web portal to all WebSphere Service Registry and Repository documentation, with conceptual, task, and reference information to help you install, configure, and use the product.
  
  
• WebSphere Service Registry and Repository documentation library
  WebSphere Service Registry and Repository announcement letters, demos, documentation, Redbooks, tutorials, Webcasts, and white papers.
  
  
• WebSphere Service Registry and Repository requirements
  Hardware and software requirements for WebSphere Process Server.
  
  
• WebSphere Service Registry and Repository support
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
• WebSphere Service Registry and Repository SupportPacs
  Includes the SA03 Audit SupportPac and the SA12 Reporting SupportPac.
  
  
• Manage service availability dynamically using WebSphere ESB and WebSphere Service Registry and Repository V6.1
  This developerWorks article shows you how to dynamically manage service availability using the WebSphere Service Registry and Repository service life cycle governance model to describe the status of a service. The article also shows you how to use the WebSphere ESB endpoint lookup mediation primitive to query the registry for service status and select the appropriate service endpoint dynamically at runtime.
  
  
• The role of an auditing and reporting service in compliance management
  by J. Ramanathan et. al., IBM Systems Journal, Volume 46, No. 2, 2007. An in-depth technical journal article on auditing and reporting (fee required).
  
  
  
  
• WebSphere SOA solutions developer resources page
  Get technical resources for WebSphere SOA solutions.
  
  
• developerWorks SOA and Web services zone
  Technical resources for evaluating, planning, designing, and implementing solutions that involve SOA and Web services.
  
  
• developerWorks WebSphere application connectivity zone
  Access to WebSphere application connectivity (formerly WebSphere business integration) how-to articles, downloads, tutorials, education, product info, and more.
  
  
• developerWorks WebSphere business process management zone
  Access to WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
  
  
• WebSphere business process management products page
  For both business and technical users, a handy overview of all business process management products.
  
  
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Technical books from IBM Press
  Convenient online ordering through Barnes & Noble.
  
  
• developerWorks technical events and Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Enable and perform auditing
• Enable and perform reporting
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Service Registry and Repository
• Article: WebSphere Service Registry and Repository
• Buy: WebSphere Service Registry and Repository

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers