Creating custom Work Item Handler in BPM Suite/jBPM 6

Hi all! In this post I am going to share my experience creating a work item handler for BPM Suite 6.0.3 (which is very similar to jbpm as explained in a previous post).

The Hello World Work Item Handler

Let's create a really simple WorkItemHandler just to print "Hello World" in the console. Of course you can implement more feature and make it receive parameters, access database, web services, etc. But in this post we will keep it simple. Really simple.

First thing to do is to create a maven project for my WorkItemHandler. Here's the pom.xml of my Maven project:

	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.jugvale.jbpm.workitemhandler</groupId>
	<artifactId>hello-workitemhandler</artifactId>
	<version>1.0</version>
	<name>Hello WorlItemHandler</name>
	<description>The simples WorkItemHandler for jbpm 6</description>
	<dependencies>
	<dependency>
	<groupId>org.jbpm</groupId>
	<artifactId>jbpm-flow</artifactId>
	<version>6.0.1.Final</version>
	<scope>provided</scope>
	</dependency>
	</dependencies>
	</project>

view raw pom.xml hosted with ❤ by GitHub

Notice that we are importing jbpm dependency so we can find the java interface that is used to create work item handlers.

Now we can start coding. Let's create a class name HelloWorkItemHandler in package org.jugvale.jbpm, here is the simple code:

	import org.drools.core.process.instance.WorkItemHandler;
	import org.kie.api.runtime.process.WorkItem;
	import org.kie.api.runtime.process.WorkItemManager;
	public class HelloWorkItemHandler implements WorkItemHandler {
	public void abortWorkItem(WorkItem wi, WorkItemManager wim) {
	System.out.println("Oh no, my item aborted..");
	}
	public void executeWorkItem(WorkItem wi, WorkItemManager wim) {
	System.out.println("Hello World!");
	wim.completeWorkItem(wi.getId(), null);
	}
	}

view raw HelloWorkItemHandler.java hosted with ❤ by GitHub

Now we can build our project and go to BPM Suite to configure it so we can use this workitem.

Registering the WorkItemHandler

UPDATE: Starting on jBPM 6.2, you can register custom work items using kie-deployment-descriptor.xml


UPDATE2: Starting on jBPM 6.5, a new feature makes even easier to add new service tasks. It is described in the documentation, however we will talk about this on this blog.

The first thing to do is to make our artifact visible to BPM Suite. We can either import it in the maven used by BPM Suite or we can upload the JAR using the web application. In any case, the common step is to build our project.

After building it, decide if you want to install it in your maven repository so you can use it in the BPM Suite project as a dependency or you can upload the JAR to BPM Suite and make it a dependency of the BPM Suite project. That's what we are going to do.

• So, after starting BPM Suite, and logging into business central, we can go to Authoring -> Artifact Repository  and upload the JAR with our Work Item Handler:

Now we create a simple project in BPM Suite. You can do this by going to Authoring -> Project Authoring and then New Item -> Project. Notice that I am considering that you have already a repository created.

Now that you have your project created, let's add the artifact we uploaded as a dependency of it. To do this, select the project and go to Tools -> Project Editor and on the Project Settings drop down menu, select Dependencies. Now you can specify the uploaded artifact as a dependency of your project using the Add from repository button and choose our artifact from the list that will show up and then we are done with this part. Don't forget the save the changes.

Remember that WorkItemHandlers are registered in the file META-INF/kmodule.xml of your project. However, we can do this visually! Go to Project Editor  and from the Project Settings dropdown button, choose Knowledge base and sessions. Add a new knowledge base, make it default and add a new ksession, make it default, edit it and add the work item handler. Here are some useful screenshots:

 Adding the kbase and the ksession:

Editing the ksession to add the work item handler:

Save it and now the project is already configured with a kbase and a ksession with our work item handler! See how our kmodule.xml looks like:

	<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<kbase name="mykbase" default="true" eventProcessingMode="stream" equalsBehavior="identity">
	<ksession name="mykasession" type="stateful" default="true" clockType="realtime">
	<workItemHandlers>
	<workItemHandler type="org.jugvale.jbpm.workitemhandler.HelloWorkItemHandler" name="HelloWorkItemHandler"/>
	</workItemHandlers>
	</ksession>
	</kbase>
	</kmodule>

view raw kmodule.xml hosted with ❤ by GitHub

We are almost done.  Let's create a process to test the WorkItemHandler we created, use the menu New Item -> Business Process and do nothing for now, just close the process editor.Now let's simple edit the file WorkDefinitions.wid of our project to include metadata about the WorkItemHandler. Here we can set the icon and the name that will appears in the process editor. We simple only set a display name:

  [
   "name" : "HelloWorkItemHandler",
    "displayName" : "Hello World!",
    "icon" : "defaultemailicon.gif"
  ]


Save the file, create a new process and MAGIC! Now you can use your custom work item handler and it will be appear in the process editor library under the Service Tasks pane. See my sample process:

If you build, deploy the project and run the process above, you see the "Hello World!" message in the logs:

00:25:16,904 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-3) Hello World!


That's our Hello World Work Item Handler! Of course you can also declare parameters for the Work Item and do more complex operations, such as access a Web Service, send email, send SMS, update a database....

Download the sources on github