Deploying jBPM Business Apps on Docker

jBPM Business Applications have an out-of-the-box configurations to deploy them as docker containers. We have created the video below to show you how easy it is to do that. The video also shows some useful docker commands to run after you have deployed your jBPM Business app as docker container. Enjoy.

jBPM Business Applications Demo - Process terminal using Spring Shell

So far our jBPM Business Applications demos have involved some sort of web-based UI for interacting with our business processes. Sometimes a web-ui is not needed and working with processes via an interactive terminal is the best way to get this done.

In this demo we show how to use Spring Shell inside your jBPM Business Application created via start.jbpm.org. Here is a quick screenshot of the demo application:

Demo schreenshot

We start our demo app as usual using the already provided launch scripts but once it starts we do not launch our browser and go to localhost:8090 (default) to access it, but instead we are presented with a prompt and can start typing in our commands to interact with our business processes.

Spring Shell provides some very useful commands out of the box, such as "help", "clear", "exit", "history", and "stacktrace". Our demo app defined ontop of that our own custom commands to interact with our business processes. 

Commands that we define in our business app demo are:

• deploy <groupId> <artifactId> <version>
• processdefs
• processinstances
• startprocess <processDefId> <deploymentId>

Our deploy command allows us to deploy a kjar module which is available in our local maven repository. The demo app comes with one such module which you can use to deploy after the application has started with the command:

The processdefs command simply shows all currently available process definition (across all deployments):

The startprocess command allows you to start a business process. It takes in the process definition id and the deployment unit id (if deployment unit id is not specified, the default one is assumed). So for example to start our "firstTestProcess" business process we can do:

Lastly, the processinstances command shows all process instances that are available, for example:

Finally here is a youtube video where we run the demo and show off all the commands. The video also explains the code and how to create custom commands using Spring Boot and Spring Shell.

(This is the first time I tried creating a youtube video intro so please don't laugh ....too much :) )

Hope this demo helps you guys get some ideas on how to create cool jBPM business apps.

Starting your jBPM Business Application as a Service

In addition to starting your jBPM Business Application generated via start.jbpm.org using the provided launch scripts, for example:

./launch.sh clean install for unix or launch.bat clean install for windows, you can also start and manage your business application as a service. This provides you with extra control of your app especially in production environments. 

Weather you are on Unix based system, Windows, or OSX the first step is to configure the business application to generate a fully executable jar. To do this locate your service module of your business app and modify its pom.xml to configure the spring-boot-maven-plugin as follows:

With this configuration building your business app will produce a fully executable jar. 

Now let's see how we can start the business app as a service under different operating systems.

1. Unix/Linux Service

Here we have two options, using init.d or systemd . 

a) To install our business app as an init.d service we need to create symlink to our executable jar, for example (using the default setup on start.jbpm.org):

sudo ln -s ~/business-application/business-application-service/target/

business-application-service-1.0.SNAPSHOT.jar 

/etc/init.d/business-application-service-1.0.SNAPSHOT.jar

after this you can start your business app with for example:

service business-application-service-1.0.SNAPSHOT.jar start

b) To install our business app as a systemd service we need to create a script called business-application-service-1.0.SNAPSHOT.service in the on-service-1.0.SNAPS directory (again we assume the default business app setup, the actual name has to reflect the real app name you have created during app creation on start.jbpm.org).  

The script could look as follows:

[Unit]

Description=business-application-service-1.0.SNAPSHOT

After=syslog.target

[Service]

User=business-application-service-1.0.SNAPSHOT

ExecStart=~/business-application/business-application-service/target/

business-application-service-1.0.SNAPSHOT.jar 

SuccessExitStatus=143

[Install]

WantedBy=multi-user.target

Don't forget to change the description, user and execstart parameters to match your installation.

Now we can tell systemd to start our business app on system boot with for example:

systemctl enable business-application-service-1.0.SNAPSHOT.service

2. Windows Service

