Deploying External Scripts with Camunda REST API

Use the Camunda REST API to deploy external scripts used by BPMN processes

5 min readJun 9, 2016

At DigitalState, we use Camunda as a BPMN engine and a rapid prototyping tool to experiment with government online service business processes and design patterns.

One of the most common use cases we see is having to reuse the same forms and scripts across different processes. In government, this comes up often because of the many services that have nearly identical user experiences: how we collect contact information location of issues, mailing address, etc. So rather than having to rebuild these for every service example, we have have assets we reuse. When we prototype digital public services, the goal is to put a quality demonstration of a service’s business process in front of government a quickly as possible and so we reuse a lot of assets.

In Camunda, you can use scripts embedded in a process, as external files on a per deployment basis, or as a shared resource available across many processes. In this example, we want to leverage the per deployment capability as our prototypes are always changing and it should remain as simple as possible to deploy new or updated processes with modifications to related scripts.

Configure the process

Using a simplified example, lets look at the following scenario:

This process collects a String/text in the Start Event, that string is passed into the the Script Task, and outputs the String as a Double Number Type. The number is then presented to the user in the Review Parsed Value user task.

Collect string to parse — Start Event Configuration:

Form Field:
ID: jsonString
Type: string
Label: String to be Parsed into JSON Object

The Start Event has a form attached as a Generated User Task Form. The process variable that will be created when the process starts will be called jsonString and will be a the data type String. The process variable’s name is determined by the ID field of the form field.

Parse String — Script Task Configuration

Details:
Script Format: JavaScript
Script Type: External Resource
Resource: deployment://parseScript.js
Result Variable: jsonParsed

The Script task is configured to use the script format JavaScript, and the script type is External Resource.

The Resource field has the following format:

deployment://parseScript.js

Where parseScript.js is the name of the script (filename) that we will deploy to the Camunda server. The Result Variable field is used to store the returned value from the script.

Review Parsed Value — User Task Configuration

Form Field:
ID: returnedPrasedValue
Type: string
Label: Returned Number
Default Value: ${jsonParsed}

Set the Form Type to Form Data. This will allow you to use Camunda’s Generated User Task Forms.

Use the “+” button below the Validation section to add a validation constraint. The validation should be configured as:

Validation:
Name: readonly

You leave the config field value blank when using the readonly validation. The readonly validation will make the form field un-editable and makes sure no input is submitted for given form field.

Deploying and Running the Process and Script

Create the following JavaScript file

praseScript.js: the file name matches the file name in the Resource field when configuring the Script Task.

// fetch execution variable called jsonString
var inputString = execution.getVariable(“jsonString”);// parse response variable with camunda-spin, 
// use the Number() function to convert the string 
// to a javascript Number
Number(S(inputString).prop(“q”).value());

The execution.getVariable() function allows the JavaScript access to the Process instance variables.

The Number() function is a javascript function that converts to JavaScript number type.

The string we are going to use in this example is string of JSON:

{"q":"12345"}

S() is the Camunda Spin function that parses JSON. see the Spin documentation on further usage of the .prop(), .value() and other related functions for reading and writing JSON.

Deploying the Process and Script

In order to use the External Script, you need to deploy the script with the process:

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

curl -w \
 -H “Accept: application/json” \
 http://LocationOfCamundaServer:8080/camunda/app/cockpit

Once curl has successfully logged in, Deploy the BPMN and JavaScript 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 \
-H “Accept: application/json” \
-F “deployment-name=rest-test” \
-F “enable-duplicate-filtering=false” \
-F “deploy-changed-only=falses” \
-F “ExternalScriptExample.bpmn=@/PATH_TO_BPMN_File/ExternalScriptExample.bpmn” \
-F “parseScript.js=@/PATH_TO_SCRIPT/parseScript.js” \
http://LocationOfCamundaServer:8080/engine-rest/deployment/create