Service task repository integrated into Business Central

Service tasks (aka work items) are of tremendous use in business processes. Users can build their custom logic into well defined tasks that can be reused across processes or even projects. jBPM comes with rather large set of service tasks out of the box, you can explore them in jbpm-work-items repository in GitHub.

jBPM also provides standalone service repo that could be used from jBPM designer to import service tasks. Though that was just intermediate step towards better integration with authoring tooling – Business Central.

Brand new integration between service task repository and business central is under development and I’d like to share a bit of news about this upcoming feature…

Service Task administration

First and foremost there is global administration of service tasks. This allows to select what service tasks (that the authoring environment comes with) are allowed to be installed in projects.

There are three configuration options

  • Install as Maven artefact – will upload the jar file of the handler if it does not exist in the local or Business Central’s maven repo
  • Install service tasks artefact as maven dependency of project – will update pom.xml of project upon installation of the service task
  • Use version range – when adding service task artefact as project dependency it will use version range instead of fixed version e.g. [7.16,) instead of 7.16.0.Final

Service task installation – project settings

Once the service tasks are enabled they can be used within projects. Simply go into project settings page and install (or uninstall) service tasks of your desire. Note that this settings page will only list service tasks that are globally enabled.

Service tasks can then be installed into projects. During installation following will be done

  • dedicated wid (work definition) file is created for installed service task
  • custom icon for the service task is installed into project resources (if exists)
  • pom.xml of the project is updated to include dependencies (if it is enabled in the global settings)
  • deployment descriptor is updated to register work item handler for the service task
Similar steps are performed for uninstallation though to remove rather than add configuration.
Here is a short video (this time with audio.. not sure if that is good or bad …) that illustrates the entire feature working together, including use of service task in business process.


This is part one of this feature so stay tuned for more updates in coming weeks…

Here is a complete video showing all features in action including

  • service repository administration
  • uploading new service tasks
  • default service tasks (REST, Email, Decision, etc)
  • installing service tasks into project with prompt for required parameters

This feature is planned for 7.17 so all the feedback is more than welcome.

Using React as frontend for jBPM Business Apps

React is a very popular and powerful JavaScript framework and is currently one of the best frontend development frameworks out there.

In this demo we show how you can easily integrate React into your existing or new jBPM Business Application and consume data from the the out-of-the-box Rest services via React components.

React Demo 

As usual all the sources of this demo are on GitHub.
The demo integrates the React front-end app with the service module of your jBPM Business application via the frontend-maven-plugin and then bundles its resources in the generated business app jar. This way you can just start your business app with the provided launch scripts and both React frontend and your business app backend will be available and started together.

When building the demo the same plugin will also attempt to install node and npm (which are needed for React apps) if they are not available on your machine. It will also build the React frontend for you, so no need to build it separately.

Here is the youtube video for this demo:

Feel free to leave us any comments about this demo and ideas on how to improve it or what you would like to see next.

Building jBPM Business Applications with Gradle

 

By default jBPM Business Applications generated via start.jbpm.org are build with Apache Maven. Your generated apps also include build scripts (for Unix, OSX, and Windows) which you can use out of the box to build all the apps modules, as well as launch your app in normal or dev modes.

Using Maven is fine however it excludes Gradle users from being able to build and launch jBPM Business Applications using their favorite build tool.

If you are using Gradle, take a look at this GitHub repo which includes Gradle build files as well as build scripts that call Gradle to build and launch your business application.

Follow the documentation there to set up your Gradle build environment for your generated jBPM business app.

Note that the out-of-the-box Maven build scripts are still the preferred choice when building your app. This is because the limitation of the Gradle scripts not being able to deploy your app on Docker and Openshift. We use the fabric8 plugin to help us do that and this plugin is not currently available for Gradle unfortunately (you can get more info on that here).

Also to note we are not Gradle experts and it would be really helpful if our jBPM community could help us with making the Gradle build for jBPM Business Applications better. If you are interested please clone https://github.com/tsurdilo/jbpm-business-apps-gradle and submit changes via git pull requests and share it to our community. We would really appreciate that!!

jBPM Business Apps and Okta Single Sign-on (SSO)

Wanted to showcase a new jBPM Business Applications demo that includes easy
integration with the Okta identity management service.