You can start your business application as a Windows service using winsw command. For details on how to do this please read detailed instructions on https://github.com/snicoll/spring-boot-daemon.

3. OSX Service

If you are on OSX, you can use the launchctl command. To get started first we need to create our launch configuration under ~/Library/LaunchAgents directory. So let's create a launch config file called business-application-service-1.0.SNAPSHOT.plist which can look as follows (again, assuming the default generation settings):

With the launch config created log out with your current user and log back in. Your business application has been started and you can right away access it under locahost:8090 in your browser. 

You can manage your business app service at this point using the launchctl command. For example to stop our business app service we would run:

launchctl stop business-application-service-1.0-SNAPSHOT

and to stop our business application from being started automatically on system startup/login we can simply remove our launch configuration .plist file from ~/Library/LaunchAgents directory.

Hope this information is useful to some of you guys when choosing options on how to launch/deploy/manage your jBPM Business Applications.

Using Apache Kafka in your jBPM Business Application - Demo

Recently our jBPM community member Prasanth Nair was kind to contribute the Kafka workitem to our jBPM workitem repository. The contributed Kafka workitem includes a handler which uses the Kafka producer to send messages to a specified topic.

In this post we will show you a small demo using this Kafka workitem. As usual this demo is based on the jBPM business applications which you can easily generate on start.jbpm.org.

You can find the source of the demo and detailed descriptions on how to set it up and get it up and running on github.

The demo app uses a simple business process that retrieves current weather information from openweathermap.org and sends it to the Kafka workitem so that this info can be sent to a Kafka topic.

The business Spring Boot app uses the Spring-kafka integration and defines a Kafka consumer configuration as well as the Spring WebSocket support to setup a WebSocket config. Kafka messages that are consumed by our business app are then being broadcasted to a websocket endpoint and picked up by our UI (via sockjs and stomp). This way our UI can dynamically update the weather info display without any page refreshes needed.

Here is the definition of the demo business app Kafka consumer. Take a look at its consume method, which simply receives the Kafka message and sends it to a WebSocket endpoint, and here is the JavaScript setup which listens to the same WebSocket endpoint and updates the weather chart once new info is received.

Here is the demo walkthrough video where we explain the demo in detail, show the code, and run the demo.

Hope this demo gives you some ideas on how to create your own cool jBPM Business App using Apache Kafka.


Many thanks to Prasanth for his contribution!

Audit log mode applied to all audit data

jBPM allows to store so called audit logs in various modes

• JPA (default)
• JMS
• None

JPA mode means that data will be stored directly and within the same transaction as process execution. That usually have some additional performance overhead although it's certainly not significant and unless huge volume is expected is a sound default setting.

JMS mode means that all audit data will be stored in background and the engine will push all required data via JMS layer. That allows to offload main thread from being responsible for storing audit logs and then allow to process more process instances while JMS listener will deal with storing audit logs in background.

None mode means that audit logs won't be stored at all, which might make sense in some cases (usually straight through processes) so the audit data is not required. Keep in mind that with disabled audit logs (set to None mode) both jBPM console and Kie Server features are limited as they do rely on audit data.

Until 7.15 audit mode applied only to process related audit data and that consists of

• ProcessInstanceLog
• NodeInstanceLog
• VariableInstanceLog

it has been improved to cover all audit logs that span across processes, user tasks and cases. With that said it covers (in addition to listed above) following

• AuditTaskImpl
• TaskEvent
• TaskVariableImpl
• CaseFileDataLog
• CaseRoleAssignmentLog

BAMTaskSummary is not covered with audit mode except for NONE mode which also disables BAM logging.

Configuration

JPA and NONE mode do not require additional configuration and can be used directly after installation. JMS does need a bit of configuration to allow to take advantage of JMS layer.

This sample configuration assumes the runtime environment is based on WildFly (or EAP) as application server.

Enable JMS queue creation in kie-server-jms.xml

