Overview

The WebSphere Service Registry and Repository IBM Tivoli Composite Application Manager for SOA Event Handler (hereafter called the Event Handler) provides integration between WebSphere Service Registry and Repository (hereafter called Service Registry and Repository) and IBM Tivoli Composite Application Manager for SOA. The Event Handler resides between Service Registry and Repository and IBM Tivoli Monitoring (Tivoli Monitoring), and performs service information federation that enables intelligent decisions to be made about service invocation based on changing conditions. The Event Handler enhances traditional service look-up and management scenarios by providing information about service health to Service Registry and Repository users. To do this, the Event Handler listens for high-level situational alerts from Composite Application Manager for SOA, and maps those that are of interest to health and performance properties associated with the services in Service Registry and Repository.

This has numerous benefits:

• A service architect, developer, or assembler can determine the relative health of a service before choosing accessing it.
• A service asset manager can use service health information as criteria for making service implementations that consistently peform poorly less visible.
• Mediations running in an Enterprise Service Bus (for example, WebSphere ESB, WebSphere Datapower for SOA Appliances, WebSphere Message Broker, and so on) can consider the health of a service in dynamic selection decisions.

The Event Handler enables you to:

• Automatically capture summary service health information in real time and place it into Service Registry and Repository.
• Make service health information visible in the context of other service metadata.
• Define the situation events that the Event Handler listens for.
• Configure the properties to which situation events map in Service Registry and Repository.
• Activate the event listener at any time when both ends of the connection are installed, because of loose coupling with both Service Registry and Repository and Composite Application Manager for SOA.

The approach used by the Event Handler for service health federation involves having the Event Handler listen for events that are triggered as a result of Composite Application Manager for SOA detecting a situation. The Event Handler checks its configuration to see if the event is one to which it is sensitive. If so, it extracts the service identity and event information from the event. This event data is mapped to a property value with the name designated in the configuration file for the event. The Service Registry and Repository publish API is used to add or modify the property associated with the identified service, where it becomes visible to Service Registry and Repository users. A correlation property is also attached to the service in the Service Registry and Repository, and is removed when the situation clears or the situation is no longer monitored.

To illustrate the integration between Service Registry and Repository and Composite Application Manager for SOA in this article, we'll use a sample Web services application (SimpleWebService.ear). This application runs in WebSphere Application Server and is monitored by Composite Application Manager for SOA for two key performance metrics: response time and message size. We'll load the WSDL files for this application into Service Registry and Repository. In this example, you'll see how to attach performance information about services to the service metadata in the registry.

In order to complete the steps in this article, you need a good understanding of service oriented architecture (SOA) and Web services concepts, and should be familiar with WebSphere Application Server (hereafter called Application Server), Service Registry and Repository, Tivoli Monitoring, and Composite Application Manager for SOA.

Back to top

Set up and configure the integration environment

In order to perform the steps in this article to demonstrate how the Event Handler provides integration between Service Registry and Repository and Composite Application Manager for SOA, you need to configure two machines as shown in Figure 1:

Back to top

Set up machine 1

Install the following software, then complete the instructions in the following sections to configure machine 1.

• Install Tivoli Monitoring Version 6.1 fix pack 4, including the Tivoli Enterprise Portal Server extensions. See Resources for more information.
• Install Composite Application Manager for SOA Version 6.1. See Resources for more information.

Configure Tivoli Monitoring to forward situation events to Service Registry and Repository

Complete the following steps to configure Tivoli Monitoring on machine 1 to forward events to an event server. Events flow from the hub Tivoli Enterprise Monitoring Server directly to the Event Handler.

1. Open Manage Tivoli Enterprise Monitoring Services.
2. Right-click Tivoli Enterprise Monitoring Server and select Reconfigure.
   
   Figure 2. Reconfigure Tivoli Enterprise Monitoring Services
   
   
   
3. In the Configuration Options dialog, select TEC Event Integration Facility.
   
   Figure 3. Selecting TEC Event Integration Facility
   
   
   
4. Leave the rest of the fields as the defaults, and click OK.
5. You'll see the Hub TEMS Configuration dialog, as shown in Figure 4. Leave the fields as the defaults, and click OK.
   
   Figure 4. Hub TEMS configuration
   
   
   