The demo uses the developer.okta.com setup and the Okta Spring boot starter to quickly set up SSO for our jBPM Business App. It also shows how easy it is to restrict access to certain pages of your jBPM Business Application using the authentication info and identity setup in Okta.

Demo source code is on github.

The demo requires you to make an account on developer.okta.com (its free) and create an Okta application and set up two group called “Admin” and “Sales”

Okta group setup

Only other configuration is in the your apps application.properties file:

application.properties setup

All of this information you get for free once you create an account and an application on the Okta developer site.

Once you have completed this setup and start the Okta demo app, go to localhost:8090 and to authenticate and access your app. Note that since there is no logout feature in the demo app, in order to simulate the logout simply delete your recent browser cookies.
If you don’t create and set up the “Sales” group in Okta for your application there accessing localhost:8090/sales will give you a “403” page:
Demo app 403 page

Otherwise you will be able to access it:

Demo sales page

The apps index page is authorized to users that are in the “Admin” group that you have set up in Okta.

Here is a youtube video which walks you through the Okta demo and shows how simple it is to set 
this all up:

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!

Workbench is now Business Central!

5 years ago, on November 2013 we released 6.0.0.Final, that included the first version of the Workbench. It has been a long journey so far, but today we’re announcing that we’re retiring the Workbench brand and officially adopting Business Central as the new brand!

Historical Context

The KIE group has been developing web tooling for more than a decade now. The first public release that shipped a browser based tool was 5.0.1 (May of 2009), but its R&D started way before that.
Tip
KIE stands for Knowledge Is Everything, and it is pronounced exactly the word key in English: /kē/ .
The first experiments of a web-based tool to manage a central repository for business rules that provided an intuitive user interface to create and package rules started back in September 2006 as jbrms. After a couple of years, it was renamed to Guvnor, and this is the name that would become known as the official name of our first web tooling.
guvnor
Figure 1. Guvnor Guided Rule Editor User Interface.
The next generation that became known as Workbench started its R&D in May of 2012 with multiple goals and challenges that could be summarized in the following major two key points:
  • A modular, plug-in based, composable tooling, to avoid the single project/repo that Guvnor became over the years
  • A Virtual File System based storage, to avoid getting stuck with a technology like JCR
workbench
Figure 2. Workbench Original NSEW Compass Drag-and-Drop
If you’re feeling nostalgic, you can play this video, and get back to May of 2013, a few months before the release. But if you have time, and want to see how our fresh released second generation looked like in practice, you have a full playlist.

Evolution

The Workbench has been distributed in two flavors: KIE Drools Workbench and KIE Workbench. Initially, the KIE Workbench used to be shipped with an embedded jBPM engine, what made the distributions significantly different. However, with the KIE-Server release and the engine unification, the embedded jBPM engine was removed from Workbench, and the differences between the two distros became just a matter of show/hide some user interface items.
It’s also clear that the current Workbench has very little in common with its original format. Over the years it not only get more polished and stable, but the target audience has evolved from a developer focused to a collaborative platform between practitioners and developers.
Based on the above facts and also looking for a more concise branding strategy a decision was made: unify the distributions and re-brand it as Business Central!

Business Central

So what’s in the new name? The major positive impact is that we have now a single distribution and terminology to reference the KIE group web tooling, that also unifies the product and community terminology.
Here’s a quick walkthrough of the changes you’ll see in the new Business Central:
business-central

Profiles and Entitlements

By default Business Central bootstrap with all the features enabled, that includes Drools, OptaPlanner, and jBPM. However, for those that are not taking advantage of our jBPM engine, we provide in settings a Profiles option that allows admins to adjust Business Central to display only the relevant profile to your needs.
The default profile can be also be defined in the startup using the org.kie.workbench.profile environment variable with the following possible values:
  • FULL
  • PLANNER_AND_RULES
  • FORCE_FULL
  • FORCE_PLANNER_AND_RULES
The main difference between the “FORCE_” values is that it will hide the settings configuration, forcing the chosen profile.

Conclusion

After five years, the KIE group has decided that was time to retire the Workbench brand. Our web tooling evolved quite a lot and the use of the word Workbench, a common term for developers, didn’t reflect the current state of it.
The consolidation and re-branding to Business Central aims to provide a clear message about its targeted audience with a concise communication strategy. If you’re interested in giving it a try, Business Central is available to download today!

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.