jBPM CustomWorkItemHandler

 💡 Introduction

In real-world business workflows, you often need to perform custom operations—like sending emails, invoking APIs, writing to databases, or integrating with external systems.

jBPM makes this possible through 🧩 Work Item Handlers (WIHs) — reusable Java components that execute custom logic in your process.

In this tutorial, you’ll learn how to create, register, and use a custom Work Item Handler in jBPM from scratch.

---

🧠 1️⃣ What is a Work Item Handler?

A Work Item Handler is a Java class that executes custom logic when a Service Task in your BPMN process is triggered.

Each handler implements the interface:

org.kie.api.runtime.process.WorkItemHandler

Every Work Item Handler must define two methods:

• executeWorkItem(WorkItem workItem, WorkItemManager manager)
  → Executes your logic.

• abortWorkItem(WorkItem workItem, WorkItemManager manager)
  → Defines what happens when the work item is canceled.

---

⚙️ 2️⃣ Create the Custom Handler Class

Let’s create a simple handler called HelloWorldWorkItemHandler that prints a message.

package com.example.handlers;

import org.kie.api.runtime.process.WorkItem;
import org.kie.api.runtime.process.WorkItemHandler;
import org.kie.api.runtime.process.WorkItemManager;

public class HelloWorldWorkItemHandler implements WorkItemHandler {

    @Override
    public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
        String name = (String) workItem.getParameter("Name");
        System.out.println("👋 Hello from jBPM Work Item Handler, " + name + "!");
        // mark the work item as complete
        manager.completeWorkItem(workItem.getId(), null);
    }

    @Override
    public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
        System.out.println("❌ Work item aborted: " + workItem.getName());
    }
}

✅ This handler reads a parameter called "Name" from the process, prints a message, and then completes the task.

---

🧩 3️⃣ Register the Handler in jBPM

Now, you need to tell jBPM about this handler so it can execute when a Service Task of a certain type is triggered.

You can register it in several ways:

🔹 A. Register programmatically

If you’re running in a standalone application:

KieSession ksession = ... // get session
ksession.getWorkItemManager().registerWorkItemHandler(
    "HelloWorldTask", new HelloWorldWorkItemHandler()
);

🔹 B. Register in Business Central (Deployment Descriptor)

If you’re deploying on Business Central / KIE Server, add this in your project’s kie-deployment-descriptor.xml:

<workItemHandlers>
  <workItemHandler name="HelloWorldTask" type="com.example.handlers.HelloWorldWorkItemHandler"/>
</workItemHandlers>

📁 Path:
src/main/resources/META-INF/kie-deployment-descriptor.xml

When you deploy the KJAR, jBPM will automatically load your handler.

---

🧱 4️⃣ Create a BPMN Process to Use It

In your BPMN file (e.g., HelloWorldProcess.bpmn):

• Add a Service Task

• Set the Task Name to "HelloWorldTask" (must match the handler name)

• Add an input parameter:

  • Name → Name

  • Value → "Shikha"

Then connect it to a start and end event.

✅ Example process flow:

Start → HelloWorldTask (Service Task) → End

---

🔍 5️⃣ Deploy and Run

Option 1: From Business Central

• Deploy your project containing the handler and BPMN.

• Start the process instance manually or via REST.

Option 2: From Java Application

KieSession ksession = KieServices.Factory.get().getKieClasspathContainer()
        .newKieSession("defaultKieSession");

ksession.startProcess("com.example.bpmn.HelloWorldProcess");

Expected Console Output:

👋 Hello from jBPM Work Item Handler, Shikha!

---

🧪 6️⃣ Add Parameters and Return Data

You can also pass data into and out of the handler using a Map.

@Override
public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
    String message = (String) workItem.getParameter("Message");
    System.out.println("📦 Processing message: " + message);

    Map<String, Object> results = new HashMap<>();
    results.put("Output", "Processed: " + message);

    manager.completeWorkItem(workItem.getId(), results);
}

Then map "Output" to a process variable in your BPMN task output.

---

⚡ 7️⃣ Example: Calling External REST API

Here’s a real-world example of a Work Item Handler that calls an API:

public class RestApiHandler implements WorkItemHandler {

    @Override
    public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
        String url = (String) workItem.getParameter("Url");

        try {
            HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
            conn.setRequestMethod("GET");
            int code = conn.getResponseCode();
            System.out.println("🌐 API Response Code: " + code);

            Map<String, Object> results = new HashMap<>();
            results.put("statusCode", code);
            manager.completeWorkItem(workItem.getId(), results);
        } catch (Exception e) {
            e.printStackTrace();
            manager.abortWorkItem(workItem.getId());
        }
    }

    @Override
    public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
        System.out.println("REST API Handler Aborted");
    }
}

---

🧰 8️⃣ How to Reuse and Extend

You can create many handlers for different tasks:

• 📧 EmailHandler — send email notifications

• 🔗 WebhookHandler — post to Slack or Teams

• 🗂️ DatabaseHandler — insert records into DB

• 📊 ElasticsearchHandler — send logs to ELK

Once registered, you can reuse them in any BPMN process.

---

👉 Watch Enable  jBPM CustomWorkItemHandler in Action better:

Here's a quick video to help you understand  jBPM CustomWorkItemHandler in Action better: YouTube: Learn IT with Shikha

Git Source Code: LearnITWithShikha/customWorkItemItemHanlder

🏁 Conclusion

🚀 A Custom Work Item Handler in jBPM gives you the power to integrate business workflows with external systems, APIs, and custom Java logic.

By combining BPMN Service Tasks and custom handlers, you can transform your automation from simple process flows to enterprise-grade orchestration.

💼 Professional Support Available 

If you are facing issues in real projects related to enterprise backend development or workflow automation, I provide paid consulting, production debugging, project support, and focused trainings. 

 Technologies covered include Java, Spring Boot, PL/SQL, Azure, and workflow automation (jBPM, Camunda BPM, RHPAM).  

📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 Website: IT Trainings | Digital metal podium