Using Activity Implementor EventWaitActivity

This implementor is used to wait for external messages, solicited (asynchronous response messages) or unsolicited (such as order cancellation messages). This implementor works with the Timer Wait activity.

Attributes

Events

The attribute Events specifies one or more events the activity instance is waiting for. Each event specification contains three entries:

Event Name. This is an event name that is used to match with event names generated by external event handlers. The event name can contain Expressions (e.g. "${variables['myVar']}") for including dynamic values such as variables or process instance IDs.
Completion code. This is used to set the completion code after the activity instance is waken by an external message. To set a transition event type other than FINISH, prepend the event type name and colon, such as "ERROR" or "ABORT:ByUser".
Recurring. This is a check box. If checked, it indicates the event can occur multiple times for the given process instance. A typical example is pending order change.

Timeout and Status after Timeout

The time out attribute specifies how long we should time out the waiting. When the value is 0 or negative, the activity waits indefinitely.

The activity should have an Event Type for DELAY outgoing transition from the Event Wait Activity to indicate what should be done when a timeout happens. If a DELAY transition is not defined, the DELAY embedded process will be looked at next. If that does not exist either, the DELAY embedded process of the parent process instance will be invoked, and so on up to any package-level DELAY handler process. If no DELAY handler is found in the process instances chain, no transition is made (and no exception will be reported).

The attribute "Status after Timeout" specifies what status the activity should be set when a timeout situation occurs. There are 3 statuses possible:

