KPI functionality and business data statistics in Camunda cockpit plugin

Again, a year has passed since our last blog post and so the time has come that Kerstin, Benjamin and I will tell you about our brand new features and improvements of our Camunda statistics plugin. If this is the first time you read about the plugin please make sure that you check out our former blog posts (part 1, part 2, part 3), too.

But now, let me start!

What happened lately?

Starting from Camunda 7.5 the appearance of the Camunda cockpit changed fundamentally and so the placement of our general overview section (which is kind of our front door 😉 ) moved to the bottom of the start page. This is because the plugin points which we’re using to display the initial overview plots are now embedded lower within in the page. Plugin points are the fundamental concept which allows you to extend both of Camunda’s out-of-the-box webapps ‘Tasklist’ and ‘Cockpit’ in many places. If you are interested in developing your own plugins, go and checkout this part of Camunda’s user guide.

A new paint for the front door!

We switched the overview plots to multi-bar charts to enhance usability. For each deployed process definition three bars are displayed which in turn represent running instances, finished instances and instances with incidents. The following figure shows the overall start page of the Camunda Cockpit with our plugin deployed and some example data. No scrolling needed 😉 !

Another ‘problem’ of the former presentation using pie charts was the missing consideration of the different versions of a process definition that are currently deployed in the engine. With the new version you can ‘drill-in’ in the respective process definition by a click on any of these bars and get both a statistical and graphical overview on the different deployed versions shown in the next figure. On the left hand side a ‘sunburst’ chart allows you to drill deeper into the different versions whereas on the right hand side collapsible sections provide aggregated statistical information like min, max or average duration.

Similar to our former version of the plugin you can filter which process definitions will be shown on the first page. The ‘Settings’ modal allows you to switch back to the pie chart presentation, too. The plots in the ‘Statistics’ tab in the process definition view are now also displayed as multi bar charts.

Soon, maybe web workers will do the REST?

To get all this information several REST calls are needed using both provided resources by Camunda and custom queries which already existed for the former representations. We have not done dedicated performance analysis yet, but we observe that the plugin even performs well with a higher number of process instances. To prevent a bad user experience with non-reactive scripts whenever the plugin has to analyze big amounts of data I want to evaluate web workers as a browser provided mechanism to push complex or long running calculations to the background. Furthermore I want to do some performance analysis on the plugin’s influence on the overall cockpit or engine performance because this is relevant for many users.

But now, lets hear some news from Kerstin 🙂

Have you thought about feature X?

Some time ago, we envisioned visualizing business data stored in process instances. For the first approach, we decided to show the values of business variables used in finished process instances. In that way, you can get insights to business data associated with business processes.

Simultaneously, we have improved the key performance indicator (KPI) functionality of our plugin. There already existed the possibility to highlight all historic activities that were overdue concerning a defined time limit. That is one key performance indicator that is also mentioned in Camunda’s blog post and addressed by the new Camunda Cockpit plugin for KPI monitoring. With the new version of our Camunda Cockpit statistics plugin you can additionally measure the average time period between any two process elements. It’s worth mentioning, that this functionality addresses one open user question at the end of the Camunda webinar about KPI monitoring.

But step by step! First, we will have a look into statistics about business data and afterwards, we will talk about KPIs.

For graspable explanations, we will use the Twitter process from the Camunda BPM training as an example process to show that new features of our Camunda Cockpit statistic plugin.

How to get statistics about business data?

The new feature ‘Business Data Statistics’ is available in the process definition view of the Camunda Cockpit plugin. There you can find a button with an information sign in the sidebar on the right. It looks like this:

After clicking on the highlighted button, on overlay shows up. In that popup you just have to click on the question mark at the top to get more information about the feature.

Information about ‘Business Data Statistics’

The distribution of your process variables – which represent your business data – is shown dependent on your settings. First of all, you choose (1) the process definition version. You have the following options: 1. the version currently selected in the process definition view and 2. all available versions of the process definition. Then you specify (2) a time period, in which the process instances should have been (a) started or (b) finished. There is the possibility to (c) take all process instances into account. Finally, you can (3) choose one of the variables available for the selected process version and time period. Each selection has to be confirmed separately. In that way, you can change one selection, e.g. the time period, and start a new query for business data.

Overlay with distribution of process variable values

One nice-to-use functionality inside the overlay is the date range picker to select the time period. Here we are using an Angular.js directive for the Bootstrap daterangepicker. The customization possibilities of the directive allow us to specify certain time periods that can be selected out-of-the-box, e.g. yesterday or the current month until now. As an alternative, you can specify a custom range by selecting the start and end date. That picker functionality is working smoothly with Camunda BPM 7.5. With previous versions, the popup does not open properly.

Picker functionality for time period selection

What’s going on behind the scenes?

In the background, multiple requests against the Camunda REST API take place. These requests can be categorized into two steps:

1. Getting all process instances in the selected time period for the chosen version.
2. Getting all variable instances linked to the determined process instances.

For the first step, the REST resource /history/process-instance is called with several parameters. The parameter finished=true makes sure that only finished process instances will be returned. Additionally, there are the parameters startedBefore and startedAfter or finishedBefore and finishedAfter to transfer the time range in which the process instances should have been started or finished. The actual parameters depend on the selection in the UI. Finally, the process definition key is handed over if the query is meant for all process definition versions. In case of querying only for one specific version, the process definition id of that version is delivered as a parameter. As result of the REST call a list of process instance ids is received. The list of process instances will be used in the second step.

If that first REST call is finished, the second step starts. The second step gathers the actual business data of the selected process instances in form of variables and their values.

