Skip to content

Using Event Handlers

You add event handlers to enable a running process to react to events that may occur. You can add event handlers to your process, at either the process or scope level.

Event handlers run in tandem with a scope and are part of normal scope behavior. When a scope is active the event handler waits for the specified events. They do not take over regular processing like fault or compensation handlers do.

There are two types of events:

  • OnEvent handlers — These are incoming messages that correspond to a WSDL operation. This means that you must specify a correlation for the incoming message.
  • OnAlarm handlers — These handlers are alarms that go off after a defined period of time or when a defined point in time is reached. Alarm events can repeat after a specified period of time and are similar in functionality to the Wait activity. This happens in parallel with whatever scope (or the process itself) that the handler is associated with.

How do they work?

  • Event handler actions can be any type of activity
  • More than one event handler can be dealt with at a time while its scope is active
  • Event handlers that belong to a scope are disabled when the scope ends.
    • If the scope ends with a fault, the processing event handler is stopped.
    • If no event occurs while the scope is active, the event handler does nothing and is disabled when the scope completes. This behavior is different from a receive or pick activity: receive or pick activities must encounter the message they are waiting for before processing can continue.
  • You cannot create an event handler minus the process; an event handler cannot create the process.

When to use an event handler

  • Event handlers work well for actions that are not predictable. Let's say a reservation is unexpectedly cancelled while the order is being processed.
  • You could use an event handler to handle status requests for a process. Activities in the event handler can collect data about the state of the process and then reply to the request that triggered the event handler.
  • There are several likely event handler responses to a trigger: send a reply, terminate the process instance without additional compensation, and throw a fault to have any ongoing work undone and compensated.

To add an event handler

Event handlers must be added to the start of the process.

  1. In the BPEL Editor, right-click at the start of your process diagram, and select Add Event Handler. An OnEvent handler is added to the process.

    If you want to add an OnAlarm handler, right-click and select Add OnAlarm. If you only want an OnAlarm event handler, you can delete the original OnEvent handler.

  2. In the empty scope, add whatever activities you need to activate the event handler.

  3. You can add additional event handlers to the process.

    add event handlers

  4. In the OnAlarm properties view, you can configure the type, date, and time duration of the alarm event.

For more information about event handlers and event handling, see the Event Handler section of the BPEL Specification.

More Information