Flowable is a low-code platform that allows you to develop a business processes and integrate them into your application without significant development effort. It has a rich CMMN and BPMN modeling tool with many built-in features. Additionally, it has an impressive web page builder tool to developer application UIs.

However, understanding why processes fail or work incorrectly can be challenging. Additionally, if you are not a developer, investigating issues can be problematic.

Here, I’m going to share my experience of how to investigate and debug during BPMN/CMMN process development if you are a modeler or developer who just started to use it.

Contents

1. Logs.

2. Debug the CMMN or BPMN process.

3. Debug Backend Expression.

4. Debug Frontend Expression.

5. Find Broken Backend Expression.

6. Review the REST button/task request issue.

7. Debug invalid form and blocked complete button.

8. More debug tips.

9. Final thoughts.

Logs

Firstly, you need to get access to the Flowable Work Log file. The log contains information of the application’s states and error messages. If the Flowable UI message is unclear, first check the Log file.

The default Flowable configuration allows access to the log file via this URL:
https://your-flowable-work-url/actuator/logfile

If you don’t have access, ask your developers to configure it or provide another method to access the Log file.

Accessing the log file is essential for Flowable modeling.

Debug the CMMN or BPMN process

Sometimes, the process fails. The error message does not have enough information to understand why and where it fails. In such cases, we need to locate the issue and identify the specific task that fails. Temporary Debug Human Tasks can help. These are regular human tasks without forms. We can use them to temporarily stop and understand the current state of the process.

Example of Debug Human Task usage

Given that, we have a simple process to write and publish an article.

It has form to write an article, then it generates an article number and adds it to the article title. Finally, it checks for plagiarism. If none is found, the article is published.

The process started, but I can’t complete the first human task. The log file didn’t provide useful information. But I guess that it fails either in the 3rd or 4th task. Now we need to add a Debug Human Task between the 3rd and 4th tasks and run the process again.

If the process stops at the debug task, it indicates failure in subsequent tasks. Additionally, we can check what variables we have before the “Check by LLM” task. But it is still not obvious where the issue occurs. We need to add more Debug Human Tasks to better locate the issue. For example, add one more after the LLM step and run the process again.

Now we can’t complete debug task. It means the issue is within the LLM task, and we need to review all its properties to fix it.

When the issue is found and fixed, remember to remove Debug Human Tasks.

Debug backend expressions

In the previous chapter, we learned how to locate issues. Typically, processes fail due to incorrect task properties or a faulty Backend Expression(BE).

If it is connected to a buggy expression, then the next steps will help you to debug it

1. Add the Debug Human Task before the failed task.

2. Run the process and stop at the debug task.

3. Open the Browser Developer Tool(F12), tab Network. (optional step)

4. Open Flowable Work Inspect, tab Inspect.

5. Select Variables in dropdown

6. Click to Evaluate Expression now.

7. Enter your buggy expression and click validate.

   
   

If the expression is correct, then it shows the value in the bottom section. But if it has an issue, then it fails and shows the error message. If the error message isn’t clear, check the last request item in Developer Tool, tab Network, tab Response.

If it’s still unclear why it fails, then go to the log file as described in the first chapter.

Debug frontend expression

The hardest part of flowable debugging is debugging frontend (FE) expressions. There is no simple way to run it as a backend expression, and the scope of variables is often unclear.

But there’s a trick to running any expression directly from your browser. Open the Component tab of the Form Debug tool and temporarily add our FE expression.

How to open form debug tool?

If you have an old Flowable version, Case/Form integrations or inspect is disabled, then you need to open the browser Developer Tool (or click F12), open the console tab, and write the next expression in the console. Finally, it will run the Form Debug Tool.

flwformsDebug = true;

If you have a new Flowable version, then open Flowable Inspect, tab Current form.

How to debug FE expressions?

The form debug tool has a tab Component. The tab allows changing form properties on the fly. Updates are immediately applied. We can use it to debug FE expressions in properties that support expression, e.g., label or value.

Example of how to run custom FE expression.

Given, we have custom FE expression like…

{{"title".concat(". With Preview: ").concat(enablePreview)}}

…and we want to run it in our form and see the result. These steps show how to use Form Debug tool to run custom FE expression.

1. Open the Form Debug tool, then tab Component.

2. Find any form element where we want the test expression and click on it. It is the first text element in the example below.

3. Then set your FE expression to property label or value. I usually use label.

4. The result of the expression is immediately shown in the form. See the label of the first text element.

Custom FE expression in the label of title element.

Check the JSON variable or special keyword value.

We can extend the approach above to check the value of a variable containing the JSON value of special keywords like self, $payload, $item etc.

To do so, we need to use flw.JSON.stringify function to transform the JSON value into a string and use it in the label property.

For example, our form has an article co-authors subform. The subform is multiple, so we can have many co-authors. The next expression returns all co-authors of the article.

{{flw.JSON.stringify($payload.coAuthors)}}

…

Find broken backend expression

Sometimes your process fails because of a wrong backend expression, and you do not know where the expression is used. This guide helps you find where the broken expression is used.

1. Export the app or process with the failed expression.

2. Open the downloaded export file in any text editors.Do a search by expression string.

3. Then read the XML tags near the failed expression.

4. Usually, it is obvious where it is used.

In the example below, my wrong expression is placed in the service task with the name Publish article in the expression property.

Now I need to find this task in the process and fix expression property.

Review the REST button/task request issue

If your process has a REST/HTTP task that fails or returns an unexpected value, then you need to follow the next steps to debug these kinds of tasks.

1. Check log file.

2. If the reason for the error is still not clear, then we need to temporarily enable the Save request variables and Save response details properties of the REST/HTTP task. Do not forget to set Result variable prefix. Now flowable starts to save all request technical details in variables with the prefix debug_

3. Run the process one more time and review the process variables. You should be able to see many variables with the prefix debug_. Review them to understand what is going wrong.

   
   

You can notice that my task fails because the HTTP request returns a 404 error code. It looks like it sent a request to the wrong URL.

Debug invalid form and blocked complete button

Sometimes it is not obvious why the human task form is not valid. A specific frontend expression helps to force form validation and understand the invalidation reason.

{{flw.validate()}}

The expression runs form validation and returns a list of invalid form elements if they exist. You can run the expression in the form element property as described in Debug Frontend Expression or in the temporal form expression button

This is an instruction on how to add a temporary expression button.

1. Add an expression button to the form.

2. Set formValidation into the button Variable property.

3. Set FE expression {{flw.validate()}} into the button expression property. More info https://documentation.flowable.com/latest/model/forms/concept/work-form-expressions#validation-and-validation-errors

4. Publish and create a new instance of the form/process/case with the form task.

5. Open Inspect/Current Form/Payload.

6. Click the expression button.

7. Do a search for the string formValidation. Finally, you will see all validation errors, messages, and invalid form element IDs.

More debug tips

• All Flowable network communication can be found in the Browser Developer tool (F12), under the Network tab.

• Current authenticated user information can be found at the following link https://yout-flowable-work-url/idm-api/current-user

Final thoughts

Flowable is a complex tool, and sometimes debugging process of it can be challenging. I hope this article assists you in your modeling and issue investigation. If you still need help, consult your developers, visit the Flowable forum, or contact me. I haven’t yet met an issue that can’t be solved.