Deploying Embedded Forms with Camunda REST API

Use the Camunda REST API to deploy Embedded Forms used by BPMN processes

Building on my previous post covering how to deploy external scripts to Camunda using Camunda’s Rest API, the API also supports the ability to deploy embedded forms alongside the BPMN process.

Embedded Forms are accessible inside of Camunda’s Tasklist web app. At DigitalState, we use embedded forms to quickly prototype new government business processes and provide interactive demos of how a As-Is business process can be transformed into a To-Be Process. These To-Be processes are then used in DigitalState’s platform to allow governments to easily build, manage, and deliver online service, or as we like to call them: Digital Public Services.

Deploying an external script and deploying an embedded form are very similar with a few exceptions. If you have not read the previous post about deploying External Scripts with Camunda’s Rest API, I suggest you quickly read that first.

Configuring a Embedded Form

We will be using Camunda Modeler to build and configure our BPMN process. Camunda’s embedded forms can be accessed though Start Events and User Tasks. In this example we will use User Tasks. Lets look at a simple process:

Select the user task and in the Properties Panel in the Forms tab configure the User Task:

Form Type: Form Key
Form Key: embedded:deployment:sampleEmbeddedForm.html

The Form Key field is the crucial component that makes all the magic happen. ‘embedded:deployment:’ tells the Tasklist how and where to access the form. In this case, that it is a embedded form, and it will be located in the deployment files related to the process.

The sampleEmbeddedForm.html file is where we keep our form HTML that will be rendered by Camunda’s Tasklist web app.

Building the Embedded Form File (sampleEmbeddedForm.html)

We need to create the sampleEmbeddedForm.html file so when the User Task calls embedded:deployment:sampleEmbeddedForm.html, Camunda will have a form to render in the Tasklist.

Create a file called: sampleEmbeddedForm.html with the following content:

<form role=”form” name=”form”>
 <div class=”form-group”>
  <label for=”customerId-field”>Customer ID</label>
  <input required
    cam-variable-name=”customerId”
    cam-variable-type=”String”
    class=”form-control” />
 </div>
 <div class=”form-group”>
  <label for=”amount-field”>Amount</label>
  <input cam-variable-name=”amount”
    cam-variable-type=”Double”
    class=”form-control” />
 </div>
</form>

This is a simple example with two fields: Customer ID and Amount. See the Camunda Form SDK documentation and Embedded Forms documentation for further information about how to build Embeddable Forms and leverage the JavaScript API. Note the cam-variable-name, and cam-variable-type html attributes. These attributes tell the Camunda JavaScript SDK to load or create the Camunda process variables when the form is rendered and submitted. If you do not have these attributes in your HTML, when the form loads or submits, Camunda will not know about the form fields or what to do with the form content.

Deploying the Process and Embedded Form

In order to use the Embedded Form, you need to deploy the form with the process. The following process is the same as deploying external scripts. You can add additional processes, forms, and scripts to the deployment as required.

Login to Camunda cockpit through Curl in terminal with the following command. Add the URL to the Camunda Server, Username and Password to their appropriate locations in the curl command.

curl -w “\n” — cookie-jar cookie.txt \
 -H “Accept: application/json” \
 -d “username=USERNAME_GOES_HERE” \
 -d “password=PASSWORD_GOES_HERE” \
 http://LocationOfCamundaServer:8080/camunda/app/cockpit

Once curl has successfully logged in, Deploy the BPMN and HTML file as part of the same Deployment by running the following curl command in terminal. Add your url to the the Camunda server, and the paths for the BPMN and Javascript files.

curl -w “\n” — cookie cookie.txt \
-H “Accept: application/json” \
-F “deployment-name=rest-test” \
-F “enable-duplicate-filtering=false” \
-F “deploy-changed-only=falses” \
-F “EmbeddedFormExample.bpmn=@/PATH_TO_BPMN_File/EmbeddedFormExample.bpmn” \
-F “sampleEmbeddedForm.html=@/PATH_TO_SCRIPT/sampleEmbeddedForm.html” \
http://LocationOfCamundaServer:8080/engine-rest/deployment/create

Example Files

You can download the BPMN and HTML Form example files here