Custom Tasks, a.k.a. custom Work Items are used when the natively provided components are not clear enough to demonstrate the required domain demands. See examples of domain-specific tasks that a business user would find useful to have available in the process designer: Enhance customer data; Validate Personal ID against Official State Service; Check customer healthRead more →
Custom Tasks, a.k.a. custom Work Items are used when the natively provided components are not clear enough to demonstrate the required domain demands. See examples of domain-specific tasks that a business user would find useful to have available in the process designer:
Creation of custom work item handler demands the involvement of a developer which knows Java. Once developed and deployed, the custom WIH will be displayed in the process designer components tab, along with the other bpmn2 tasks. In this way the business automation specialists can drag and drop it into the flow, and care only about the parameters, and not about the logic execution itself.
Let’s separate the Custom WIH in four topics:
Once developed, deployed and installed, the custom task is displayed in the process designer pallet, under the service tasks option ready to be used during the authoring phase.
To develop a custom WI, a new Java project needs to be created. This project can be created from scratch or from an official jBPM maven archetype.
Here is some important information the developer should know:
Let’s see how to create it using a maven archetype org.jbpm.jbpm-workitems-archetype which provides all the basic starters already set and ready to use.
[INFO] For versions prior to jBPM 7.40.0 , it is required to use JDK 8. You can confirm you Java version by running the “java -version” command on your terminal. Check details here: https://issues.redhat.com/browse/JBPM-9204
The first step is to download the project which contains the official work item archetype:
$ mkdir ~/projects/jbpm-getting-started-lab/ && cd ~/projects/jbpm-getting-started-lab/ $ git clone https://github.com/kiegroup/jbpm-work-items $ cd jbpm-work-items $ mvn clean install
It might take a while until the dependencies are downloaded. Then, it is possible to create a new project using the archetype:
$ mvn archetype:generate -DarchetypeGroupId=org.jbpm -DarchetypeArtifactId=jbpm-workitems-archetype -DarchetypeVersion=7.40.0-SNAPSHOT -DgroupId=org.kie.learning -DartifactId=hello-workitem -DclassPrefix=Custom -Dversion=7.40.0-SNAPSHOT -DarchetypeCatalog=local
The following parameters can be changed according to your environment and needs.
pom.xml using the command$ head -10 ~/projects/jbpm-getting-started-lab/jbpm-work-items/pom.xml
After executing the archetype generation command, Maven will download all the required libs to build the project. You will be asked to confirm if the data is correct. If it is correct, input Y and press enter.
A new project will be created in the current directory with the name of your artifactId, in this example, hello-workitem. The developer can import the project to eclipse, check its structure, created classes, annotations, tests and implement the custom logic.
Once the development is done, compile the project with mvn clean install. The file jar file is created inside the target folder.
Now, it is ready to be deployed to jBPM and configured in BA Projects.
Once the coding phase is done, the project should be compiled and installed in a maven repository which is visible for Business Central (during authoring) and for Kie Server (for execution).
Compile the project using the command below and the jar will be available inside target folder.
$ cd hello-workitem/
$ mvn clean package
Install it into the maven repository or do this using business central UI.
~/projects/labs/hello-workitem/target/hello-workitem-7.40.0-SNAPSHOT.jar.
If you open the class src/main/java/org/kie/learning/CustomWorkItemHandler.java, you will see the class-level annotation defining this WIH name as “CustomDefinitions”.
The custom WIH will now be available to be installed in any project. Let’s proceed.
Now that your Business Central and Kie Server have access to your custom task (the jar is in the maven repository), the business application can be configured.
CustomDefinitions, new org.kie.learning.CustomWorkItemHandler()If you open a new business process and check the tasks, you will be able to see your custom task:
That’s it, you can now create custom tasks with so that the user who is authoring business process can re-use domain logic in a more customize and visible way.
This blog post is part of the fourth section of the jBPM Getting started series:
Effective modeling, Integration and Delivery.
When planning usage of processes that are complex, long-running, and with possible points of failures like custom work item handlers, asynchronous tasks, timers, signals, and service tasks, it is crucial to understand how jBPM deals with transactions. This knowledge might save some troubleshooting hours if you have persistent processes. “Why?“, you might ask: if theRead more →
When planning usage of processes that are complex, long-running, and with possible points of failures like custom work item handlers, asynchronous tasks, timers, signals, and service tasks, it is crucial to understand how jBPM deals with transactions.
This knowledge might save some troubleshooting hours if you have persistent processes. “Why?“, you might ask: if the process is not properly designed and an unhandled error occurs, you may end-up with tasks being triggered more times than you planned.
Let’s drill down.
During the following process execution, jBPM will execute all these tasks in a single transaction:
Therefore, if the process reaches Service B, and it throws an exception, Service A won’t be rolled back. This process will not be persisted on the database, it is like it was never executed. This would happen because there is no wait state point in this process.
To the engine, a wait state is any point during the process execution which it might need to wait for some external intervention. When this occurs, the engine persists the process state in the database. These are the possible wait states of a process:
So, if we consider the following process, what will happen if Service B throws an exception?
If service B with an unrecoverable error and throwing exception, Service A would be triggered three times. (worrying, right?)
In this case, the process was persisted when the human task was completed. So, when Service B threw an exception, the transaction will roll back and return to the Human Task again. Gateway is validated, Service A is triggered the second time, and then, Service B is triggered. If B throws an exception, the execution again returns to the Human Task. This will happen as many times as configured in the engine retry count, which by default is three.
In cases like the one represented below, by simply configuring Rest Task 2 as Async you can make the engine persist the process state, and in case of an error on REST Task 3, Rest Task 1 and 2 would not be executed again.
To avoid situations like this, during the process authoring, have the transaction boundaries clear in your mind. Choose wisely which task should be async, which are the wait states, and if you need to create any wait state or handle errors with compensation events to avoid unexpected businesses outcomes.
Understanding how the engine works will help business automation specialists and developers to deliver fine-tuned projects that perform better on the jBPM engine. The business automation specialist should be able to absorb the business requirements and be able to reflect this on the project not only by authoring the assets but by improving the execution of these assets adjusting every configuration to best perform in each scenario and by being able to understand the impacts of the transaction boundaries in each delivered process.
This blog post is part of the fifth section of the jBPM Getting started series:
Techniques to boost a BA Project
When working with business processes, it is expected to work with persistent process data scenarios. Considering this situation, it is common for users to use a different database to store process data, apart from the database where the domain information is stored. As an example, storing critical information from customers apart from the engine databaseRead more →
When working with business processes, it is expected to work with persistent process data scenarios. Considering this situation, it is common for users to use a different database to store process data, apart from the database where the domain information is stored.
As an example, storing critical information from customers apart from the engine database is an expected data architecture. In this way, the user can maintain the data consistent and isolated. But what if these objects, stored in a different database, needs to be used in one of the business automation projects?
[INFO] Many of the concepts here applied are valid for any application which involves distributed transactions (XA Transactions), this means, any application which might possibly have a transaction which spawns through two or more different databases. An overview of how application deployed in Java EE application servers, communicates with a database can be found at this blog post: Datasources, what, why, how?
Let’s understand how to configure and access different databases within the same project.
Here are the steps required to make a business automation process store process variables (domain information) in a different database:
Once this is done, every time this object gets created or updated during the process execution, it will be properly persisted on the database. Let’s check this with a hands-on exercise.
To run this example, using docker to start a database is the easiest way to get a database up and running. Make sure you have docker running in your environment. Let’s create a directory to store the database information.
$ mkdir -p ~/projects/jbpm-getting-started-lab/postgresql
Make sure you have Docker up and running. Then you can start a Postgres container:
$ docker run --name jbpm-postgres-container -e POSTGRES_PASSWORD=psqlpass -d -p 6543:5432 -v $HOME/projects/jbpm-getting-started-lab/postgres:/var/lib/postgresql postgres:9.4
This command will download the image (if you don’t have it locally), start a container named postgres, based on the latest PostgreSQL image. expose the internal port 5432 opened by PostgreSQL, to be accessed externally also in 6543.
Let’s enter in this SQL Server to create a new database for our jBPM tables. Run the command below to get the Container ID of this psql container:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 620350186bbe postgres:9.4 "docker-entrypoint.s…" About a minute ago Up About a minute 0.0.0.0:6543->5432/tcp jbpm-postgres-container
Use the whole ID, or simply the first two numbers, to enter the container. Then, we will start the psql client:
$ docker exec -it jbpm-postgres-container /bin/bash $ psql -h localhost -U postgres -d postgres
Now, let’s create a database to be used by jBPM, with a new a user and password. This user needs permision on this new database. The tables will be created automatically by jBPM on startup.
[TIP] You might want to create additional indexes on some tables and columns in your production environment
CREATE DATABASE jbpmdb; CREATE USER jbpmdb WITH ENCRYPTED PASSWORD 'jbpmdb'; GRANT ALL PRIVILEGES ON DATABASE jbpmdb TO jbpmdb;
And create another database, to store the specific domain data.
CREATE DATABASE labpvp; CREATE USER labuser WITH ENCRYPTED PASSWORD 'labuser'; GRANT ALL PRIVILEGES ON DATABASE labpvp TO labuser;
When done, type q and press enter, to quit psql client, and then exit to exit the container.
Now, let’s configure WildFly: we will create two datasources one connecting to jbpmdb and other to labpvp . Once the datasources are configured, applications can start connecting to these databases.
In this example we expect that you have downloaded jBPM and have it available in your ~/projects directory. If you want to use the commands here, you can optionally create a symbolic link for the folder with the command below:
$ ln -s ~/projects/jbpm-server-7.38.0.Final-dist ~/projects/jbpm
Configuring WildFly basically requires two steps:
The simplest way to add a JDBC driver to WildFly is deploying it. Download postgresql-42.2.2.jar and place it into ~/projects/jbpm/standalone/deployments. WildFly will immediately tell you the driver is deployed:
16:11:07,515 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-4) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 42.2) 16:11:07,540 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-5) WFLYJCA0018: Started Driver service with driver-name = postgresql-42.2.12.jar 16:13:33,885 INFO [org.jboss.as.server] (ServerService Thread Pool -- 45) WFLYSRV0010: Deployed "postgresql-42.2.12.jar" (runtime-name : "postgresql-42.2.12.jar")
Let’s use the JBoss CLI script, which is less error-prone, to do the configuration. Start your WildFly in one terminal tab, and open another terminal tab so you can connect to it using CLI.
$ ~/projects/jbpm/bin/jboss-cli.sh -c
Add a new datasource, informing the connection data, and your deployed driver name:
[standalone@localhost:9990 /] xa-data-source add --name=psqljBPMXA --jndi-name="java:/jboss/datasources/psqljBPMXADS" --user-name=jbpmdb --password=jbpmdb --driver-name=postgresql-42.2.2.jar --xa-datasource-class=org.postgresql.xa.PGXADataSource --xa-datasource-properties=[{ServerName=localhost,PortNumber=6543,DatabaseName=jbpmdb}]
Now, let’s add a datasource to connect to our domain-specific database, labpvp:
[standalone@localhost:9990 /] xa-data-source add --name=psqlLabPVP --jndi-name="java:/jboss/datasources/psqlLabPVP" --user-name=labuser --password=labuser --driver-name=postgresql-42.2.2.jar --xa-datasource-class=org.postgresql.xa.PGXADataSource --xa-datasource-properties=[{ServerName=localhost,PortNumber=6543,DatabaseName=labpvp}]
The following test commands validate both datasource configurations:
[standalone@localhost:9990 /] /subsystem=datasources/xa-data-source=psqljBPMXA:test-connection-in-pool
{
"outcome" => "success",
"result" => [true]
}
Finally, we need to tell jBPM to stop using the H2 database and start using Postgres by connecting through the datasource with JNDI name: java:/jboss/datasources/psqljBPMXADS .
[standalone@localhost:9990 /] /system-property=org.kie.server.persistence.ds:write-attribute(value=java:/jboss/datasources/psqljBPMXADS, name=value) [standalone@localhost:9990 /] /system-property=org.kie.server.persistence.dialect:add(value=org.hibernate.dialect.PostgreSQLDialect)
Restart jBPM.
It will bootstrap creating its tables inside the Postgres in your docker container. You can confirm this by getting into your Postgres container and listing the tables:
$ docker exec -it jbpm-postgres-container /bin/bash root@620350186bbe:/# psql -h localhost -U jbpmdb -d jbpmdb psql (9.4.22) Type "help" for help. jbpmdb=>d
Scenario: You joined a team which has on-going project, hello-jbpm. In this project, the final user does a question, complain or suggestion and gets an automatic or a manual answer. You noticed that the data architecture can be improved by storing the reported issue and person details, into a separate database. apart from the one used by the engine.
Import project 02-customer-service-jbpm if you don’t have it in your business central yet. You should see it in your space:
In order to persist a POJO into a database, we need will make use of JPA benefits and to convert it into a JPA Entity.
Open hello-jbpm project, and notice both data object named Issue and the Person.
Let’s start by configuring Person. By clicking on the “Source” tab you can view it’s code.
[TIP] In order to be persisted, classes should implement java.io.Serializable interface. By default, Business Central creates the Data Objects implementing Serializable interface.
@javax.persistence.Entity annotation;@javax.persistence.Table(name = "Person") Long to Person.java. Don’t forget the attribute should have the get and set method and be annotated with @javax.persistence.Id.Person.java should look like this:
@javax.persistence.Entity
@javax.persistence.Table(name = "Person")
public class Person implements java.io.Serializable {
@javax.persistence.Id
@javax.persistence.SequenceGenerator(name = "ID_GENERATOR", sequenceName = "PERSON_ID_SEQUENCE")
private java.lang.Long id;
Click on the save button.
The persistence unit, if the configuration which tells a Java EE application which datasource it must use to connect to the database. To configure a business application to persist process variables in a custom database, inform the datasource details in the persistence unit, and create a Marshaller configuration. This Marshaller configuration allows the engine to convert the variables data to/from process and database.
When the JPA Marshaller is configured, every JPA Entity used as a process variable, is automatically persisted in the database pointed by the application used datasource.
2. Considering we are using PostgreSQL and the datasource configured in the last step, use the following values in the form:
customer-service-jbpm-pujava:/jboss/datasources/psqlLabPVPorg.hibernate.dialect.PostgreSQLDialecttrue
3. Set the show_sql attribute to true, to enable logs and permit checking in the server logs if the entity is being manipulated as expected. Save the configuration.
4. Make sure you scroll down and add the persistable class, Person:
4. Still in the project Settings, configure the JPA Marshaller. Access the Deployments option, and select Marshalling Strategies.
5. Click on “Add Marshalling Strategy“, insert the following value and hit save:
new org.drools.persistence.jpa.marshaller.JPAPlaceholderResolverStrategy("customer-service-jbpm-pu", classLoader)
Now you have JPA Classes ready to be used as process variables, and to be automatically persisted in a different database!
You can check the result of this work by clicking on the Deploy button. If everything is properly set, you should see something similar in the server log:
17:41:12,801 INFO [stdout] (default task-20) Hibernate: create table Person (id int8 not null, birthDate timestamp, name varchar(255), primary key (id))
Start a new process instance, and validate if the object was persisted in the database table you specified.
This blog post is part of the fifth section of the jBPM Getting started series:
Techniques to boost a BA Project
During the development phase, it is expected that developers deal and treat unexpected behaviors, predictable and unpredicted errors that might happen during the execution of code. Consider the following situation: An online traveling company named MaTrip.com sells a whole trip experience with a discount for a single package buying: flight + hotel. But each ofRead more →
During the development phase, it is expected that developers deal and treat unexpected behaviors, predictable and unpredicted errors that might happen during the execution of code. Consider the following situation:
An online traveling company named MaTrip.com sells a whole trip experience with a discount for a single package buying: flight + hotel. But each of these services is independent as they are provided by external specialized companies. In this way, MaTrip orders need to interact with the services via services integration.
The customer has bought a trip package and the flight has already been successfully booked. What should happen if the hotel application services go offline for two days? Should the flight be canceled? Should it be automatically reassigned? Should the user be contacted in order to schedule a new trip?
There are several business outcomes to solve this scenario, all it takes is that the developer properly handles this incidents. There are cases where only the main biz scenarios are described by the biz team, and the development team does not have enough information to implement the exception handling. In these cases, the Business Analyst of the project should be involved in order to define the outcomes of these scenarios.
When handling errors like this, for example, in a Java or Javascript code, the developer directly implement exception handling with try and catch; When considering the endpoint layers, developers likely uses HTTP codes to transmit a proper message to the consumer; but, how to deal with exceptions and errors when working with a business flow?
Give a look at the following situation, considering it is at an initial development phase. The “happy path” for this trip schedule flow is:
There are two gaps in this process that can lead to instances aborted or failed:
Business Exceptions are errors that are not technical. They are not thrown by unexpectederrors in the code itself. See some examples of business exceptions:
These exceptions are examples of behaviors directly related to each domain exception. The recommended way to handle business exceptions would be to catch the error
using error events, and then, triggering following actions to handle the error according to the business logic. By using this approach, the whole process – including the treatment of the errors – is clear for all the personas involved in the project. This will facilitate validation by the business users and further maintenance, and enhancements.
Look at this process of a store which opted to follow digital transformation. They allow their customer to select products in a rich multi-channel online store; once payment is confirmed, a personal shopper manually chooses the items; finally, the delivery team takes the order to the customer address:
Both tasks Charge from credit card service and reserve products from stock are rest tasks. Eventually, the store can run out of available products in the stock when the task reserve products from stock is triggered. Does this look like a business exception to you?
We just identified a business exception: NoAvailableProductException. Let’s consider that this Java REST Service treats this error like this:
if (!product.isAvailable()){
log.error("Product is not available, throwing exception.");
throw new NoAvailableProductException(Response.Status.CONFLICT);
}
In this example, you can consider that NoAvailableProductException extends WebApplicationException.
Now, the author of the process design knows which error the service will throw in case of a NoAvailableProductException: HTTP 409 code.
 |
javax.ws.rs.core.Response.Status.CONFLICT relates to HTTP 409. As per RFC specification, this code should be used in situations where the user might be able to try the same request and possibly get a different response. The server should include information about the error in the payload for the consumers. See more details in: https://tools.ietf.org/html/rfc7231#section-6.5.8 |
The business automation specialist also receives the updates from the business team, and the new exception flow business scope is also defined: if the product is not available, the personal shopper should call the consumer and switch missing item for a similar one or remove it from the order. The order price will change and the new value should be charged.
Scenario 1: The BA specialist increments his process to deal with the business exception thrown in a specific task: He/She added a boundary intermediate catch event to the REST Task. The error code is configured on the error events properties.
In this way, the business analyst can capture business exceptions thrown in specific tasks and provide proper handling for each scenario. But when there are too many possible errors, this approach can make the process too verbose and might affect the clarity of the flow.
Considering that the same business exception can be thrown by more than one task, the author can choose to group the tasks in a subprocess and catch the exception in the parent process definition. See the following scenario.
Scenario 2: Tasks inside a subprocess throw an error end event, which will be catch and handled by the parent process.
Another possible approach is to store the output of the processing in a process variable instead of throwing an exception. Based on the variable value, a gateway can lead to an end error event which will be handled by an event subprocess.
Scenario 3: Process throws an error endevent, which will be handled by an event subprocess with a starting error event.
The author of the process should choose the proper option which better suits the business needs, worrying about the variable scopes and with the understanding and maintainability of the process. On scenario 2 for example, the variables contained inside the subprocess, will not be available during the handling of the exception in the parent process.
Treating business exceptions inside a business process is considered an advanced process modeling technique, and is crucial for proper implementation of successful projects. The Business Exceptions also matters for the organization improvement and the modeling of it can also lead to the creation of business monitoring dashboards.
Technical exceptions are raised within the code implementation itself and are not related to the domain flow. It can happen on script tasks, on custom code implemented on “On Entry” an “On Exit” properties of tasks and custom Work Item Handlers. See some examples of technical exception:
Integration with external components should be handled by external services and not by treated by the process design itself
These kinds of errors can and should be avoided by leveraging the usage of custom code to necessary scenarios, and by increasing the usage of the provided native features. Exceptions raised on script tasks, cannot be caught and handled by the error events demonstrated on the “Business Exceptions” examples.
This blog post is part of the fourth section of the jBPM Getting started series:
Effective modeling, Integration and Delivery.
Great post from Sudhish Nair, an expert on process and rules automation. TechBlogs jBPM provides options to configure notification emails to be send to any user if the human task is not started or not completed. We will start with configuring JavaMail sessions via JNDI so that infrastructure for mail is handled. We would beRead more →
Great post from Sudhish Nair, an expert on process and rules automation.
We will start with configuring JavaMail sessions via JNDI so that infrastructure for mail is handled.
We would be using “jbpm-server-7.37.0.Final-dist” version for this example.
In the standalone configuration for jBPM we need add below configurations.
<outbound-socket-binding name="mail-notification-smtp">
<remote-destination host="smtp.gmail.com" port="465"/>
</outbound-socket-binding>
host -: host name of SMTP server
port -: port no of SMTP server.
<mail-session name="notification" jndi-name="java:/notificationMailSession" from="youremailid@gmail.com">
<smtp-server outbound-socket-binding-ref="mail-notification-smtp" ssl="true" username="youremailid@gmail.com" password="yourPassw0rd"/>
</mail-session>
from -: From address for your emails (Valid email account on SMTP server).
username -: username for the email account
password -: password for the email account.
Add below system property to standalone.xml file.
<system-properties>
<property name="org.kie.mail.session" value="java:/notificationMailSession"/>
</system-properties>
View original post 423 more words
User Tasks allow the interaction of humans with a set of automated tasks. In this way, a series of automatic tasks can be triggered before – providing input for – human decisions, and the output of the user task can then be used to define further actions of a flow. User tasks have a moreRead more →
User Tasks allow the interaction of humans with a set of automated tasks. In this way, a series of automatic tasks can be triggered before – providing input for – human decisions, and the output of the user task can then be used to define further actions of a flow.
User tasks have a more elaborate lifecycle than other activity tasks. The lifecycle of a Human Task involves states and actions. The actions that can be used to interact with the human task and change its state.
Considering the lifecycle of a human task, let’s talk about some possibilities that can be achieved out-of-the-box by using a user task. Here is hiring process an example of a process that has a different ending based on a human decision:
Once started, the candidate should send his curriculum vitae (first user task). The next step is that someone from the Human Resource team picks this task and do an analysis over the candidate curriculum. Based on this analysis, this person should decide whether this is or not an appropriate candidate for the role. This decision is stored in a process variable, that will be evaluated by the exclusive gateway, defining if the candidate was reproved (send an email) or approved (start hiring processes).Let’s analyze some important concepts based on this example:
User task variables can be manipulated by the human that owns the task. This is how the process variables are updated by humans involved in this execution:
The process contains two variables named CV and hr_approval. The user that interacts with this task, has access to the variables specified in “Data Inputs and Assignments“, in this case, in_CV. The user can interact with this task in many ways – a form in a web application, mobile app, business central, google home, etc – in whichever way, in the end, this interaction will be converted into a request submitted to the engine.When the user completes this task, his outputs with the answer are stored into “Data Outputs and Assignments” fields, in this case,out_approval. This simple boolean which tells if the candidate was approved or not, will be automatically assigned to the process variable hr_approval in order to be used in other steps of this hiring flow.
A client application with a customized layout can interact with human tasks via the available APIs, but for now, let’s see how to interact with this task using business central. Business Central provides a Task Inbox, accessible via the menu.
It is required that the user belongs to the HR group, otherwise, he is not a potential owner and won’t be able to visualize the tasks. When the user opens the inbox, he/she will see the list of tasks which he/she is a potential owner:
There are two tasks in this list, because two candidates applied and we have two running process instances. One of the tasks is currently in progress and being executed by a user named karina. Another task is “Ready” to be executed and has no owner. Notice the possible actions for this task: Claim and Claim and Work. But what exactly does this mean?
In order to understand this, we should go back to the WS-HT specification and the lifecycle of a human task.
According to the WS-HT specification, human tasks can be in the following states:
And, they can the possible actions can be used upon the human task:
jBPM provides Java client API and REST API available to interact with the task and move it through states. Check these states and actions represented on the following diagram:
jBPM implements an easy and comprehensible flow based on Web Services Human Task specification (a.k.a WS-HT Spec).
http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-bpel4people/WS-HumanTask_v1.pdf
But how is this translated into a real example? Let’s get back to our hiring process, in the point when the candidate finishes the first task, and the second task is activated:
As showed above, a whole lifecycle of management of user interactions is already provided out-of-the-box by jBPM. The user role also matters. It is directly related to the actions that can be executed over a task.
We are now going to enhance the human interaction by using forms. The Form Modeler is a component from Business Central which allows the Business Automation Specialist to create forms in a low-code manner. It significantly shortens the time spent into forms creation.
These forms are .frm files delivered as part of the kjar and can be also consumed via rest and embedded into custom client applications. This makes it easy to consume the whole process from a single point, without propagating changes to other services and impacting their functioning.
See how simple it is to create a form for the hiring process: once all the input and output variables are properly defined for user tasks, look for the option Generate all forms in the process designer toolbar.
All the forms are made available and are accessible via the project lateral toolbar, or in the project main page. The lateral toolbar shows the assets categorized by type.
By clicking on one of the forms, in this example, “ValidateCV-taskform”, the form modeler will open with the generated form. This generated form has a proper field for every variable configured on the input/output assignment variables of the human task. It takes in consideration the variable class type, so for example, for the document it provided a file upload component. For the boolean field, it provided a checkbox.
All the BA specialist needs to do is adjust the form according to the domain knowledge and requirements. By clicking on the three dots on the right corner, of each field, options for editing and removing are available. To reorganize items, simply drag and drop them. See the edition of the checkbox for a more appropriate label:
The HTML field type editor is a rich text editor to give more flexibility to the user. There is a whole set of components to be used into the form creation. Also, if the user adds new variables or wants to remove them, they will be displayed in the “Model Fields” tab to be used dragged into the form is necessary.
And this is how, after three minutes, a whole new reusable form got created without much coding:
In order to test it, the project needs to be deployed to kie server. Once deployed, when the task is activated, the results can be visualized via business central when clicking on the task. The same form could be embedded into a custom client application.
The form can be obtained in two ways:
This blog post is part of the fourth section of the jBPM Getting started series:
Effective modeling, Integration and Delivery.
In a business automation project, business process assets are described with BPMN diagram or CMMN diagrams. It’s recommended to base the creation of diagrams on specifications definition, therefore, the implementation will be executable in any software which attends to the specification. Process modeling knowledge is not restricted to specific products. Just like a Java classRead more →
In a business automation project, business process assets are described with BPMN diagram or CMMN diagrams. It’s recommended to base the creation of diagrams on specifications definition, therefore, the implementation will be executable in any software which attends to the specification. Process modeling knowledge is not restricted to specific products.
 |
Just like a Java class can be imported and edited within different IDEs like Eclipse, VSCode, and IntelliJ, the BPMN2 files are also parsed and displayed correctly in other BPMN Modeling tools. If the user chooses different BA tools to work on process authoring, that’s fine, as long as the tools follow the specification definition. |
First, let’s review the core concepts of commonly used BPMN2 elements and how jBPM provides them. Then, we will proceed on more in-depth details about how model processes following best practices and advanced modeling concepts.
Along with the descriptions, the book also references the specific jBPM source code which delivers the features. In this way, dev-focused readers can have a better understanding of how everything works under the covers.
|
Visualizing the source code of open-source projects is an advantage for developers who wants to get more in-depth on the functioning without going depending exclusively on documentation. |
Business processes can be modeled in diagrams using this three element types: Events, Activities, and Gateways. Let’s start with the events.
As per BPMN2 specification: An Event is something that “happens” during a process execution.
Events are categorized as: Starting events, Intermediate events and End events. Events can react to and be triggered based on different happenings. It can also be used to throw a result, raise an error. All these behaviors are examples of events of a business process. The events are represented with circles, and BPMN2 specification has sixty-four different types of events.
Don’t worry, though. It is not necessary to know all sixty-four. Once you understand the concept behind the types, you will then know when to use them. The more you get familiar with it, the more intuitive it gets. The following concepts provide a baseline:
The BA Specialist should mix these capacities to deliver the expected business solution. Take a look at the following example. It represents the usage of different events: two start events, two catching intermediate events, one throwing intermediate event, and four end events.
Note the events placed along with the flow and the ones placed as boundary events of the tasks. Notice how the Intermediate Error is used on top of an external REST Service, which makes an external request, to catch possible errors. Also, the Intermediate Timer set on top of the Human Task “Collect User feedback” to take necessary steps in case of delayed user action after a determined time limit.
When an event happens, a step or series of steps are then triggered: tasks which need human interaction, e-mails that should be sent, external services which need to be called, business rules which needs to validate data within the process. The actions executed during the flow are considered activities.
Activities can be atomic, or they can be decomposable. Atomic activity, is, for example, a Service Task which does a call to an external service (REST Task), or a User Task, which needs intervention from a human. The decomposable activity would be a step which contains steps within it; in other words, a subprocess.
jBPM delivers the following activity types:
Before proceeding, it’s essential to understand how jBPM implements and delivers activities, look deeper into the concept of Work Items.
A Work Item (WI) is a set of logic that can be automated, graphically represented in a process or case. The same logic can be reused by simply changing the parameters. BPMN2 and CMMN specs already defined the most commonly used work items.
|
Understanding these concepts facilitates the task of creating custom tasks, content described later in this section. This concept is mainly essential for developers or the ops team who needs to deploy custom tasks into environments; |
Every WI has two main components:
Definition: defines a unique name, a description, and a 16×16 icon. This information isdisplayed in the process designer. It is a .wid file;
Handler: Actual logic that makes the task happen, that executes the task. The WIH is a Javaclass which implements WorkItemHandler interface. It has at least, an execute and an abort method.
Some Work Items, mostly Service Tasks, requires configuration during its initialization, and because of that, it needs to be configured in the project deployment settings. This configuration is set via parameters in the class constructor method. The topics Service Tasks and Custom Tasks will show more details about the initialization configuration.
Finally, the business automation specialist can choose whether to use the native work items provided by jBPM or to create custom work items which are adapted for domain-specific logic.
A service task is a task that does not require any human action with the engine. It can be executed by the engine synchronously or asynchronously (process execution should wait for the execution or not, respectively). We can invoke external services via REST, send e-mails, log messages, and even invoke complex business rules in order to define the next steps to be taken in the process flow.
|
Service Task Configuration Tips: Service tasks need additional configuration, set in the Deployment Configuration, Work Item Handlers Section of the project. These configurations can either be set manually or added via the Service Tasks menu. The configuration is set into /projectDir/src/main/resources/META-INF/kie-deployment-descriptor.xml. |
Rest Task : The Rest Task allows external services to be accessed using REST standards and using HTTP 4.3 API.
Every new task will have by default the following variables available. Use or not authentication, use different types of HTTP methods, and body formats. All these configurations are done via variables in the task.
The Data Inputs and Assignments are further converted and used in the request, like URL, headers, body, etc. The Data Outputs and Assignments receives the response, the resulting information from the execution, returned by the service.
Email Task: The e-mail task handles e-mail transmission and allows the user to addwithout email functionality to a process, without coding a new feature or service. The transmission is handled directly from the process server, in other words, the kie server can use the application server SMTP, previously configured.
The Data Inputs and Assignments are further converted and used in the request, like URL, headers, body, etc. The Data Outputs and Assignments receives the response, the resulting information from the execution, returned by the service.
During the process design, the following parameters are expected by default on the Email task: the subject, content of the email, the sender e-mail, and the destination (single or list).
Log Task: The Log task can be used in a process to output information into the applicationserver logs. To configure it, it is possible to use the out-of-the-box WIH SystemOutWorkItemHandler, or create a custom one to handle specific business needs.
Business Rules Tasks: jBPM engine has cloud-native BRM capabilities which allow the businessautomation specialist to author processes and rules, and execute them with scalable native core engine integration.
The capability of adding decision tasks to a process brings the possibility of creating simple solutions to solve complex scenarios.
When the process reaches a Business Rules Task, the configured set of rules is triggered in the Drools engine within Kie Server. Once there are no more active rules, the flow goes on to the next node. jBPM offers three out-of-the-box options to use this feature: Business Rule Task, Decision Task, Business Rules Remote Task. More details are presented further in this section, in the blog post about “Business Tasks”.
This blog post is part of the fourth section of the jBPM Getting started series:
Effective modeling, Integration and Delivery.
Being familiar your BA tool guides to better decision taking on development and architecture decisions. Let’s start by learning a little bit more about the core components and about jBPM installation. jBPM main components jBPM is mainly based on two components: Business Central and Kie Server. Reinforcing the concepts: business central is the authoring andRead more →
Being familiar your BA tool guides to better decision taking on development and architecture decisions. Let’s start by learning a little bit more about the core components and about jBPM installation.
jBPM is mainly based on two components: Business Central and Kie Server. Reinforcing the concepts: business central is the authoring and monitoring environment. Kie Server is the engine, where the execution of business assets happens.
In a business automation project with jBPM, during the application design phase the architect must take into consideration the determination of the architecture regarding the business automation services:
There are many ways to architect business applications and address the specific needs of development, operations, and business teams. The jBPM Getting Started series will bring possible architectures in later on in a post about Advanced Architecting , including information about enterprise cloud architectures for business automation projects.
Business automation involves managing projects and business assets in a friendly way, for all the personas involved in the project. Let’s get started by performing some basic tasks using jBPM. The tool is available for download in the official site http://jbpm.org.
Cloud-ready kjars can run on Java Application Servers, Spring Boot, Thorntail, or Web Server Container (tomcat). For our first try, we will work with WildFly, an open-source Application Server (also known as JBoss in earlier versions).
The first hands-on guides you through a setup of jBPM in a local environment.
Wildfly, also known as JBoss Enterprise Application Platform (JBoss EAP), is an open-source option of a Java EE Application Server. It is widely used in critical environments and it has been proven stable over the years. jBPM website provides a ready-to-use jBPM installed on top of WildFly.
To download and install jBPM follow these steps:
2. Extract the files from the downloaded package into a folder of your preference. WildFly is extracted and jBPM is available and configured.
# Create a folder dir for your instalation $ mkdir ~/learn-jbpm # Unzip the downloaded file into opt folder $ unzip jbpm-server-7.36.0.Final-dist.zip -d ~/learn-jbpm/opt/jbpm # Enter jBPM folder $ cd ~/learn-jbpm/jbpm # Start jBPM $ ./bin/standalone.sh
The default installation comes with predefined users and their respective roles. Here are some of the users which you can use in this lab. The password is equal to the username.
| Username | Roles |
| wbadmin | admin,analyst,user,process-admin,kie-server |
| krisv | admin,analyst,user,process-admin,kie-server |
| maciek | admin,analyst,user,PM,HR,kie-server |
|
jBPM uses the Java Authentication and Authorization Service (JAAS) provided by WildFly login module. Later on upcoming blog posts we’ll understand how to integrate with authentication and authorization using Keycloak. |
WildFly users and groups are defined within application-users.properties and application-roles.properties files. Both files are located under $WILDFLY_HOME/standalone/configuration directory. In our jBPM installation, the standalone.xml file has customization that changes the used files to configure users and roles. The new files used are users.properties and roles.properties respectively. The following code sets this customization within the standalone.xml file:
<security-realm name="ApplicationRealm">
...
<authentication>
<local default-user="$local" allowed-users="*" skip-group-loading="true"/>
<properties path="users.properties" relative-to=“jboss.server.config.dir"/>
</authentication>
<authorization>
<properties path="roles.properties" relative-to="jboss.server.config.dir"/>
</authorization>
</security-realm>
In this post, we will use the users.properties and roles.properties provided by the out-of-the-box authentication and authorization configuration.
In higher environments (like UAT or production), this auth strategy is not recommended. jBPM should connect to external authorization and authentication providers like LDAP or Keycloak.
The next topics provides an introduction on how to run jBPM on Spring-boot and Docker.
jBPM community also provides a website that allows you to easily create business applications using Spring Boot. To try this approach, download a business application with all the required structure to be executed on-premise or in the cloud.
→ unzip business-application.zip -d ~/learn-jbpm/labs/hello-sb-jbpm → tree -L 2 hello-sb-jbpm
This design of business application consists of three (or more) projects: a module for the business assets, a module for the application models, and another one for the services. It is possible to have multiple modules of each type, this decision should match the environment and application requirements.
cd ~/learn-jbpm/labs/hello-sb-jbpm/business-application-service/ sh launch.sh clean install
You will notice that Maven starts downloading the project dependencies in order to build and compile the whole project. Once services are up and running you should be able to access them in: http://localhost:8090/rest/server . You can test it with the default user wbadmin and password wbadmin.
The code example below shows how the users and roles are defined within com.company.service.DefaultWebSecurityConfig class in the service project:
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth.inMemoryAuthentication().withUser("user").password("user").roles("kie-server");
auth.inMemoryAuthentication().withUser("wbadmin").password("wbadmin").roles("admin");
auth.inMemoryAuthentication().withUser("kieserver").password("kieserver1!").roles("kie-server");
}
In a development environment when the user is not connecting to external authorization tools like Keycloak, this is where users can alter roles and groups.
jBPM community also works to provide docker images into Docker Hub repository. There are currently three images:
Let’s try the jbpm-server-full image. This image provides a full authoring and execution environment running on top of WildFly. It is really simple to run a container with the latest project version:
$ docker run -p 8080:8080 -p 8001:8001 -d --name jbpm-server-full jboss/jbpm-server-full:latest
This should start a container, exposing the port 8080 to enables access to Business Central and Kie Server, and port 8001 to enable importing and exporting projects using git:
$ docker ps
This startup command does not map any volume, so be aware that work executed inside this Docker container is not persisted. It is possible to follow the server logs if necessary (change 06 with your docker container id):
$ docker logs -f jbpm-server-full
jBPM is started, and both services are running:
To stop the docker container, use the following command. This command should stop the instance which is running jBPM server.
$ docker stop jbpm-server-full
Three possible ways to work with jBPM were presented: jBPM deployed in WildFly application server; business applications deployed within spring-boot; docker image with a ready to use jBPM deployed in a WildFly Application Server.
On the next blog post, we’ll check the main components of jBPM and how we can start using them towards a business automation project delivery.
<
p class=”has-text-align-center”>This blog post is part of the third section of the jBPM Getting started series: Automate your business with jBPM
Next week Red Hat Summit 2020 will be held, not in San Francisco as we were hoping, but as a virtual event. While this unfortunately won’t give us the possibility to meet in person, a lot of the keynotes and breakout sessions will be held online. Virtual Red Hat Summit is completely FREE, so ifRead more →
Virtual Red Hat Summit is completely FREE, so if you haven’t done so yet, register today!
Below is an overview of various sessions around business automation. So if you’re looking for the latest news on Kogito, our next gen cloud-native business automation toolkit, or how to leverage Red Hat Process Automation Manager and Decision Manager for use cases that involve microservice orchestration or machine learning, or to hear from our customers. But take a look at the full agenda as well.
There will also be an opportunity to come and chat with us in the community area. After signing in, click Explore and open up the “Middleware & cloud applications” Community Central chat room to ask questions! Or you can just join our KIE chat channels we announced recently anytime.
Below is the list of presentations around business automation that I am aware of !
The state-of-the-art of developer tools to build business-intelligent apps for RHPAM v7 and Kogito
Eder Ignatowicz (Red Hat), Alex Porcelli (Red Hat)
Empowering Amadeus’ competitive advantage with cloud-native decision making on Quarkus
Matteo Casalino (Amadeus), Giacomo Margaria (Amadeus), Mario Fusco (Red Hat)
We are glad to announce the Kogito 0.9.1 release is now available! This goes hand in hand with the Kogito Tooling 0.3.1 release. From a feature point of view there are only minor changes compared to 0.9.0, but on top of bug fixing we have also spent quite some time on following areas: Kogito documentationRead more →
All artefacts are available now: