Community extension to KIE Server - welcome Apache Thrift

In previous articles about KIE Server I described how it can be extended to bring in more features to it, starting with enhanced REST endpoints, through building addition transport layers, and finishing at building custom kie server client implementations.

It didn't take long and we got official confirmation that it works!!!

Maurice Betzel, has done excellent job and implemented KIE Server extensions that brings in Apache Thrift into the picture. That allowed him to bridge the gap between Java and PHP to make use of rule evaluation using KIE Server.

KIE Server with Apache Thrift

I'd like to encourage every one to look at detailed description about Maurice's work and take it for a spin to see how powerful it is.

All the credit goes to Maurice and I'd like to thank you as well for keeping me in the loop and verifying extensions mechanism of KIE Server in real life.

jBPM UI extension on KIE Server

KIE Server that was first released in 6.3.0.Final with jBPM capabilities (among others) was purely focused on execution. Though it was lacking part of functionality BPM users expects:

• process diagram visualization 
• process instance diagram visualization
• process and task forms information 

Since KIE Server is execution server thus it does not come with any UI and to be able to interact with it a custom UI needs to be built. Technology used to build such UI does not really matter and is left to developers to choose. Though certain parts should be possible to get out from KIE Server to improve the UI capabilities.

One of the most desired use case is to be able to visualize state of given process instance - including graphical annotations about which nodes are active and which are already completed, showing complete flow of the process instance.

This has been added to KIE Server as part of jBPM UI extensions and provides following capabilities:

• display process definition diagram as SVG
• display annotated process instance diagram as SVG
• greyed out are completed nodes
• marked as red are active nodes
• display structure of process forms
• display structure of task forms

While displaying process diagrams is self-explanatory, then operation around forms might be bit confusing. So let's go over them first to understand their usage. 

Primary authoring environment is KIE workbench where users can build various assets such as processes, rules, decision tables, data model and forms. Forms in workbench are built with Form Modeler that allows good integration with process and task variables providing binding between inputs and outputs - how data are taken out from process/task variable and displayed in the form and vice-versa how form data is put back to process variables.

Since KIE Server does not provide any UI it does not allow to render task nor process forms. It simply expect the data to be given that will be mapped (by name) to their process or task variables. While this is completely ok from execution point of view, it's not so great from UI and data collection stand point. So to ease a bit in this area, KIE Server is now capable to return form structure that can be used later on to render the form with whatever UI technology/framework you like.

Let's take a test drive of it. We will use our well known HR example to guide you through the usage of this UI support jBPM extension to KIE Server.

Form operations

First endpoint we are going to discuss is to get process form for given process definition - similar to what you get when you start a process instance in workbench.

Endpoint:

• http://localhost:8230/kie-server/services/rest/server/containers/hr/forms/processes/hiring

Method:

• GET

where:

• hr - is container id
• hiring - is process id

When you issue this request you'll get following response:

You can notice few important properties there:

• form/name - hiring-taskform - is the name of the form built in form modeler - you'll find it in workbench under "Form definitions" section in Project explorer
• form/field/name is the name of the first field on that form
• under field properties you can find lots of details and depending on your form design you'll see more or less data, though still important
• fieldName
• fieldRequired
• readonly
• inputBinding
• outputBinding

This form structure directly translates to what KIE workbench will render when you start hiring process

Similar thing can be done for task forms with slightly different endpoint url as it refers to tasks (already active tasks)

Endpoint:

• http://localhost:8230/kie-server/services/rest/server/containers/hr/forms/tasks/123

Method:

• GET

where:

• hr - is container id
• 123 - is task id

same content as in case of process forms are returned for tasks. You can notice that there are different data filled for different fields. Like some have inputBinding set some have outputBinding set. 

So this structure represents this form rendered by workbench:

So with this you can build a custom renderer that is based on same form structure that was designed in Form Modeler that comes with KIE workbench.

Note: In the above example the content is XML but by changing the Accept header to be application/json you'll get JSON content instead.

Image operations

There are two operations available - get "pure" process definition diagram or get annotated process instance diagram.

To get process diagram use following endpoint 

Endpoint:

• http://localhost:8230/kie-server/services/rest/server/containers/hr/images/processes/hiring

Method:

• GET

where:

• hr - is container id
• hiring - is process id

and this is what you'll get in your browser

To get annotated process instance, first of all you have to have process instance active and one you have its process instance id you can issue following 

Endpoint:

• http://localhost:8230/kie-server/services/rest/server/containers/hr/images/processes/instances/123

Method:

• GET

where:

• hr - is container id
• 123 - is process instance id

and you'll get this

Here you can see that start event is greyed out and thus means it was already completed and currently process instance is in HR Interview task.

Returned content for image operations are SVG - where its MIME type is: application/svg+xml

so make sure you have your client capable of displaying SVG content to properly display the diagrams. Note that all major browsers do support SVG and if you can display process diagram in KIE workbench with given browser you'll be fine.

Now, the most important configuration parameter to enable image operations. KIE workbench by default does not store SVG version of the process so that means such SVG will not be included in kjar and thus won't be available to KIE Server. To be able to take advantage of this feature you need to enable it in workbench configuration files.

Enable SVG on store in workbench

Edit file jbpm.xml that is stored in (depending on what installation you have):

• jbpm installer: 
• jbpm-console.war/org.kie.workbench.KIEWebapp/profiles/jbpm.xml
• manual installation 
• kie-wb{version-container}.war/org.kie.workbench.KIEWebapp/profiles/jbpm.xml
• Red Hat JBoss BPMS: 
• business-central.war/org.kie.workbench.KIEWebapp/profiles/jbpm.xml

in this file you need to find 

        <storesvgonsave enabled="false"/>

