jBPM WorkItemHandler Example with Spring Boot (Step-by-Step)

Introduction

In jBPM, not all business logic can be modeled using BPMN elements alone.
Whenever a process needs to:

• Call an external service

• Execute custom Java logic

• Integrate with Spring beans

• Perform non-standard operations

we use a WorkItemHandler.

This blog explains what a WorkItemHandler is, when to use it, and shows a complete working example using Spring Boot + jBPM.

---

What Is a WorkItemHandler in jBPM?

A WorkItemHandler is a Java component that:

• Executes custom logic for a BPMN Service Task

• Receives inputs from the process

• Returns results back to the process

It acts as a bridge between BPMN and Java/Spring code.

---

When Should You Use a WorkItemHandler?

✔ Calling REST / SOAP services
✔ Sending emails or notifications
✔ Database or legacy system calls
✔ Custom validations
✔ Integration with Spring services

❌ Avoid using it for simple logic (use Script Tasks instead)

---

Architecture Overview

Spring Boot Application
        |
   jBPM Engine
        |
 Service Task (BPMN)
        |
 WorkItemHandler
        |
 Spring Service / External API

---

Step 1: Maven Dependencies

Add required dependencies to your Spring Boot project.

<dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-spring-boot-starter</artifactId>
    <version>7.74.1.Final</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

---

Step 2: Create a BPMN Service Task

In your BPMN file:

• Task type: Service Task

• Implementation: Custom

• Name: EmailTask

• Parameters:

  • Email (String)

This task will be handled by our custom WorkItemHandler.

---

Step 3: Implement the WorkItemHandler

@Component
public class EmailWorkItemHandler implements WorkItemHandler {

    @Override
    public void executeWorkItem(WorkItem workItem,
                                WorkItemManager manager) {

        String email = (String) workItem.getParameter("Email");

        System.out.println("Sending email to: " + email);

        Map<String, Object> results = new HashMap<>();
        results.put("Status", "SENT");

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

    @Override
    public void abortWorkItem(WorkItem workItem,
                              WorkItemManager manager) {

        manager.abortWorkItem(workItem.getId());
    }
}

---

Step 4: Register the WorkItemHandler

Register the handler in your Spring configuration.

@Configuration
public class JBPMConfig {

    @Bean
    public KieSession kieSession() {
        KieSession session = kieContainer().newKieSession();

        session.getWorkItemManager()
               .registerWorkItemHandler(
                   "EmailTask",
                   new EmailWorkItemHandler()
               );

        return session;
    }
}

👉 The name EmailTask must match the BPMN task name.

---

Step 5: Use Spring Services Inside Handler

You can inject Spring beans directly.

@Component
public class EmailWorkItemHandler implements WorkItemHandler {

    private final EmailService emailService;

    public EmailWorkItemHandler(EmailService emailService) {
        this.emailService = emailService;
    }

    @Override
    public void executeWorkItem(WorkItem workItem,
                                WorkItemManager manager) {

        String email = (String) workItem.getParameter("Email");

        emailService.send(email);

        manager.completeWorkItem(workItem.getId(), Map.of("Status", "SENT"));
    }
}

This is the recommended enterprise approach.

---

Step 6: Access Output in BPMN

In BPMN:

• Map output parameter Status

• Store it in a process variable

Example:

status = Status

---

Step 7: Error Handling Best Practice

Always handle exceptions properly.

try {
    emailService.send(email);
    manager.completeWorkItem(workItem.getId(), result);
} catch (Exception ex) {
    manager.abortWorkItem(workItem.getId());
    throw ex;
}

For business errors, prefer Error Events instead of aborting.

---

Common Mistakes

❌ Task name mismatch
❌ Not completing the work item
❌ Blocking long-running logic
❌ Hard-coding configuration
❌ Using Script Task instead of Handler

---

Best Practices (Very Important)

✔ One handler per responsibility
✔ Keep handlers stateless
✔ Inject Spring services
✔ Externalize configuration
✔ Avoid heavy logic inside handler
✔ Use async for long tasks

---

Interview Question (Very Common)

Q: Why not use Script Task instead of WorkItemHandler?
A: Script Tasks are limited, hard to test, and not suitable for complex logic or integrations. WorkItemHandlers are reusable, testable, and production-ready.

---

Real-World Use Cases

Use Case	Recommended
Send email	WorkItemHandler
Call REST API	WorkItemHandler
Simple variable update	Script Task
Human interaction	Human Task
Decision logic	DMN

---

Conclusion

A WorkItemHandler is the most powerful extension mechanism in jBPM.
When combined with Spring Boot, it allows you to build clean, testable, and enterprise-grade BPM solutions.

If you are serious about jBPM development, mastering WorkItemHandlers is mandatory.

💼 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