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


@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-services.html

📩 Email: ishikhanirankari@gmail.com | info@realtechnologiesindia.com
🌐 IT Trainings | Digital metal podium

✔ Available for quick consulting calls and project-based support
✔ Response within 24 hours

🎥 Learn IT with Shikha on YouTube

Prefer learning through videos? Watch practical tutorials on Kafka, Camunda, Alfresco, Java, Spring Boot, Microservices and Enterprise Architecture.

▶ Subscribe to Learn IT with Shikha on YouTube

Search This Blog

Learn IT with Shikha Blogs

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