and set it to true

        <storesvgonsave enabled="true"/>

Once this enabled (re)start workbench and go to your process definition to save it again (any modification will be required) and that will trigger SVG file for that process to be generated and stored in kjar.

Then deploy that kjar to KIE Server and you can enjoy KIE Server shipping process images for your custom UI.

That's it for the jBPM UI extensions that is coming with 6.4.0.Final very soon so stay tuned. 

Are you ready to dive into (wildfly) swarm?

KIE Server is a lightweight execution server that comes with various capabilities where out of the box are following:

• BRM - rules execution (Drools)
• BPM - business process execution, task management, background jobs (jBPM)
• BPM-UI - visualize your bpm components on runtime such as process definition and instance (since 6.4)
• BRP - business resource planning (Optaplanner) (since 6.4)

It's by default packaged as JEE application (web archive) and deployed to various containers, such as:

• JBoss EAP
• Wildfly
• Tomcat
• WebLogic
• WebSphere

While all this is already quite nice coverage, we don't stay idle and do work on bringing more to you. Let's see what's coming next...

All the hype about micro service is bringing in tons of new stuff that allows alternative approach for packaging and deployment of our systems or services if you like. Taking into consideration what capabilities KIE Server comes with it would be a crime to not take advantage of it to start building micro services with it. Instead of rewriting all the stuff in different way.

It's time to introduce Wildfly Swarm (to those that haven't heard about it yet) ...

Swarm offers an innovative approach to packaging and running JavaEE applications by packaging them with just enough of the platform to "java -jar" your application

So what Wildfly Swarm means in context of KIE Server?

Actually it means a lot:

• first of all it allows us to build executable jars that will bring in KIE Server capabilities to simple java -jar way of working with all it's power!
• next you can have a "executable kjar" just by starting it with argument that identifies kjar to be available for execution (Group Artifact Version)
• you can still run in managed mode - connected to controller and managed from within controller but without a need to provision your application server

With this in mind let's take a look at how to use it with Wildfly Swarm.

• Clone this repository kie-server-swarm into your local environment.
• Build the project with maven (mvn clean package)
• Make sure you run it with latest Maven otherwise you might run into build errors - I tested it with 3.3.9 so it works certainly with it
• Once it's successfully build you'll find following file inside the target folder
• kie-server-swarm-1.0-swarm.jar
• Now you're ready to rock with KIE Server on Wildfly Swarm

but before we start our KIE Server on Swarm, let's look at what options we have for the project we just built. This project, same as KIE Server, is modularized and allows us to pick only the things we are interested with. While KIE Server allows to disable extensions on runtime (via system properties) sometimes it does not make sense to bring in lots of dependencies if they are not going to be used.

So you can build the project with following profiles:

• BRM - includes BRM capability of the KIE Server that allows rules execution only
• no server components besides REST is configured
• build it with - mvn clean package -PBRM
• BPM - includes both BRM and BPM capabilities of the KIE Server - this is the default profile
• configures Swarm to have transactions and data sources enabled
• build it with - mvn clean package -PBPM or mvn clean package

So why it's important to have it done as profiles? It's because the size of resulting file (executable jar) will be smaller. Moreover it reduces number of things Swarm is going to configure and boot when we start our system. So keep this in mind as it might become handy one day or another :)

Let's get our hands dirty with running KIE Server on Wildfly Swarm

First thing, let's just start empty server that will let us manage it manually - creating containers, running rules and processes via REST api

Make sure you're in the project folder (where you executed maven build) and then simply run this command:

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -Dswarm.port.offset=300 -jar target/kie-server-swarm-1.0-swarm.jar

Wait for a while to boot Wildfly Swarm and KIE Server on it. Once it's completed you should be able to access it at http://localhost:8380/server

NOTE: since KIE Server requires authentication, whenever you attempt to access its REST endpoints you need to logon - by default you should be able to logon with kieserver/kieserver1!
you can customize users and roles by editing following files:

kie-server-swarm/src/main/config/security/application-users.properties

kie-server-swarm/src/main/config/security/application-roles.properties

Now let's examine a bit what all these parameters mean:

•  -Dorg.kie.server.id=swarm-kie-server - specifies the unique identifier of the kie server - it is important when running in managed mode but good to use it always to make it a habit
• -Dorg.kie.server.location=http://localhost:8380/server - specifies the actual location where our KIE Server is going to be available - this must be a direct URL to actual instance even it if's behind load balancer - again important when running in managed mode
• -Dswarm.port.offset=300  - sets global port offset to avoid port conflicts when running many instances of wildfly on same machine

Next, let's run our first executable KJAR... to do so we just extend the command from first run and add arguments to the execution

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -jar target/kie-server-swarm-1.0-swarm.jar org.jbpm:HR:1.0

as you can see the only difference is:
org.jbpm:HR:1.0

which is GAV of a KJAR that is going to be deployed upon start of KIE Server on Swarm. So with just single command line we have fully functional server with BPM capabilities and HR project deployed to it.

Last but not least, let's run it in fully managed way - with controller.
Before you start wildfly Swarm with KIE Server, make sure you start controller (KIE workbench) so you'll see how nicely it registers automatically upon start.

Once controller (workbench) is running issue following command:

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller -jar target/kie-server-swarm-1.0-swarm.jar

Again, a singe parameter difference between the first command we used to start empty KIE Server on Swarm - in this case it's controller url:

• -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller

Make sure that this URL matches your controller being deployed - it can differer in terms of

• host (localhost in this case)
• port (8080 in this case)
• context root (kie-wb in this case)

Now you're ready to rock with Wildfly Swarm and KIE Server to build your own micro services backed by business knowledge.

Enjoy your dive into Swarm and as usual comments are more than welcome.