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

MARCH 27, 2023

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:

  • Error Event Definitions: Define the types of errors that can occur during process execution, either globally or ad hoc in Flowable.

  • Error End Event: Processes and sub-processes use this modeling element to indicate that an error situation has occurred. Activities can generate BPMN errors programmatically.

  • Error Boundary Event: Handles BPMN errors that occur during the execution of a specific activity (task or sub-process) and is triggered when an error arises.

  • Error Start Event: Triggers an event sub-process to handle errors.

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.


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


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.

  • The green box shows, that the execution start listener is called before the task activity is called.

  • The red box shows the execution end listener after the activity has finished.

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.


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.

Arthur Hupka-Merle

Senior Software Architect

Flowable Product Software Architect and passionate software enthusiast. Has 15 years of experience writing and using enterprise software in the business rules and decision management domain. Co-founder and organizer of a heavy metal festival in Germany.

Share this Blog post
Engineering | FEBRUARY 19, 2024
The Value of AI in Modeling

As AI gains prominence as a pivotal technology and enterprises increasingly seek to leverage its capabilities, we are actively exploring diverse avenues for integrating AI into process automation.

Engineering | OCTOBER 3, 2023
Low-code, High Impact: Flowable & CMMN for Complex Use Cases

The key to managing complexity is to combine different and multiple tools leads to better, faster, and more maintainable solutions. For example, combining BPMN with CMMN.

Engineering | OCTOBER 2, 2023
The New Flowable eLearning Platform

Discover the reasons behind our brand-new Flowable eLearning platform and explore its features by registering for our inaugural free course.