Heatmap Component for Business Central and jBPM

For a long time, Business Central has Dashboards capabilities to build reports from process execution data. Recently with the addition of external components, it is also possible to create any visual representation for the dataset coming from Business Central.

In this post, we will discuss a new category of visual components added in jBPM 7.48.0 Final: heatmaps.

Heatmaps Components

Processes are visually represented in a BPMN Editor and Kie Server projects contain the process BPMN and an SVG representation for the process. All the process execution data is stored in jBPM Log tables and, especially, the NodeInstanceLog table contains information about the nodes executed for a process instance. This information, along with the process SVG is what the heatmap components use under the hood to gather data from your process.

In 7.48.0 Final, when authoring a page you will notice a new Heatmaps category. It contains two new components: Process Heatmap and Processes Heatmaps. To enable these components, make sure you have system property dashbuilder.components.enable as true and when accessing Pages in Business Central you will notice the new components:

Heatmap component in action

Heatmaps Category

Process Heatmap Component

This component can be used to display a specific process heatmap. In the components properties users need to fill:

• Server Template: The Kie Server server template where the process is running;
• Container ID: The container that contains the process definition;
• Process ID: The process id.

Process Heatmap configuratino

This should be enough information to have the process diagram being rendered. To put heat information you must use a Data Set that contains the node id and a value for the heat, such as Total hits.

A sample dataset can be found in the previous post: Nodes execution time and hits and Nodes updates at the last minute. When configuring a Data Set make sure to provide a column with the node id and the value you want to use to build the heat:

Data Set setup for Process Heatmap Component

All Processes Heatmaps Component

This component should be used If you want to explore all the processes in a Kie Server installation. The only manual setting is the server template id.

All processes heatmaps component configuration

The data about the container, process, node, and heat value will come from the dataset. You can use the same query Nodes execution time and hits from the last post and provide columns EXTERNALID, PROCESSID, NID, and some of the values for the heat, such as AVERAGEEXECUTIONTIME.

Processes Heatmaps Data Set configuration

Heatmaps Tutorial

Here are the detailed steps to use heatmaps feature in jBPM 7.48.0 Final:

Run Business Central connected to Kie Server

The main requirement is to have Business Central running and connected to at least one Kie Server. Also, make sure that you have a container and some data for testing. You can use the sample “Evaluation” project and use a jBPM server distribution which comes configured with a Kie Server connected to it.

Kie Server connected to Business Central

Create a Kie Server dataset to retrieve nodes information

Following the steps from Queries for Building Kie Server post create a dataset to retrieve container, process, nodes, and heat information from Kie Server. The query Nodes execution time and hits could be a good option.

https://gist.github.com/jesuino/260362fae039ec4af9ac64e16f78e44a#file-nodes-execution-time-and-hits-sql

Having defined the query then you can go to Business Central and create the data set:

Creating Data Set

Create a page and drag heatmap components to it

Now we are ready to use heatmaps components. In order to do this, we need to go to the Pages tool. Using the Menu click on Pages on the Design Menu. Now we can start using heatmaps components.

Process Heatmap: It shows a specific process heatmap. Drag it from the component pallet to the page and you will notice that the component is not immediately displayed, instead we see a warning message saying that a server template is required.

Process Heatmap configuration issue

The message says that some properties are missing, so go to the Component Editor tab and fill in the required information. Once you finish the information you will see the process SVG.

Process Heatmap configuration

Now go to the Data tab and select the data set we created in step 2. Once the data set is selected you may see another WARNING message saying that the columns are invalid.

Process Heatmap data set bad configuration

What we need to do is simply select the correct columns: the first column must contain the node id and the second column a value for the heat for that node. Once it is done the SVG will be back with print values

Process Heatmap data set configuration

The process heatmap is tight to a specific process definition. For multiple processes, we can use the All Processes Heatmaps component.

All Processes Heatmaps: All processes heatmaps component is capable of showing heatmaps for multiple processes available in a Kie Server instance. Find it under the Heatmaps category and drag it to the Page and you will notice a warning message