First you need to enable dedicated JMS queue for sending audit data through. To do so, go to  kie-server.war/META-INF and edit kie-server-jms.xml file. Locate the commended queue named KIE.SERVER.AUDIT and uncomment the entire queue configuration, it should look like

<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server name="default">
    <jms-destinations>

      <!-- Kie Server REQUEST queue -->
      <jms-queue name="KIE.SERVER.REQUEST">
        <entry name="queue/KIE.SERVER.REQUEST" />
        <entry name="java:jboss/exported/jms/queue/KIE.SERVER.REQUEST" />
      </jms-queue>

      <!-- Kie Server RESPONSE queue -->
      <jms-queue name="KIE.SERVER.RESPONSE">
        <entry name="queue/KIE.SERVER.RESPONSE" />
        <entry name="java:jboss/exported/jms/queue/KIE.SERVER.RESPONSE" />
      </jms-queue>

      <!-- Kie Server EXECUTOR queue -->
      <jms-queue name="KIE.SERVER.EXECUTOR">
        <entry name="queue/KIE.SERVER.EXECUTOR" />
      </jms-queue>

      <!-- JMS queue for signals -->
      <!-- enable when external signals are required -->
      <!--
      <jms-queue name="KIE.SERVER.SIGNAL.QUEUE">
        <entry name="queue/KIE.SERVER.SIGNAL" />
        <entry name="java:jboss/exported/jms/queue/KIE.SERVER.SIGNAL" />
      </jms-queue>
      -->

      <!-- JMS queue for audit -->
      <!-- enable when jms mode for audit is required -->
      <!---->
      <jms-queue name="KIE.SERVER.AUDIT">
        <entry name="queue/KIE.SERVER.AUDIT"/>
        <entry name="java:jboss/exported/jms/queue/KIE.SERVER.AUDIT"/>
      </jms-queue>

    </jms-destinations>
  </server>
</messaging-deployment>

Enable message listener in ejb-jar.xml

Next, go to kie-server.war/WEB-INF and edit ejb-jar.xml file. Locate  CompositeAsyncAuditLogReceiver and uncomment entire section for that message driven bean. Also uncomment the enterprise-beans tags for the document.
It should look like below

<ejb-jar id="ejb-jar_ID" version="3.1"
      xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                          http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd">


  <!---->
  <enterprise-beans>

  <!-- enable when external signals are required and queue and connection factory is defined
    <message-driven>
      <ejb-name>JMSSignalReceiver</ejb-name>
      <ejb-class>org.jbpm.process.workitem.jms.JMSSignalReceiver</ejb-class>
      <transaction-type>Bean</transaction-type>
      <activation-config>
        <activation-config-property>
          <activation-config-property-name>destinationType</activation-config-property-name>
          <activation-config-property-value>javax.jms.Queue</activation-config-property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>destination</activation-config-property-name>
          <activation-config-property-value>java:/queue/KIE.SERVER.SIGNAL</activation-config-property-value>
        </activation-config-property>
      </activation-config>
    </message-driven>
    -->

    <!-- enable when jms mode for audit is required and queue and connection factory is defined-->
    <message-driven>
      <ejb-name>CompositeAsyncAuditLogReceiver</ejb-name>
      <ejb-class>org.jbpm.kie.services.impl.CompositeAsyncAuditLogReceiver</ejb-class>
      <transaction-type>Container</transaction-type>
      <activation-config>
        <activation-config-property>
          <activation-config-property-name>destinationType</activation-config-property-name>
          <activation-config-property-value>javax.jms.Queue</activation-config-property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>destination</activation-config-property-name>
          <activation-config-property-value>java:/queue/KIE.SERVER.AUDIT</activation-config-property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>maxSession</activation-config-property-name>
          <activation-config-property-value>1</activation-config-property-value>
        </activation-config-property>
      </activation-config>
    </message-driven>

  <!---->
  </enterprise-beans>

</ejb-jar>

Configure JMS related config for audit logs

