Use event handlers

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Developing business processes > Building BPEL processes > Defining BPEL process logic > Adding an activity to a BPEL process
Use event handlers

Event handlers are constructs that respond to external stimuli with an appropriate defined action.
In the Graphical User Interface environment, events usually signify that the user has made a demand on the system, and the application must respond to it appropriately. In such cases, a receive or pick activity can usually be used, but they have limitations.
For example, they can only be used when a process is functioning normally, and they can only be implemented once. This effectively means that you have to know ahead of time how many events to expect, and when to expect them.
Event handlers make a BPEL process more dynamic by dealing with events that happen independently of, or asynchronously to the processing of the application. They can respond to events that happen at any time during an application's lifetime, or as many times as those events repeat.

Configure an event handler

You can define and configure an event handler either on individual scopes within the process, or for the whole process in its entirety.
To create an event handler , proceed as follows:

Hover either over a scope activity or the green start node that represents the process a whole until the action bar appears as shown in this screen cap.

Click the Add event handler icon. An event handler will appear that is populated with an OnEvent element as shown here:

There are two parts to an event handler. The first part defines the conditions under which an event handler is to be invoked; that is, it defines the type of the event handler. You have the two following choices:

Element Icon Description
OnEvent element Use this element to create a control path and specify the operation that will cause this path to be followed.
Timeout element Use this element to create a control path that is followed when a specified time has either been reached or has elapsed. This element is used on a single path, and is configured to specify either a specific date, or period of time. When the process is running, this path is chosen when no input is received within this time period, or by the specified date.

The second part of an event handler defines the implementation of the event handler, or more specifically, the action that the event handler is to take when it runs. To specify this action, simply populate that handler with the necessary process activities from the palette.
There can be 0..n onEvent branches, but only one onAlarm branch. In addition, they can be mixed.
For example, you can use an event handler to wait for message A and B, and if neither arrive within a specified amount of time, then the onAlarm branch is followed.

Lifecycle of an event handler

Each event handler is enabled when the process or scope it is associated with starts. Each event handler is disabled when the process or scope it is associated with ends. Multiple instances of each event handler can be started as long as the event handler is enabled. If instances of event handlers are still running when a scope ends, then they are allowed to complete.
It is important to distinguish between enablement and dispatching. An event handler is said to be enabled once the associated scope starts. An onEvent event handler instance is said to be dispatched when the event handler is enabled, and the associated operation is invoked on the process. Similarly, an onAlarm event handler instance is dispatched when the event handler is enabled, and the specified timeout is reached.

Fault handling

Event handlers are considered a part of the normal processing of a scope. Faults within event handlers are treated like faults in the associated scope. If a fault occurs within a scope (or in an event handler associated with the scope) the fault handler disables all event handlers associated with the scope and then implicitly terminates all activities directly enclosed within the scope that are currently active. This includes the activities within currently active event handlers.

Concurrency

Multiple onEvent and timeout events can occur concurrently and they are treated as concurrent activities. An event handler is permitted to have several simultaneously active instances. A private copy of all process data and control behavior defined within an event handler is provided to each instance of an event handler.

Restrictions

Conflicting receive

Multiple event handlers with the identical interface, operation, correlation set, and partner cannot be activated simultaneously, otherwise a bpws:conflictingReceive standard fault is thrown because the process engine does not know to where to deliver an incoming message.

Conflicting request

Similarly, if multiple request-response operations.share a port type, operation, correlation set, or partner links, then a bpws:conflictingRequest standard fault exception is thrown because the client cannot distinguish the source of the reply. The effect of this is that if an event handler implements a request-response operation, then only one instance of such an event handler may be active at any point in time.

Isolated scopes

If an event handler contains an isolated scope (one that has concurrent access to shared variables), and multiple instances of this event handler are started, then concurrent processing of these instances is severely constrained. Since this may contradict the whole idea of event handlers, you should use isolated scopes carefully within event handlers. You need isolated scopes only if your scope reads a global variable in one transaction and updates the same global variable in another transaction. In most situations it is possible to avoid such a variable access pattern.

Here is an example that demonstrates how an event handler can be used in a BPEL process.

This sample BPEL process is for a job posting on an internet bulletin board.
The process begins when input is received that specifies a job description and the number of days that the offering should appear on the board. Then, a snippet activity post the information live, and a reply activity returns a posting number to the partner who initiated the process instance. At this point, the process enters a scope activity with a nested wait activity within it. The wait activity will keep the process instance active for the required number of days, and wait for input. The input is governed by an event handler that is set on the scope activity. The event handler has two control paths in it. The first begins with an OnEvent element, and is followed when an external user applies for the job. Activities on this path will then add the application to the list, and return a confirmation message to the user. The second control path begins with a timeout activity, and is set to deliver a daily report on the number of applications that have been received.
When the posting period expires, the wait activity resumes the BPEL process. At this point, a snippet activity deletes the job posting, and a complete list of all applications is sent to the human resources department.

Adding an activity to a BPEL process

Related concepts:
Replacement variables and context variables
Use Java methods in process snippets
Use custom properties for human tasks

Related tasks:
Modify the properties of an activity
Modify the type of an activity
Work with basic activities
Work with structured activities
Modeling human workflows

Element	Icon	Description
OnEvent element		Use this element to create a control path and specify the operation that will cause this path to be followed.
Timeout element		Use this element to create a control path that is followed when a specified time has either been reached or has elapsed. This element is used on a single path, and is configured to specify either a specific date, or period of time. When the process is running, this path is chosen when no input is received within this time period, or by the specified date.