6. In the TEC Server: Location and Port Number dialog, configure the TEC server by do the following:
   • In the TEC Server Location field, specify the host name or IP address for the server where the Event Handler is deployed. The Event Handler Acts as an Event Integration Facility listener and intercepts events directly from Tivoli Monitoring.
   • In the TEC Port Number field, specify the port number that the Event Handler is listening on. By default, the Event Handler uses port number 1111. The port number must match the port number value specified when you configure the event handler.
   • Click OK.
     
     Figure 5. Configure the TEC Server
     
     
     
7. Edit the Event Integration Facility (EIF) configuration file on the server where Tivoli Enterprise Monitoring Server is installed. You'll find the file at C:\IBM\ITM\cms\TECLIB\OM_TEC.CONFIG, where C:\IBM\ITM is the default location where the Tivoli Enterprise Monitoring Server is installed.

   Add or change the parameters in the EIF configuration file, as shown in the table below. It's assumed that you haven't already configured Tivoli Monitoring to point to another event server like the Tivoli Enterprise Console. If the EIF configuration file already contains values for any of the parameters listed above, replace the current values with the values in the table.

   Note: The EIF configuration file also contains other parameters, including Server Location and Server Port, which are set to the values you configured in step 5. However, you must use the procedure described in step 5 to specify the host name and port number for the Event Handler, rather than editing the EIF configuration file directly with these values.

   
   
   

   Name	Value	Description
   FilterMode	IN	Enables event filtering
   Filter:Class	ITM_Services_Inventory_610;	Event filter that forwards all Composite Application Manager for SOA events for the Services_Inventory_610 table to the Event Handler
   FilterCache:Class	ITM_Services_Inventory_610;	Filter that specifies which events to cache when Tivoli Monitoring is unable to forward an event to the Event Handler

   
   
   
8. If not already there, copy the kd4.map file to the same directory as the EIF configuration file. You'll find the kd4.map file on the Composite Application Manager for SOA V6.1 installation media or in the Composite Application Manager4soa-tec-file.zip file included in the sa04.zip and sa04.tgz files that you can download from the WebSphere Service Registry and Repository Composite Application Manager for SOA Event Handler Web page.
9. Restart the Tivoli Enterprise Monitoring Server.

Install the sample Web services application

To illustrate the integration between Service Registry and Repository and Composite Application Manager for SOA, we've created a sample Web services application that you can use to fire situations on demand. Download the sample application SimpleWebService.ear and install it into WebSphere Application Server on machine 2 by doing the following from the administrative console:

1. Select Windows => Start => Programs => IBM WebSphere => Application Server V6 => Profiles => default => Administrative Console.
2. Under Applications, select Install New Application, then select SimpleWebService.ear, and click Next, as shown in Figure 6:
   
   Figure 6. Specify the file to install
   
   
   
3. Click Next on the next three dialogs, then Finish on the final installation dialog, leaving all settings as the defaults, and complete the installation.
4. On the next dialog, click Save to Master Configuration, as shown in Figure 7.
   
   Figure 7. Save the configuration
   
   
   
5. Click Save on the next dialog, as shown in Figure 8:
   
   Figure 8. Save to the master configuration
   
   
   
6. Return to the application list by selecting Applications => Enterprise Applications, and start the application. Figure 9 shows the sample Web services application installed and started:
   
   Figure 9. Sample application installed in WebSphere Application Server
   
   
   
7. Open the test client for the application in a browser. The default URL is: http://localhost:9080/SimpleWebServiceClient/sampleSimpleServiceProxy/TestClient.jsp. You should see the interface, as shown in Figure 10:
   
   Figure 10. Sample application user interface
   
   
   

   On the left you see the methods available in the sample Web service. At the bottom is the results frame, where the results of any invoked methods will appear. Above that is the main frame where parameters are completed and the methods are actually invoked. We'll use the following methods:

   • getEndpoint() - Returns the current SOAP endpoint. The default is http://localhost:9080/SimpleWebService/services/SimpleService. However, if the server is running on port 9081, the test client will fail. You can use getEndpoint to get the current value on which to base the parameter to send to the setEndpoint method.
   • setEndpoint(java.lang.String) - Use this method to set the SOAP endpoint of the simple service. When running on a non-standard port, use this method coupled with getEndpoint() to specify the relevant endpoint.
   • echoWithBytes(java.lang.String,int) - Use this method to echo a string back to the client followed by extra data to ensure the total message size is at least as large as the number of bytes specified by the int parameter. You can use this method to exceed the default 1600-byte threshold of the MessageSize_610 situation.
   • echoWithDelay(java.lang.String,int) - Use this method to echo a string back to the client after a delay of the number of seconds specified by the int parameter. You can use this method to delay a message long enough to trigger a ResponseTimeCritical_610, which has a default threshold of 10 seconds.

Set up machine 2

Install the following software, then complete the steps in the following sections.

• Install WebSphere Service Registry and Repository Version 6, fix pack 1. See Resources for more information.
• Install Tivoli Composite Application Manager for SOA Event Handler for WebSphere Service Registry and Repository. See Resources for more information.

Load the WSDL into Service Registry and Repository

In order to update metadata in Service Registry and Repository for the sample service, you need to load the service's WSDL document, SimpleService.wsdl, into Service Registry and Repository. The WSDL is available in the Downloads section. Using the Service Registry and Repository user interface, complete the following steps:

1. Browse to the registry's URL: http://localhost:9080/ServiceRegistry.
2. Select Service Documents => WSDL Documents, then click Load Document, as shown in Figure 11:
   
   Figure 11. Load the WSDL file into the registry - step 1
   
   
   
3. In the next dialog, specify the WSDL file to load by doing the following, as shown in Figure 12:
   • Select Remote file location.
   • In the Specify URL field, enter the URL of the WSDL for the example service, as follows:

     http://<hostname>:9080/SimpleWebService/services/SimpleService/wsdl/SimpleService.wsdl

     
     

     In our example, the registry and the service are on different hosts, as shown in Figure 12, so you need to update the host name to reflect the server on which the service is deployed. Also if clients, such as the ESB, are to retrieve the endpoint from Service Registry and Repository to bind to at runtime, you need to specify the actual host name instead of localhost.

   • Optionally, enter an description and version.
   • Click OK.
     
     Figure 12. Load the WSDL file into Service Registry and Repository - step 2
     
     
     
4. Select Service Metadata => WSDL => Ports, and select Simple Service.
5. Select Custom properties under Additional properties on the right, as shown in Figure 13:
   
   Figure 13. Service metadata custom properties
   
   
   

   This is where the metadata properties for the WSDLPort object are added or updated by the Event Handler.

Download and install the Event Handler

Next you need to download and install the Event Handler. See Resources for more information. Do the following to configure the Event Handler:

1. Open the Event Handler by browsing to: http://<servername>:<portnumber>/Composite Application ManagerWeb/admin, where <servername>:<portnumber> are the server name and port number of the application server on which the Event Handler is running. For example, http://myserver:9080/Composite Application ManagerWeb/admin.
2. Specify the registry to be updated by the Event Handler in the Endpoint field. For example, http://<hostname>:9080/WSRRCoreSDO/services/WSRRCoreSDOPort where <hostname> is the host name of the machine on which the Event Handler is running.
3. Make sure that the Port field is set to the default of 1111.
   
   Figure 14. Event Handler user interface
   
   
   
4. Leave the default values for the required security and logging information. On the left hand side are links to the status page, where the Event Handler can be stopped and started and the Event Mapping page where the incoming ITCAM for SOA events are mapped to custom properties in the registry.
5. You can configure the Event Handler to process Composite Application Manager for SOA situation events generated from the Services Services Inventory_610 table. Composite Application Manager for SOA provides a set of predefined situations for this table. The Event Handler uses the port name and port namespace event properties to identify the WSDLPort and SCA Export to update in the registry. Composite Application Manager for SOA forwards events detected for service requesters and service providers to the Event Handler. However, the Event Handler only updates properties in the registry when it receives an event for a service provider.

   Select EventMapping on the left to map the incoming Composite Application Manager for SOA events to custom properties in the registry, then do the following, as shown in Figure 15:

   • Delete all the default properties by clicking Delete next to each property.
   • Click Create and add the two event mappings shown in Figure 15.
     
     Figure 15. Event mapping
     
     
     When the Response Time Critical event fires, the WSRRPropertyName (max_elapsed_time_RTC_610) is added to WSDLPort and is set to the value of the max_elapsed_time slot in the event. The value of the max_elapsed_time_RTC_601 property is reset to normal once the situation clears. When the Message Size fires, the WSRRPropertyName (avg_message_length) is added to WSDLPort and is set to the static string "event is being opened". This property is removed when the situation clears.
   • Click Submit to save the configuration.

