/ Development  

The power of BI to keep track on your BPMs in production

Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

You are finally there!…The long-time craftsmanship of your solution (as Minimal Viable Product!?) will land on the steady multi-tenant production environment shortly. Off-course in the most safely / sustainable way and with all the best monitoring in place! The delivered solution contains lots of business processes to cover the most advanced features, but how to keep track of all the fired BPMs when things will (eventually!) start to fail? There is only one abbreviation possible to bring structure into the chaos of large systems with lots of BPMs. It’s called Business Identifiers (BI). This post will show you how to use them, so you help the administrator-people to see the light in the dark tunnel of BPMs…

Let get right into it…

What do we need? Well…I guess some BPMs??, but first let’s dive into the creation of a new ‘Business Identifier’ type of document. For this we introduce a new business folder to our project with a subfolder called ids.


In this folder we just create that new type of document…A ‘Business Identifier’ with input like this:


Save it and publish it. Now what? How do we use a BI? Well, that’s a 2-step process…

  1. Add a value to it
  2. Use it as filter in the PIM

But first…


Make sure you have an entity available. In my case a simple casex entity with a cx_name property of type ‘Text’. Generate all the rest.


I use my own Business ID for the entity. Keep in mind this has no relation to the BI document created before! Later on you’ll see we reuse the value of this entity Business Identity BB in the BI document…I hope you’re still with me, as it can be confusing!

Next step is to make sure we can start a BPM (for whatever reason!?). The simplest thing for this is to create a new action type of ‘Rule’ BB with the fancy name a_start_bpm. You can do this on your own…I guess!? Because we start a BPM from this rule it would be nice to also have a BPM ready…duh? I have the simplest 1-activity BPM available with the name bmp_dummy. Of-course saved in the ‘bpms’ folder of the project.

No greatness here…Just like this:


This is what we see in runtime once we publish it all:


Hit the gas…start some BPMs…because we can, and check the PIM:


Now, let’s expand…

  • Create a thousand entity instances.
  • For each instance you hit that button! 😅

Don’t do this manually, but just imagine! How are we going to filter out the BPMs for a certain entity instance? Well, that’s exactly the scope of this post…Let’s continue in the next step…

Add a value to the BI

Open the dummy BPM again and open the model properties panel. Go to the ‘Business Identifiers’ tab and add our created BI document:


We leave the other settings for now…They are explained later on.

Next step is to open the ‘Message Map’ of the BPM and make a mapping from the ‘rootEntityInstanceId’ to our BI ‘bi_casex’. Like this:



  • The BI value is a one-direction ‘value set’ principle. You can not reuse / read the value again from a next activity (like a kind of variable!)
  • A BI document can be attached to multiple BPMs where each can have their own value applied (like a BI instance!)
  • #RTFM (‘Advanced Development Guide’): Assigning values larger than 250 characters to a BI will truncate at run-time. Have yourself a search for ‘Business Identifier’ in this same guide!

Save the BPM and publish it. From the runtime perspective make sure to create two instances of the related entity and start some BPM instances from the crafted action button.

Next step…

Filter process instances in the PIM artifact

Back in design-time, we will open the PIM where we see our BPM instances passing by. Time to hit the ‘find’ icon:


You’ll see a new modal popup where we are able to add our BI document as selectable option. The ‘equals’ value you see, is a copy of my entity instance ‘ItemId’. The value for this can be copied from the URL in runtime when you have the entity instance open. Like this sample URL:


Now you see only the BPM instance related to the value of the selected BI identifier value…How nice! 🤗 Time to bring your own creativity to your own BPMs. So, think about what information needs to be saved to make the administrator-people happy when they need to maintain BPM instances.

That’s it for now…Let’s look further, to find more on the BI-power!

Other information to know about

In the model properties of the BPM other options where possible to make.

Publish Business Identifier Values enables you to retrieve the business identifier values published through a Web service. The webservice required for this is called PersistBusinessIdentifiers; The ‘Java’ implementation for this must be created by yourself. Have a look in the ‘Advanced Development Guide’ under the section “Publishing business identifier values”. To have some more guidance, have a look at this post where we expose our own SOAP service via a UDDI service container (with our own Java implementation.)

The option can have 2 values:

  • Non-Transactional No-Reply (no JMS queue)
  • Transactional No-Reply (using JMS queue)

The difference is all about the “queue” implementation done on the service side of the implementation. When you use a Java Messaging Service queue in the implementation there is no need to wait for a response (as the queue will manage it on service unavailability). Without a queue (and the service is down) the call will raise an alert and will log it in the logfile.

Defer publish of BI values to database until next recovery point

#RTFM: ‘This helps in reducing the number of database updates and improves performance’

From what I understand this option is in relation with two other ‘recovery point’ settings. One can be found in the “Recovery” tab for these type of activities: ‘Web service’, ‘Send / Receive Message’, ‘Decision Table’, ‘Case Model Activity’, ‘Independent Sub-process’, and when the activity is a manual task. The other one is the “Monitoring” tab, and the corresponding “Store recovery data” enablement.

This last section sounds pretty technical (and a bit out of scope for this specific post). Comment me if you created this implementation, and we’ll have a chat about it. I also don’t know if it’s used that often, but now you know it’s a choice to make.

I give it a “DONE” on this valuable BPM maintenance post. We learned about the ‘Business Identifier’ document, how we assign a value to it and bring it as powerful search filter to the PIM. Use your own creativity on how to implement it on your own solution, so the administration-people are provided with a structure to find back process instances in the PIM artifact. Have a nice week-end…Cheers! 🍺

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?