piątek, 4 marca 2016

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.

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

  • 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)

  • http://localhost:8230/kie-server/services/rest/server/containers/hr/forms/tasks/123
  • GET
  • 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 
  • http://localhost:8230/kie-server/services/rest/server/containers/hr/images/processes/hiring
  • GET
  • 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 
  • http://localhost:8230/kie-server/services/rest/server/containers/hr/images/processes/instances/123
  • GET
  • 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. 

38 komentarzy:

  1. Excellent, thank you very much. this works for me.
    In this scenario, What would be the correct way to fill out the form? ¿Recovering process instance variables in another request?

  2. yes, you first need to get the variables (task as for process it supports only start form) and then combine both data - variables and form for presentation. Once the form is completed you will need to collect the values and send them over to kie server as REST call to complete a task.

  3. Hi,

    I'm planning to use this feature in my app.
    Is there away to evaluate field formulas given in properties like defaultValueFormula, formula, etc. using kie server api? I'll need this to render my forms.

    1. No, kie server only deliver the content and does not process it in any way. You have to execute the formula on client side once received from kie server

  4. Hi Maciej,
    first of all - it's a great blog with a lot of useful information, thanks for all posts here. For some time Im discovering jBPM and now KIE-server+wb (thanks to you ;-) ) and have one issue that I couldnt find answer for. Is it possbile to get from process definition on kie-server complete process definition with all items (like it is in bpmn2 file - all events, tasks, flows etc) ? I also tried to find corelation between process definition and repository path to bpmn2 model in KIE/JBPM-WB - without success.

    Thanks in advance for any help,
    Mikołaj Stefaniak

    1. thanks, glad you like it.

      unfortunately there is no out of the box way to get all nodes in process via kie server api. Though if you need that you can build an extension for kie server that will expose additional endpoint so you can retrieve that info.

      there is no correlation between project path and process definition. The only thing you could use for that is package name of the process to be the path in repository. But make sure this is properly set when creating the process definition. So then you can assume it's in: project-name/src/main/resources/package/process.bpmn2

    2. Thanks for reply. I found sth like below in kie-server-client QueryServicesClient to get all NodeInstances for a given process instance:
      queryClient.findNodeInstances(processInstanceId, 0, 10);

      That is cool but requires process to be started. Too bad it cant be fetched from process definition (same applies to svg image that can be fetched from instance only).
      This could be good for external app use case where user could browse deployed process definitions (with all process model details) and deciding weather to start them or not.

    3. BTW I also checked that in KIE-WB, when checking process definition it possible to display process model. WB opens popup with following url :


      Looks like it is using some Guvnor api (maybe guvnor asset mamagement) to get BPMN2 file used in exactly this process definition (filtering by deploymentID). This looks promising for my use case however I dont know (yet ;-)) how to repeat that in some kie-server extention for instnace.

      BR, Mikolaj

    4. findNodeInstance will only return already visited or active node instances and not all that exists in process definition. Process definition can be fetch without any active process instance, see the available endpoints for image resource.

    5. Thanks, you are right. Finally I decided to write server extension similar to jbpm-ui but serving bpmn2 diagram instead of an image.

      I also noticed interesting issue (maybe potential bug) in JBPM-WB : new processes are always created with package "org.jbpm".

      For instance I created new project (groupid=miko,artifactid=mikoservice) within new organizational unit and new repository. Next I created new process "MyProcess" (selected miko.mikoservice package in create dialog).
      Unfortunatelly package name for this process is always "org.jbpm". This is visible in WB UI in "Process Documentation" as well as in bpmn2 file - .

      Naturally when it comes to kjar, path to my process is "miko/mikoservice/MyProcess.bpmn2".

      As there is incosistency between actual package and path in jar versus package name in process definition there are issues in jbpm-ui kie-server extension.

      In org.kie.server.services.jbpm.ui.ImageServiceBase.java in getProcessImageAsBytes(..) :
      ProcessDefinition procDef getPackageName(..) always returns "org.jbpm". Meanwhile in kjar this process wont exist in org/jpbm/MyProcess.bpmn2". In a result diagram or svg image will be not found.

      I repeated process creation in WB many times and always had "org.jpbm" package. Either I missing sth or there is some bug.
      I Use version 6.4.0-FINAL.

    6. Small note : process package can be changed in WB in editor (properties of bpmn-diagram) but it doesnt change the fact that by default it is "org.jbpm". It should be value from selected package in create dialog or groupid+artifactid of actual project by default.

  5. Hi Maciej, how are you? If we model the process with Jboss Developer Studio, is there a way to get the process image with kie-server REST API? Or it only works if we model in business-central?

    1. at the moment only workbench is capable of generating svg format of the process diagram that can be then visualized by kie server. There are plans to build a utility so it could be used from standard maven build (over kie maven plugin) to include svg.

  6. Hi again Maciej! I'm trying to implement an environment with 2 kie-server instances. All my processes have async services invocations, so I understand that there are quartz jobs to manage them. I've created quartz tables in my schema but I didn't configure nothing about it. Do I have to do some quartz configuration to prevent "job stealing" within my instances?

    1. async jobs are not managed by quartz, only timers can use quartz. For async jobs jbpm executor is used and that is fully supported in cluster - just make sure all your instances use same data base and executor will do the rest - it uses pessimistic lock on given job to claim it before execution.

    2. Thanks for your answer Maciej. Async jobs are managed by job executor. I will do some tests with it (and probably ask you again about!!!).
      Talking about quartz to manage the timers. How are the timers managed if I didn't configure quartz in my HA environment?

      Thanks for your time!

    3. there are different timer service implementations - simplest in memory backed by thread pool so it's certainly not valid for cluster setup. Another one is quartz - so you simply configure quartz via properties file and point that property via org.quartz.properties system property (jvm). Last out of the box is ejb service based one, so if you run on JEE app server that has support for clustered ejb timer service you can use this one. The only thing you need to do is to make sure the jbpm-services-ejb-timer jar is on kie server class path.

      now default selection of timer service impl is as follows:
      - if ejb timer service is on class path and is found in JNDI then it is used
      - if quartz property is set then uses quartz
      - otherwise uses in memory timer service

    4. Hi Maciej! I've installed jbpm without configure nothing special, so I have to assume that my timers are working with "in memory timer service" and it's not a solution for a clustered environment. Am I right? So I have to decide to use quartz or ejb-timer, right?

    5. I'm seeing jbpm-services-ejb-timer jar in the kie-server webapp that I've installed in my jboss. How do I know if it's in JNDI or not?

      I promise that I have only 1245 more questions...

    6. since it's there and you run on JBoss then it means it's used as JBoss is JEE app server that provides ejb timer service

  7. Ten komentarz został usunięty przez autora.

    1. Hi Maciej, how is the way that the subform has to be managed by this new capability?

    2. it should work for subforms as well as far as I remember, they all are provided in single call. Do you run into any particular issue?

    3. Yes, if a form has a subform, the response is the next:


      and the response does not include input types and their properties

    4. as you can see we do process subforms and multi subforms https://github.com/droolsjbpm/droolsjbpm-integration/blob/master/kie-server-parent/kie-server-services/kie-server-services-jbpm-ui/src/main/java/org/kie/server/services/jbpm/ui/form/InMemoryFormProvider.java#L151 so it should work though maybe there is some edge case not covered. You'd have to provide reproducer for us to try it

  8. Quantum Technologies. Find out why we are Houston IT Service Provider. Never Overpay for IT Support again, Managed Services, Cloud Hosting, Server Support, Business IT Support and Business Support.

  9. Hi,

    I am getting the below error after following your steps,
    03:16:01,031 ERROR [org.kie.server.remote.rest.jbpm.ui.ImageResource] (http- Unexpected error during processing null: java.lang.NullPointerException
    at org.kie.server.services.jbpm.ui.img.ImageReference.getImageContent(ImageReference.java:34) [kie-server-services-jbpm-ui-6.4.0.Final-redhat-3.jar:6.4.0.Final-redhat-3]
    at org.kie.server.services.jbpm.ui.ImageServiceBase.getProcessImageAsBytes(ImageServiceBase.java:60) [kie-server-services-jbpm-ui-6.4.0.Final-redhat-3.jar:6.4.0.Final-redhat-3]
    at org.kie.server.services.jbpm.ui.ImageServiceBase.getActiveProcessImage(ImageServiceBase.java:90) [kie-server-services-jbpm-ui-6.4.0.Final-redhat-3.jar:6.4.0.Final-redhat-3]
    at org.kie.server.remote.rest.jbpm.ui.ImageResource.getProcessInstanceImage(ImageResource.java:83) [kie-server-rest-jbpm-ui-6.4.0.Final-redhat-3.jar:6.4.0.Final-redhat-3]
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) [rt.jar:1.8.0_101]
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) [rt.jar:1.8.0_101]
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [rt.jar:1.8.0_101]
    at java.lang.reflect.Method.invoke(Method.java:498) [rt.jar:1.8.0_101]
    at org.jboss.resteasy.core.MethodInjectorImpl.invoke(MethodInjectorImpl.java:168) [resteasy-jaxrs-2.3.15.Final-redhat-1.jar:]
    at org.jboss.resteasy.core.ResourceMethod.invokeOnTarget(ResourceMethod.java:269) [resteasy-jaxrs-2.3.15.Final-redhat-1.jar:]

  10. Thanks for the article on SVGs - very helpful!

    Question about rendering SVGs on a browser with 6.5-final:

    My browser automatically downloads the SVG instead of rendering on the page.
    For instance, the following url forces Chrome to download a file named "image" without .svg suffix:

    Chrome downloads file name "3" without ".svg" suffix

    I have tried the following in my html file:

    Curious how you got the SVG URLs to render nicely on the page?

    1. not sure what this can actually be - I suspect some http response headers that drive the browser decision how to render. One difference is that you use workbench rest api while this article talks about kie server instead. So you can compare both to see the difference in http response headers to figure out what it could be.

  11. I am trying to deploy kie-server.war file. Although it get's deployed but with following error:

    Caused by: java.lang.NoClassDefFoundError: Could not initialize class org.kie.server.controller.rest.ControllerUtils
    at org.kie.server.controller.rest.RestKieServerControllerImpl.connectKieServer(RestKieServerControllerImpl.java:56)
    at org.kie.workbench.common.screens.server.management.backend.runtime.KieServerControllerCDI$Proxy$_$$_WeldClientProxy.connectKieServer(Unknown Source)

    at sun.reflect.GeneratedMethodAccessor394.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.jboss.resteasy.core.MethodInjectorImpl.invoke(MethodInjectorImpl.java:139)
    at org.jboss.resteasy.core.ResourceMethodInvoker.invokeOnTarget(ResourceMethodInvoker.java:295)
    at org.jboss.resteasy.core.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:249)
    at org.jboss.resteasy.core.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:236)
    at org.jboss.resteasy.core.SynchronousDispatcher.invoke(SynchronousDispatcher.java:402)
    ... 62 more

    so i am not able to see the remote servers when created conainter

    any help


    1. what failed to deploy here is not kie server but workbench. looks like this is not complete stack trace but I'd recommend to remove .niogit (or move it somewhere else) folder and start the server again

    2. Able to resolve that issue. Yes it was on workbench, added 2 jars jackson-mapper-lgpl and jackson-xc into workbench solved this.


      so calling above url getting the following error:
      Cannot find runtime manager for task 53

    3. I am able to create container and can see the remote server. started the process.
      can see tasks in task list on workbench but none of the above call is working.

      every url is returning 404
      and there is no log on server except one line in my previous comment

    4. when i see tasks from workbench there is deployment units but with above calls deploymentsMap is empty in AbstractDeploymentServcie

    5. resolved it.

      Container name should be same as deployment ID.

      Ref: http://mswiderski.blogspot.com/2017/03/get-ready-for-jbpm-7-migrate-from-65-to.html

      " The name of the container is important as it must match the deployment id of the project deployed in workbench execution server"