czwartek, 17 września 2015

Unified KIE Execution Server - Part 4

Here we come with next part of the Unified KIE Execution Server blog series - this time Part 4 that introduces Client UI written in JavaScript - AngularJS.
This aims at illustrating how easy it is to built fully featured Client UI that interacts with KIE Execution Server through REST API.

KIE Execution Server has been designed from the very beginning to be lightweight and consumable with whatever technology you like. Obviously it has to run on Java but components that integrate with it can be written in any language. To demonstrate that it actually works I came up with very basic UI written in AngularJS that uses:

  • JSON as data format

So what can it do? Quite a lot to be honest - although those who are familiar with AngularJS will directly notice that I am not an expert in this area while looking at the code. Apologies for that, although this was not the intention to show best practice in building AngularJS applications but to show you how easy it is (as I managed to do so :)) to interact with KIE Execution Server.

Let's start with it then...


Installation is extremely  simple - just clone this repository where you find jbpm-angular-js module. This is the application that we'll be using for the demo. Once you have it locally 
  • copy app folder that exists in jbpm-angular-js into your wildfly installation:
          it should be co-located with kie-server.war
  • rename the folder from app to app.war
And that's it, your installation is complete.

NOTE: we did put that on the same server as KIE Execution Server to avoid any CORS releated issues that will come up when using JavaScript application that resides on different server than the back end application.

Now you can start the Wildfly server and (assuming you use configuration used in previous parts of this blog series) access the AngularJS application at: 

AngularJS logon screen for KIE Execution Server app
You'll be presented with very simple logon screen that asks (as usual) for user name and password and in addition to that for KIE Execution Server URL that will be used as our backend service. Here you can simply put:

Make sure to provide valid credentials (e.g kieserver/kieserver1!) that are known to KIE Execution Server to be properly authenticated.

Demo description

Let's try to make use of the application and backend KIE Execution Server to see how it works. Here are list of steps we are going to perform to illustrate capabilities of custom UI application:
  • look at available containers 
  • look at available process definitions
  • examine details of process definition we are going to start an instance of
  • start process instance with variables (both simple type and custom type)
  • examine process instance details
  • work with user tasks
    • list available user tasks for logged in user
    • examine details of selected task
    • claim task
    • start task
    • complete task with variables (complex type)
Following screenshot shows the process definition that we are going to use:

A very simple process that consists of two user tasks:
  • first 'Review and Register' is used for gathering data from assigned user
  • second 'Show details' is just for the demo purpose to illustrate that process variable was properly updated with data given in first task
This process has two process variables:
  • person - that is of type org.jbpm.test.Person and consists of following fields
    • name - String
    • address - String
    • age - Integer
    • registered - Boolean
  • note - String
While working with this process we are going to exchange data between client (JavaScript) and server (Java) and as data format we will use JSON.

An important note for this application - this is a vary basic and generic application so it requires to provide valid JSON values when working with variables. To give an example (or two...)

  • "my string" - for string type
  • 123 - for number type
  • {"one", "two", "three"} - for list of strings
  • {"Person":{"name":"john","age":25}} - for custom objects 
Custom objects requires identifier that KIE Execution Server can use when unmarshalling to proper type. This can be given in either way:
  • Simple class name = Person
  • Fully qualified class name = org.jbpm.test.Person
Both formats are supported, though FQCN is usually safer (in case of possible conflicts when there are more than one class with same simple name). That's not so common case therefore short/simple name might be used in most of the cases.

Before it can be actually used (as presented in below screencast) you need to deploy the container to kie server. Deploy sample project called kie-server-demo that you can find in this repository (simply clone it and build locally with maven or with (even better) KIE workbench) - see part 3 on how to deploy containers/projects


Here is screen cast demoing entire application working with described process. 

I'd like to encourage you to give it a try yourself and see how does it fit your needs. With this you can start building UI for KIE Execution Server in the preferred technology/language. It's has never be so simple :)

Comments and ideas for improvements more than welcome.

11 komentarzy:

  1. Cześć,
    Przeglądając twojego bloga widzę że jesteś osobą bardzo obeznaną w temacie jbpma. Od jakiegoś czasu próbuję stworzyć w javie program korzystający z RestApi który ma za zadanie odpalić zdalnie proces. Próbowalem już różnych tutoriali znalezionych w internecie ale to co zrobiłem nie dało mi zamierzonego efektu. Czy robiłeś kiedyś coś podobnego? Czy mógłbym liczyć na jakąś twoją podpowiedź, ewentualnie jakąś pomoc?


    1. here is a complete example how to invoke remotely process in kie server over REST api:

  2. Thanks for reply. In the bulid path i have two missing jar(Maven Dependencies), kie-internal-6.3.0-SNAPSHOT.jar and kie-server-client-6.3.0-SNAPSHOT.jar. i'm download form mvnrepository kie-server-client-6.3.0.jar and kie-internal-6.3.0.jar and add external jars but. im have errors in pom.xml Missing artifact org.kie:kie-internal:jar:6.3.0-SNAPSHOT and Missing artifact org.kie.server:kie-server-client:jar:6.3.0-SNAPSHOT.


    1. change them to latest final version - 6.5.0.Final

    2. Becouse i not found newest files in repository on disk c i use kie-internal 6.4.0 final and kie-service-klient 6.0.1 (folder kie-server-klient not working and have different files structure becouse i use path to service-client). Now i have no compilation errors but program still not working correctly.

      This is my console content:

      Exception in thread "main" java.lang.NoClassDefFoundError: org/optaplanner/core/api/score/buildin/simple/SimpleScore
      at org.kie.server.api.marshalling.jaxb.JaxbMarshaller.(
      at org.kie.server.api.marshalling.MarshallerFactory.getMarshaller(
      at org.kie.server.client.impl.AbstractKieServicesClientImpl.(
      at org.kie.server.client.impl.KieServicesClientImpl.(
      at org.kie.server.client.KieServicesFactory.newKieServicesClient(
      at org.jbpm.test.kieserver.KieExecutionServerClientTest.main(
      Caused by: java.lang.ClassNotFoundException: org.optaplanner.core.api.score.buildin.simple.SimpleScore
      at Source)
      at java.lang.ClassLoader.loadClass(Unknown Source)
      at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
      at java.lang.ClassLoader.loadClass(Unknown Source)
      ... 7 more

  3. I found line that is the reason of errors.
    KieServicesClient kieServicesClient = KieServicesFactory.newKieServicesClient(configuration);
    with this line program stops

  4. How can i query the server if i need the definition of the class Person ?

  5. Hi Maciej. This looks convincing, we are using the jbpm 6.1 in embedded mode in our web application. And definitely this would be very useful for us to separate it out to an execution server. However I see the following 3 features which are still lacking, do you guys have any plans for that or is it already there in some other form ?

    1) Option to develop rich/fancy and custom forms.
    We want to develop the html forms with branding,look and feel which fits to our project. Can we develop them externally (job of an UI developer) and re integrate back to process definition in workbench.

    2) How can we achieve user input validations which are performed on server side ? Meaning we would like to validate the user input by our own business logic by contacting some other web service or by contacting other DB.

    3) Can we persist the java objects used as process variables within process instance to external DB (other than JBPM DB ) ?

    1. >>>1) Option to develop rich/fancy and custom forms.
      >>>We want to develop the html forms with branding,look and feel which fits to our project. Can we develop them >>>externally (job of an UI developer) and re integrate back to process definition in workbench.

      take a look at this article that shows how you can use form content to render your own UI

      >>>2) How can we achieve user input validations which are performed on server side ? Meaning we would like to >>>validate the user input by our own business logic by contacting some other web service or by contacting >>>other DB.
      you would have to write your own kie server extension (see this article) to achieve that

      >>> 3) Can we persist the java objects used as process variables within process instance to external DB (other than JBPM DB ) ?
      of course you can see this

    2. Thanks for responding it very quickly...

      I will try out the answers for Question 1 and 2. Meanwhile can you please let me know how do I configure persistent strategy in KIE execution server(
      For question 3). I would like to have Process variables stored in Database-1 for Container-1 (kjar) and similarly would like to have the process variables
      stored in Database-2 for Container-2 (kjar). Is there any configuration file kind of thing which defines the persistence configurations for each
      container that I can drop in jboss application server without modifying the kie execution server ?

      I have looked into your blog for the configuration of persistence strategy but I believe it works if Iam using jBPM in embedded mode or If I have
      direct access to jBPM APIs.

    3. you can design your data object to be persistable see docs ( Generation of JPA enabled Data Models) then it's really up to your data source definition that is referenced from persistence.xml where that data will be stored. Make sure data source is XA so it can properly participate in transaction.

      this configuration can work in kie server without any issue.