Canceled. The activity instance will be canceled.
Hold. The activity instance will be put on a hold status (showing cyan color in the MDWHub's process instance view). The activity instance in hold status will not react to external messages received until it is resumed waiting (discussed below).
Waiting. The activity instance continues waiting (i.e. still actively listening for events).

Notes About Timeouts

The mdw.timer.ThresholdForDelay setting (in minutes, with a default of 60) controls whether JMS or DB is used for storing timeouts (values below the threshold use JMS; those above use DB).
The MDW scheduled event monitor runs at a frequency specified by mdw.timer.CheckInterval (in seconds with a default of 60), and with an initial startup delay of mdw.timer.InitialDelay (in seconds with a default value of 300). So this means that db timeouts cannot be expected to be more accurate +/- 1 minute. It also means that when the server is initially started the check will not be performed for at least 5 minutes.
It is highly recommended that the value of ThresholdForDelay NOT be set below 5 minutes.
During testing, you may desire shorter timeouts than those expected in real-world scenarios. In that case, it's important that you understand that the delays may not be accurate down to the minute if they're stored in the db.
Also, you should understand that if the delay is stored in JMS then it can be lost after a server shutdown. Furthermore, if your scenario calls for the timeout to be rescheduled, this can only be accommodated in the database as JMS timeouts cannot be changed once established.

If a DELAY transition is defined, to resume the activity instance into waiting status, there must be another transition leading into the activity. If a DELAY transition is not defined but there is a DELAY embedded subprocess (in the current or ancestor process instances), the activity instance is resumed to waiting status when the embedded subprocess terminates. When the activity instance is resumed to waiting status, it immediately processes any events received while in holding status, so the activity instance may actually be set to COMPLETED status immediately, depending on the result of event processing.

Processing Events

With this built-in implementor, you can only configure it to transition to specified next activities. More often than not, you may need to process the messages received with the event and perform some business logic. This can be achieved by subclassing this implementor and override the method Integer processMessage(String message). The only argument to the method is the XML message (in String form) received along with the event (probably from external systems and stored in DOCUMENT table). After this method call is complete, it will call handleCompletionCode() method to return an activity status, dictating the status of the activity instance to be set after processing the message. The valid statuses include:

WorkStatus.STATUS_COMPLETED: the activity instance is set to completed and transitions are made to next activities according to completion code specified in the configuration, which can be overriden using setReturnCode(). This is probably the return value of the choice in most cases.
WorkStatus.STATUS_WAITING: the activity instance is kept as in waiting status. No transition is made unless the completion code indicates a CORRECT or ABORT event type, in which case it makes that transition while still waiting for events (in parallel).
WorkStatus.STATUS_HOLD: the activity instance is set to hold status. No transition is made unless the completion code indicates a CORRECT or ABORT event type, in which case it makes that transition. Typically you will need to specify a transition out to CORRECT, as there will be no way to resume the activity instance without that.
WorkStatus.STATUS_CANCELLED: the activity instance is set to cancel status. No transition is made unless the completion code indicates a CORRECT or ABORT event type, in which case it makes that transition.

The default method processMessage(String) does nothing if Received Message Variable is not defined and returns WorkStatus.STATUS_COMPLETED.

If you do not have a need to override the method but would like to leave the activity in a status other than Completed, you can configure the completion code in MDW Studio by prepending "Waiting::", "Hold::", or "Cancelled::" to regular completion code. Examples include "Hold::CORRECT" and "Waiting::".

Following table compares 2 different types of activities and how to set the completion code with activity status = Hold. You can replace Hold with Waiting and Cancelled if that is what you want.

Activity Name Event Wait Timer Wait/Manual Task/Sync/Heterogeneous

Invoke Correction Handler with activity in Hold Completion code = Hold::CORRECT Completion code =CORRECT and select Hold from drop down on "status after receiving event"

Invoke CancellationHandler with activity in Hold Completion code = Hold:ABORT Completion code =ABORT and select Hold from drop down on "status after receiving event"

Activity Name	Event Wait	Timer Wait/Manual Task/Sync/Heterogeneous
Invoke Correction Handler with activity in Hold	Completion code = Hold::CORRECT	Completion code =CORRECT and select Hold from drop down on "status after receiving event"
Invoke CancellationHandler with activity in Hold	Completion code = Hold:ABORT	Completion code =ABORT and select Hold from drop down on "status after receiving event"

Return from Embedded Process

If a transition is made to a CORRECT, ABORT, ERROR or DELAY embedded process (the ERROR embedded process is possible when the activity instance throws an exception), when the embedded process terminates:

For ABORT embedded processes, it never comes back to the parent process, so there is never an impact.
If the activity instance is in Hold status, it will be put back in Waiting status (just like DELAY discussed above). If there are any events received while in hold status, the method processMessage() will be invoked again, which may immediately put the activity instance in a different status described above.
If the activity instance is in any other status (possibly Waiting, Cancelled, Completed and Error), nothing will be done (especially, there will be no transition made to the next activities).

You can override the behavior (except for ABORT embedded processes, whose behavior cannot be overriden) by setting the completion code of the embedded process (by calling setProcessInstanceCompletionCode(), or by selecting certain task actions described below in a manual task in the ERROR embedded process). The following table summarizes the impacts:

Subprocess completion code	Activity instance status is Hold	Activity instance status is Waiting,Cancelled or Failed	Activity instance status is Completed
null (this is default) or `RESUME`	put the activity in waiting status again and process pending events if there are any, as described above.	do nothing for Waiting and Cancelled statuses. For Failed status, complete the activity instance and transition with null completion code.	do nothing
`START` (corresponding to task action Retry)	(undefined)	cancel current activity instance and restart another instance of the activity	restart another instance of the activity
`ABORT` (corresponding to task action Cancel)	(undefined)	Cancel the activity	Do nothing
`ABORT:this_process` (corresponding to task action Abort)	(undefined)	cancel the activity and terminate (complete) the parent process	terminate (complete) the parent process
`FINISH` (corresponding to task action Complete)	(undefined)	complete the activity instance, and transition accordingly (using transitions with no completion code)	transition accordingly (using transitions with no completion code)
`FINISH:compcode` (corresponding to custom task action compcode)	(undefined)	complete the activity instance, and transition accordingly (first looking at transitions with `RESUME:compcode` then `compcode` )	transition accordingly (first looking at transitions with `RESUME:compcode` then `compcode` )

Impact of Recurring Flag

When the recurring flag is not checked (default), we have made the assumption that the event with the same name will never occur again. In this case, MDW allows multiple recipients for the event. In another word, if there are multiple event wait activities registered for waiting the same event, then all activities will be informed.

When the recurring flag is checked, it is an indication that potentially multiple events with the same name can be received. To prevent processing of an old event, MDW restricts that only one activity instance can wait for an event. This is achieved as follows: when an event wait activity registers to wait for a multiple occurrence event, the system automatically de-register other activities registered for waiting the same event (if there is any). Once the event is processed, it is marked as finished, so future registration for the same event will wait for another message.

Important note: you should never put the activity in Hold or Waiting status for a non-recurring event. This is because, for Hold status, when the CORRECT embedded process returns, it sees the non-recurring event again and invoke the CORRECT embedded process again, causing infinite loop; and for Waiting status, it sees the same event again immediately.

Event Wait in Other Activities

Besides EventWaitActivity (event wait), several other activities allow to wait for unsolicited events:

The same event configuration mechanism is used to register event waits. Additionally, you must specify the status of the activity instance to be left when unsolicited event arrives. The default status is Hold. The following table lists allowed statuses:

Activity	Hold	Waiting	Cancelled
Timer Wait	hold on timer expiration until the activity instance is resumed waiting	continue responding to timer expiration in parallel	cancel the activity
Custom Manual Task	hold on task completion until the activity instance is resumed waiting	continue responding to task completion event in parallel	cancel the activity, as well as the task
Invoke Multiple Subprocesses	hold on checking for all subprocess termination until the activity instance is resumed waiting	continue responding to subprocess termination in parallel	not allowed (MDW Studio does not give the option)
Synchronization Activity	hold on checking for synchronization until the activity instance is resumed waiting	continue checking synchronization as incoming transitions arrive, in parallel	not allowed (MDW Studio does not give the option)

To customize event processing, you will need to override TimerWaitActivity.processOtherMessage(String message) (not processMessage() which is for event wait). The method does not return anything, the default method does nothing.

When an embedded process returns, the same behavior as event wait activity described above applies, except when resuming waiting from a hold status, each activity behaves in its native way:

For timer wait, it checks if the timer is already expired while in holding status. If yes, completes the activity, otherwise check if another unsolicited event arrived. If yes, invoke processOtherMessage() again.
For manual task, it checks if the task has been completed. If yes, process the task action accordingly; otherwise check if another unsolicited event arrived. If yes, invoke processOtherMessage() again.
For invoke multiple processes, it checks if all subprocesses are terminated. If yes, completes the activity, otherwise check if another unsolicited event arrived. If yes, invoke processOtherMessage() again.
For synchronization activity, it checks if the synchronization condition is satisfied. If yes, completes the activity, otherwise check if another unsolicited event arrived. If yes, invoke processOtherMessage() again.

Event Wait: How to store received message in a process variable

If you want to store the message received by an Event wait you need to do following
Define a process variable of Document type.
Some of the common one used are as follows

org.w3c.dom.Document
org.apache.xmlbeans.XmlObject
com.centurylink.mdw.model.StringDocument

Once you have defined then you have to go to Design tab on the Event Wait activity. There this variable would be available in drop down of attribute named "Received Message Variable", if variable is defined of Document type. This variable would store the received message when Event wait receives the event.