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.
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
To create an event handler:
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:
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 org.eclipse.stardust.common.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 org.eclipse.stardust.common.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
When a primitive data (of type long) is associated with the timer event, then the timeout time should be specified in milliseconds format. So, if a user wants to enter the timeout time then he needs to specify (current time in milliseconds + required timeout time in milliseconds).
For example, the following java code returns date/time: 22-Sep-2011 T13:12 in milliseconds format:
Date d = new Date(2011,9,22,13,12); // Date: 22-Sep-2011 T13:12 System.out.println("time in milliseconds format = " + d.getTime()); // Output: 61277413320000
So, lets assume that for a timer event user wants to enter timeout time as 10secs and current date/time is 22-Sep-2011 T 13:12. Then user needs to enter time (current time in milliseconds + required timeout time in milliseconds) that is (61277413320000 + 10000 = 61277413330000)
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:
Figure: Add a Timer Event Handler.
Figure: Set the Event Handler Properties.
Please do not change the Id for the timer event handler to something other than Resubmission as in that case the event handler is not recognized as resubmission, e.g. in the Portal. Also take care when changing the name if option Enable Auto ID Generation is enabled in the Process Manager preferences.
Now add a scheduled bind action with activity instance state hibernated:
Figure: Add a Bind Action.
Now add a scheduled event action with activity instance state suspended:
Figure: Add an Event Action.
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:
Figure: Option to send an Activity to the Default Performer
For an activity state change event handler you can specify the intended source state and target state you want to match.
Figure: State Change Event Handler Properties
Note: Activity State Change Event handling is not supported with a source state N/A in combination with a target state created.
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.
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.
For event handler assignment nothing has to be configured.
Event handlers can be modified by selecting them in the overview tree and then editing their properties in the details pane.
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.
An event handler can be deleted by selecting it in the event handlers pane of the properties dialog and then pressing the Delete button.
To create an event action for an event handler:
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.
The following event action types are available depending on the event handler type:
|Event Action Type||Activity Event Handler Types|
|Abort Process||Timer, On Exception|
|Abort Activity||Timer, On Exception|
|Delegate Activity||On Activity State Change, Timer, On Exception|
|Send Mail||On Activity State Change, Timer, On Exception, On Assignment|
|Process Trigger||On Activity State Change, Timer, On Exception, On Assignment|
|Schedule Activity Actions||On Activity State Change, Timer, On Exception, On Assignment|
|Set Data Actions||On Activity State Change, Timer, Exception|
|Activate Activity Actions||On Assignment|
|Complete Activity||Timer, On Exception|
|Exclude User Action||On Assignment|
Abort process actions implicitly target the process instance hosting the current activity instance, thus not needing to be configured.
You have the option to choose whether the abortion is performed starting from the root process instance or starting from the subprocess.
Figure: Abort Activity Options
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.
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.
In the Send to worklist of section select the participant to whose worklist the activity is delegated.
Figure: Delegate Activity Action
For send mail actions the following properties may be specified:
Figure: Send Mail Action Properties
In the Send Mail To section, choose a recipient:
In this case, the receiver mail address from the users, who have this role, is
Figure: Choose a Model Participant as Recipient.
Figure: Choose a Predefined Address as Recipient.
In that case, the email id of the user, which was supplied during user
creation (i.e. in the Administration Perspective or per command line tool), is used.
Figure: Choose the User Performer as Recipient.
The sender mail address is used from the Mail.Sender property, set in the carnot.properties file.
In the Mail Subject entry field, you can enter a subject for the mail. The default value of the subject is "Stardust Notification Mail".
In the Runtime Defined Message section, add the email body text in one of the following ways:
Figure: Enter Mail Content as Predefined Message
Figure: Choose a Runtime Defined Message
For trigger process actions you have to select the process to be triggered.
Figure: Selecting the Trigger Process
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.
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 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
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.
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.
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:
Figure: Exclude User Action
Queries exclude activity instances from their return list if they are executed by a user who was set as excluded user in the activity.
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.
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.
An event action or bind action is deleted by selecting it in the event handlers pane and pressing the Delete button.