Working With Activity Event Handlers

Event handlers and -actions for activities are managed in the activity properties dialog. By selecting Event Handlers and respectively subordinate the handlers or actions in the overview tree on the left side, the corresponding pane opens on the right side.

 

Activity Event Handler Pane
Figure: Structure of an Event Action Pane

The overview tree groups handlers by type. Subordinate to the handlers the bind actions and event actions are listed.

 


Figure: The Overview Tree

Creating Event Handlers

To create an event handler:

  1. In the event handlers pane, choose an event handler type.
  2. Press the Add button.
  3. In the corresponding pane of the new event handler, optionally change the ID and name of the event handler. Please note that IDs containing hyphens, blanks or dots and IDs starting with digits are not supported. The name is used to display the handler in the overview tree.

 


Figure: Definition of an Event Handler

Event handlers must have an ID uniquely identifying them in the scope of the associated activity and a probably human readable name. Additionally, event handlers may have some of the following general attributes:

Please refer to Events for basic informations.

The following event handlers are provided for activities:

Timer Event Handlers

A timer event handler can be configured either through the handler dialog or through workflow data. While a modeling-time timer constant can only be of type ag.carnot.base.Period (specifying an offset to the event binding time), a timer derived from workflow data may either be of type java.util.Date, long or java.lang.Long (defining an absolute time) or ag.carnot.base.Period (again specifying an offset to the event binding time). Numeric timer values are considered to be milliseconds since January 1, 1970 0:0 GMT, according to the specification of method getTime() of class java.util.Date.


Figure: Timer Event Handler Properties

Timer Event Handlers for Resubmission

Resubmission of an activity means removing an interactive activity instance from a worklist and putting it back later, based on some criterion. To model resubmission for an activity, you have to create a timer event handler with specific settings in the following way:

Add a Timer Event Handler
Figure: Add a Timer Event Handler.

Event Handler Properties
Figure: Set the Event Handler Properties.

Now add a scheduled bind action with activity instance state hibernated:

Bind Action
Figure: Add a Bind Action.

Now add a scheduled event action with activity instance state suspended:

Event Action
Figure: Add an Event Action.

Sending activities to the default performers worklist

In case you don't like the activity to go back into the worklist of the user but to the default performer worklist, add an event action with the action type Delegate Activity and the option to send the activity to the default performer:

Send an Activity to the Default Performer
Figure: Option to send an Activity to the Default Performer

Activity State Change Event Handlers

For an activity state change event handler you can specify the intended source state and target state you want to match.

State Change Event Handler Properties
Figure: State Change Event Handler Properties

Exception Handlers

For an exception event handler you can specify the exception type to be caught. The set of caught exceptions is aligned to Java try...catch rules as all instances of specializations of the specified exception type are caught as well.

Activity Properties Dialog with the Exception Event Action
Figure: Activity Properties Dialog with the Exception Event Action

Catching exceptions will prevent the targeted activity instance from being interrupted. Any caught exception is available to event actions associated with the event handler through dereferentiation of an event access point.

Assignment Event Handlers

For event handler assignment nothing has to be configured.

Modifying Event Handlers

Event handlers can be modified by selecting them in the overview tree and then editing their properties in the details pane.

Order of event handlers

All engine event handlers are executed in the order specified in the corresponding properties dialogs, e.g. the activity properties dialog and the process definition dialog. Event handlers may be reordered by selecting an event handler in the event handlers pane of the corresponding properties dialog and then moving it by pressing the Move Up and Move Down buttons.

Deleting Event Handlers

An event handler can be deleted by selecting it in the event handlers pane of the properties dialog and then pressing the Delete button.

Creating Event Actions

To create an event action for an event handler:

  1. In the Event Handling section of the overview tree, select for example On Activity State Change to open the event handlers pane.
  2. In the event handlers pane, select the event handler and press the Add Event Action button.
  3. Optionally, change the ID and the name of the action.

Apply an Event Action
Figure: Apply an Event Action

Bind actions are created in a similar manner. Click Add Bind Action or Add Unbind Action to add a bind or unbind action. See also Event Binding.

