Running Custom Tasks in jBPM with work item handlers
Introduction
You can use a WorkItemHandler to run custom tasks during the execution of a process in jBPM. In this article, you will run through the steps to create a custom task and use it in a process.
IMPORTANT: This tutorial uses version 7.72.0.Final of jBPM.
The application you’re going to create is a process that concatenates first and last names, and prints the result to the console.
The concatenation is going to be processed in a custom task. So, start by creating the WorkItemHandler.
NOTE: If you don’t want to create the project, you can clone it from GitHub.
Creating the WorkItemHandler
Run the following command to create a work item handler project:
mvn archetype:generate \ -DarchetypeGroupId=org.jbpm \ -DarchetypeArtifactId=jbpm-workitems-archetype \ -DarchetypeVersion=7.72.0.Final \ -DgroupId=org.acme \ -DartifactId=myconcatworkitem \ -Dversion=1.0.0-SNAPSHOT \ -DclassPrefix=MyConcat
Replace the content of
src/main/java/org/acme/MyConcatWorkItemHandler.java
file with the following:package org.acme; import org.jbpm.process.workitem.core.AbstractLogOrThrowWorkItemHandler; import org.jbpm.process.workitem.core.util.RequiredParameterValidator; import org.jbpm.process.workitem.core.util.Wid; import org.jbpm.process.workitem.core.util.WidMavenDepends; import org.jbpm.process.workitem.core.util.WidParameter; import org.jbpm.process.workitem.core.util.WidResult; import org.jbpm.process.workitem.core.util.service.WidAction; import org.jbpm.process.workitem.core.util.service.WidAuth; import org.jbpm.process.workitem.core.util.service.WidService; import org.kie.api.runtime.process.WorkItem; import org.kie.api.runtime.process.WorkItemManager; import java.util.HashMap; import java.util.Map; @Wid(widfile = "MyConcatDefinitions.wid", name = "MyConcatDefinitions", displayName = "MyConcatDefinitions", defaultHandler = "mvel: new org.acme.MyConcatWorkItemHandler()", documentation = "myconcatworkitem/index.html", category = "myconcatworkitem", icon = "MyConcatDefinitions.png", parameters = { @WidParameter(name = "FirstName"), @WidParameter(name = "LastName") }, results = { @WidResult(name = "FullName") }, mavenDepends = { @WidMavenDepends(group = "org.acme", artifact = "myconcatworkitem", version = "1.0.0-SNAPSHOT") }, serviceInfo = @WidService(category = "myconcatworkitem", description = "${description}", keywords = "", action = @WidAction(title = "Sample Title"), authinfo = @WidAuth(required = true, params = {"FirstName", "LastName"}, paramsdescription = {"First name", "Last name"}, referencesite = "referenceSiteURL") ) ) public class MyConcatWorkItemHandler extends AbstractLogOrThrowWorkItemHandler { public void executeWorkItem(WorkItem workItem, WorkItemManager manager) { try { RequiredParameterValidator.validate(this.getClass(), workItem); String firstName = (String) workItem.getParameter("FirstName"); // Gets the "FirstName" parameter String lastName = (String) workItem.getParameter("LastName"); // Gets the "LastName" parameter String fullName = firstName + " " + lastName; // Concatenates the "firstName" and "lastName" Map results = new HashMap(); results.put("FullName", fullName); // Adds "fullName" to the "results" object manager.completeWorkItem(workItem.getId(), results); } catch (Throwable cause) { handleException(cause); } } @Override public void abortWorkItem(WorkItem workItem, WorkItemManager manager) { } }
Update the
src/test/java/org/acme/MyConcatWorkItemHandlerTest.java
test file with the following:package org.acme; import org.drools.core.process.instance.impl.WorkItemImpl; import org.jbpm.process.workitem.core.TestWorkItemManager; import org.jbpm.test.AbstractBaseTest; import org.junit.Test; import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertNotNull; import static org.junit.Assert.assertTrue; public class MyConcatWorkItemHandlerTest extends AbstractBaseTest { @Test public void testHandler() { WorkItemImpl workItem = new WorkItemImpl(); workItem.setParameter("FirstName", "John"); workItem.setParameter("LastName", "Doe"); TestWorkItemManager manager = new TestWorkItemManager(); MyConcatWorkItemHandler handler = new MyConcatWorkItemHandler(); handler.setLogThrownException(true); handler.executeWorkItem(workItem, manager); assertNotNull(manager.getResults()); assertEquals(1, manager.getResults().size()); assertEquals("John Doe", manager.getResults().get(0L).get("FullName")); assertTrue(manager.getResults().containsKey(workItem.getId())); } }
Package and install the work item handler project into your Maven local repository.
From the
myconcatworkitem
directory, run:mvn clean install
You should see the generated
myconcatworkitem-1.0.0-SNAPSHOT.jar
file in thetarget
directory.
Adding the work item handler to Business Central as a Custom Task
- Open Business Central
- Click the gear icon in the upper-right corner
- Click "Custom Tasks Administration"
- Click the "Add Custom Task" button
- Upload the
myconcatworkitem-1.0.0-SNAPSHOT.jar
file. After the upload, the Custom Task should appear in the list of Custom Tasks in the same window as the "Add Custom Task" button - Locate the Custom Task (MyConcatDefinitions) in the list and activate it
Installing the Custom Task in your project
- Open your project in Business Central and click "Settings"
- Click "Custom Tasks" on the left corner
- Click the "Install" button of the Custom Task (MyConcatDefinitions)
- Click the "Save" button
- On the left side of the screen, click "Dependencies"
- Click "Add from Repository" and then search for the "myconcatworkitem" artifact and select it
- Click the "Save" button and confirm the dialog
Using the Custom Task
Create a new Business Process
Add three process variables to the process. In "Properties", expand "Process Data" and add the following
String
variables:firstName
lastName
fullName
Add a new Start Event
Add a new End Event
Click "Custom Tasks" (gear button on the left side of the screen), select "MyConcatDefinitions" and add it to the process
Select the node you just added and in Properties, expand "Data Assignments" and click the edit button
Bind the process variables to the Custom Task parameters and click OK
Add a Script Task to the process
Select the node you just added and in Properties, expand "Implementation/Execution" and add the following script:
System.out.println(fullName);
Connect all the nodes in the process
Start - MyConcatDefinitions - Task - End
Save and deploy the process
When you start a new process instance, you’ll be asked to enter the first and last names. After submitting, you will see the concatenated fullName
in the console.
Conclusion
In this tutorial, you’ve learned how to create and use a custom work item handler in jBPM by creating a process that concatenates the first and last names received as parameters.