Sample Guide - Event Handler

Objective

Event handlers are part of the process definitions and they can be defined at either the scope (local) or process (global) levels and they remain active as long as their enclosing scope or process remains active. Event Handlers define how the process will deal with events that occur independently of the process itself. An Event Handler's event is triggered when a defined event occurs, either a message event or an alarm event. The message events are triggered by an incoming message, whereas Alarms are triggered by either a deadline or duration. A definition of an event handler has two parts:

  • Conditions under which an event handler is to be invoked. It defines the type of the event handler.
    1. An onEvent event handler handles the occurrence of an external message event. This is the invocation of an operation.
    2. An onAlarm event handler handles the expiration of a timeout.
  • Actions the event handler has to take. It defines the implementation of the event handler or the business logic.
An event handler is statically enforced to contain at least one <onEvent> or <onAlarm> element. The portType attribute on <onEvent> is optional. If the portType attribute is included, the value of the portType attribute must match with the portType value implied by the value of the partnerLink's myRole attribute. All instances of <onEvent> must use exactly one of messageType, element or <fromParts>. The activity enclosed within <onEvent> and <onAlarm> must be a <scope>.

Prerequisites

  • Log in into BPS server admin console.
  • Under Business Processes -> Add BPEL.
  • Upload the SampleEventHandler.zip, (located at <BPS_HOME>/repository/samples/bpel directory)
  • Under the Business Processes -> Processes.
  • Under the WSDL details widget -> Create instance

Overall Idea

A sample Event Handler Syntax has shown below.

<eventHandlers>?
	<!-- Note: There must be at least one onEvent or onAlarm. -->
	<onEvent partnerLink="NCName" portType="QName"? operation="NCName"
			( messageType="QName" | element="QName" )?
			variable="BPELVariableName"? messageExchange="NCName"?>*
		<correlations>?
			<correlation set="NCName" initiate="yes|join|no"? />+
		</correlations>
		<fromParts>?
			<fromPart part="NCName" toVariable="BPELVariableName" />+
		</fromParts>
		<scope ...>...</scope>
	</onEvent>
	<onAlarm>*
		( <for expressionLanguage="anyURI"?>duration-expr</for> |
		<until expressionLanguage="anyURI"?>deadline-expr</until> )?
		<repeatEvery expressionLanguage="anyURI"?>duration-expr
		</repeatEvery>?
		<scope ...>...</scope>
	</onAlarm>
</eventHandlers>

It has an onEvent definition section and an onAlarm definition section. It is required to have either an OnMessage or an OnAlarm defined for an Event Handler. The Event Handler section can have a Correlation Set as the Event Handler is part of the conversation with one of our partners and the Correlation Set will continue to maintain the ongoing conversation's integrity. The onEvent section is followed by an "onAlarm" activity definition. The OnAlarm can be based on either a duration (eg: wait for 2 hours) or a deadline (eg: wait until 2 PM) and has an optional "repeatEvery" setting which allows a duration alarm to reset after being triggered.