Creating a Custom WorkItemHandler in jBPM for Eclipse

I had to create a custom WorkItemHandler for jBPM in Eclipse to execute my own code when reaching a specific node in a Business Process, since a ScriptTask (which allows to execute code) was not enough because it does not allow to manipulate Process variables. A custom WorkItemHandler would also allow for better maintainability of the Business Process because it does not depend on scripts hidden in the process definition, but is directly visible in its own java class.
1 answer

Creating a Custom WorkItemHandler in jBPM for Eclipse

Assuming you have Eclipse and the jbpm dependencies installed correctly via maven you can create custom work items with the following steps:

#1 Under src/main/resources/ in your eclipse project create a file called "CustomWorkItem.wid" where you put your custom workitem definition:

import org.drools.process.core.datatype.impl.type.StringDataType;

"name" : "CustomWorkItem",
"parameters" : [
"keywords" : new StringDataType(),
"limit" : new StringDataType()
"displayName" : "CustomWorkItem"

#2 Create another file called "drools.rulebase.conf" in the same directory where you register your custom workitem definition like so:

drools.workDefinitions = CustomWorkItem.wid WorkDefinitions.conf

#3 Create a java class that implements the Interface "WorkItemHandler" from the package "org.kie.api.runtime.process.WorkItemHandler". You will get the following two method stubs from the interface:

public void abortWorkItem(WorkItem workItem, WorkItemManager manager) { }

public void executeWorkItem(WorkItem workItem, WorkItemManager manager) { }

The executeWorkItem method will be called by the bpm engine when the business process reaches your custom work item handler.

#4 Register your custom WorktItemHandler class with the bpm engine:

kSession.getWorkItemManager().registerWorkItemHandler("CustomWorkItem", new CustomWorkItemHandler());

Note that the first parameter should match the name from the work item definition and the second parameter should be a new instance of your custom work itemhandler java class created in step #3.

#5 Restart eclipse and use the new custom work item as a task in your business process!