When metadata is updated in the Service Registry and Repository, a correlation property is added to the custom properties in the Service Registry and Repository. The Correlation property enables the Event Handler to quickly identify the property that needs to be changed when the situation clears. Do not modify this property.

A Compound property is used by the Event Handler to append the service operation to the WSRRPropertyName. It helps to differentiate the service health of one operation from another for the same service.

Fire situations for the monitored Web service

Composite Application Manager for SOA has predefined situations that you can use to monitor service performance metrics. In this article, we'll use the Message Size and the Response Time Critical situations to illustrate the integration between Service Registry and Repository and Composite Application Manager for SOA.

Fire a Response Time Critical siituation

The Response Time Critical situation has a predefined value of 10 seconds. This means that when the response to a Web service exceeds 10 seconds, a Response Time Critical situation is fired by Tivoli Monitoring. To trigger the situation, invoke the echoWithDelay operation using the SimpleWebService.ear user interface with any string and a delay of greater than 10 seconds, as shown in Figure 16:

The default interval is five minutes, so one request with a response of 20 seconds in a five minute period should be enough to fire the event, as long as you make no other shorter requests during the same interval. The SimpleWebService.earResponse Time Critical situation should display in the Tivoli Enterprise Portal console as shown in Figure 17.

Fire the MessageSize_610 situation

The Message Size situation has a default threshold of 1600 bytes. Assuming this default has not been changed, call the echoWithBytes operation of SimpleWebService.ear with any string and a number of bytes greater than 1600, as shown in Figure 18:

Make a message request with 11000 bytes by calling the echoWithBytes operation in the sampling interval of 5 minutes. This triggers the situation, which displays in Tivoli Enterprise Portal console as shown in Figure 19:

Back to top

How metadata is updated in the registry

When Tivoli Monitoring detects an Composite Application Manager for SOA event for a service, it sends an event to the Event Handler (optionally using Tivoli Enterprise Console), which updates metadata in the registry for that service. The Event Handler creates, updates, or removes properties on the WSDLPort or SCA Export logical objects in the registry. Figure 20 shows how the metadata property is updated in the registry when both situations have fired.

Once the situation clears within a sampling interval, the metadata properties on the WSDL port object are updated according to the configuration defined in the Event Handler. In our example, we configured the clearing value for the Response Time Critical situation,to be a static string "back to normal" as shown in Figure 21. For the Message Size situation, we configured the Event Handler to remove the property. The Correlation properties for all situations are always removed when a situation clears.

Back to top

Summary

In this article, you used the sample Web services application provided to attach performance information about a service to service metadata in the registry. This information can be used by mediations running in ESBs to dynamically select services based on service health, and by developers choosing a specific service to access.

Back to top

Downloads

Information about download methods

Resources

Learn

• WebSphere Service Registry and Repository IBM Tivoli Composite Application Manager for SOA Event Handler product information
  
  
• Tivoli Monitoring Information Center
  
  
• IBM Tivoli Composite Application Manager for SOA Information Center
  
  
• WebSphere Service Registry and Repository Information Center
  
  
• IBM Tivoli Composite Application Manager for SOA, Version 6.1 Installation Guide
  
  
• IBM Tivoli Composite Application Manager for SOA Event Handler for WebSphere Service Registry and Repository User Guide
  
  
• Composite Application Manager for SOA Information Center
  
  
• developerWorks Websphere business integration zone
  
  
• developerWorks Websphere SOA zone
  
  

Get products and technologies

• SA04: WebSphere Service Registry and Repository Composite Application Manager for SOA Event Handler
  
  

About the authors

Rohit Badlaney is an Advisory Software Engineer at IBM in RTP, North Carolina. He is the QA Lead for ITCAM for SOA. You can reach Rohit at ribadlan@us.ibm.com.

Son Cao is a Staff Software Engineer at IBM Tivoli in RTP, North Carolina. He is part of the component test team for ITCAM for SOA. You can reach Son at scao@us.ibm.com.

Stephen Willoughby is a Staff Software Engineer at IBM Hursley, UK. He is a system tester for the registry team. You can reach Stephen at stephen.willoughby@uk.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Overview
• Set up and configure the integration environment
• Set up machine 1
• Set up machine 2
• Fire situations for the monitored Web service
• How metadata is updated in the registry
• Summary
• Downloads
• Resources
• About the authors
• 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

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers