2018/11/16

jBPM empowered by Camel to integrate with ... everything!

Apache Camel is extremely powerful integration library, comes with hundreds of components to integrate with 3rd party systems. jBPM on the other hand provides great support for business processes and cases. In many situations data produced by jBPM is required to be pushed to external systems or business processes would need to be informed about changes in external systems that can influence business logic.

So why not combine these two and provide state of the art business solution that can focus on business goals and yet integrate with pretty much anything in the world.

Improved camel-jbpm component

camel-jbpm component has been added in 2.6 version of Camel. At that time it was based on jBPM 6.5 and provided only producer based on kie-remote-client that interacts with jBPM console (aka workbench) REST api. It's been a while since then and even more important jBPM Console REST api for execution does not exists any more and same applies for kie-remote-client. It has been replaced completely with way more powerful kie server client.

So it was high time to improve the camel-jbpm component to first of all upgrade to latest version (7.14) and replace use of kie-remote-client with kie-server-client for producer usage. And to provide consumer support as well that will enable simple integration with outside world for pushing out data from jBPM.

So when it comes to consumer of camel-jbpm component users can now take advantage of following integrations of jBPM empowered by Camel
  • ProcessEventListeners
  • TaskLifeCycleEventListeners
  • CaseEventListeners
  • EventEmitter
All of these can be easily configured as Camel routes, here is a simple example that will be triggered upon process events being generated by jBPM

<routes xmlns="http://camel.apache.org/schema/spring">
    <route id="processes">
        <from uri="jbpm:events:process"/>
        <filter>
          <simple>${in.header.EventType} == 'beforeProcessStarted'</simple>
          <to uri="log:kjar.processes?level=INFO&amp;showBody=true&amp;showHeaders=true"/>
        </filter>
    </route>
</routes>

as you can see as soon as there will be events produced on the jbpm:events:processes a new exchange will be processed that will simply go over filter and get only beforeProcessStarted events (each event type is set as header) and the body is actual event produced by jBPM.

NOTE: if you need more than one on the same consumer type you should suffix it with sort of classifier to make the endpoints unique jbpm:events:process:startedOnly

Similar endpoints can be used for user tasks and cases

  • jbpm:events:tasks
  • jbpm:events:cases

Configure routes

Routes can be configured either on application level (kie server or business app) or kjar level. 

camel-jbpm component comes with KIE server extension that will be automatically registered in KIE Server when the jar file is present - see Installation section for more details on it.

Global routes should be created in the root of the application class path (kie-server.war/WEB-INF/classes) in a file name global-camel-routes.xml

Such global routes will apply to all deployed kjars in KIE Server.

KJAR specific routes can also be used by placing camel-routes.xml file in the root of kjar class path (src/main/resources folder of the kjar source). When such file is found new (kjar scoped) CamelContext is created with all routes defined in that file. These routes will only apply to that specific KIE Container.


Installation

Installation is really simple, it requires to drop two jar files into kie-server.war/WEB-INF/lib
  • camel-core
  • camel-jbpm
and that's it, start the server and you will see that Camel KIE Server extensions boots and does its thing :)

In case you would like to use another component to interact with, you need to do the same, drop the component jar file and its runtime dependencies. For the sake of example we use camel-kafka that requires these jar files to be placed in kie-server.war/WEB-INF/lib
  • camel-kafka-2.19.0.jar
  • kafka-clients-0.10.2.0.jar
  • lz4-1.3.0.jar
  • snappy-java-1.1.2.6.jar
NOTE: Make sure to use camel-kafka and kafka-clients matching your Kafka cluster.

Example

A simple use case to illustrate is to take advantage of the camel-jbpm consumer to react to events produced by jBPM for both tasks and processes
  • for tasks we just log them to console
  • for processes we push them out to Kafka
here is the camel-routes.xml for this example
<routes xmlns="http://camel.apache.org/schema/spring">    
    <route id="processes">
        <from uri="jbpm:events:process:test"/>
        <filter>
          <simple>${in.header.EventType} starts with 'before'</simple>
          <transform>
            <simple>${in.header.EventType} for process instance ${body.processInstance.id}</simple>
          </transform>
          <to uri="kafka:TestLog?brokers=localhost:9092"/>
        </filter>
    </route>
    
    <route id="tasks">
        <from uri="jbpm:events:task:test"/>
        <filter>
          <simple>${in.header.EventType} starts with 'before'</simple>
          <to uri="log:kjar.tasks?level=INFO&amp;showBody=true&amp;showHeaders=true"/>
        </filter>
    </route>
</routes>

and here is just a short screencast showing this in action


IMPORTANT: This improved camel-jbpm component is not yet released, it will go out with Apache Camel 2.23.0 release that is expected to be out in couple of days from now. So prepare yourself and make sure to give it a go.

Implement your own form renderer for KIE Server

As it was described in this article, KIE Server now provides form renderers for process and task forms built in jBPM Console (aka workbench). Out of the box there are two renderers provided

  • based on PatterFly to provide same look and feel as entire jBPM tooling - it's the default renderer
  • based on Bootstrap to provide a simple alternative that utilises well established framework for building web and mobile UIs
This obviously won't cover all possible needs of users and thus the renderers are actually pluggable. In this article we build a custom one from scratch to illustrate what it takes to have your own.

Create project with dependencies

First of all, a new maven project needs to be created. It should be most basic project with packaging jar. Then let's add required dependencies to pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.kie.server.samples</groupId>
  <artifactId>custom-form-renderer</artifactId>
  <version>1.0.0</version>
  <name>Custom Form Renderer</name>
  
  <properties>
    <version.org.kie>7.14.0.Final</version.org.kie>
  </properties>
  
  <dependencies>
    <dependency>
      <groupId>org.kie.server</groupId>
      <artifactId>kie-server-services-jbpm-ui</artifactId>
      <version>${version.org.kie}</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

Create configuration folders

Create folders in the project that will configure the renderer - all should be done src/main/resources
  • form-templates-providers - folder that will contain templates, css and java script files used to render the form
  • META-INF/services/org.kie.server.services.jbpm.ui.form.render.FormRenderer - an empty file that will be used as discovery mechanism to find and register the renderer - it will be edited a bit later to provide actual implementation details

Create form renderer implementation

In src/main/java create a class (e.g. org.kie.server.samples.CustomFormRenderer) that will extend org.kie.server.services.jbpm.ui.form.render.AbstractFormRenderer and implement the required methods 
  • getName - provide the name of the template that shall be used as reference when rendering
  • loadTemplates - main implementation that loads different types of templates to be used by renderer
  • default constructor
IMPORTANT: this new class must be configured as the implementation of the renderer so add its fully qualified class name into 
META-INF/services/org.kie.server.services.jbpm.ui.form.render.FormRenderer

There are several types of templates that renderer must provide (and load on startup)
  • master - main template that builds the HTML page
  • header - header template that creates header of the form
  • form-group - form input fields template
  • case-layout - layout for case forms
  • process-layout - layout for process forms
  • task-layout - layout for user task forms
  • table - table to be build for multi subforms
The easiest way is to base your customisation on top of the out of the box templates (either patternfly or bootstrap). In this example I will use bootstrap templates that can be found here.

Copy all resources from the linked directory into 
src/main/resources/form-templates-providers/custom

and then implement the loadTemplates method of the CustomFormRenderer class
package org.kie.server.samples;

import org.kie.server.services.jbpm.ui.form.render.AbstractFormRenderer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;


public class CustomFormRenderer extends AbstractFormRenderer {
    
    private static final Logger logger = LoggerFactory.getLogger(CustomFormRenderer.class);

    public CustomFormRenderer() {
        super(null,  null);
    }
    
    public CustomFormRenderer(String serverPath, String resources) {
        super(serverPath, resources);
    }
    
    public String getName() {
        return "custom";
    }

    @Override
    protected void loadTemplates() {
        loadTemplate(MASTER_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/master-template.html"));
        loadTemplate(PROCESS_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/process-layout-template.html"));
        loadTemplate(TASK_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/task-layout-template.html"));
        loadTemplate(FORM_GROUP_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/input-form-group-template.html"));
        loadTemplate(HEADER_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/header-template.html"));
        loadTemplate(CASE_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/case-layout-template.html"));
        loadTemplate(TABLE_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/table-template.html"));
        
        logger.info("Custom Form renderer templates loaded successfully.");
    }

}

Customise your templates

Since the templates where copied from another renderer we need to customise it, let's start with master template. Open it and replace ${serverPath}/bootstrap with ${serverPath}/custom  
This will ensure that our customised files will be loaded.

Make any additional changes to the master template as needed. I will just add custom text next to header.

Master template is the place where you can add additional scripts or stylesheets. There is main js file called kieserver-ui.js that provide all the logic required to manage and submit forms. It also includes validation, so in case you need extensions to that logic consider to create new file with your changes and replace the location of it to point to your new file.

Make additional customisation to other templates as needed.

Build and deploy renderer to KIE Server

Implementation is completed so now it's time to build the project and deploy to KIE Server.
  • Build the project with maven - mvn clean package
  • Deploy the project to KIE Server by coping the jar file to kie-server.war/WEB-INF/lib
Start the server and take advantage of your custom renderer by using following URL that works for one of the sample projects - Evaluation (make sure to deploy it before using the renderer).

http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/processes/evaluation/content?renderer=custom

http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/tasks/1/content?renderer=custom

As you can see new renderer is fully operational and customised to your needs.

That's it, you have now your custom form renderer. The sample described in this article can be found in GitHub.

2018/10/30

Business Process Driven Web Terminal - jBPM Business Apps Demo

In this jBPM Business Application demo we show how you can dynamically present your business process data to your users.


Demo sample


The demo app is a Websocket terminal app where you can enter in different commands and results of those commands are displayed back. Each command entered triggers our demo business process which uses the jBPM Business Rules task to evaluate the command and then passes it on to
the jBPM Exec workitem (or the OpenWeatherMap workitem if weather info is requested).


Business process used in demo

The demo shows off how results of business process execution can dynamically trigger updates of your app UI. It also shows the power of the jBPM Exec workitem which can come really handy in my business app situations.

For more details and a walkthrough of this demo app view the youtube video here:




2018/10/15

Launch of Business Applications

The time has come - Business Applications are here!!!


It's a great pleasure to announce that the Business Applications are now officially launched and ready for you to get started.

start.jbpm.org

Business application can be defined as an automated solution, built with selected frameworks and capabilities that implements business functions and/or business problems. Capabilities can be (among others):
  • persistence
  • messaging
  • transactions
  • business processes, 
  • business rules
  • planning solutions
Capabilities essentially define the features that your business application will be equipped with. Available options are:
  • Business automation covers features for process management, case management, decision management and optimisation. These will be by default configured in the service project of your business application. Although you can turn them off via configuration.
  • Decision management covers mainly decision and rules related features (backed by Drools project)
  • Business optimisation covers planning problems and solutions related features (backed by OptaPlanner project)

Business application is more of a logical grouping of individual services that represent certain business capabilities. Usually they are deployed separately and can also be versioned individually. Overall goal is that the complete business application will allow particular domain to achieve their business goals e.g. order management, accommodation management, etc.

Business application consists of various project types
  • data model - basic maven/jar project to keep the data structures
  • business assets - kjar project that can be easily imported into workbench for development
  • service - service project that will include chosen capabilities with all bits configured
Read more about business applications here


Get started now!

To get started with your first business application, just go to start.jbpm.org and generate your business application. This will provide you with a zip file that will consists of (selected) projects ready to run.

Once you have the application up and running have a look at documentation that provides detailed description about business applications and various options in terms of configuration and development.

Make sure to not miss the tutorials that are included in the official documentation... these are being constantly updated so more and more guides are on the way. Each release will introduce at least 2 new tutorials ... so stay tuned.



Samples and more

business-applications samples
Business application launch cannot be done without quite few examples that can give you some ideas on how to get going, to name just few (and again more are coming)
  • Driver pickup with IFTTT 
  • Dashboard app with Thymeleaf
  • IT Orders with tracking service built with Vert.x
  • Riot League of Legends
This business application GitHub organisation includes also source code for tutorials so make sure you visit it (and stay around for a bit as more will come).



Call for contribution and feedback

Last but not least, we would like to call out for contribution and feedback. Please give this approach a go and let us know what you think, what we could improve or share the ideas for business application you might have.

Reach out to us via standard channels such as mailing lists or IRC channel.

2018/10/12

jBPM Business Applications + IFTTT = Control everything!

Here is another jBPM Business Application demo which uses the IFTTT workitem handler to connect your business processes in your business applications with the IFTTT Service.

In this demo we present users with a simple form where they can enter in their info and the location where they are in order for someone to come pick them up:


Once the form is submitted our business process is started which passes this information to the IFTTT workitem handler that then calls an Applet on the IFTTT platform:


This applet takes in the address entered by our user and launches Google Maps on our phone showing us the directions where the user is and also sends us an SMS message showing this information as well.



The demo also shows how we can start a business process in your business application in HTML via the kie-server thymeleaf dialect.

The source code of the demo can be downloaded here.

Here is also a video with a walkthrough of this demo. Watch the whole video or skip to the end to see the demo actually working ;)



With the jBPM IFTTT Workitem you can do some really powerful things, connect your business processes with different devices for example. Hope this demo gives you some ideas on creating your own cool apps with jBPM Business Applications.

2018/10/11

Handle service exceptions via subprocess

Interacting with services as part of your business process (or in more general business automation) is a common requirement. Though we all know that services tend to fail from time to time and business automation solutions should be able to cope with that. A worth reading article was recently published by Donato Marrazzo and can be found here Reducing data inconsistencies with Red Hat Process Automation Manager

Described feature in this article was actually inspired by discussion with Donato so all credit goes to him!

BPMN2 has already a construct for similar thing - error boundary events that can be easily attached to service tasks to deal with exceptions and perform additional processing or decision taking. This approach has some drawbacks in more advanced scenarios

  • error handling needs to be done on individual task level
  • retry of the same service call needs to be done via process modelling - usually a loop
  • each error type needs to be handled separately and by that makes the process definition too verbose

The first point from the above list can be addressed by using even based subprocess that starts with error event but that still suffers from the two other points.

To address this an additional error handling is introduced (in jBPM version 7.13) that allows the work item handlers (that implement the logic responsible for service interaction) to throw special type of exception org.kie.api.runtime.process.ProcessWorkItemHandlerException

This exception requires three parameters
  • process id that should be created to deal with this exception
  • selected handling strategy to be applied when exception handling process is completed
  • root cause exception
When such exception is thrown from work item handler it triggers automatic error handling by starting subprocess instance with the definition identified by process id set on the exception. If the process is straight through (meaning does not have any wait states) service task that failed will apply the handling strategy directly, otherwise it puts the service task in a wait state until the subprocess instance is completed. Then the strategy is applied on the service task.

Supported strategies

There are four predefined strategies 
  • COMPLETE - it completes the service task with the variables from the completed subprocess instance - these variables will be given to the service task as output of the service interaction and thus mapped to main process instance variables
  • ABORT - it aborts the service task and moves on the process without setting any variables
  • RETRY - it retries the service task logic (calls the work item handler again) with variables from both the original service task parameters and the variables from subprocess instance - variables from subprocess instance overrides any variables of the same name
  • RETHROW - it simply throws the error back to the caller - this strategy should not be used with wait state subprocesses as it will simply rollback the transaction and thus the completion of the subprocess instance
With this feature service implementors (those who implement work item handlers) can simply decide how the exception should be handled and what strategy it should apply to the failing service tasks once the error was evaluated and fixed.

Out of the box handlers and exception handling

Three major out of the box work item handlers are equipped with this handling automatically as soon as they are created with process id to handle exception and strategy. This takes over the regular error handling that will be applied when RETHROW strategy is selected.

  • RESTWorkItemHandler
  • WebServiceWorkItemHandler
  • EmailWorkItemHandler

Sample registration for RESTWorkItemHandler via deployment descriptor would be

new org.jbpm.process.workitem.rest.RESTWorkItemHandler("username", "password", classLoader, "handlingProcessId", "handlingStrategy")

Look at available constructors of given handler class to see all possible options. Similar way email and Webservice handlers can be configured to handle the exceptions via subprocess.

Use cases

Here are few examples that could be implemented
  • report to administrator that service task failed - this would have to be via subprocess that has user task assigned to administrators 
  • use a timer based sub process to introduce some delay in retries
  • ask business users to provide the information in case system is down in time critical situations 
There can be many more use cases implemented by that and one of the most important things with this is it does not have to be modelled for each and every task that could fail. It is up to the service handler to instruct what and how should be done in case of errors.

In action...

A short screencast showing this in action, simple process with custom service task that has a work item handler that throws ProcessWorkItemHandlerException exception and starts user focused subprocess to provide expected values and then apply COMPLETE strategy.



Here is the complete sample repository shown in the above screencast.

Hopefully you will find this useful and that will allow you to better automate your business to avoid any repetitive actions ...

Visit jbpm.org to download latest version of the jBPM project

2018/10/09

jBPM Business Apps - dashboard demo



This is first part of the "What do after I generate my business app?" series where we show demos that are supposed to give you ideas on how to get started on your own to build really cool business apps.

In this demo we very quickly (seriously less than 20 lines of code) create a dashboard through which we can interact with business processes in our business app. You can follow the steps shown in the video below and get this up and running. 

Here are the links:

* Youtube Video:



* Kie Server Dialect project used in the video (note this location may change soon so look there for a link to the projects new home once its moved).

Happy jBPM Business App coding