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

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.

---

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