Uploaded image for project: 'jBPM'
  1. jBPM
  2. JBPM-5223

Improve WorkItemHandler parameter definition


    • Type: Enhancement
    • Status: Resolved (View Workflow)
    • Priority: Minor
    • Resolution: Done
    • Affects Version/s: 7.0.0.Final
    • Fix Version/s: None
    • Component/s: Runtime Engine
    • Labels:
    • Sprint:
      2018 Week 09-10, 2018 Week 11-12, 2018 Week 13-14, 2018 Week 15-16
    • Docs QE Status:
    • QE Status:


      Hello, could you please consider changing the way how WorkItemHandler obtains parameters from process?

      Current situation

      It looks like many WorkItemHandlers follow this schema currently:

      • obtain parameter from Map<String, Object> and hope it's defined and has proper type
        for instance https://github.com/droolsjbpm/jbpm/blob/master/jbpm-workitems/src/main/java/org/jbpm/process/workitem/email/EmailWorkItemHandler.java#L95
        public class EmailWorkItemHandler extends AbstractLogOrThrowWorkItemHandler {
            public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
              Person p = (Person) workItem.getParameter("inPerson");
              String address = (String) workItem.getParameter("targetAddress");
              // do something
              manager.completeWorkItem(workItem.getId(), null); 
      • write Javadoc to class so user is able to guess right parameters to pass to work item handler

      When user wan't to use this work item handler, he must create WorkItem definition in his project to be able to drag and drop work item into process right ?

      • fill proper parameters to work item definition
            "name" : "CustomHandler",
            "parameters" : [
              "inPerson" : new ObjectDataType(),
              "targetAddress" : new StringDataType(),
            "displayName" : "CustomHandler",
            "icon" : "defaultemailicon.gif"

      And then keep work item handler sources and WID in project "in sync".

      About Apache Camel

      I believe it would be useful to take inspiration from Apache Camel project and theirs component model.
      Camel is routing framework which allows creating route from start, through some processors to end. Kind of like process, right ?
      They model process in following way

         .log("Sending '${header.CamelFileName}' by mail")
         .to("smtp://smtp.gmail.com?username=jludvice&password=somepwd" +

      In the source code they use annotations @UriParam and @UriPath to

      • process tne component configuration smtp://smtp.gmail.com?username=jludvice&password=somepwd&to=nobody@gmail.com&subject=Nothing
      • generate documentation http://camel.apache.org/mail.html
      • generate so-caled camel catalog - jar containg all component definitions (~200 components) which is used for tooling like eclipse camel editor or hawtio to visualise routes and show help && documentation

      See for instance source code of camel mail component - anotation for defining default value of mail sender - property from
      And the default value is also in camel docs http://camel.apache.org/mail.html (CTRL+F camel@localhost)

      Proposed change

      So the Work item handler source might look like like this

      public class EmailWorkItemHandler extends AbstractLogOrThrowWorkItemHandler {
          @Param(name="inPerson", required=true, documentation="This might explain to user what is this property good for")
          private Person p;
          @Param(name="targetAddress", required=false, defaultValue="info@mycompany.com", documentation="Put here string in form of 'login@mail.server.com'. It will send e-mail here")
          private String address;
          private WorkItemManager manager;
          public void executeWorkItem() {
            // do something
            manager.completeWorkItem(workItem.getId(), null); 


      It might allow you

      • to have easier definition of WorkItemHandlers for users - just anotate your class with certain annotations...
      • business central could automatically discover available work item handlers && provide correct, complete and up to date Data IO Mapping in BPM process modeler
      • no need for users to maintain their own WorkItemDefinition

      What do you think about this?
      Is it something worth implementing in jBPM ?

        Gliffy Diagrams




              • Assignee:
                tsurdilovic Tihomir Surdilovic
                jludvice Josef Ludvicek
              • Votes:
                2 Vote for this issue
                7 Start watching this issue


                • Created: