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:

  • REST API
  • 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

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:
          WILDFLY_HOME/standalone/deployments
          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

Demo


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.

27 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?

    Pozdrawiam

    OdpowiedzUsuń
    Odpowiedzi
    1. here is a complete example how to invoke remotely process in kie server over REST api:
      https://github.com/mswiderski/jbpm-examples/blob/master/kie-server-test/src/main/java/org/jbpm/test/kieserver/KieExecutionServerClientTest.java

      Usuń
  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.

    Regards

    OdpowiedzUsuń
    Odpowiedzi
    1. change them to latest final version - 6.5.0.Final

      Usuń
    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.(JaxbMarshaller.java:114)
      at org.kie.server.api.marshalling.BaseMarshallerBuilder.build(BaseMarshallerBuilder.java:40)
      at org.kie.server.api.marshalling.MarshallerFactory.getMarshaller(MarshallerFactory.java:52)
      at org.kie.server.client.impl.AbstractKieServicesClientImpl.(AbstractKieServicesClientImpl.java:76)
      at org.kie.server.client.impl.KieServicesClientImpl.(KieServicesClientImpl.java:70)
      at org.kie.server.client.KieServicesFactory.newKieServicesClient(KieServicesFactory.java:101)
      at org.jbpm.test.kieserver.KieExecutionServerClientTest.main(KieExecutionServerClientTest.java:46)
      Caused by: java.lang.ClassNotFoundException: org.optaplanner.core.api.score.buildin.simple.SimpleScore
      at java.net.URLClassLoader.findClass(Unknown 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

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

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

    OdpowiedzUsuń
  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 ) ?

    OdpowiedzUsuń
    Odpowiedzi
    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 http://mswiderski.blogspot.com/2016/03/jbpm-ui-extension-on-kie-server.html

      >>>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 http://mswiderski.blogspot.com/2015/12/kie-server-extend-existing-server.html

      >>> 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 http://mswiderski.blogspot.com/2014/02/jbpm-6-store-your-process-variables.html

      Usuń
    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.

      Usuń
    3. you can design your data object to be persistable see docs (25.3.2.5. 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.

      Usuń
  6. Hi Maciej,
    Many thanks for this article, it helped me to understand how to use rest api Calls.
    I used app with version 7.1.
    After i press New to create process instance i got submit button Only and when press submit the process start.
    Even when i press Details to view variables the page didn't show the variables (the response contain the variables but the page didn't print the variables ).
    thanks

    OdpowiedzUsuń
  7. HI Maciej Swiderski,

    I was trying to build UI using AngularJs and integrate with JBPM so i have downloaded the jbpm-angular-js module and copy the app.war in parallel to kie-server.war and started the server.

    with localhost:8080/app it is showing 404-pagenot found but other endpoints i.e. process defination/querying the containers are working fine. Can you please let me know what could be the reason of showing 404

    OdpowiedzUsuń
    Odpowiedzi
    1. difficult to say but maybe the app was simply not deployed - make sure you have the app.war.dodeploy marker file next to it

      Usuń
  8. Hi Maciej

    Thank you for your quick response....after adding dodeploy I am able to hit app.war

    OdpowiedzUsuń
  9. Hi Maciej

    I am running the angularjs App application and backend side using registerperson bpmn process. While submitting person details in text area as JSon getting following error

    [org.kie.server.remote.rest.jbpm.ProcessResource] (default task-38) Unexpected error during processing No enum constant org.kie.server.api.marshalling.MarshallingFormat.application/json;charset=UTF-8: java.lang.IllegalArgumentException: No enum constant org.kie.server.api.marshalling.MarshallingFormat.application/json;charset=UTF-8
    at java.lang.Enum.valueOf(Enum.java:238)



    Please let me know your input/suggestion on how to resolve the issue

    Regards
    Nilesh

    OdpowiedzUsuń
    Odpowiedzi
    1. Hi Maciej

      I was able to find the issue it seems it got fixed in new versions jar. Moved to next step now I clicking on Task link in app application getting following error

      14:39:17,553 INFO [org.jbpm.services.task.identity.adapter.WebSphereUserGroupAdapter] (default task-30) Unable to look up UserRegistry in JNDI under key 'UserRegistry', disabling websphere adapter
      14:39:17,554 INFO [org.jbpm.services.task.identity.adapter.WeblogicUserGroupAdapter] (default task-30) Unable to find weblogic.security.Security, disabling weblogic adapter


      Usuń
    2. this is just info as you're not running on WAS or WLS

      Usuń
  10. Hi Maciej,

    When I am clclicked on Task link on top nothing is showing up and hence I am not able to update/modified the initial request that I was submitted.


    How to get the task details . I was only seeing above info

    Regards

    OdpowiedzUsuń
  11. Hi Maciej,

    When I am querying the rest endpoint for task I am getting task summary as empty. Even my task has taskname and also has group not sure why it is not showing created /ready task in page.

    Please provide your input/suggestion

    Regards
    Nilesh

    OdpowiedzUsuń
    Odpowiedzi
    1. most likely you are not eligible for this task - you (user that is logged in) don't have access to task meaning you are not potential owner of the task

      Usuń
  12. Hi Maciej

    I am logged in through kieserver as user. In app example it is not assigned any actor in so what I am missing. Please provide me your input

    I wanted to run the app and backed application end to end as given in the the example

    Regards
    Nilesh

    OdpowiedzUsuń
  13. Hi Maciej

    After going through blogs , I was added HR group to user kieserver but still task summary is empty. Also when in details page the initiator coming as "UnKnown". Please help me to get it work end to end.

    Regards
    Nilesh

    OdpowiedzUsuń
  14. Hi Maciej

    Do you have any suggestion to get it resolved?

    Regards
    Nilesh

    OdpowiedzUsuń
    Odpowiedzi
    1. Hi Maciej

      Sorry my question on how resolve task summary issue? I was added user with role and group by running the add user bat command.

      Regards
      Nilesh

      Usuń
  15. Hi Maciej,

    Following steps are done for UserGroup Callback and UserInfo

    - Created Custom Class for both UserGroupCallbackImpl and UserInfoImpl to fetch/validate user/group details from the Database.
    - Also added following properties
    org.jbpm.ht.callback=custom
    org.jbpm.ht.custom.callback=com.nav.usergroup.CustomDBUserGroupCallbackImpl
    org.jbpm.ht.userinfo=custom
    org.jbpm.ht.custom.userinfo=com.nav.usergroup.CustomDBUserInfoImpl

    - But when i start the task from rest getting following exception

    ...../containers/evaluation_2.0/tasks/641/states/started?user=kieworkbench


    org.jbpm.services.task.exception.PermissionDeniedException: User '[UserImpl:'unknown']' was unable to execute operation 'Start' on task id 641 due to a no 'current status' match
    at org.jbpm.services.task.internals.lifecycle.MVELLifeCycleManager.evalCommand(MVELLifeCycleManager.java:161) ~[jbpm-human-task-core-7.1.0.Final.jar:7.1.0.Final]

    When i debug the code, identityProvider.getName() [org.kie.server.services.jbpm.UserTaskServiceBase] is giving "unknown"

    Could you please help in resolving the issue

    Thanks & Regards
    Naveen D

    OdpowiedzUsuń
    Odpowiedzi
    1. looks like an issue with authorisation. what app server do you use?

      Usuń