Creating an ActiveBPEL Engine Event Monitor

Introduction

During normal operation of the ActiveBPEL^® Engine, events occur and are reported via the internal logging mechanism. This typically includes output to the host server console and/or logging system (e.g., log files).

ActiveBPEL Engine events can also be monitored by a remote web service. This service can then process the events as its designer sees fit. For instance, critical alerts or periodic updates can be sent to another service, emailed to an administrator account, etc.

This sample will demonstrate the construction and configuration of a simple event monitor. It utilizes mechanisms that are very similar to those covered in the ActiveBPEL Admin API and Custom Invoke Handler samples. You should familiarize yourself with those samples before continuing, as this sample will not cover those topics in any great depth.

NOTE: This sample is compatible with ActiveBPEL version 4.1 and above only.

Objectives

• Implement an event monitor service / BPEL process that listens for and optionally reports on engine events.
• Deploy the above process and send custom messages to the event monitor to enable/disable event monitoring.

Getting Set Up

The files provided with this article are contained in engine_event_monitor.zip. Extract this archive into a directory of your choosing. The archive contains numerous folders containing an Eclipse Java Project, an ActiveBPEL^® Designer project, various support, test and deployment files, and this documentation page.

Event Monitor BPEL Process

If you plan to use the ActiveBPEL Designer to create, simulate or test your process, start the ActiveBPEL Designer application. From the main menu, select File / Import / Existing project into workspace and navigate to the following project directory

[archive extraction location]/engine_event_monitor/support/bpel_process

This opens a project called Event_Monitor, which appears in the Navigator View.

With the project successfully imported, switch to the Web References view and select the Add a Web Reference icon. Select the Browse Projects... button and navigate to the wsdl directory under the Event_Monitor project folder. Add the WSDL files that you see there. They appear in the Web References View.

Event Monitor Custom Invoke Handlers

If you’re using Eclipse for the Java development portion of this project, run Eclipse. From the main menu, select File / Import / Existing project into workspace and navigate to the following Eclipse project directory

[archive extraction location]/engine_event_monitor

This opens a project called engine_event_monitor, with various supporting directories. The project is self-sufficient and contains the source files needed to build our sample custom invoke handlers as well as a test client application.

One manual step you may need to perform is to create an AESAMPLES_LIB variable for the project's Java Build Path (i.e., you may see "Unbound classpath variable"; errors for the project). Create the variable by right-clicking on the project in the Package Explorer and selecting Build Path / Configure Build Path... . Select the Libraries tab, and click the Add Variable... button. Click the Configure Variables... button in the dialog that appears, and then New... Create an AESAMPLES_LIB variable that points to the the appropriate directory, as specified in the common library sample archive (click here for more information). Click OK to exit the dialogs and answer Yes if asked to do a full rebuild of the project.

Note: it's possible you'll see Eclipse Warnings in the Problems view for this project, i.e., "missing required library". Unless you also see Errors associated with these, the warnings can be safely ignored.
 

If you’re not using Eclipse, you can still use the files supplied with this sample. There is a build.xml Ant script in the project directory root that contains build targets for creating the custom event processing invoke handler - all described in detail below. Here’s the archive’s directory structure.

Using the Remote Admin / Event Handler Framework

The ActiveBPEL server exposes a web service interface that provides for implementation of a remote control application. This is the mechanism that is used by ActiveBPEL Designer when running in the Remote Debug mode.

One of the features of this interface is the ability to register for and receive event notification messages as events occur within the engine. These include instantiation of a new process, process faults, etc. This is the mechanism we will leverage for our Event Monitor process.

BPEL Admin and Event Handler Web Service WSDLs

In the ActiveBPEL Admin API sample, we found that the WSDL definitions we need to communicate with the ActiveBPEL Engine are published at the following URL:

http://localhost:8080/active-bpel/services/ActiveBpelAdmin?wsdl

This WSDL is found in file ActiveBpelAdmin.wsdl. Also, because we'll be exposing "callback" services to the engine for event reporting, we'll be importing another set of definitions found in ActiveBpelEventHandler.wsdl. This WSDL file specifies the operations and messages that must be implemented so that the engine can send event information to our event monitor process.  Both files are located in /engine_event_monitor/support/bpel_process/wsdl.

