Process debugger

Hi all,

I would like to start a discussion about the debugger which I have implemented some time ago.

I have several questions to answer:

  1. Is the concept of debugger useful?
  2. Does it make sense to put it on the roadmap?
  3. Are there any volunteers who would like participate?

    Any comment is welcome.


Hi Martin,
my 2 cents:
not sure if we are talking about the same type of debugging, but with processes that don’t behave as expected, often the question arises: 'what is this process waiting for? ’ . Which tasks should be completed, which timers are waiting, which other catching events are possible…

In our application with activiti, we created a poor-man’s solution that prints the execution tree in ascii. We also included showing bpmn-message or bpmn-signal subscriptions for the scope of execution nodes. It’s nothing fancy and probably could be optimized, but it greatly helps people understand what is happening and gives some debugging powers to business people (non-developers). And it avoids having to write hierarchical database queries.
See below for sample output.
But you get the idea… you can see what’s happening, and given some fancy gui work you can imagine showing extra relevant debugging info when clicking a node in the tree.

Sample output

└── 1605002 ProcessInstance[1605002] ParallelGateway[sid-7343E6FE-FD29-4826-A28A-5F90949E1984]
    ├── 1612502 ConcurrentExecution[1605002] UserTask[na 5min wachten]
    ├── 1612503 ConcurrentExecution[1605002] ParallelGateway[sid-AEAC7B2D-128B-47F0-B7EF-323D52AEA63E]
    └── 1612504 ConcurrentExecution[1605002]
        └── 1612516 ScopeExecution[1605002]
            └── 1610020 ScopeExecution[1605002] ParallelGateway[sid-9CE52A78-2DCD-447C-97AF-17D82AFEB40C] Scope[subproces in tweede subproces,stap 3 tweede subproces]
                ├── 1610024 ConcurrentExecution[1605002] UserTask[taak in subsub A]
                └── 1610025 ConcurrentExecution[1605002] UserTask[taak in subsub B]

Hi Pieter.

Thank you for your comment.
You solution displays audit trail. How the process behaved before he ends in the wait state. And it is really the first step.

This debugger implementation wants to provide functionality to stop process execution everywhere (not only in the wait state). Breakpoint specifies exact place where to stop. When the execution is stopped modeler can observe or change variables/process state… and after that continue in the process execution.

Do you find it useful?


Hi Martin,

“You solution displays audit trail”

Yeah indeed, although ‘audit’ makes me - semantically - makes me think more about the historyservice, so I wouldn’t call it like that.

Ok, but I see where you’re going when you write “modeler can observe”. Ideally the ‘execution’ tree could be, in some GUI, linked to the BPMN model. And the active executions could be rendered as “tokens” on the model (if memory serves me well, the Camunda folks created such a thing).

So, if I understand your question, you would active a “breakpoint” on any BPMN element; and then the engine should halt the execution when the execution reaches that particular , and it would be possible to investigate the process variables, etc…
For me personally, I haven’t felt the need as much to have such breakpoints. I guess it can get very tricky with transactions, or with parallel tasks, timers, transaction timeouts defined by the java EE container, …I don’t know if that’s a real issue though.

Hi Martin,

This sounds like a great idea. We have considered creating a testing simulator and this sort of debugging ability would be a great help. One other thing that I see is the need for starting in the middle of a flow so that a segment or single branch can be tested.

We currently are creating an administrative UI that allows us to look at the active state of a process. It would be useful to be able to copy the live state of an active workflow into a new debugging process so that we can identify and potentially correct flow issues.


Hi Glenn,

re: testing simulator
Did you have a look on the activiti-crystalball already, I did it several years ago, so some refactoring will be needed. activiti-crystalball has its own debugger and possibility to playback and replay processes… ++.
getting started with activiti-crystalball
I am really interested - provide me some details please.

re: correct flow issues.
Interesting. Currently I am working on the functionality which is tightly connected with correcting flow issues.
May be you would like grasshopper example :slight_smile meanwhile:

to display status of the workflow: (little bit old…)
audit trail

Anyway, I am interested in these topics a lot. Could you provide more details please?


Hi Martin,

Thanks for the information on crystalball. This type of simulation is what we are looking for. I would need to give it more of a deep-dive to see how it fits in our processing, but it looks very promising.
Our main focus in this area is to provide mock testing like you show in order to find errors. But we are also interested in throughput testing where we run the same process numerous times to find the bottlenecks and possibly help with process optimization or re-engineering. I didn’t look in detail at how crystalball handles variations of input and output data or timing variations, but what we are looking for appears similar to what is in your monitoring example.

A question about grasshopper, I see that it deletes an active task, but cannot see how it rolls back - does deleting cause the deleted task to be recreated? If so I can see this being useful when the task is a breakpoint and we want to tweak the input data. We would use something like this to check sequence conditions but also to check the data object usage in our service tasks – i.e. to make sure the the service tasks accept and use the input properly.

For audit trail, we have created a separate history service that monitors that active processes to get the active state and also to gather historical metrics – ideally we can use these metrics to feed our simulations and design process improvements.

I am happy to provide even more detail about what we would like to achieve, some of it is better fleshed out than others. I will try to take a deeper dive into crystalball soon as that to me has a lot a potential for us.



Hi Glenn,

Yes, I know what you mean. Simulation experiment which consists of several simulation runs. I worked on this topic but I did not finish it. org.activiti.crystalball.examples.mortages.monitoring.MonitoringTest#escalationProbabilityTest

Virtual process engine lives in the virtual time so you can manage it as you wish. :slight_smile:

No, grasshopper is just simple example how to move execution from one state to another. When you put execution e.g. before the user task and trigger it again user task will be recreated. So you have to know what you are doing and possibilities are limited. An interesting feature could be to implement something like undo (or reverse flow) - I would say implementation is not trivial, but feasible.

Yes that’s possible with grashopper and the current debugger implementation too.

Yes that was the idea in crystalball too. Use history service or events to drive simulation experiment.


Hi Martin, I think a process debugger is a very useful thing. I am still ramping up with BPM and the flowable engine through the book Activiti in Action. Yes, it is an older book, though it is something to start from. I’ll be moving to the User Guide on Flowable once I feel comfortable with Activiti.

I would like to help with the process debugger. It seems like debugging, if done right, could make using processes much easier to support and understand at execution time. I’d like to help on this. I don’t know many of the details yet I believe I would need to know in order to be helpful on this. As I become more conversant in Flowable I’ll be able to help with this.

Hi Kentoj,

How did you proceed?


Process debugger UI.
May be somebody will find it usefull

Hi @martin.grofcik the debugger its a very nice feature.

I think its very helpful.

So, you can keep an eye on me to help to code this.

Best regards.

Just let me know. I will try to help you.


@martin.grofcik this looks very useful. Thank you for providing this! I have not used it yet and I just dropped my attempts at process debugging. I see I can take then up again now.

@martin.grofcik why is this feature not visible in version 6.2.1? I see that the debugger.enabled is by default set to false now and after setting it to true the feature is still not available.

the BE functionality is merged to the master. There is a FE implementation pull request opened for process debugger:

If you want to read more:


How can I install your process debugger? I don’t know how to build flowable from source, so I don’t know how to make use of your github fork. I know how to install flowable if I have .war files, so are there any .war files available that contain the process debugger code?

The best way is to build app from sources.
I built wars from my local branch:

I will keep them for some time.

1 Like

Thanks for the .war files Martin. What version of flowable are they? I installed with the v6.2.1 flowable-rest.war (since it wasn’t included in your uploads), and I’m unable to login to flowable.

Hi Rob.

Is there any stacktrace or error message displayed?