jBPM Work Items repository tips + tricks

In his previous post, Maciej showcased the updates to the jBPM Work Items module and how easy it is now to get up and running with creating new workitems and start using them in your business processes right away.

In this post I wanted to leverage on what Maciej showed and add a couple of cool features that the jBPM Work Item repository gives you out of the box, specifically related to the repository content generation.

1. Skinning
By default the work item repository generates static content including all workitem info, documentation and download links. Here is what they look like out of the box:

1. Default repository index page

2. Default workitem documentation page

Using the default look/feel is fine, but there are cases you might want to change it to fit your company/business better by changing the colors, adding your logo, or even completely change the layout of these pages and here is how you can do it. 

The jBPM work items module includes a sub-module called template-resources. In this module you can find all related templates that are used to build your final repository content. Lets take a look at these files to find out what each dose:

a) repoheader.html and repofooter.html - responsible for the top and bottom part of your repository index page. You can change these to for example define different page colors, add your logo to it, etc. Whatever you feel like. 

b) repoindex.part- defines each workitem information (each table row on the repository index page). You can change this to change the display for each of your workitems, add/remove download links etc.

c) indextemplate.st - this is a StringTemplate file that is used by each workitem module to generate its documentation page. Again you have free reign to change the look/feel of your workitem documentation as you wish.

With little knowledge of html (and power of jQuery and Boostrap that are built in) you can customize your workitem repository, for example (I'm not a designer btw :):

3) "Skinned" workitem repository index page

2. Excluding workitems from generated repository content

By default all workitems in the jBPM work items module will be displayed in the generated repository. You may not want to expose all of the available ones to your clients and can control which ones you wish to expose via the repository Maven assembly descriptor.

Here in the dependencySet section you can define excludes on the workitems you do not wish to display. Let's say you do not want to show the Archive and Dropbox workitems, you would do:

<excludes>
  <exclude>${project.groupId}:repository-springboot</exclude>
  <exclude>${project.groupId}:archive-workitem</exclude>
  <exclude>${project.groupId}:dropbox-workitem</exclude>
</excludes>

and those will not show up in the generated repository content any more. 



3. Generating additional download content using workitem handler information

By default each workitem in the repository might have one or more handler implementations. Each handler describes itself via the @Wid annotation, here is an example handler for sending Twitter messages.  During compilation step of your handlers repository gathers the info from this annotations and uses it to generate the workitem defintion configuration, the json config, the deployment descriptor xml, etc etc. You may want to generate additional configuration files that currently do not exist. 

This can be configured in the main project's pom.xml file. Here you can add more or remove existing config files generated from the annotation information in your workitem handlers.



I hope this info will be of some help to you guys. As always if there are any questions or if you have ideas on how to further enhance the workitem repository feel free to ask. 

jBPM Work Items are really simple!

Work items are the way to build custom (domain specific) services that can be used from within a process. They are as any other activity in the process with the difference that they are usually focused on given domain or area.

Work Items are by default placed under Service Tasks category on the palette so can be easily drag and dropped into the canvas when designing processes and cases. Location on the palette is also configurable via category property of the work item definition. So let's have a guided tour on how to create a very simple but functional work item.

The complete process consists of following steps:

• generating maven project for work item (both definition and handler)
• implementing handler and configuring work item
• optionally provide custom icon (16x16)
• add work item project into service repository
• import work item into project in workbench

Let's get our hands dirty and implement simple work item and then use it in a process.

Generate work item maven project

First step is to generate maven project that will be our base for:

• work item definition
• work item handler

First things first, what is work item definition and what is work item handler?

Work Item definition is a description of the work to be done. That is usually described by unique name, description, to make it more visible on the diagram - an icon and then what is expected at the entry (data inputs - parameters) and what is expected at the exit (data output - results).

Work Item handler is a logic that will be actually executed when given activity (representing work item) will be triggered as part of the process instance execution. 

Work Item is then a runtime representation of the Work Item definition that is backed by Work Item handler that is registered in the process engine via Work Item name. This registration gives users additional flexibility to allow usage of different logic to be executed depending where the process is executed - test vs production environment.

So to generate a maven project use maven archetype

mvn archetype:generate \
-DarchetypeGroupId=org.jbpm \
-DarchetypeArtifactId=jbpm-workitems-archetype \
-DarchetypeVersion=7.8.0-SNAPSHOT \
-DgroupId=org.jbpm.contrib \
-DartifactId=custom-workitem \
-DclassPrefix=Custom \
-Dversion=7.8.0-SNAPSHOT \
-DarchetypeCatalog=local

This command will generate a new project with:

• groupId - org.jbpm.contrib
• artifactId - custom-workitem
• version - 7.8.0-SNAPSHOT
• with work item configuration and handler class custom-workitem/src/main/java/org/jbpm/contrib/CustomWorkItemHandler.java

I'd like to recommend to generate this project as part of the official jbpm-work-items repository to benefit from service repository included in there. The rest of the article will assume this has been done. 
If you haven't done it yet, follow these:

• clone github project: https://github.com/kiegroup/jbpm-work-items
• go into jbpm-work-items
• check the version number of the cloned project and adjust version argument accordingly in the maven archetype:generate command

Once the project is generated, import it into your IDE and implement the handler - CustomWorkItemHandler.java. You might need to add additional dependencies to your project, depending your the implementation - when doing so please keep following in mind:

• dependencies that are already included in KIE Server - mark them as provided
• check for any conflicts with application server, KIE Server and your app dependencies and resolve them - either by adjusting your handler project dependencies or runtime environment

CustomWorkItemHandler.java class consists of @Wid annotation that is actually responsible for configuring your work item definition. It allows you to define (to name just few):

• name
• description
• category
• icon
• input parameters
• results
• handler

Most of the important parts are already generated for you, so examine them and check for correctness. Most likely parameters and results will be the one most often changed when implementing handlers.

Once that is done, proceed with implementation of the executeWorkItem method which is the heart of your custom work item.

Expose your work item in Service Repository

Now to take advantage of repository generation of jbpm-work-items project you need to add your newly generated project into two pom files:

• main pom.xml file of jbpm-work-items project - one regular and one zip dependency

<dependency>
        <groupId>org.jbpm.contrib</groupId>
        <artifactId>custom-workitem</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>org.jbpm.contrib</groupId>
        <artifactId>custom-workitem</artifactId>
        <version>${project.version}</version>
        <type>zip</type>
      </dependency>

• repository/pom.xml - only zip dependency (but this time without the version tag)

<dependency>
      <groupId>org.jbpm.contrib</groupId>
      <artifactId>custom-workitem</artifactId>
      <type>zip</type>
    </dependency>

When you're finished just build the project (assuming you're in jbpm-work-items repository) use following:

mvn clean install -DskipTests -rf :custom-workitem

this will then build your project (custom-work item - adjust it if the artifactId is different) and repositories. Then if you start SpringBoot based Service Repository

java -jar repository-springboot/target/repository-springboot-7.8.0-SNAPSHOT.jar

you'll have your work item available there, just go to http://localhost:8090/repository

And that's it, you have your work item implemented, built and exposed via Service Repository!!!

Use work item in workbench

To make use of your newly created work item, login to workbench and:

• create project
• create asset - Business Process
• use the yellow repository icon in the designer menu to open service repository browser
• select work item and install it
• reopen process editor and you'll find your installed work item under Service Tasks category (unless you changed the category when implementing work item)

That's all you need, in the background when the work item was installed your project was modified to add:

• dependency to your work item jar (as maven dependency of your workbench's project)
• deployment descriptor to register work item handler 

So now you're ready to launch it - just build and deploy your project in workbench and enjoy your work item being executed.

All this in single screen cast can be found below

Data set editor for KIE Server custom queries

Custom queries feature in KIE Server has been out for quite a while and proved to be very useful. Although there was no integration with workbench to take advantage of when:

• working with subset of data from various tables that are not exposed via runtime views (processes or tasks)
• building data set entries for reporting purpose
• building dashboards

With version 7.8, jBPM is now equipped with data set editor for KIE Server custom queries, it allows users to:

• define (as data set) and test queries on remote KIE Servers
• save and edit existing data sets 
• use defined data sets when building dashboards via Pages feature of workbench

Moreover, data set editor for KIE Server queries is built in a way that it ensures that queries are always send to all known kie servers when using managed mode. New KIE Servers connecting to controller (workbench) will also receive custom queries defined via data set editor.

See all this in action in short screencast

As usual, comments are more than welcome