Lastly, go to kie-server.war/WEB-INF/classes and rename the wildfly-jbpm.audit.jms.properties to jbpm.audit.jms.properties

And that's all that is required to make use of JMS audit logging in jBPM. For other applications servers, make sure to create JMS queue (and then refer to it in ejb-jar.xml file) according to application server guides for JMS.

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.


A sample project with just camel logging the events can be found here.

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.

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:

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.

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.

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

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

Let's embed forms ... rendered by KIE Server

jBPM comes with rather sophisticated form modeller that allows to graphically build forms for processes and tasks. These forms can then be used to interact with process engine to start new instances or complete user tasks.

One of the biggest advantages of using forms built in workbench is that they share the same life cycle as your business assets (processes and user tasks). By that they are versioned exactly the same way - so if you have another version of a process that requires more information to start you simply create new version of the project and make changes to both process definition and form. Once deployed you can start different versions of the process using dedicated forms.

Although to be able to take advantage of these forms users have to be logged into workbench as the only way to render the content is ... through workbench itself. These days are now over ... KIE Server provides pluggable renderers for forms created in workbench. That means you can solely interact with kie server to perform all the needed operations. So what does this brings:

• renders process forms - used to start new instances
• renders case forms - used to start new case instances - includes both data and role assignments
• renders user task forms - used to interact with user tasks - includes life cycle operations

Worth noting is that rendered forms are fully operational, meaning they come with buttons to perform all the operations that are based on the context - e.g. if user task is in in progress state there are buttons to stop, release, save and complete.

Here are few screenshots on how the forms look like, these are taken from the sample projects that come out of the box with jBPM distribution

Evaluation start process form

Mortgage start process form

IT Orders start case form

As it was mentioned, form renderers are pluggable and out of the box there are two implementations

• based on PatternFly - this is the default renderer that keeps the look and feel consistent with workbench
• based on Bootstrap

Renderers can be switched per each form rendering request by simply appending query parameter

?renderer=patternfly or ?renderer=boostrap if not given patternfly is the default one.

Here are few examples of the REST endpoints that illustrate how to get these forms rendered

http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/processes/evaluation/content
http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/tasks/1/content


http://localhost:8080/kie-server/services/rest/server/containers/mortgage-process/forms/processes/Mortgage_Process.MortgageApprovalProcess/content
http://localhost:8080/kie-server/services/rest/server/containers/mortgage-process/forms/tasks/2/content


http://localhost:8080/kie-server/services/rest/server/containers/itorders/forms/cases/itorders.orderhardware/content
http://localhost:8080/kie-server/services/rest/server/containers/itorders/forms/tasks/3/content

Note that containers are given as alias so that brings in additional benefits when working with forms and multiple project versions.

And at the end few short screen casts showing this feature in action

Evaluation process

Mortgage process

IT Orders case

Multi Sub Form - dealing with list of items in forms

More technical information will be provided in the next article as this one is just a quick preview of what's coming. Hope you like it and don't forget to provide feedback!

Business Applications by jBPM - League of Legends Stats Demo

A lot of our development focus recently has been around business applications, specifically rapid creation/development of business apps that include the full power of jBPM, are easily deployable to the cloud, and are fun and easy to work with.
We are at a point currently where we can start showcasing our work and what better way than with a demo.

This demo shows off the power of business app generation with jBPM and shows how easy it is to then extend it to create a unique and fun app for your users/customers.


The youtube video for the demo can be found here (or click on the image below).

Feel free to leave any comments/questions/ideas on the video itself or here if you like. The video shows how we generated the business app with start.jbpm.org, extend it and gives alot of good info on how to get up and running with all this.

And also here are some important links to get you started:

• Generate your business app - start.jbpm.org
• Read more about business apps and jBPM in docs.
• Demo app source code and install instructions.

And some images of the demo app that you can build easily yourself:

Demo app - Summoner Search

Demo app - Match Results

