Improve WorkItemHandler parameter definition

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");
        p.setAddress(address);
        // 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

from("file:inputDir?flatten=true")
   .log("Sending '${header.CamelFileName}' by mail")
   .to("smtp://smtp.gmail.com?username=jludvice&password=somepwd" +
           "&to=nobody@gmail.com&subject=Nothing")
   .log("Sent");

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
https://github.com/apache/camel/blob/d6f4266f6d14cb4dd8cc09d591ed8fce474385ad/components/camel-mail/src/main/java/org/apache/camel/component/mail/MailConfiguration.java#L67
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;
    @Inject
    private WorkItemManager manager;

    public void executeWorkItem() {
      p.setAddress(address);
      // do something
      manager.completeWorkItem(workItem.getId(), null); 
    }
 }

Conclusion

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 ?