Include Camunda Forms in auto-deployment by default

[alan-pilic-ca]

User Story (Required on creation)

As a software developer, I can reference Camunda Forms in my BPMN, place all relevant files inside my process application, and they are all automatically deployed by default.

Functional Requirements (Required before implementation)

• Camunda Forms are automatically deployed (just like BPMN and DMN files).

Technical Requirements (Required before implementation)

• Camunda Forms are added to the default list of automatically deployed resources.
• Camunda Forms are automatically deployed in all supported environments alike.

Limitations of Scope

Hints

• In Camunda Run, all additional resources (including Camunda Forms) are automatically deployed when placed inside the configuration/resources directory.

Links

Breakdown

Dev2QA handover

• [ ] Does this ticket need a QA test and the testing goals are not clear from the description? Add a Dev2QA handover comment

---

Original description

### Environment (Required on creation) Spring Boot Camunda C7 7.17.6-ee and 7.17 community edition ### Description (Required on creation; please attach any relevant screenshots, stacktraces, log files, etc. to the ticket) I have discovered an issue with Spring Deployment of C7 17.17.6-ee User Task Camunda forms when coupled with a simple bpmn process that links the form to a User Task. This seems to happen with the utilization of the @EnableProcessApplication annotation as well as without the annotation. The Camunda forms do not get deployed while the bpmn process does. This results in a "Form failure error" in the Task List and the form can't be completed as it is not deployed. Doing a bit more research, I have discovered that you would need to add additional properties into the process.xml file, specifically, for the @EnableProcessApplication annotation method. By doing this, Spring deploy can find the appropriate suffix for the forms which subsequently allows all .form data to be deployed. Here is the specific code that was required to be placed into the process.xml location for this to work. .form Furthermore, for the non @EnableProcessApplication method, i.e. using the @SpringBootApplication annotation, the classpath for both the bpnm and forms are required in the yaml. Mine looks something along the lines of this. deployment-resource-pattern: classpath*:**/bpmn/*, classpath*:**/forms/* I have tested this on both 7.17.6-ee as well as 7.17 community edition and this seems to be the case on both versions ### Steps to reproduce (Required on creation) 1. Create out of box Spring Boot C7 7.17.6-ee project 2. Create simple out of box BPMN process with only a Camunda User Task form 3. Create Camunda User Task form and link to process 4. Spring Deploy and you will notice that when starting the process that you receive a form failure error.     ### Observed Behavior (Required on creation) When Spring auto deploying the files, spring does not automatically deploy the form files. It is only when specific entries are added into either the yaml file or the process.xml file that spring deploys the form files. ### Expected behavior (Required on creation) Expected behavior is that when Spring auto deploys it includes the form files. ### Root Cause (Required on prioritization) Potential suffixes addition missing in this line of code; https://github.com/camunda/camunda-bpm-platform/blob/master/spring-boot-starter/starter/src/main/java/org/camunda/bpm/spring/boot/starter/property/CamundaBpmProperties.java#L47-L49 ### Solution Ideas The form properties might potentially need to be added to the CamundaBpmProperties.java entry ### Hints Example of spring boot with annotation https://github.com/alan-pilic-ca/spring-boot-test1/tree/camunda-forms-w-epa-anno Remove comments from process.xml and then run to see form failure occur and then uncomment the properties in the process.xml file to see the work around Example of spring boot without annotation https://github.com/alan-pilic-ca/spring-boot-test1/tree/camunda-forms-no-anno Run spring application to see form failure behavior and then remove comment from #deployment-resource-pattern: classpath*:**/bpmn/*, classpath*:**/forms/* in the application.yaml file to see the work around

[tmetzke]

Hi @alan-pilic-ca,

thanks for creating this. I think your report makes sense in general. Also, thanks for the detailed description, this is really helpful!

We'll give this a proper look as soon as possible and come back with proper feedback.

Best, Tobias

[jonathanlukas]

Shortcut: I would assume that when using a ProcessApplication that has resouces to deploy, this method should be adjusted:

https://github.com/camunda/camunda-bpm-platform/blob/791db13890dfe0d5785d44cac0ccd9e507592847/engine/src/main/java/org/camunda/bpm/container/impl/deployment/scanning/ProcessApplicationScanningUtil.java#L72-L76

[tmetzke]

Hi @alan-pilic-ca,

sorry for the long wait here. I had a closer look at your issue now.

While I think your idea makes sense in general, I'd like to clarify that this behavior is expected and therefore no bug. The Spring Boot documentation (look for .deployment-resource-pattern) states that the auto-deployed resources are limited to the following by default:

classpath*:**/*.bpmn,
classpath*:**/*.bpmn20.xml,
classpath*:**/*.dmn,
classpath*:**/*.dmn11.xml,
classpath*:**/*.cmmn,
classpath*:**/*.cmmn10.xml,
classpath*:**/*.cmmn11.xml

Furthermore, the User Task Forms guide states the following:

Can be either deployment or app: deployment: The file is part of your deployment (e.g., by adding it to your process archive or by deploying from the Camunda Modeler), [...]

So, task forms deployment (no matter if HTML, Javascript, or Camunda Form) has to be done manually via engine configuration (if auto-deployment is required) or via the Camunda Modeler. This has also been discussed in the forum in the following threads:

• https://forum.camunda.io/t/auto-deployment-of-camunda-forms/27597
• https://forum.camunda.io/t/form-failure-no-camunda-form-definition-was-found/30906

That being said, note that Camunda BPM Run brings auto-deployment of all resources as a built-in convenience feature. This is however specific to Camunda Run to allow for a convenient getting-started experience. Developing your own engine application with Spring Boot, you are free to include such a feature as well or use the configuration options that are described in the documentation as linked above.

If you like, we can take this up as a feature request. For transparency, I want to highlight that this topic might be more complex than it looks initially: First of all, the behavior should be consistent for all distributions that Camunda 7 supports (including Spring Boot, enterprise application servers, Quarkus, and more). Plus, it has to be decided if this should only account for Camunda Forms or also HTML forms, Javascript forms, and other resources like scripts. All of those additional resources are not included by default to avoid unexpected results.

I am happy for any feedback that you have regarding this topic and assessment.

Cheers, Tobias

[jonathanlukas]

Hello @tmetzke ,

as Camunda Forms are only accessible as deployed resource AND they are from Camunda, it would indeed make sense to have them included to process application deployments by default.

This would work by adjusting the Code marked above and would affect all distributions using the Process Application pattern.

As alternative, you could create a Camunda 7 specific "Heads up" section that states the workarounds:

• manual deployment
• Adjusting the processes.xml (basically copy the default one and add a property additionalResourceSuffixes) which is documented here
• Using distribution-specific pattern like spring-boot auto-deployment

Hint on consistency across platforms: Users that utilize Camunda-Run do not have the problem as there is a better deployment pattern

[tmetzke]

Thanks for the feedback, @jonathanlukas 👍

I definitely agree that it would make sense to include them. I am not entirely sure if the code you reference is actually enough as Spring Boot applications might handle this a bit differently, for example. But as I said, I don't know for sure. But this is exactly what I mean: we need to ensure that this works the same for all environments which doesn't come for free.

Regarding the heads-up section, where would you like to see this in the documentation specifically? In the Camunda Forms guide?

Cheers, Tobias

[jonathanlukas]

Hello @tmetzke ,

I would actually create a "Heads up" section in the "Deployment" section of the proposed page.

[tmetzke]

Hi @jonathanlukas and @alan-pilic-ca,

thanks again for your input here. I adjusted this issue to be a feature request rather than a bug.

The described behavior itself is expected and therefore not a bug. Plus, there are documented ways of getting the Camunda Forms auto-deployed (just like any other additional resource like scripts). I proposed an additional hint in the documentation with https://github.com/camunda/camunda-bpm-platform/issues/3216.

We will prioritize this in our backlog accordingly. The attached PR definitely helps here to speed up things. Let me know if you have any further questions.

Best, Tobias