Exemple de WorkItemHandler jBPM avec Spring Boot (Guide pas à pas)

January 13, 2026

Introduction

Dans jBPM, toute la logique métier ne peut pas toujours être modélisée uniquement avec des éléments BPMN standards.
Dès qu’un processus doit:

Appeler un service externe
Exécuter une logique Java personnalisée
Intégrer des beans Spring
Interagir avec un système tiers

👉 on utilise un WorkItemHandler.

Ce guide explique ce qu’est un WorkItemHandler, quand l’utiliser, et fournit un exemple complet et fonctionnel avec Spring Boot.

Cette architecture est couramment utilisée dans les environnements microservices modernes.

👉 environnements microservices modernes

Qu’est-ce qu’un WorkItemHandler dans jBPM ?

Un WorkItemHandler est un composant Java qui :

Exécute une logique personnalisée pour une Service Task BPMN
Reçoit des paramètres depuis le processus
Retourne des résultats vers le processus

Il fait le lien entre le modèle BPMN et le code Java / Spring.

Quand utiliser un WorkItemHandler ?

✔ Appel d’API REST / SOAP
✔ Envoi d’e-mails ou notifications
✔ Intégration avec des systèmes legacy
✔ Validations complexes
✔ Appels à des services Spring

❌ À éviter pour une logique simple (préférer un Script Task)

Vue d’ensemble de l’architecture


Application Spring Boot
        |
     Moteur jBPM
        |
   Service Task (BPMN)
        |
   WorkItemHandler
        |
 Service Spring / API externe

Étape 1 : Dépendances Maven

Ajoutez les dépendances nécessaires à votre projet Spring Boot.


<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>

Étape 2 : Créer la Service Task BPMN

Dans votre fichier BPMN :

Type : Service Task
Implémentation : Custom
Nom de la tâche : EmailTask
Paramètre :
- Email (String)

Ce nom devra correspondre exactement au WorkItemHandler enregistré.

Étape 3 : Implémenter le WorkItemHandler


@Component
public class EmailWorkItemHandler implements WorkItemHandler {

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

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

        System.out.println("Envoi d'email à : " + 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());
    }
}

Étape 4 : Enregistrer le WorkItemHandler

Dans la configuration Spring :


@Configuration
public class JBPMConfig {

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

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

        return session;
    }
}

⚠️ Le nom EmailTask doit correspondre exactement au nom défini dans le BPMN.

Étape 5 : Injecter des services Spring

C’est la bonne pratique en entreprise.


@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")
        );
    }
}

Étape 6 : Récupérer la sortie dans le BPMN

Dans la Service Task :

Mapper le paramètre de sortie Status
Le stocker dans une variable de processus

Exemple :


processStatus = Status

Étape 7 : Gestion des erreurs (bonne pratique)


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

👉 Pour des erreurs métier, utilisez plutôt des Error Events BPMN.

Erreurs fréquentes

❌ Nom de tâche incorrect
❌ WorkItem non complété
❌ Logique longue et bloquante
❌ Configuration codée en dur
❌ Utiliser un Script Task à la place

Bonnes pratiques essentielles

✔ Un handler = une responsabilité
✔ Handlers sans état (stateless)
✔ Injection de services Spring
✔ Configuration externalisée
✔ Logique légère dans le handler
✔ Asynchrone pour les traitements longs

Question d’entretien fréquente

Q : Pourquoi ne pas utiliser un Script Task à la place ?
R : Les Script Tasks sont difficiles à tester, peu maintenables et non adaptées aux intégrations complexes. Les WorkItemHandlers sont réutilisables et robustes.

Cas d’usage réels

Cas	Solution recommandée
Envoi d’e-mail	WorkItemHandler
Appel REST	WorkItemHandler
Mise à jour simple	Script Task
Interaction humaine	Human Task
Décision métier	DMN

Conclusion

Le WorkItemHandler est le mécanisme d’extension le plus puissant de jBPM.
Combiné à Spring Boot, il permet de créer des solutions BPM propres, testables et prêtes pour la production.

Maîtriser les WorkItemHandlers est indispensable pour tout développeur jBPM sérieux.

💼 Support professionnel disponible

Si vous rencontrez des problèmes sur des projets réels liés au développement backend d’entreprise ou à l’automatisation des workflows, je propose des services de conseil payants, de débogage en production, de support projet et de formations ciblées.

Les technologies couvertes incluent Java, Spring Boot, PL/SQL, Azure, ainsi que l’automatisation des workflows (jBPM, Camunda BPM, RHPAM).

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

🌐 Website: IT Trainings | Digital lectern | Digital rostrum | Digital metal podium

Search This Blog

Learn IT with Shikha Blogs