Скрипты
OpenBPM Engine выполняет скрипты через script engine, совместимые с JSR-223. Интеграция протестирована с Groovy, JavaScript, JRuby и Jython. Чтобы подключить script engine, добавьте его JAR-файл в classpath.
|
В готовые дистрибутивы OpenBPM Engine входят GraalVM JavaScript и Groovy 5. Подробнее о JavaScript см. раздел Особенности JavaScript. |
В таблице перечислены BPMN-элементы, в которых можно выполнять скрипты.
| BPMN-элемент | Поддержка скриптов |
|---|---|
Скрипт внутри скриптовой задачи |
|
Скрипт как слушатель выполнения |
|
Скрипт как слушатель задачи |
|
Скрипт как условное выражение потока управления |
|
"Все задачи, все события, транзакции, подпроцессы и коннекторы" |
Скрипт внутри маппинга входных/выходных параметров |
Скриптовые задачи
Скриптовая задача BPMN 2.0 добавляет скрипт в процесс (подробнее см. справочник BPMN 2.0).
В этом простом процессе скриптовая задача на Groovy суммирует элементы массива.
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
targetNamespace="http://openbpm.ru/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>
Для запуска процесса нужна переменная inputArray.
Map<String, Object> variables = new HashMap<String, Object>();
variables.put("inputArray", new Integer[]{5, 23, 42});
runtimeService.startProcessInstanceByKey("process", variables);
Скрипты как слушатели выполнения
Слушатель выполнения можно реализовать Java-кодом, выражением или скриптом. Общие сведения о слушателях выполнения см. в соответствующем разделе.
Чтобы использовать скрипт как слушатель выполнения, добавьте элемент camunda:script в элемент
camunda:executionListener. Во время вычисления скрипта доступна переменная execution,
которая реализует интерфейс DelegateExecution.
Пример скриптов в роли слушателей выполнения:
<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>
Скрипты как слушатели задач
Слушатель задачи тоже можно реализовать скриптом. Общие сведения о слушателях задач см. в соответствующем разделе.
Чтобы использовать скрипт как слушатель задачи, добавьте элемент camunda:script в элемент
camunda:taskListener. Внутри скрипта доступна переменная task, которая реализует
интерфейс DelegateTask.
Пример скриптов в роли слушателей задачи:
<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>
Скрипты как условия
В conditionExpression условного потока управления вместо выражения можно использовать скрипт.
Для этого укажите язык скрипта в атрибуте language элемента conditionExpression. Исходный код
скрипта, как и выражение, задается текстовым содержимым элемента. Кроме того, исходный код можно
загрузить из внешнего источника, как описано в разделе Источник скрипта.
Пример скриптов в роли условий. Переменная Groovy status здесь означает
переменную процесса, доступную внутри скрипта.
<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>
Скрипты как входные и выходные параметры
Элемент расширения inputOutput позволяет вычислить значение inputParameter или outputParameter
скриптом. В примере ниже Groovy-скрипт из предыдущего примера присваивает
переменной x значение переменной Groovy sum, и затем x использует Java Delegate.
|
Значением параметра становится результат последнего выражения скрипта. Так работают Groovy,
JavaScript и JRuby, но не Jython. В Jython скрипт должен состоять из одного выражения,
например |
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:camunda="http://camunda.org/schema/1.0/bpmn"
targetNamespace="http://openbpm.ru/example">
<process id="process" isExecutable="true">
<startEvent id="start"/>
<sequenceFlow id="sequenceFlow1" sourceRef="start" targetRef="task"/>
<serviceTask id="task" camunda:class="io.openbpm.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>
Когда скрипт вычислит sum, переменную x можно использовать в коде
Java Delegate.
public class SumDelegate implements JavaDelegate {
public void execute(DelegateExecution execution) throws Exception {
Integer x = (Integer) execution.getVariable("x");
// ваш код
}
}
Исходный код скрипта также можно загрузить из внешнего ресурса, как описано для скриптовой задачи.
<camunda:inputOutput>
<camunda:inputParameter name="x">
<camunda:script scriptFormat="groovy" resource="org/camunda/bpm/example/sum.groovy"/>
</camunda:inputParameter>
</camunda:inputOutput>
Кеширование script engine
Каждый раз, когда нужно выполнить скрипт, процессный движок ищет script engine по имени языка. По умолчанию при первом запросе создается новый script engine. Если script engine объявляет себя потокобезопасным, движок его кеширует и не создает новый экземпляр при каждом запросе для того же языка.
По умолчанию script engine кешируются на уровне процессного приложения: у каждого процессного приложения свой экземпляр script engine для каждого языка. Если установить флаг конфигурации процессного движка enableFetchScriptEngineFromProcessApplication в false, script engine будут кешироваться глобально на уровне процессного движка и станут общими для всех процессных приложений. Подробнее о флаге enableFetchScriptEngineFromProcessApplication см. в разделе Классы процессного приложения в скриптах.
Чтобы полностью отключить кеширование script engine, установите флаг конфигурации процессного движка enableScriptEngineCaching в false.
Компиляция скриптов
Перед выполнением большинство script engine компилируют исходный код скрипта в Java-класс или
в другой промежуточный формат. Script engine, реализующие Java-интерфейс Compilable,
позволяют получить и закешировать результат компиляции. По умолчанию процессный движок
проверяет, поддерживает ли script engine компиляцию. Если поддерживает и кеширование script engine включено,
скрипт компилируется, а результат компиляции кешируется. Так исходный код не компилируется заново
при каждом выполнении одной и той же скриптовой задачи.
Компиляция скриптов включена по умолчанию. Чтобы ее отключить, установите флаг конфигурации процессного движка enableScriptCompilation в false.
Загрузка script engine
Если флаг конфигурации процессного движка enableFetchScriptEngineFromProcessApplication установлен в true, script engine можно загружать и из classpath процессного приложения. Для этого упакуйте script engine как библиотеку внутри процессного приложения. Можно также установить script engine глобально.
Настройка script engine
Большинство script engine позволяют настраивать, как выполняются скрипты. Перед выполнением кода процессный движок применяет к поддерживаемым script engine следующие настройки по умолчанию:
| Script engine | Настройка по умолчанию |
|---|---|
GraalVM JavaScript |
Разрешены доступ к хост-среде (host access) и поиск хост-классов (host class lookup): параметры |
Groovy |
Скомпилированные скрипты хранят только слабые ссылки (weak) на Java-методы: параметр |
Помимо настроек по умолчанию, script engine можно настроить так:
-
задать флаги конфигурации процессного движка для конкретного script engine;
-
передать системные свойства (system properties) конкретного script engine;
-
предоставить собственную реализацию интерфейса
ScriptEngineResolver.
Для JavaScript можно выбрать script engine в зависимости от окружения. Подробнее см. раздел Особенности JavaScript.
Флаги процессного движка
На настройку отдельных script engine влияют следующие флаги конфигурации процессного движка:
-
configureScriptEngineHostAccess: доступны ли скрипту ресурсы хост-языка, например классы и их методы;
-
enableScriptEngineLoadExternalResources: можно ли загружать внешние ресурсы из файловой системы;
-
enableScriptEngineNashornCompatibility: включен ли в GraalVM JavaScript режим совместимости с Nashorn.
Системные свойства
Некоторые script engine настраиваются через собственные системные свойства. Доступные параметры описаны в руководстве разработчика конкретного script engine. Набор поддерживаемых параметров может меняться от версии к версии.
Системные свойства задаются программно через System.setProperty(parameter, value) или как аргументы JVM,
например -Dparameter=value при запуске приложения из командной строки. Tomcat принимает аргументы JVM через переменные окружения JAVA_OPTS или JAVA_OPTIONS.
Как передать аргументы JVM в ваш сервер приложений, см. в его документации. OpenBPM Engine Run тоже принимает
аргументы JVM через переменную окружения JAVA_OPTS.
Собственный ScriptEngineResolver
Для настройки script engine можно написать собственную реализацию ScriptEngineResolver. В зависимости от script engine
этот способ дает больше возможностей. Подключите свой resolver к конфигурации движка
методом #setScriptEngineResolver(ScriptEngineResolver).
Если достаточно донастроить уже созданный экземпляр script engine, унаследуйтесь от io.openbpm.bpm.engine.impl.scripting.engine.DefaultScriptEngineResolver
и переопределите метод #configureScriptEngines(String, ScriptEngine). В нем можно изменить настройки
переданного экземпляра script engine:
public class CustomScriptEngineResolver extends DefaultScriptEngineResolver {
public CustomScriptEngineResolver(ScriptEngineManager scriptEngineManager) {
super(scriptEngineManager);
}
protected void configureScriptEngines(String language, ScriptEngine scriptEngine) {
super.configureScriptEngines(language, scriptEngine);
if (ScriptingEngines.GROOVY_SCRIPTING_LANGUAGE.equals(language)) {
// скомпилированные Groovy-скрипты хранят мягкие (soft) ссылки на Java-методы
scriptEngine.getContext().setAttribute("#jsr223.groovy.engine.keep.globals", "soft", ScriptContext.ENGINE_SCOPE);
}
}
}
Для более гибкой настройки переопределите метод, стоящий выше в цепочке создания script engine, или напишите собственную реализацию интерфейса. В следующем примере создается собственный экземпляр GraalVM JavaScript с включенным режимом совместимости с Nashorn:
public class CustomScriptEngineResolver extends DefaultScriptEngineResolver {
public CustomScriptEngineResolver(ScriptEngineManager scriptEngineManager) {
super(scriptEngineManager);
}
@Override
protected void configureGraalJsScriptEngine(ScriptEngine scriptEngine) {
// ничего не делать
}
@Override
protected ScriptEngine getJavaScriptScriptEngine(String language) {
return com.oracle.truffle.js.scriptengine.GraalJSScriptEngine.create(null,
org.graalvm.polyglot.Context.newBuilder("js")
// разрешить GraalVM JS доступ к хост-среде и поиск классов
.allowHostClassLookup(s -> true)
// включить режим совместимости с Nashorn
.allowExperimentalOptions(true)
.option("js.nashorn-compat", "true"));
}
}
Классы процессного приложения в скриптах
Скрипт может обращаться к классам процессного приложения, если импортирует их, как в этом Groovy-скрипте:
import my.process.application.CustomClass
sum = new CustomClass().calculate()
execution.setVariable('sum', sum)
Чтобы избежать проблем с загрузкой классов во время выполнения скрипта, рекомендуется установить флаг конфигурации процессного движка enableFetchScriptEngineFromProcessApplication в true.
Флаг enableFetchScriptEngineFromProcessApplication действует только при работе с общим процессным движком.
Переменные, доступные во время выполнения скрипта
Во время выполнения скрипта доступны все переменные процесса, видимые в текущей области видимости (scope).
К ним можно обращаться прямо по имени (например, sum). Исключение составляет
JRuby: в нем переменная доступна как глобальная переменная Ruby с префиксом $
(например, $sum).
Кроме того, доступны специальные переменные:
-
executionдоступна всегда, если скрипт выполняется в области видимости выполнения, например в скриптовой задаче (DelegateExecution). -
taskдоступна, если скрипт выполняется в области видимости задачи, например в слушателе задачи (DelegateTask). -
connectorдоступна, если скрипт выполняется в области видимости переменных коннектора, например вoutputParameterэлементаcamunda:connector(ConnectorVariableScope).
Эти переменные реализуют интерфейсы DelegateExecution, DelegateTask и ConnectorVariableScope
соответственно. Через них можно читать и устанавливать переменные или обращаться к сервисам процессного движка.
// прочитать переменную процесса
sum = execution.getVariable('x')
// установить переменную процесса
execution.setVariable('y', x + 15)
// получить TaskService и найти задачу
task = execution.getProcessEngineServices().getTaskService()
.createTaskQuery()
.taskDefinitionKey("task")
.singleResult()
Доступ к сервисам процессного движка из скриптов
Java API OpenBPM Engine дает доступ к сервисам процессного движка, и к этим сервисам можно обращаться из скриптов:
Пример корреляции BPMN-сообщения с ключом work:
execution.getProcessEngineServices().getRuntimeService().createMessageCorrelation("work").correlateWithResult();
Вывод в консоль из скриптов
Для логирования и отладки скрипт может выводить сообщения в консоль.
Примеры для разных языков:
-
Groovy:
println 'This prints to the console'
-
JavaScript:
var system = java.lang.System;
system.out.println('This prints to the console');
Источник скрипта
Обычно исходный код скрипта записывают прямо в XML-файл BPMN-модели. OpenBPM Engine поддерживает и другие способы.
Для любого языка скриптов, кроме языка выражений, источник скрипта можно задать выражением, которое возвращает исполняемый исходный код. Тогда исходный код может храниться, например, в переменной процесса.
В следующем фрагменте процессный движок вычисляет выражение ${sourceCode} в
текущем контексте при каждом выполнении элемента.
<!-- в скриптовой задаче -->
<scriptTask scriptFormat="groovy">
<script>${sourceCode}</script>
</scriptTask>
<!-- в слушателе выполнения -->
<camunda:executionListener>
<camunda:script scriptFormat="groovy">${sourceCode}</camunda:script>
</camunda:executionListener>
<!-- в условном выражении -->
<sequenceFlow id="flow" sourceRef="theStart" targetRef="theTask">
<conditionExpression xsi:type="tFormalExpression" language="groovy">
${sourceCode}
</conditionExpression>
</sequenceFlow>
<!-- в маппинге входных/выходных параметров -->
<camunda:inputOutput>
<camunda:inputParameter name="x">
<camunda:script scriptFormat="groovy">${sourceCode}</camunda:script>
</camunda:inputParameter>
</camunda:inputOutput>
Кроме того, у элементов scriptTask и conditionExpression можно указать атрибут camunda:resource,
а у элемента camunda:script атрибут resource. Этот атрибут расширения задает путь к внешнему ресурсу
с исходным кодом скрипта. К пути можно добавить схему в стиле URL, чтобы указать,
где лежит ресурс: в развертывании или в classpath.
По умолчанию ресурс ищется в classpath, поэтому первые два элемента
scriptTask в следующем примере эквивалентны.
<!-- в скриптовой задаче -->
<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"/>
<!-- в слушателе выполнения -->
<camunda:executionListener>
<camunda:script scriptFormat="groovy" resource="deployment://org/camunda/bpm/listener.groovy"/>
</camunda:executionListener>
<!-- в conditionExpression -->
<conditionExpression xsi:type="tFormalExpression" language="groovy"
camunda:resource="org/camunda/bpm/condition.groovy" />
<!-- в inputParameter -->
<camunda:inputParameter name="x">
<camunda:script scriptFormat="groovy" resource="org/camunda/bpm/mapX.groovy" />
</camunda:inputParameter>
Путь к ресурсу можно задать и выражением, которое вычисляется при запуске скриптовой задачи.
<scriptTask scriptFormat="groovy" camunda:resource="${scriptPath}"/>
Подробнее см. описание атрибута camunda:resource в разделе Расширения.
Особенности JavaScript
В поддерживаемых версиях Java нет встроенного script engine для JavaScript, поэтому в готовые дистрибутивы OpenBPM Engine входит GraalVM JavaScript.
Если этот script engine доступен, процессный движок выполняет JavaScript-код через него.
Если он не найден, движок использует любой другой script engine, зарегистрированный в JVM для языка javascript или ecmascript.
Свойство конфигурации процессного движка scriptEngineNameJavaScript задает script engine для языков javascript и ecmascript.
Если script engine с указанным именем не найден, процессный движок не ищет замену и выбрасывает исключение.
Подробнее о GraalVM JavaScript см. в официальном руководстве GraalVM JavaScript. Там же есть руководство по переходу с Nashorn для скриптов, написанных под Nashorn.
Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.