Currently, the parameter processInstanceIdIn for the resource /history/variable-instance is not working (see bug ticket here). Therefore it is not possible to get all variable instances for a list of process instance ids with only one REST call at the moment. As a workaround, one REST call with the process instance id is made for each process instance in the list. HTTP requests are sent one after the other and the single promises are combined into one promise. For that, the angular function $q.all(promises) is used. When receiving the resulting promise, a list with objects containing the name, type and actual value of the variable is available.

Due to complexity issues, we have limited the level of detail for process variables with objects as values. We are listing object properties only for the first depth level of the object as variables for selection. Our example Twitter process has a process variable called ‘tweet’. That variable has an object as value. Therefore we are looking for the properties of the object in the first level. We are adding these properties to the list of available variables. The name of the object is put as prefix to the variable name. If a property of the object has another object as value, that property is ignored.

What are the next steps?

We are aware of the fact that the performance is suffering under the huge amount of REST calls. The more process instances are taken into account, the more REST calls are sent. As soon as the mentioned bug is fixed, we will change all the requests to the resource /history/variable-instance into one single request. As a result, only two REST calls will be needed altogether – no matter how many process instances are considered.

Now we have talked enough about business data statistics. What’s about the KPI feature that was already mentioned? First, let’s examine KPIs in general and then Benni will have a look at the second new feature.

Why KPIs?

KPI (key performance indicators) can be used to measure the success and the performance of processes. It is strongly related to certain metrics of your executed processes like their overall duration  or the duration of certain sub paths of the overall process. As an example you can think of the delivery time of some products you ordered in an online shop from your initial order (you clicked to “order” button) to the moment of the delivery via some logistics service at your front door. As a process owner you want to make sure that you always have an eye on the time.  Depending on the available data you could for instance measure to what extent the overall delivery-to-front-door time influences the “I will order again in that shop” mentality of your customer. An interesting sub part of this process could be the time from your order to the time your package was handed over to the logistics service.

Some existing BPM products allow you to model your specific measurement points already during modelling time. Afterwards some other product component helps you to build fancy charts. Camunda recommends in their best practices to simulate KPIs by modeling empty intermediate events. In that way it is possible to get a clear time stamp at certain points of your process. Because I want to enable all of you to check out our plugin we developed a new KPI feature that can be used without the need of remodeling your process. This feature calculates the average time period between two selected elements of a process considering their individual process instances.

Two blue colored activities of the Twitter process indicating the selected start and end element

How to use the new KPI feature?

The KPI extension is activated by clicking the KPI icon within the right navigation bar. After the menu is shown, you have to mark the start and end element for your measurement by clicking on the respective elements on the rendered process definition model. The selected elements are then marked by changing their color to blue. The KPI menu now displays the name of the start and end element. You can calculate the mean duration between both elements by clicking on the ‘Calculate’ button. Please make sure that your end element is located the same sequence as your start element. Otherwise you will get an error message and nothing will be calculated.

To control whether the start or end time of an element is considered for the calculation, you can use the “exclusive” switch for both start and end element. This switch is necessary as you probably do not want to always include the duration of either start or end element for your measurements (e.g. a long running service call or user task).

Four modes are available: (The last column explains the calculation that takes place.)

If you want to do another calculation, you can hit the “Reset” button. Now you can select two other elements and start a new calculation.

KPI extension menu

How is it implemented?

To calculate the differences between the selected elements, we request all finished activities of the selected process definition and version by using the REST resource /history/activity-instance including the processDefinitionId parameter. In the resulting response, we only look for activities whose id matches either the id of the selected start or the selected end element. These activities are stored in a list and sorted by their process instance id. If there is a process instance id, for which no data is available for both activities, i.e. this process instance might run another path, this process instance id is no longer considered for the upcoming calculations. After sorting out these incomplete process instances, we iterate through all remaining process instances and calculate the difference by subtracting the x time of the start element from the y time of the end element. The variables x and y can be the start time or the end time. That depends on the setting of the “exclusive” flag. Afterwards, we sum up all the differences and divide it by their quantities. Finally, the result is formatted to show the average duration between the two elements in days, hours, minutes and seconds.

For failure management, we check the order of the selected elements by their time stamps. If the first selected element has an end time stamp greater the start time stamp of the second selected element, then the plugin will return an error. We also check if the selected elements can occur together in one process instance. That means, if one of the selected elements is located in another process path, the plugin will return a failure message too and you need to choose an element of another path.

For usability, we implemented a loading animation which will be displayed while the calculation is still running. The same image is shown in the overlay for business data statistic.

What’s next?

For future development, it will be possible to mark the selected elements with a colored gradient to show which element is inclusive and which is exclusive. For example, two elements which are both inclusive have a red gradient on both outer sides. The following graphic shows how this feature might look like.

Gradient overlaying as a function of the inclusive or exclusive option

In addition, we will visualize how often and via which end event the process finished. A process can have more than one end event, the respective distribution of passed end events may help to clear questions why a process does not take the happy path as often as assumed. This future feature could look like this:

Process with two end events

Last but not least, it will be interesting to get information about the variance or the trend of the duration between two elements over the last year. Therefore we envision integrating a kind of time interval selection where you can choose between “daily”, “weekly” and “monthly”. Depending on your selection, the average time period between the two selected process elements will be calculated for each day, week or month. These differences will be plotted in one diagram to show the trend. In that way, you could easily recognize if the performance of your process is increasing or decreasing.

Now, it’s your turn!

Have a look at the new version if our Camunda Cockpit statistic plugin on Github. Try out our new features! For a quick hands-on experience go visit our example deployment.

Needless to say, we are eager to get more feedback from you. What do you like about our new feature? Do you have any ideas for improvement or additional features? And feel free to report bugs as well.