Elevate your BPMN models: Streamlining error handling with Flowable's latest features in 3.13 and OSS 6.8

Today we want to shed some light on a topic that is often overlooked when it comes to BPMN models: Error handling. We all know that when it comes to modeling processes, we tend to focus on the happy path. However, real-life scenarios frequently present us with error situations that demand efficient strategies.

In this post, we'll discuss the features introduced in Flowable Open Source 6.8.0 and Enterprise 3.13, and how they can help you enhance your error-handling techniques.

You will learn how features introduced in Flowable Open Source 6.8.0 and Enterprise 3.13 can enhance your error handling strategies through centralized error handling in models, simplified throwing of BPMN errors in scripts, and insights about the throwing BPMN errors in execution listeners and task listeners.

BPMN offers various constructs to help us deal with errors during process execution:

A BPMN Error carries an error code (required) and an optional message, which can be used to react to specific errors in the model.

Let's explore a simplified client onboarding process model using the mentioned BPMN elements. By the way: This example was inspired by the Flowable trial onboarding process. We use Flowable behind the scenes, when you sign up for the Flowable trial experience.

In the example above, we have Error End Events labeled "invalid data" and "junk email", we have error boundary events that handle specific errors, and we have a generic error handling event sub-process with an error start event that handles errors which are not specifically handled elsewhere.

Errors can be handled by specifying the Error reference or Error code for the to-be-handled error for the error events. If left empty the error events act as "catch-all" handlers.

In Flowable BPMN errors are technically represented by the BpmnError class.

org.flowable.engine.delegate.BpmnError 

This is important to know, when BPMN errors should be returned from custom logic implemented in Java.

Central BPMN error handling by accessing the BPMN error code

Access to the error code in the error handling path is a feature that has been requested for quite some time (for example, have a look here and here).

Previously, when a BPMN error was thrown, the error code could not be retrieved at the point where the error was handled. This meant that it wasn't possible to create a central error handling sub-process that handled different errors in different ways. The approach was to use separate error boundary events for separate error codes, which quickly could lead to cluttered models:

If you see your models are suffering of such symptoms, consider to use a error handling event sub process instead, which allows to centralize error handling:

This approach allows you to maintain a more organized and readable model.

It looks a lot cleaner. How to achieve that?

The key is to make the BPMN error code available in the scope of the error handling sub process. This can be done by specifying an Error variable name on the Start error event of the event handling sub process: 

Flowable's engine then stores the BPMN error code to this variable, making it accessible in the gateway flow condition expressions to handle specific errors e.g.

${errorCode == 'ERROR_A'}

It can also be specified whether the error variable should be stored as transient variable or in the local scope only.

Note: This feature has been sitting around silently in the open source codebase for quite a while. The silence is now hopefully over, as this is a quite handy pattern to nicely centralize error handling in process models. In Flowable Design Enterprise those attributes are available since release 3.13 too.

Throwing BPMN errors in Execution Listeners and Task Listeners

✅ New in Flowable OSS 6.8.0

It is now possible to throw BPMN errors in execution listener and task listener code, which can be handled in the model. Exceptions of type

org.flowable.engine.delegate.BpmnError 

are now being treated as BPMN errors and propagated to model based error handling, when thrown in Execution- or Task Listeners. However, there is an important thing to note, which might not be expected at a first glance. An excerpt from the docs:

"It is important to note, that BPMN Errors thrown in Execution Listeners are only caught on parent scoped error boundary events, not on the boundary event of the activity."

The following image illustrates this fact:

Given that "A Task" has an execution listener defined, which throws a BpmnError at some point: The error is only caught if the error boundary event on the 'Subprocess' matches (the red one in the image)

Looking at the lifecycle of the execution listener invocations, this becomes obvious: at the time where the "start" or "end" execution listeners are invoked, the activity is either not yet fully initialized (or the execution has already left it) and therefore the attached boundary error event is not available to handle a BPMN error thrown by the listener code. The green and red boxes underline this.

For this reason, only the boundary error events that are scoped by the parent or the start error events are taken into account. It is good to keep that picture in mind, when working with listener code. The listeners are executed either before the activity is initialized or after the activity has already completed, not within the lifecycle of the activity itself. The same principles apply to user tasks and task listeners.

Simplified throwing of BPMN Errors in scripts

✅ New in Flowable Enterprise 3.13

In enterprise, it is now possible to throw an BPMN Error wherever scripts are supported using this util method

flw.bpmn.throwError('ERROR_CODE', 'Error Message');

If used within a script this means that we can now visually model error handling in the BPMN diagram and have all the nice things described above.

Watch our 3.13 release video for a summary

Dive into our captivating Enterprise 3.13 release video, which not only highlights the discussed enhancements but also introduces an extra subject – error handling when working with REST data objects:

Click here to jump straight to the error handling section to enrich your understanding.

Conclusion

Effective error handling is a crucial aspect of BPMN process modeling that can help ensure the reliability, maintainability, and effectiveness of your processes. BPMN offers various constructs to help you deal with (business) errors, including error event definitions, error end events, error boundary events, and error start events. However, it's not enough to just know these constructs; you also need to think of, establish and follow an error handling strategy in your models.

Fortunately, the latest and greatest features in Flowable Open Source 6.8.0 and Enterprise 3.13 help you with that. These features include simplified throwing of BPMN errors in scripts, improved support for handling errors in execution listeners and task listeners, and the ability to centralize error handling using an error handling event sub-process, together with the ability to access the error code.