BPM: Howto configure custom form for start event?


I try to configure a custom form for the start event of a process. I implemented the ProcForm interface. Now, I found in the documentation (chapter 5.2.2 of BPM subsystem manual) that the custom form has to be configured inside a file bpm-app.xml (app property bpm.formsConfig). I have several questions concerning this:

  1. Do I have to insert the bpm.formsConfig property in the app.properties file of the core module?
  2. Where (in which directory) do I have to create the bpm-app.xml file?

Can anybody help me?

Thank you,


Hi, Markus!
You have to do the following steps:

  1. Create an ‘app-bpm-forms.xml’ file under the ‘src’ directory of the ‘web’ module.
  2. Define a ‘bpm.formsConfig’ property in the web-app.properties file

bpm.formsConfig = bpm-forms.xml app-bpm-forms.xml
  1. The app-bpm-forms.xml must contain your custom forms definitions, something like this:

<?xml version="1.0" encoding="UTF-8"?>
<forms xmlns="http://schemas.haulmont.com/cuba/bpm-forms.xsd">
    <form name="myCustomForm">
        <param name="myParam" value="myDefaultValue"/>

See the attached demo project that illustrates adding a custom form to the project. We will update the documentation to make things more clear.

custom-form-demo.zip (104.4K)

Hi Max,

thank you for your reply. I applied the changes you proposed, and additionally, I inserted a mapping in web-screens.xml. Now, I get an empty list when I should select a start form for a start event (only the item ‘select a form’ is available. Is there any way how I can debug what is going on, or can I take any further information from a log file? I did not find anything.
Anyhow, I tried the sample project you provided (thank you for this also). This works on my side.

Kind regards,

Hi! You can figure out what’s happening by debugging the com.haulmont.bpm.gui.app.ProcessFormRepository class. The list of available forms is build there. If you still won’t be able to find a problem, attach a small project that demonstrates how you adds a new form, I’ll take a look.

Hi Max,
thank you very much for your help. Anyhow, I did not succeed to get my form configured as start form. I attached my project here. There is only one business process defined. It is empty until now. If you drag a start event in it, and then try to set the start form for this event, you will see that the selection box for the start forms stays empty. I thought there should be two forms offered: The standard form and my AuditPrepare form. I would appreciate very much if you could have a look on my project.

Thank you very much, kind regards,

bpmTest.rar (355.5K)

You’ve duplicated the XML declaration line in your app-bpm-forms.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml version="1.0" encoding="UTF-8"?>

Just remove the one and your form will appear in the forms list.

Shame on me! Thank you very much!