Camunda SpringBoot Starter -3
Introduction
This is the third article of this series. You can find links below to read first two of it.
In this third article, I will tell about;
- bpmn parse listener
BPMN Parse Listener
When a new bpmn file is deployed to camunda engine, camunda will load it as a new process definition and parses the xml file.
Think of a scenario that whenever a new bpmn file is deployed, you need to run validations on the bpmn components. In the below example that I’m gonna show, I will validate a specific rule and try to find out the cases where my rule is not met. My rule is;
- all sequence flows goes out from a UserTask should be named with a “UserChoice” prefix.
So lets start coding !
Camunda Java API provides us a bpmn parse listener interface and the chance to be a part of the parsing phase. First, we need a class which implements the BpmnParseListener or extends the AbstractBpmnParseListener.
If you just implement the BpmnParseListener interface, you have to code all these below methods with required logic which is not something we would like to do. So we better use AbstractBpmnParseListener class to just override the ones we are interested in.
Our bpmn parse listener class would look like this.
Now we need to configure this parse listener in the process engine so camunda will know about it.
That’s all and ready to be tested.
I added below bpmn file to the classpath and it has one sequence goes out from a user task and its name does not have the prefix “UserChoice”. This is against our rule and must be logged as an Error.
Let’s run it with below curl command.
As expected, validation error log is printed for the sequence “endNow”.
2021–09–13 21:23:16.108 ERROR 47390 — — [ main] g.g.c.s.config.CustomBpmnParseListener : Validation fails for sequence [endNow], name does not start with UserChoice
Parse listener can be used for many different use cases. It not only allows you to run validations, but also allows you to modify your bpmn model programmatically.
You can add execution or task listeners on the bpmn components. This can be super useful when you need to add generic logic or code in your bpmn models and want this done automatically in the deployment procedure.
Let’s see this in an example.
Camunda history listener does not provide an event to catch the sequences passed by. A workaround solution might be to add an ExecutionListener on the sequences to log them or persist into a database table to let us track the issues later on.
Here is an execution listener to log the sequence (transition) id.
Now, let’s add the execution listener on all Sequences found in the parse listener. I added a criteria to set this on. I only choose the sequences which have a name assigned to it.
I added below sample flow to see this on action.
Let’s run it with below curl command.
And here is the result.
2021–09–13 22:02:55.420 INFO 50560 — — [nio-8080-exec-1] g.g.c.s.e.SequenceFlowExecutionListener : Sequence flow event [processKey=mySampleBpmn2, rootProcessInstanceId=329c00b7–14c5–11ec-95d8–72acf5b41a7b, transitionName=setMyVariable]
2021–09–13 22:02:57.883 INFO 50560 — — [nio-8080-exec-1] g.g.c.s.e.SequenceFlowExecutionListener : Sequence flow event [processKey=mySampleBpmn2, rootProcessInstanceId=329c00b7–14c5–11ec-95d8–72acf5b41a7b, transitionName=myVariableTrue]
There is no limitations on what you can achieve in the parse listener. You can even add new transitions that do not exist in the bpmn file at all !
Sum Up
Here is the github link where you can find the project covering all the content mentioned in this post. You can check my following posts related to camunda and springboot.
