5 Replies Latest reply on Jun 6, 2014 6:12 PM by Laura delli Paoli

    jBPM6: Custom work item handlers

    Stijn C. Newbie



      So I am looking at implementing a custom work item handler through the KIE-WB (jBPM 6), and I am kind of stumped on how to do so.

      I have created a simple process in the web-designer with a single service task. Now I want this task to use my custom work item handler. How would I do this (through the web-console)?


      I have already done the following:

      - created a Java class implementing WorkItemHandler and created a JAR with this class

      - added a work item definition to the process:


          "name" : "CustomTestTask",

          "parameters" : [

              "aParam" : new StringDataType()


          "results" : [

              "id" : new StringDataType(),


          "displayName" : "CustomTestTask",

          "icon" : "defaultservicenodeicon.png"



      Now, I assume I need to do the following now:

      - add the JAR with the implementation as dependency to the BPM project

      - "register" the custom handler


      Adding the JAR as dependency shouldn't be too hard, I just need to know where exactly it should go.

      Registering my custom handler class is something that completely eludes me, though. I've found some documentation advising me to adapt a conf file ("CustomWorkItemHandlers.conf") and then re-running the install.jBPM-console target on the build.xml script, but that doesn't seem like a very "clean" way. I'll be adding lots of custom handlers and I do not want to be reinstalling the jbpm-console each time. I've also found some Java code that is supposed to do it, by invoking ksession.getWorkItemManager().registerWorkItemHandler(), but then I am not sure where I am supposed to invoke this code from? I want to use a single, stateful ksession, so my handlers should be defined on start-up.


      Preferrably, I'd like to do all of this through the web-console and not go fiddle in server XML or config files (that in my case are located on a remote server).

      Any useful tips, or if anyone could point me to some relevant documentation?



      Hmm. I found the "CustomWorkItemHandler.conf" file in the jbpm-console.war/WEB-INF/classes/META-INF in my server's deployment directory. I assume that I need to adapt this file to register my customer handler, however, I hope there is an easier way than to extract the WAR, adapt the file manually, re-package the WAR and restart the server? I hope this sort of thing can be registered through the web-console? Seems logical, as I would assume it is a commonly used function...


      And where does the JAR go, that has the custom class? Also in the WAR?

        • 1. Re: jBPM6: Custom work item handlers
          Maciej Swiderski Master

          in this section of docs you'll find more details how you can register handlers. But in general your findings are correct, you should define it in the conf file (or use producers for it see docs) and the jars needs to be placed on application classpath - web-inf/lib. There will be further enhancements coming in with next release so you can define handlers as part of kmodule.xml or use custom deployment descriptors. But that is still to come.



          • 2. Re: jBPM6: Custom work item handlers
            Stijn C. Newbie

            Ah, looking at that documentation, you suggest I build such a RuntimeManager and register my handlers through that? It's not entirely clear where I put the Java code for this RuntimeManager somewhere...?

            I'll try to dig a little deeper, but if you have more examples of how to implement this, that would be great!


            And, being able to register handlers through the kmodule.xml or deployment descriptors would be very convenient. Any idea when I can expect that?

            • 3. Re: jBPM6: Custom work item handlers
              Andreas G. Novice

              According to the this entry in thread jBPM Console Server can't find WorkItem Handler Implementation I solved this by

              • Extract file jbpm-console.war in serverlocation\standalone\deployments\.
              • Delete the original file jbpm-console.war.
              • Be sure that the name of the created directory is exactly the same as the original war-file (in our case jbpm-console.war).
              • Restart the server afterwards and check if the console has been started (file jbpm-console.war.deployed must exists in \standalone\deployments). If not create a file with the name jbpm-console.war.dodeploy in deployments folder and start the server again.
              • register custom workitemhandler in file CustomWorkItemHandlers.conf. The location of this file is serverlocation\standalone\deployments\jbpm-console.war\WEB-INF\classes\META-INF
              • copy the jar file which contains the customworkitemhandler to the directory standalone\deployments\jbpm-console.war\WEB-INF\lib
              • start the server again
              • create processdefinition and define your customworkitem in file . The workitemhandler is registered and should process the workitem.
              • 4. Re: jBPM6: Custom work item handlers
                Stijn C. Newbie

                Hello Andreas,


                Thanks for your reply.


                I tried to follow your steps, and it all seems to work. I managed to add the custom work item to my process and all of that, however when I try to run the process it complains it can't find it.

                "Caused by: org.drools.core.WorkItemHandlerNotFoundException: Could not find work item handler for CustomTestTask".


                However, I did add the JAR with the class in the WEB-INF lib directory, updated the work definitions and added the handler to the CustomWorkItemHandlers.conf file.


                Any ideas?


                Also, one would assume adding custom handlers like this would be less of a pain, but the support for this is really, really poor.

                • 5. Re: jBPM6: Custom work item handlers
                  Laura delli Paoli Master


                  Did you find any solution???

                  I was wondering about loading custom workitem handlers as a jboss global module...  But I've Not succeeded yet.