Event Action Types

The following event action types are available depending on the event handler type:

Event Action Type Activity Event Handler Types
Abort ProcessTimer, On Exception
Abort ActivityTimer, On Exception
Delegate ActivityOn Activity State Change, Timer, On Exception
Send MailOn Activity State Change, Timer, On Exception, On Assignment
Process TriggerOn Activity State Change, Timer, On Exception, On Assignment
Schedule Activity ActionsOn Activity State Change, Timer, On Exception, On Assignment
Set Data ActionsOn Activity State Change, Timer, Exception
Activate Activity ActionsOn Assignment
Complete ActivityTimer, On Exception
Exclude User ActionOn Assignment

Abort Process Actions

Abort process actions implicitly target the process instance hosting the current activity instance, thus not needing to be configured.

Abort Activity Actions

You have the option to choose whether the abortion is performed starting from the root process instance or starting from the subprocess.

Abort Activity Options
Figure: Abort Activity Options

Abort starting from the root hierarchy

In case an activity instance has the scope RootHierarchy, an abortion will cause the denoted activity instance to be aborted at the next possible commit points, e.g. as soon as synchronous activity threads are terminated. If the denoted activity instance is a subprocess activity, the corresponding subprocess will be terminated likewise.

Abort starting from the subprocess

If the activity instance has the scope SubHierarchy, the subprocess termination is performed similar to an abortion of a process instance. The difference is that the calling superprocess instance will continue to be processed normally after a subprocess abortion, like as if the subprocess activity had been completed regularly. Thus an abortion of the process instance will not propagate upwards in the process hierarchy.

Delegate Activity Actions

In the Send to worklist of section select the participant to whose worklist the activity is delegated.


Figure: Delegate Activity Action

Send Mail Actions

For send mail actions the following properties may be specified:


Figure: Send Mail Action Properties

Recipient

In the Send Mail To section, choose a recipient:

The sender mail address is used from the Mail.Sender property, set in the carnot.properties file.

Mail Subject

In the Mail Subject entry field, you can enter a subject for the mail. The default value of the subject is "Infinity Process Platform Notification Mail".

Mail Content

In the Runtime Defined Message section, add the email body text in one of the following ways:

Trigger Process Actions

For trigger process actions you have to select the process to be triggered.

Selecting the Trigger Process
Figure: Selecting the Trigger Process

Schedule Activity Actions

The activity will be put to rest by changing its state to either Suspended or Hibernated. The intended target state has to be defined by the user.

Schedule Activity Action
Figure: Schedule Activity Action

Combining this action with a Delegate Activity Action or a Timer Event Handler allows for rich scheduling scenarios.

Set Data Actions

Set data actions will set values retrieved from the event handler on workflow data similar to data mappings. To do this, every event handler offers a certain set of access points (which may be empty). This way the following properties may be configured:


Figure: Activity Properties Dialog

Activate Activity Actions

Activity activation will be performed by starting an activity thread at the affected activity asynchronously, completing the activity instance and traversing all enabled out transitions. No extra configuration is needed.

In consequence, the activity will not be immediately completed upon return from this action but after some background processing.

Complete Activity Actions

Activity completion will be performed by starting an activity thread at the affected activity synchronously, completing the activity instance and traversing all enabled out transitions. No extra configuration is needed.

Exclude User Action

This action is especially designed to be used in combination with an On Assignment event handler. The action checks any user intended to be the performer of the target activity and prevents delegation if needed. A common application consists of enforcement of any four-eyes scenario.

One of the following properties have to be specified:

To add an Exclude User Action:

Exclude User Action
Figure: Exclude User Action

Modifying Event Actions

An event action is modified by selecting it in the overview tree and then editing its properties in the details pane.

Bind actions are modified similarly.

Order of event actions

All event actions are executed in the order specified in the model. Event actions may be reordered by selecting an event action in the event handlers pane of the properties dialog and clicking on the Move Up and Move Down buttons. The same applies to bind actions.

Deleting Event Actions

An event action or bind action is deleted by selecting it in the event handlers pane and pressing the Delete button.