Process debugger

Author: Martin Grofčík

The flowable 6.3.1 release brings a lot of new features. One that can attract the attention of modelers is the experimental process debugger. To make your first steps with the process debugger, you need to enable process debugging by setting the property flowable.experimental.debugger.enabled to true (e.g by JVM option -Dflowable.experimental.debugger.enabled=true in flowable-task application) and start flowable-task application. From this time, the process engine runs in debug mode. For those who are interested in engine configuration details follow org.flowable.ui.task.conf.FlowableDebuggerConfiguration.

First breakpoint

Let’s take simple process with a gateway as an example to show process debugger in action. The process model (gatewayApp) is simple:

The process instance start form allows us to choose between yes/no options to decide whether to create a ‘yes’ or ‘no’ task.


When the process instance is started, ‘yes’ task is created. Click on the ‘Show diagram’ button next to the process instance name.

That’s the place where the debugger starts. Execution waits on the ‘yes’ task (full red circle). Grey circles show the places where breakpoints can be created. Click on the grey circle above the exclusive gateway, and your first breakpoint is here.

Before we start to debug the process instance, look at the bottom tabs of the debugger. The Variables tab shows all variables available in the selected execution. In this example, there are ‘initiator’ and ‘decide’. The next tab displays executions:


The Log tab contains all process events logged into the database for auditing purposes. The remaining tabs will be described later.

When we have our first breakpoint ready, start a new process instance:

Start process init form.
Process instance started.
Process instance break point reached.

As you see, no user task is created and the process diagram has a small play button above the exclusive gateway. The ‘decide’ variable is set to ‘no’. The expected behavior is that process takes the sequence flow to the ‘no’ task. Click on the play button and enjoy your first executed break point. (despite the result, continue on the next step)

Evaluate expression

If you did it, and “nothing” has happened after the click on the play button, do not worry. It is not your fault. Check your logs and you will find terrible stacktrace there:

org.flowable.common.engine.api.FlowableException: Unknown property used in expression: ${decision == 'nonExistingValue'}

As you see, a wrong expression in the model caused this issue. These kind of errors are quite common. Now is the time for the Expression tab to come into play.

You can evaluate any expression in the context of selected execution using the Executions tab. You can also select execution by clicking on a task in the process diagram.

In the first step, let’s take an expression from the model and evaluate it:

The expression evaluation has failed. As you have seen on the Variables tab, the variable name is not ‘decision’ but ‘decide’ and its current value is ‘no’. When the expression is rewritten, we can re-execute it again:

The result  is true and we can easily change our process model to fix the bug.

Execute script

Another common source of errors are scripts. It is easy to make an error in the script at design time. Scripts in the debugger are also executed in the scope of the selected execution. Our first script is the well known Hello world! example.

The output is written into the console log. We can argue how useful println('Hello world!') is. Let’s try to add new variable into execution. It’s easy:

expression.setVariable("newVariable", "newVariableValue");

and check on the Variables tab that new variable was added.

What to do next

Leave a comment, participate on the project or just enjoy our new debugger.

Comments are closed.