Hi there AppWorks fans,
Welcome to a new installment of AppWorks tips.
With this post I want to share something nice I saw during my daily job. It’s a BPM feature we all can learn from. Not hard, but just nice to know it’s possible. Probably also other solutions are possible, but you’ll see that crafting a BPM is just like writing some programming code.
Let get right into it…
We start really easy with a short use-case: Build an endless looping BPM with steps where the end-user chooses when it is enough!*…How hard can it be!? 😜
What do we need and how do we start with this?
- Well, a project with some folder structure…As always!
- An entity with some basic properties and the basic building blocks to create/view the instances
- One ‘special’ property that we will check for breaking the loop
- A layout with a button to start our BPM (via an action rule building block)
- A ‘Read’ webservice that we can use in the BPM.
- A BPM that roughly executes this pseudo code
1 | while(true) { |
Spin up our VM and entering our “Walhalla” of AppWorks with our developer role where I will start with this project setup where I will use that ‘entities’ and ‘bpms’ folder
The task entity looks like this for a first setup
- task_description is a ‘Long text’
- task_name is a ‘Text’
- task_is_repeatable is a ‘Boolean’ where I only configured TRUE (default) and FALSE. The ‘None’ option is removed from the list.
That “send_to_inbox” BPM you see in the first image is for now just a dummy BPM that looks like this:
First setup is clear now…next step for some more low coding…
Add webservice building block
Add the webservice building block to the ‘Task’ entity and make sure to enable the ‘Read’ operation, so we can use it later in our BPM
Publish only the entity for now, so we can connect that service operation to the ‘Application Server Connector’. This is required, so our AppWorks platform “knows” what service container can be used to execute this operation. This post tells you how to create a new ‘WS-AppServer’, but the ‘Application Server Connector’ has the same wizard. In the second step you just need to select our published ‘Read’ operation:
With this connection in place we are able to test the service with the ‘Service Test Tool’ artifact like this (so we can use it also in our BPM later on).
That ‘ItemId’ value in the SOAP request is retrieved from the runtime URL when you open an existing instance of the ‘Task’ entity: /home/appworks_tips/app/start/web/item/08002707d5efa1eaafda0e8928722529.655361
This should be sufficient information for the webservice building block…next step…
Start a BPM from rule building block
Add a new rule building block to the ‘task’ entity and make it a type ‘Action’, so we can connect it to a button.
Give it a nice name for the button (Send to inbox
) and a name for the building block itself (on_btn_click_bpm_send_to_inbox
)
Now make sure our crafted process is starting with these settings:
To get rid of the ‘red’ error you can add a simple condition in the advanced editor like this
true==true
To trigger this new rule we need to have an ‘Action bar’ building block. Just add a new one with the name default_action_bar
and make sure it looks like this:
To make sure the action bar is also available to our users we need to add a new ‘Layout’ building block with the fancy name default_layout
!
We make it simple where we just add a ‘Form’ panel that will show our ‘Create’ form, and an ‘Actions’ panel that shows all available actions by default.
Now go back to the entity overview and make sure you select the new layout and make it available for viewing the entity with these 2 marks:
Save it all and do a full publish of the project and do the first tests with creating instances of this entity and see if you can start that BPM (this can be checked with the ‘Process Instance Manager’ artifact we already learned to use!)
This is the runtime view of my entity:
When I hit that ‘Send to inbox’ twice I see 2 instances in my ‘PIM’ artifact
We’re getting somewhere!…Next
Get a “real” task in the inbox
Open the ‘send_to_inbox’ BPM and right-click that ‘Dummy’ activity to select an option I already posted a blog on:
In that new model screen you need to select the correct layout! Hover over it so you see it’s the layout from our ‘Task’ entity!
After selection, you see that our dummy activity is changed from an auto-activity to a manual-activity!
Let’s publish and check it out in runtime…Create a new instance of the ‘Task’ entity and hit the new crafted button. After this action you can go to your inbox and open the ‘All Tasks’ where you can select your task!
You will see a screen like this!?
And indeed…That’s a default xForm screen that represents the ‘Task’ information for our BPM…What happened to the ‘default_layout’ we’ve created?
That is a valid question you ask, with a simple answer to give…It can’t be found!!…Why? Because we start a BPM directly from our entity model is has no relation between a ‘task’ of the entity and running BPM at that moment!
How can we solve this issue?…Check the next section…As it’s all magic from within the lifecycle building block!
Fix the xForm issue
Let’s start by adding the ‘Lifecycle’ building block to our entity…And with that we get that ‘special’ related lifecycle-task entity!
Indeed, a little uncomfortable to have a ‘task’ entity and a ‘lifecycle-task’ entity at the moment, but that is the choice we made.
That lifecycle is really simple and clean…
It’s doing nothing but makes it possible that we have our special ‘lifecycle-task’ entity available on our entity!
Back to our entity overview where we see a new building block in the list with the name ‘Task list’. Click on it, and in the right panel you can open it by clicking that related link.
In that new building block list we craft 2 items:
A ‘Default’ form building block with some task related properties the can also show the parent-related entity ‘Default’ form!
A default task ‘Layout’ that will show our ‘Default’ form of this lifecycle-task entity. I give it the name
task_layout
with 2 panels (‘Actions’ to handle the task and ‘Form’ to show that ‘Default’ form)
Last thing to do?…Yes…Connecting this last ‘task_layout’ to the layout of our BPM activity (by right-click and select the new crafted entity layout)!
Ok…Publish it all and check again the results in our runtime.
- Create a new task entity instance
- View it
- Hit that button we’ve created
- Check the inbox
Et voila…much better in the entity modeling UI!
But what about the repeatable task? “Yes man”…talk to me! 😜
The repeatable task!
Now that our inbox task is in place…let’s make it repeatable until to user decides not to repeat it anymore with that checkable option on our task form.
Open the ‘send_to_inbox’ BPM and low code the next screen (with those disconnected start/end points!):
After this update we select the middle part of the BPM (that blue rectangle), and we right-click that selection to get the context menu where we group the selection as ‘while’ group.
And after this grouping we connect the input and output to that group, so you have this end-result
Get the properties of that while loop, and make sure it’s an endless loop in the select condition with function value true()
and give it a nice name.
Next we need to update the 2 new end points
The one on the right will be a ‘Break’
The one on the bottom will be a ‘Continue’
You see both endpoints getting a new icon (with an extra red big dot)
Now get the properties of the decision split and make it an ‘Exclusive’ decision so when the first condition has a match, our decision split is fine, and we get to the next step (without validation of the other conditions).
Go to the ‘Conditions’ tab for the decision and craft it for now like this
Later on we’ll update that ‘Continue’ condition as it needs to validate the ‘task_is_repeatable’ property of the task entity, but for that we need to get the ‘Task’ entity into the BPM!
Your end-result looks like this, and you should also be able to ‘debug’ the BPM (<Ctrl>+<F12>
) and see it’s looping continuously.
Ready for the next step?
Read the Task entity and update the ‘Continue’ condition
Back to our BPM model where we need to drag & drop our ‘ReadTask’ webservice operation! This one can be found in the ‘Insert’ tab in the bottom where you can open the ‘Web Service Operations’ accordion tab and search for ‘Task’…Check the image!
Next step is to make sure this service gets some input, so we can get a result from it…We already saw it’s sufficient to pass the ‘ItemId’ of the task and that value is available in the BPM during startup in the element called ‘rootEntityInstanceId’. We just need to make the mapping correct in the ‘Message Map’ (open it from that tab in the bottom of the BPM model)
We know the service operation is already working so let’s publish it and do a quick test shall we!?
From our PIM artifact we should be able to check the output message for the webservice call…
Well…Looks fine to me…Now we just need to update our condition in the decision point with a real simple condition like this (might look a little different on your environment with the namespaces):
matches(ns2:ReadtaskOutput/ns2:ReadtaskResponse/ns3:task/ns3:task_is_repeatable/text(), 'true')
It just grabs the ‘Is repeatable’ value of our ‘Task’ entity and matches it with the value ‘true’. So, when that value is ‘false’ it will drop to our ‘Break’ endpoint and when ‘true’ it will return to the ‘Readtask’ activity as we already tested.
Ok…Deploy and test in runtime…You’ll be fine (I believe in you!)
When ^&%$%#^%$ hits the fan in BPM
Do a debug session on your BPM with (
<Ctrl>+<F12>
)To make that ‘Readtask’ work in debug mode you need make sure the ‘ItemId’ is filled with a fixed value as we don’t have a ‘rootEntityInstanceId’ value available in debug mode!
Enable monitoring on the BPM model properties
After a change in the BPM, do a save, do a ‘Validate and Build’ (
<F9>
) and publish it again (there’s some caching involved from what I experience)
And that’s it my AppWorks friends…Our “DONE” for this post where we learned more about the while-loop in a BPM and much more like:
- Calling a BPM from an action button (via a Rule)
- Calling an entity webservice from a BPM
- And learning about the importance of a lifecycle-task layout!
Have a great weekend, and I see you (as always) in the next one.
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”?