Let us know what you think. A lot more info about this is coming your way so stay tuned and have fun generating your business apps!

jBPM Workitems Spotlight - GitHub and Slack

So far we have posted a number of articles describing the jBPM Workitem Repository and its features but there was little mention about its actual content and the powerful integration capabilities it brings to your business processes.

Currently the workitem repository includes 25 different workitem groups and a total of 57 individual workitem handlers. These include various integration services with Google,  Dropbox, IBM, Twitter and many more. New workitems can easily be added as was described in this previous article.  Given that the number of workitems in growing at a steady pace we thought to start showcasing them with simple working examples that you can take and use to start implementing your custom integration solutions.

In this article we will focus on two workitem groups, namely GitHub and Slack:

For our simple example to showcase these workitems we will create a business process which fetches all open issues from one of your GitHub repositories, accumulate them into a message and then send this message to a specified channel on Slack notifying you of these open issues and give you simple links to each so you can start addressing them.

First let's look at the pre-requisites for each of the workitems. To start using GitHub workitems the required information is your login data, namely your username and password. For this example we will use the FetchIssuesWorkitemHandler where you will also need to know the name of the repository where you want to fetch the issues from.

To start using the Slack workitem handlers you need to first create a Slack App. Follow this link to get started with that. Once you create your app make sure to enable OAuth so Slack will create an access token for it. This access token is then passed to the workitem handler as it needs it for authentication with the Slack service. The workitem handler we will use here is PostMessageToChannelWorkitemHandler which also needs the name of one of the channels your slack app has access posting messages to.

To follow this example we also assume that you have the KIE workbench+server set up and ready but if you don't you can follow this article to do that literally in minutes. We also assume that you have an existing GitHub repository set up with some real or test issues defined. If you don't you could use this test one. 

Test GitHub repo with some test issues

With our KIE worbench running log in and create a new project. Within this project create a new business process (with legacy editor as it's currently only one capable of installing workitems from a repository).  Click on the repository icon in the process editor menu bar and connect to your running service repository

Installing workitems from workbench legacy bpmn2 editor

Find the two workitem handlers we mentioned earlier, namely FetchIssuesWorkitemHandler and PostMessageToChannelWorkitemHandler and click on the little wrench icon next to each to install them into your workbench. Note that the install also updates your project pom with all necessary maven dependencies to execute these workitems as well as your projects deployment descriptor xml. 

To finish the setup we do need to edit the projects deployment descriptor slightly, passing in our login information to the github workitem as well as the Slack access token created to the slack workitem so they can authenticate with their respective services correctly:

For this in the project explorer navigate to your projects /src/main/resources/META-INF directory and edit the kie-deployment-descriptor.xml file. Note that under the work-item-handlers element in this xml file the workitem installer has already added the definitions of two workitem handlers we want to use, however it needs to be slightly changed to add the sensitive info we talked about:

So for the GitHub handler we need to add:

<identifier>new org.jbpm.process.workitem.github.FetchIssuesWorkitemHandler("YOUR_GITHUB_LOGIN_NAME", "YOUR_GITHUB_LOGIN_PASSWORD")</identifier>

and for the Slack handler:

<identifier>new org.jbpm.process.workitem.slack.PostMessageToChannelWorkitemHandler("YOUR_SLACK_APP_ACCESS_TOKEN")</identifier>

Note that in the image below I have cut off the sensitive info as I used my personal login information when making the demo

Modifying the kie deployment descriptor

            

Now we should be all set up to create our business process. You can download or import the one used in this example from this Gist.

Our test business process

The example process first fetches all open issues from our testrepo GitHub repository. This list is then saved in a process variable which the script task iterates to create a message. The created message is then used by the Slack workitem to connect to your defined channel and create a new post to it.

You can now build and deploy your worbench process and start and instance of our example process

Starting new instance of the example process

Process instance completed info panel

Once the process has completed execution you should see in your Slack channel the result message:

And that's it :) Let us know what other workitems you would like to see featured next.