Camunda Platform supports scripting with JSR-223 compatible script engine implementations. Currently we test the integration for Groovy, JavaScript, JRuby and Jython. To use a scripting engine it is necessary to add the corresponding jar to the classpath.

The following table provides an overview of the BPMN elements which support the execution of scripts.

BPMN element	Script support
Script Task	Script inside a script task
Processes, Activities, Sequence Flows, Gateways and Events	Script as an execution listener
User Tasks	Script as a task listener
Sequence Flows	Script as condition expression of a sequence flow
All Tasks, All Events, Transactions, Subprocesses and Connectors	Script inside an inputOutput parameter mapping

Use Script Tasks

With a BPMN 2.0 script task you can add a script to your BPM process (for more information see the BPMN 2.0 reference.

The following process is a simple example with a Groovy script task that sums up the elements of an array.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
                   targetNamespace="http://camunda.org/example">
  <process id="process" isExecutable="true">
    <startEvent id="start"/>
    <sequenceFlow id="sequenceFlow1" sourceRef="start" targetRef="task"/>
    <scriptTask id="task" name="Groovy Script" scriptFormat="groovy">
      <script>
        <![CDATA[
        sum = 0

        for ( i in inputArray ) {
          sum += i
        }

        println "Sum: " + sum
        ]]>
      </script>
    </scriptTask>
    <sequenceFlow id="sequenceFlow2" sourceRef="task" targetRef="end"/>
    <endEvent id="end"/>
  </process>
</definitions>

To start the process, a variable inputArray is necessary.

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("inputArray", new Integer[]{5, 23, 42});
runtimeService.startProcessInstanceByKey("process", variables);

Use Scripts as Execution Listeners

Besides Java code and expression language, Camunda Platform also supports the execution of a script as an execution listener. For general information about execution listeners see the corresponding section.

To use a script as an execution listener, a camunda:script element has to be added as a child element of the camunda:executionListener element. During script evaluation, the variable execution is available, which corresponds to the DelegateExecution interface.

The following example shows usage of scripts as execution listeners.

<process id="process" isExecutable="true">
  <extensionElements>
    <camunda:executionListener event="start">
      <camunda:script scriptFormat="groovy">
        println "Process " + execution.eventName + "ed"
      </camunda:script>
    </camunda:executionListener>
  </extensionElements>

  <startEvent id="start">
    <extensionElements>
      <camunda:executionListener event="end">
        <camunda:script scriptFormat="groovy">
          println execution.activityId + " " + execution.eventName + "ed"
        </camunda:script>
      </camunda:executionListener>
    </extensionElements>
  </startEvent>
  <sequenceFlow id="flow1" startRef="start" targetRef="task">
    <extensionElements>
      <camunda:executionListener>
        <camunda:script scriptFormat="groovy" resource="org/camunda/bpm/transition.groovy" />
      </camunda:executionListener>
    </extensionElements>
  </sequenceFlow>

  <!--
    ... remaining process omitted
  -->
</process>

Use Scripts as Task Listeners

Similar to execution listeners, task listeners can also be implemented as scripts. For general information about task listeners see the corresponding section.

To use a script as a task listener, a camunda:script element has to be added as a child element of the camunda:taskListener element. Inside the script, the variable task is available, which corresponds to the DelegateTask interface.

The following example shows usage of scripts as task listeners.

<userTask id="userTask">
  <extensionElements>
    <camunda:taskListener event="create">
      <camunda:script scriptFormat="groovy">println task.eventName</camunda:script>
    </camunda:taskListener>
    <camunda:taskListener event="assignment">
      <camunda:script scriptFormat="groovy" resource="org/camunda/bpm/assignemnt.groovy" />
    </camunda:taskListener>
  </extensionElements>
</userTask>

Use Scripts as Conditions

As an alternative to expression language, Camunda Platform allows you to use scripts as conditionExpression of conditional sequence flows. To do that, the language attribute of the conditionExpression element has to be set to the desired scripting language. The script source code is the text content of the element, as with expression language. Another way to specify the script source code is to define an external source as described in the script source section.

The following example shows usage of scripts as conditions. The Groovy variable status is a process variable which is available inside the script.

<sequenceFlow>
  <conditionExpression xsi:type="tFormalExpression" language="groovy">
    status == 'closed'
  </conditionExpression>
</sequenceFlow>

<sequenceFlow>
  <conditionExpression xsi:type="tFormalExpression" language="groovy"
      camunda:resource="org/camunda/bpm/condition.groovy" />
</sequenceFlow>

Use Scripts as inputOutput Parameters

With the Camunda inputOutput extension element you can map an inputParameter or outputParameter with a script. The following example process uses the Groovy script from the previous example to assign the Groovy variable sum to the process variable x for a Java delegate.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
                   xmlns:camunda="http://activiti.org/bpmn"
                   targetNamespace="http://camunda.org/example">
  <process id="process" isExecutable="true">
    <startEvent id="start"/>
    <sequenceFlow id="sequenceFlow1" sourceRef="start" targetRef="task"/>
    <serviceTask id="task" camunda:class="org.camunda.bpm.example.SumDelegate">
      <extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="x">
             <camunda:script scriptFormat="groovy">
              <![CDATA[

              sum = 0

              for ( i in inputArray ) {
                sum += i
              }

              sum
              ]]>
            </camunda:script>
          </camunda:inputParameter>
        </camunda:inputOutput>
      </extensionElements>
    </serviceTask>
    <sequenceFlow id="sequenceFlow2" sourceRef="task" targetRef="end"/>
    <endEvent id="end"/>
  </process>
</definitions>

After the script has assigned a value to the sum variable, x can be used inside the Java delegate code.

public class SumDelegate implements JavaDelegate {

  public void execute(DelegateExecution execution) throws Exception {
    Integer x = (Integer) execution.getVariable("x");

    // do something
  }

}

The script source code can also be loaded from an external resource in the same way as described for script tasks.

<camunda:inputOutput>
  <camunda:inputParameter name="x">
     <camunda:script scriptFormat="groovy" resource="org/camunda/bpm/example/sum.groovy"/>
  </camunda:inputParameter>
</camunda:inputOutput>

Script Engine Caching

Whenever the process engine reaches a point where a script has to be executed, the process engine looks for a Script Engine by a language name. The default behavior is that if it is the first request, a new Script Engine is created. If the Script Engine declares to be thread safe, it is also cached. The caching prevents the process engine from creating a new Script Engine for each request for the same script language.

By default the caching of Script Engines happens at process application level. Each process application holds an own instance of a Script Engine for a given language. This behavior can be disabled by setting the process engine configuration flag named enableFetchScriptEngineFromProcessApplication to false. Consequently, the Script Engines are cached globally at process engine level and they are shared between each process application. For further details about the process engine configuration flag enableFetchScriptEngineFromProcessApplication, please read the section about referencing process application classes.

If it is not desired to cache Script Engines in general, it can be disabled by setting the process engine configuration flag name enableScriptEngineCaching to false.

Script Compilation

Most script engines compile script source code either to a Java class or to a different intermediary format prior to executing the script. Script engines implementing the Java Compilable interface allow programs to retrieve and cache the script compilation. The default setting of the process engine is to check if a Script Engine supports the compile feature. If true and the caching of Script Engines is enabled, the script engine compiles the script and then caches the compilation result. This prevents the process engine from compiling a script source each time the same script task is executed.

By default, compilation of scripts is enabled. If you need to disable script compilation, you can set the process engine configuration flag named enableScriptCompilation to false.

Load Script Engine

If the process engine configuration flag named enableFetchScriptEngineFromProcessApplication is set to true, it is also possible to load Script Engines from the classpath of the process application. For that, the Script Engine can be packaged as a library within the process application. It is also possible to install the Script Engine globally.

In case the Script Engine module should be installed globally and JBoss is used, it is necessary to add a module dependency to the Script Engine. This can be done by adding a jboss-deployment-structure.xml to the process application, e.g.,:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="org.codehaus.groovy.groovy-all"
              services="import" />
    </dependencies>
  </deployment>
</jboss-deployment-structure>

Reference Process Application Provided Classes

The script can reference to process application provided classes by importing them like in the following groovy script example.

import my.process.application.CustomClass

sum = new CustomClass().calculate()
execution.setVariable('sum', sum)

To avoid possible class loading problems during the script execution, it is recommended to set the process engine configuration flag name enableFetchScriptEngineFromProcessApplication to true.

Be aware that the process engine flag enableFetchScriptEngineFromProcessApplication is only relevant in a shared engine scenario.

Variables Available During Script Execution

During the execution of scripts, all process variables visible in the current scope are available. They can be accessed directly by the name of the variable (i.e., sum). This does not apply for JRuby where you have to access the variable as a ruby global variable (prepend with a dollar sign, i.e., $sum)

There are also special variables:

1. execution, which is always available if the script is executed in an execution scope (e.g., in a script task) (DelegateExecution).
2. task, which is available if the script is executed in a task scope (e.g., a task listener) (DelegateTask).
3. connector, which is available if the script is executed in a connector variable scope (e.g., outputParameter of a camunda:connector) (ConnectorVariableScope).

These variables correspond to the DelegateExecution, DelegateTask or resp. ConnectorVariableScope interface which means that it can be used to get and set variables or access process engine services.

// get process variable
sum = execution.getVariable('x')

// set process variable
execution.setVariable('y', x + 15)

// get task service and query for task
task = execution.getProcessEngineServices().getTaskService()
  .createTaskQuery()
  .taskDefinitionKey("task")
  .singleResult()

Accessing Process Engine Services using Scripts

Camunda’s Java API provides access to Camunda’s process engine services; these services can be accessed using Scripts:

Process Engine Services Public Java API of Camunda Platform Engine

Example of creating a BPMN Message that correlates with the message key “work”:

execution.getProcessEngineServices().getRuntimeService().createMessageCorrelation("work").correlateWithResult();

Printing to Console using Scripts

During the execution of scripts, it might be desired to print to the console due to logging and debugging reasons.

Here are examples on how this can be accomplished in the respective language:

• Groovy:

println 'This prints to the console'

• Javascript:

var system = java.lang.System;
system.out.println('This prints to the console');

Script Source

The standard way to specify the script source code in the BPMN XML model is to add it directly to the XML file. Nonetheless, Camunda Platform provides additional ways to specify the script source.

If you use another scripting language than Expression Language, you can also specify the script source as an expression which returns the source code to be executed. This way, the source code can, for example, be contained in a process variable.

In the following example snippet the process engine will evaluate the expression ${sourceCode} in the current context every time the element is executed.

<!-- inside a script task -->
<scriptTask scriptFormat="groovy">
  <script>${sourceCode}</script>
</scriptTask>

<!-- as an execution listener -->
<camunda:executionListener>
  <camunda:script scriptFormat="groovy">${sourceCode}</camunda:script>
</camunda:executionListener>

<!-- as a condition expression -->
<sequenceFlow id="flow" sourceRef="theStart" targetRef="theTask">
  <conditionExpression xsi:type="tFormalExpression" language="groovy">
    ${sourceCode}
  </conditionExpression>
</sequenceFlow>

<!-- as an inputOutput mapping -->
<camunda:inputOutput>
  <camunda:inputParameter name="x">
    <camunda:script scriptFormat="groovy">${sourceCode}</camunda:script>
  </camunda:inputParameter>
</camunda:inputOutput>

You can also specify the attribute camunda:resource on the scriptTask and conditionExpression element, respectively the resource attribute on the camunda:script element. This extension attribute specifies the location of an external resource which should be used as script source code. Optionally, the resource path can be prefixed with an URL-like scheme to specify if the resource is contained in the deployment or classpath. The default behaviour is that the resource is part of the classpath. This means that the first two script task elements in the following examples are equal.

<!-- on a script task -->
<scriptTask scriptFormat="groovy" camunda:resource="org/camunda/bpm/task.groovy"/>
<scriptTask scriptFormat="groovy" camunda:resource="classpath://org/camunda/bpm/task.groovy"/>
<scriptTask scriptFormat="groovy" camunda:resource="deployment://org/camunda/bpm/task.groovy"/>

<!-- in an execution listener -->
<camunda:executionListener>
  <camunda:script scriptFormat="groovy" resource="deployment://org/camunda/bpm/listener.groovy"/>
</camunda:executionListener>

<!-- on a conditionExpression -->
<conditionExpression xsi:type="tFormalExpression" language="groovy"
    camunda:resource="org/camunda/bpm/condition.groovy" />

<!-- in an inputParameter -->
<camunda:inputParameter name="x">
  <camunda:script scriptFormat="groovy" resource="org/camunda/bpm/mapX.groovy" />
</camunda:inputParameter>

The resource path can also be specified as an expression which is evaluated on the invocation of the script task.

<scriptTask scriptFormat="groovy" camunda:resource="${scriptPath}"/>

For more information, see the camunda:resource section of the Custom Extensions chapter.