Handle service exceptions via subprocess

Interacting with services as part of your business process (or in more general business automation) is a common requirement. Though we all know that services tend to fail from time to time and business automation solutions should be able to cope with that. A worth reading article was recently published by Donato Marrazzo and can be found here Reducing data inconsistencies with Red Hat Process Automation Manager

Described feature in this article was actually inspired by discussion with Donato so all credit goes to him!

BPMN2 has already a construct for similar thing – error boundary events that can be easily attached to service tasks to deal with exceptions and perform additional processing or decision taking. This approach has some drawbacks in more advanced scenarios

  • error handling needs to be done on individual task level
  • retry of the same service call needs to be done via process modelling – usually a loop
  • each error type needs to be handled separately and by that makes the process definition too verbose
The first point from the above list can be addressed by using even based subprocess that starts with error event but that still suffers from the two other points.
To address this an additional error handling is introduced (in jBPM version 7.13) that allows the work item handlers (that implement the logic responsible for service interaction) to throw special type of exception org.kie.api.runtime.process.ProcessWorkItemHandlerException
This exception requires three parameters
  • process id that should be created to deal with this exception
  • selected handling strategy to be applied when exception handling process is completed
  • root cause exception
When such exception is thrown from work item handler it triggers automatic error handling by starting subprocess instance with the definition identified by process id set on the exception. If the process is straight through (meaning does not have any wait states) service task that failed will apply the handling strategy directly, otherwise it puts the service task in a wait state until the subprocess instance is completed. Then the strategy is applied on the service task.

Supported strategies

There are four predefined strategies 
  • COMPLETE – it completes the service task with the variables from the completed subprocess instance – these variables will be given to the service task as output of the service interaction and thus mapped to main process instance variables
  • ABORT – it aborts the service task and moves on the process without setting any variables
  • RETRY – it retries the service task logic (calls the work item handler again) with variables from both the original service task parameters and the variables from subprocess instance – variables from subprocess instance overrides any variables of the same name
  • RETHROW – it simply throws the error back to the caller – this strategy should not be used with wait state subprocesses as it will simply rollback the transaction and thus the completion of the subprocess instance
With this feature service implementors (those who implement work item handlers) can simply decide how the exception should be handled and what strategy it should apply to the failing service tasks once the error was evaluated and fixed.

Out of the box handlers and exception handling

Three major out of the box work item handlers are equipped with this handling automatically as soon as they are created with process id to handle exception and strategy. This takes over the regular error handling that will be applied when RETHROW strategy is selected.

  • RESTWorkItemHandler
  • WebServiceWorkItemHandler
  • EmailWorkItemHandler

Sample registration for RESTWorkItemHandler via deployment descriptor would be

new org.jbpm.process.workitem.rest.RESTWorkItemHandler("username", "password", classLoader, "handlingProcessId", "handlingStrategy")

Look at available constructors of given handler class to see all possible options. Similar way email and Webservice handlers can be configured to handle the exceptions via subprocess.

Use cases

Here are few examples that could be implemented
  • report to administrator that service task failed – this would have to be via subprocess that has user task assigned to administrators 
  • use a timer based sub process to introduce some delay in retries
  • ask business users to provide the information in case system is down in time critical situations 
There can be many more use cases implemented by that and one of the most important things with this is it does not have to be modelled for each and every task that could fail. It is up to the service handler to instruct what and how should be done in case of errors.

In action…

A short screencast showing this in action, simple process with custom service task that has a work item handler that throws ProcessWorkItemHandlerException exception and starts user focused subprocess to provide expected values and then apply COMPLETE strategy.

Here is the complete sample repository shown in the above screencast.

Hopefully you will find this useful and that will allow you to better automate your business to avoid any repetitive actions …

Visit jbpm.org to download latest version of the jBPM project


5 1 vote
Article Rating
Notify of
Inline Feedbacks
View all comments