For detailed information on event types and their meanings, see the IAeEngineEvent and IAeProcessInfoEvent interfaces in the org.activebpel.rt.bpel package of the ActiveBPEL Open Source Engine code distribution, which is available here.

Constructing the Event Notification Service WSDL File

Examine the eventNotification.wsdl file, located in /engine_event_monitor/support/bpel_process/wsdl. Note that there are a series of namespace definitions, two wsdl:import declarations, a wsdl:types/schema declaration section and several definition sections identified by comment markers.

The namespace definitions include the following two declarations

http://docs.active-endpoints/wsdl/activebpeladmin/2007/01/activebpeladmin.wsdl

http://docs.active-endpoints/wsdl/eventhandler/2007/01/eventhandler.wsdl

These are imported as ActiveBpelAdmin.wsdl and ActiveBpelEventHandler.wsdl, respectively, and include the web service information needed to communicate with the ActiveBPEL Engine.

Following this, we have a message definition - arrayOfEvents - defined to make handling of our event list arrays easier. This message has one part - stringArray - that is of type ArrayOfString, which is defined in the xsd:schema section above the message.

The first set of definitions are those needed to remotely control our monitor service. The eventMonitorEnablePLT and eventMonitorDisablePLT partnerLinkTypes are associated with the following message, portTypes and operations:

• eventMonitorSwitch message
• EventMonitorEnablePortType portType
• EventMonitorDisablePortType portType
• enable operation
• disable operation

Note that the eventMonitorSwitch message has a part based on a type with no elements. We want to invoke this process with a message style of Document Literal, so we need to give this message's part an empty root element, thus the need for the switchOnOff schema definition.

Next are the definitions for interaction with our custom invoke handler, which sends an email as notification for engine events. Examine org.activebpel.samples.event_monitor.pojo.EngineEventNotifier.java to see the details of how the incoming event message is processed. The interface to this custom invoke handler is associated with the eventNotificationPLT partnerLinkType and utilizes the following:

• eventNotification message
• EventNotificationPortType portType
• notify operation

Next, the partnerLinkType we'll use to register and unregister our process with the ActiveBPEL engine as an event listener is defined as addListenerPLT.

The service exposed by our process will also need to support an operation that allows the ActiveBPEL engine to send us event notification messages - a form of callback mechanism. This is specified in ActiveBpelEventHandler.wsdl and will be reference by the partnerLinkType named eventHandlerPLT.

Constructing the Event Monitor's Custom Invoke Handler 

When our event monitor process is invoked by the ActiveBPEL server, it will be sent a WSDL message that contains a process ID (PID), process name and an event type. The process will extract the event type and PID and store them for transmission later as a concatenated list of events, delimited with the tilde ('~') character. Also, commas in the incoming message will be converted to tabs for formatted output.  This concatenated string will be sent to the custom invoke handler for transmission.

Our event monitor's custom invoke handler will be a Plain Old Java Object (POJO) - EngineEventNotifier.java. It implements the IAeInvokeHandler interface and accepts the message parameters from the notify invocation. The service definition for this handler is found in eventNotification.wsdl. This WSDL defines the structure of the message that will be sent to our POJO, which does the work of sending out our email message. This class gets its information from two sources. These are: the message sent via the invocation, which provides the list of events that occurred, and invokeHandler parameters defined in the event monitor process' PDD, which will provide the email sender, recipient, SMTP host, etc. These parameters are defined when the event monitor BPEL process is deployed, which is discussed below.

Use the build.xml Ant script to create engine_event_monitor.jar (run the ant command in the project's root directory). Copy this jar file to your working library directory for the ActiveBPEL server type you're using. For instance, with ActiveBPEL Enterprise for Tomcat, this file will go into the %CATALINA_HOME%/shared/lib directory. Consult your application server documentation to locate the appropriate directory for other product configurations.

Note that additional email-related jars (smtp.jar, activation.jar, etc.) may be needed if your installation doesn't already have these available. Examples of these are provided in the project's lib directory.

Constructing the Event Monitor BPEL Process

The next step is to create the event monitor BPEL process itself. This has already been done for you in this sample. The process definition can be found in event_monitor.bpel.  If you wish to reproduce this process in a new file, or modify it, you'll need to add eventNotification.wsdl, ActiveBpelAdmin.wsdl and ActiveBpelEventHandler.wsdl to Web References.

The event monitor process operates as follows.

• TurnOnEventMonitor receives an empty message via invocation of the enable operation, instantiating the process.
• Subsequent invocations of the enable operation are handled by the On Event handler in the process-level Event Handlers section - this prevents multiple instances of the process from being created. These incoming messages are purposely uncorrelated, which makes this process act as a 'singleton' - so you will see Warnings if you open the process file in ActiveBPEL Designer. This is expected.
• Initialization sets up the callback URL and context ID for event listener registration. It also initializes the monitor and sets flags so that incoming events will be added to the 'A' event list.
• AddEngineEventListener sends a message to the ActiveBPEL engine, requesting event listener status. The synchronous reply is an empty message.
• RunUntilMonitorIsDisabled is a while loop that repeats until the monitorEnabled flag is set to false by the On Event activity in the Event Handlers section
• This On Event - the one containing Exit and RemoveEngineEventListener - exposes the disable operation, which is what we use to turn the monitor off. Note that this On Event is also purposely uncorrelated. When this operation is invoked, the monitorEnabled flag is set to false and the process is un-registered with the ActiveBPEL engine. The process terminates the next time through the loop, sending any events that have accumulated before it does so.
• The first activity in the While is a Wait - CheckEvery60Seconds - that has a 60 second timeout (you can reconfigure this as desired by changing its for attribute).
• During the Wait activity's delay, the third On Event in the Event Handlers section receives (again, uncorrelated) incoming event messages from the ActiveBPEL engine.
• AddNewEvent defines a Scope for local variables.
• Because multiple instances of this On Event may be executing simultaneously, a local copy of the current eventListIndex is recorded by GrabIndexAndIncrement and then the index is incremented in the same Assign activity. This precludes crosstalk between concurrently running On Event instances that might potentially result in lost events.
• AddToAorB determines whether the process is presently filling the 'A' or 'B' event list, and branches accordingly.
• Both AddEventToA and AddEventToB are identical, except for the event list they update. The incoming message is parsed and the process ID, a delimiting comma, and event type are used to construct a string which is added to the event list array.
• Finally, RespondToEventMsg sends an empty message back to the engine to acknowledge receipt of the event.
• When the timeout expires, the CheckForNewEvents Switch determines whether or not any new events have been added to the currently active event list ('A' or 'B'). If so, the execution continues in the SendEventList Scope, otherwise an Empty activity, NoAction, is executed and the loop repeats, beginning with another timeout.
• LocalInit sets the loop counter and sets up the initial text of the outgoing event message.
• ProcessAorB_Accumulator determines which is the currently active event list and branches accordingly.
• SwitchToB and SwitchToA toggle the currently active event list (double buffer) so that one list can be filled with incoming events while the other is being processed. These also append their list ID ('A' or 'B') to the event list header.
• The subsequent While activity loops once for each entry in the now-currently-inactive event list, concatenating these into one string, with the individual events delimited by tilde ('~') characters.
• SendEventList calls our custom invoke handler POJO to process the event list string and email it off using the parameters defined in the process' PDD.

You can simulate this process by using sample data files found in the wsdl subdirectory - eventMessage.xml, which is used for the On Event that accepts events from the ActiveBPEL engine, and turnOnOff.xml, which is used to start the process via TurnOnEventMonitor or disable/terminate it via the On Event set up for that purpose .

Deploying the Event Monitor Process

Once you've constructed the event monitor BPEL process, it can be deployed to ActiveBPEL, and configured to report on any events detected by the BPEL engine. Creating the deployment descriptor for this process involves a couple of extra considerations, however.

Note that there is an event_monitor.pdd file included in this sample. You can use this if you only need to modify the email parameters (described below). If so, skip down to the Deployment section.

If you want to build your own process deployment descriptor, the following instructions describe how this file is constructed using ActiveBPEL Designer.

Select event_monitor.bpel from the Navigator View and right-click. Select New / Deployment Descriptor to start the New Deployment Descriptor wizard. Select your product type as the Deployment Platform and click Next. Then click Next again to accept the default persistence settings.

The Partner Links page is where we'll define the run-time bindings for the partner links defined in our process. Select addListenerPLT from the list of Partner Links. Under Partner Role, select an Endpoint Type of static. Click the "..." button to the right of the Endpoint Reference text area. Select the WSDL drop-down list near the middle of the dialog and select ActiveBpelAdmin.wsdl. Select ActiveBpelAdmin - ActiveBpelAdmin in the Service - Port window. Click OK to accept. The Endpoint Reference text area is filled with the service binding information required to communicate with the engine. Note that if your engine is installed on a host/port other than localhost:8080, you'll need to modify this.

Next, select eventNotificationPLT at the bottom of the list of Partner Links. This is the partnerLink associated with our custom invoke handler POJO. Under Partner Role, select an Invoke Handler of java. A text entry box appears to its right. Click the "..." button to the right of that. Here is where we'll enter the details of how our custom invoke handler is called. Set the Name and Query String values as follows:

Name: org.activebpel.samples.event_monitor.pojo.EngineEventNotifier

Query String: sender=from@sender.com&recipient=to@recipient.com&SMTPHost=mail.mailhost.com

You should replace from@sender.com, to@recipient.com and mail.mailhost.com with the values appropriate to your enterprise. The first two must be valid email addresses and the third must be a valid SMTP mail host from which hosts in your domain are authorized to send email. If your mailhost requires password authorization to send mail, enter it as an SMTPAuth argument after SMTPHost. Click OK. The two values are combined in the text entry box. Select an Endpoint Type of static. Note that the Endpoint Reference text area is populated with a default definition. You must replace the entries that begin with "FILL_IN...". Replace these as follows.

FILL_IN_NAMESPACE: http://www.active-endpoints.com/services/eventNotification

FILL_IN_ADDRESS_URI: http://no.target.address.specified

FILL_IN_PORT_NAME: EventNotificationPortType

FILL_IN_SERVICE_NAME: EventNotificationService

Note that all of these are simple placeholders except for the namespace value.

Select eventHandlerPLT from the list of Partner Links. Under My Role select a Binding of Document Literal. Next, select eventMonitorDisablePLT, select a My Role Binding of Document Literal and remove the "PLT" from the Service name. Do the same for eventMonitorEnablePLT.

Click Next, then Next again to go past the Indexed Properties page. Accept (or edit, if you wish) the File name value and click Finish.

Deployment

Once the PDD has been created you can deploy your event monitor process. Ensure that the ActiveBPEL engine (or Enterprise) is running, right-click on the event_monitor.pdd file (or whatever name you chose) in the Navigator View and select Export... In the Export wizard, select Business Process Archive File and click Next. Enter or accept the BPR file desination. Under Deployment select a Type of Web Service. Leave the checkbox under the Options section un-checked (or un-check, as needed). Click Finish to deploy your process to the server.

Test the Event Monitor

Once the event monitor process is deployed, you can start/enable it by sending the following message to it using any web service client. The soapUI application works well for this. Create a New WSDL Project with the following URL:

    URL: http://localhost:8080/active-bpel/services/eventMonitorEnableService?wsdl

Submit a web service request message using eventMonitorEnableServiceBinding/enable/Request 1 request definition. There is no response message, but you should be able to see your process in the Active Processes list (via the ActiveBPEL Admin Console) with a status of "Running" at this point. Check console or log output for errors if you don't see it there or if its status is "Faulted", etc. 

You can now start/stop/fault other processes. These actions will generate events that will be sent to your event monitor. Once each minute these events, if received, will be sent to the email address specified in your PDD. The message contains a table of Event types and their associate Process IDs. The letter in parentheses indicates which activity list the message was reported from.

When desired, you can turn the event monitor off by sending the message above to the disable service. Note that because of the Wait activity, it may take up to a minute for the process to terminate.

    URL: http://localhost:8080/active-bpel/services/eventMonitorDisableService?wsdl

Copyright © 2004–2007 Active Endpoints, Inc.