jBPM – Work Item Handler personnalisé

💡 Introduction

Dans les systèmes d’entreprise modernes, il est fréquent de devoir exécuter une logique spécifique — comme envoyer un e-mail, appeler une API REST, écrire dans une base de données ou se connecter à des applications externes.

Avec 🧩 jBPM, cela est possible grâce aux Work Item Handlers personnalisés (WIH) — des composants Java réutilisables qui exécutent une logique spécifique lorsqu’une tâche de service BPMN est déclenchée.

Dans cet article, nous allons apprendre à créer, enregistrer et utiliser un Work Item Handler personnalisé dans jBPM, étape par étape.

🧠 1️⃣ Qu’est-ce qu’un Work Item Handler ?

Un Work Item Handler est une classe Java qui définit la logique exécutée lorsqu’une tâche de service (Service Task) est appelée dans un processus BPMN.

Chaque handler implémente l’interface :


org.kie.api.runtime.process.WorkItemHandler

Elle contient deux méthodes :

executeWorkItem(WorkItem workItem, WorkItemManager manager) → exécute votre logique.
abortWorkItem(WorkItem workItem, WorkItemManager manager) → définit le comportement en cas d’annulation.

⚙️ 2️⃣ Créer la classe du Handler

Créons un simple handler appelé HelloWorldWorkItemHandler qui affiche un message dans la console :


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("👋 Bonjour depuis le Work Item Handler jBPM, " + name + " !");
        manager.completeWorkItem(workItem.getId(), null);
    }

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

✅ Ce handler lit le paramètre "Name" depuis le processus, affiche un message, puis termine la tâche.

🧩 3️⃣ Enregistrer le Handler dans jBPM

Une fois le handler créé, il faut le déclarer dans jBPM afin qu’il soit exécuté lorsque la tâche de service correspondante est appelée.

🔹 A. Enregistrement programmatique

Si vous exécutez jBPM dans une application Java autonome :


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

🔹 B. Enregistrement via Business Central (Descripteur de déploiement)

Dans le fichier kie-deployment-descriptor.xml, ajoutez :


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

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

Ainsi, le handler sera automatiquement chargé au déploiement du projet.

🧱 4️⃣ Créer un processus BPMN pour l’utiliser

Dans votre fichier BPMN (HelloWorldProcess.bpmn) :

Ajoutez une tâche de service
Définissez son Nom sur HelloWorldTask (doit correspondre au handler)
Ajoutez un paramètre d’entrée :
- Nom : Name
- Valeur : "Shikha"

✅ Exemple de flux :
Start → HelloWorldTask → End

🔍 5️⃣ Déployer et exécuter

Option 1 : via Business Central

Déployez votre projet contenant le handler et le BPMN
Lancez une instance du processus depuis l’interface ou via l’API REST

Option 2 : via Java Application


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

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

Résultat attendu :


👋 Bonjour depuis le Work Item Handler jBPM, Shikha !

🧪 6️⃣ Ajouter des paramètres et des résultats

Vous pouvez aussi passer et retourner des données via une Map :


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

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

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

👉 Vous pouvez ensuite lier "Output" à une variable de processus dans votre BPMN.

⚡ 7️⃣ Exemple réel : appel d’une API REST

Voici un Work Item Handler qui appelle une API REST :


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("🌐 Code réponse API : " + 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("❌ Handler REST API annulé");
    }
}

🧰 8️⃣ Réutilisation et extensions

Vous pouvez créer plusieurs handlers spécialisés :

📧 EmailHandler – envoyer des notifications par e-mail
🔗 WebhookHandler – envoyer un message à Slack / Teams
🗂️ DatabaseHandler – écrire dans une base de données
📊 ElasticsearchHandler – envoyer des logs vers ELK

Une fois enregistrés, ces handlers peuvent être utilisés dans tous vos processus BPMN.

👉 Regardez l’activation du Work Item Handler personnalisé jBPM en action :
Voici une courte vidéo pour mieux comprendre le fonctionnement du Work Item Handler personnalisé dans jBPM : 🎥 YouTube: Learn IT with Shikha

👉 Code source: https://github.com/LearnITWithShikha/customWorkItemItemHanlder

🏁 Conclusion

🚀 Les Work Item Handlers personnalisés de jBPM permettent d’intégrer facilement votre logique métier, vos APIs et vos systèmes externes dans vos processus.

Ils transforment vos workflows en véritables orchestrations d’entreprise, tout en restant faciles à maintenir et à réutiliser.

💼 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