Hi marcusk,

Thank you for reaching out to with this.

As a first step, I would like to understand better your goal and the reasoning behind the feature request (before the decision for custom implementation of custom FormEngine).
You mentioned that you want to use the "built-in form functionality", could you tell us more about what have you tried and what is missing for you?
Have you looked into the Embedded Task Forms functionality (User guide)? Does it fit your needs?
After giving us more details on the above, I will continue with your concrete questions/bullets.

Best regards,
Yana

Hi Yana,

With "built-in form functionality" I meant the API for rendering forms (FormService::getRenderedTaskForm, which delegates to FormEngine for the actual rendering) and submitting forms (FormService::submitTaskForm, which delegates to FormHandler for converting the submitted values to process variables), and the API for customizing their behavior (by configuring a different FormEngine using processEngineConfiguration::setCustomFormEngines / by providing a custom FormHandler in camunda:formHandlerClass).

The built-in task form renderers (including Embedded Task Forms and Generated Task Forms) and default submit-handling do not fit my needs. To be more concrete, the way we do form handling is by providing a form class that contains (potentially nested) properties for every form field, and annotations containing meta-data about how a field should be rendered, validated etc. When a form is submitted the entered values are put into a new instance of the form class, which is then stored in a single process variable.

So just to be clear, Camunda already supports the configuration of a custom FormEngine, ánd providing custom FormHandlers. It's just that I've encountered some issues when actually trying to use these extension points. For this I have some improvements in mind.

Regards, Marcus

Hi Marcus,

Thank you for your explanation. I have a couple of more questions:

1. the functionality that is common to rendering and submission is needed by these two classes.
   > FormEngine and FormHandler are interfaces, maybe you can implement one class which implement both of them?
2. the FormHandler.submitFormVariables method has no access to the FormData.
   > It will be interesting to give us an example of your use case why do you need access to the FormData.
3. the only way to provide a custom FormHandler is by putting the camunda:formHandlerClass attribute on every task.
   > Did you consider implementing a ParseListener?

Hi Yana,

I've created a minimized version of our current implementation here, including the use of a ParseListener as you suggested. I'm relatively happy with this implementation, except for the breaking issue I mention in point 3.

2. It will be interesting to give us an example of your use case why do you need access to the FormData.

Remember that in our case the formKey contains the fully qualified name of the class that represents the form, which together with the deploymentId is used to load the class. This class is just as much needed for form submission as it is for rendering, because during submitForm a new instance of that class is created, and its fields are filled using the entered values. As a workaround I retrieve the formKey and deploymentId in parseConfiguration, so they can be used by submitFormVariables, which delegates most work to the FormEngine (where I think it should be), and then stores the resulting Form-instance in a process variable.

1. FormEngine and FormHandler are interfaces, maybe you can implement one class which implement both of them?

That's possible, but each task definition has its own FormHandler instance (since it's also responsible for storing the result of parseConfiguration), so you'd still need additional measures to be able to share state (e.g. caching, so we don't have to load en analyse the form class each time) between the form engine and the form handlers. The solution I chose is to have a reference to the FormEngine in each FormHandler.

3. Did you consider implementing a ParseListener?

Good idea, I did not think of that I used it in the linked implementation, and it works quite well in principle.

However, this has brought to light a fundamental issue with overring a FormHandler in a ParseListener. When ParseListener#parseUserTask is called, a FormHandler has already been assigned to the task (by BpmnParse::parseTaskDefinition), and its parseConfiguration-method has already been invoked (from the same place). Therefore parseConfiguration on the new FormHandler will never be called!

Now I don't want to come across as negative, so let me offer some suggestions instead of complaining

In the short term, a small enhancement would solve my primary issue: support the possibility to specify a default FormHandler-factory* in the ProcessEngineConfiguration. This default is then used (instead of "new DefaultTaskFormHandler()" as it is now) to assign a form handler when it isn't explicitly specified using camunda:formHandlerClass. This change would remove the need for a ParseListener to set the custom FormHandler, and therefore circumvent the problem I mentioned in point 3.
(* why a factory instead of a class? so we can easily pass additional constructor parameters)

On the longer term, if Camunda ever considers a redesign of the form handling API, I have the following ideas about that:

• FormHandler should only be responsible for parsing the task definition XML, and create FormData-instances based on that. It would also make sense to have it decide on the name of the FormEngine to use (e.g. based on the parsed XML, or bound to the FormHandler type), unless one is specified explicitly.
• FormEngine should be responsible for form rendering and submission.
• Perhaps have FormEngine parameterized on the subtype of (Start/Task)FormData, so FormHandler can easily pass additional data to the FormEngine it chose.

I think this would be a cleaner seperation of concerns, making the functionality easier to understand and extend.

I said:

In the short term, a small enhancement would solve my primary issue: support the possibility to specify a default FormHandler-factory* in the ProcessEngineConfiguration.

but while working on a PR for this, this turned out have more impact than I initially thought, because there's no clear access path from BpmnParse to the ProcessEngineConfiguration.

So I'm now working on the bug concerning the faulty interaction between ParseListeners and FormHandlers instead, which I probably should have in the first place That should solve my primary issue.

Hi Marcus,

Thank you for the provided input. I just want to verify that I understood you correctly.
You decided to choose the approach to implement a ParseListener. However, you stumble upon the problem that FormHandler has already been assigned to the task when the ParseListener#parseUserTask is called.
And now you are focused on resolving this problem, is that right?