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.
