How to use a boundary error event in JBoss BPM Suite

Solution Verified - Updated

Environment

  • Red Hat JBoss BPM Suite
    • 6.0.2

Issue

  • How to programatically trigger a boundary error event when an Exception is thrown in a WorItemHandler?

Resolution

Here are the expected use cases of BoundaryErrorEvent

1. Attach a BoundaryErrorEvent on a Task where a WorkItemHandler of the Task may throw an Exception (See onTask.png)
 -> BoundaryErrorEvent is triggered when an Exception is thrown
  * errorCode should be the FQCN of the Exception class

2. Attach a BoundaryErrorEvent on a Subprocess where a WorkItemHandler of the Task in the Subprocess may throw an Exception (See onSubProcess.png)
 -> BoundaryErrorEvent is triggered when an Exception is thrown
  * errorCode should be the FQCN of the Exception class

3. Attach a BoundaryErrorEvent on a Subprocess which has an ErrorEndEvent (See ErrorEndEvent.png)
 -> BoundaryErrorEvent is triggered when the ErrorEndEvent is executed

You don't need to programatically trigger a boundary error event when an Exception is thrown in WorItemHandler

  • Set FQN of the Exception as errorCode for the boundary error event (In Web Designer, it's 'ErrorRef' property)
  <bpmn2:error id="Error_1" errorCode="com.sample.MyException" name="Error_1" structureRef="_applicationIdItem"/>
  • Just throw the Exception in the WorItemHandler
    public void executeWorkItem(WorkItem workItem, WorkItemManager workItemManager) {
            ...
            throw new MyException();
    }

Attached jbpm6ex63_exceptionhandling_simple.zip for a full code example.

If you want the BoundaryErrorEvent to catch all Exceptions ("default exception handler"), remove errorCode and structureRef attributes. From GUI editor perspective:

  • [JBDS BPMN2 Diagram Editor plugin] : Leave 'Error Code' and 'Data Type' in 'Error Details' ([Definitions]->[Error List] in process property) blank.
  • [Web Designer] : Leave 'ErrorRef' of BoundaryErrorEvent blank
    Attached jbpm6ex63_exceptionhandling_defaulthandler.zip for a full code example.

To be precise, 'no structureRef' is effective in BPMS 6.0.2 and 'no errorCode' will be effective since BPMS 6.1.0 (https://bugzilla.redhat.com/show_bug.cgi?id=1175689). Considering compatibility, removing both attributes would be recommended. Unfortunately, in BPMS 6.0.3, 'no structureRef' is not effective (because of BZ1120122) so there is no way to implement default exception handler. In other words, you have to explicitly write FQN of the Exception in errorCode (e.g. org.jbpm.bpmn2.handler.WorkItemHandlerRuntimeException) in BPMS 6.0.3.

NOTE: BoundaryErrorEvent on a Subprocess doesn't mean all Exceptions inside subprocess are handled by the BoundaryErrorEvent. For example, Exceptions from WorkItemHandler and ScriptTask are handled. But not from BusinessRuleTask. Generally, unexpected Exceptions should not be handled by process model. Client program should handle it instead.

Root Cause

Signal type for a boundary event would be "Error-"+$AttachedNodeID+"-"+$ERROR_CODE. But directly calling signalEvent() for the Boundary Error Event is not recommended because sending the signal bypasses some parts of the boundary error event functionality (it's not cancelling the attached node instance and it's not using the nested exception scopes) and it relies on internal implementation details that might be changed in the future.

This content is not included.https://bugzilla.redhat.com/show_bug.cgi?id=1146372

SBR
Product(s)

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.