Bad configuration for All Processes Heatmaps component

Go to the Component Editor tab and fill a Server Template value and the warning message will change, now it will complain about the dataset columns.

Data Set bad configuration

Select the Data tab and then the dataset you created in step 2 with the columns in this order: CONTAINER ID, PROCESS ID, NODE ID, and some value for the heat. Then you should see the process diagram with the heat values, but this time with a selector to select other processes

All Processes Heatmaps configuration

Running Heatmaps on Dashbuilder Runtime

You can export dashboards containing heatmap using the data transfer feature and to import in Dashbuilder you just have to configure system properties to setup the server template credentials and URL as described in Introduction to Dashbuilder Runtime post.

For example, let’s say the server template used in the heatmap component and in the dataset is sample-server. In Dashbuilder Runtime you must set the following system properties:

dashbuilder.kieserver.serverTemplate.sample-server.location=http://localhost:8080/kie-server/services/rest/server

dashbuilder.kieserver.serverTemplate.sample-server.user=kieserver

dashbuilder.kieserver.serverTemplate.sample-server.password=kieserver1!

To run the same dashboard against another Kie Server simply change the values for the properties above. You may also set the replace_query flag as true so Dashbuilder Runtime will create the required queries on Kie Server side (be aware that it will replace the queries with the same UUID)

-Ddashbuilder.kieserver.serverTemplate.sample-server.replace_query=true

Sample Heatmaps Dashboard

You can use Dashbuilder Runtime to run a generic sample heatmaps report that can connect to any Kie Server installation.

1. Download Heatmaps.zip from GitHub: https://github.com/jesuino/dashbuilder-docker/raw/7.10/demos/jbpm_integration_dashboards/models/Heatmaps.zip
2. Make sure you setup Kie Server credentials for server template “sample-server” (see the sample properties on our last section
3. Start Dashbuilder Runtime by setting the system property “dashbuilder.runtime.import” pointing to the Heatmaps.zip file, here’s an example:

./bin/standalone.sh \

-Djboss.socket.binding.port-offset=100 \

-Ddashbuilder.kieserver.serverTemplate.sample-server.location=http://localhost:8080/kie-server/services/rest/server \

-Ddashbuilder.kieserver.serverTemplate.sample-server.user=kieserver \

-Ddashbuilder.kieserver.serverTemplate.sample-server.password=kieserver1! \

-Ddashbuilder.kieserver.serverTemplate.sample-server.replace_query=true \

-Ddashbuilder.runtime.import=/home/wsiqueir/Downloads/Heatmaps.zip

Import samples heatmaps

Alternative to step 3 you can:

• Start Dashbuilder only with Kie Server credentials and in the first Dashbuilder Runtime access upload the Heatmaps ZIP or;
• Start Dashbuilder Runtime server with the system property dashbuilder.runtime.allowExternal as true and then when accessing Dashbuilder Runtime pass the heatmaps dashboard url, for example:

http://localhost:8280?import=https://github.com/jesuino/dashbuilder-docker/raw/7.10/demos/jbpm_integration_dashboards/models/Heatmaps.zip

Troubleshooting

You may face the error “There was an error retrieving process SVG: There was an error executing the function” when setting up heatmaps component.

Error when the process SVG is not found

The Heatmap component relies on the UI Extension, hence there are different causes for this problem:

1. The container does not contain the process SVG. In this case, make sure to open the process diagram on Business Central project explorer before deploying the container. The SVG can also be inserted directly into the kjar, see this
2. Server Template, Process Id, or container id is wrong. Review the component settings and try again;
3. Kie Server is not accessible. Check if you can manually access the SVG in Kie Server using a web browser.

Another problem is when doing the lookup in Kie Server. In these cases, you will see an “Unexpected Error” message. In these cases check also Kie Server logs to see what went wrong.

Conclusion

In this post, we introduced the Heatmap component! We hope you will find other use cases for it. You have any questions or issue feel free to contact the Kie community on Zulip chat.