camunda-community-hub / script-connector

Zeebe worker for script evaluation

Script Connector

This is a community project that provides a connector. It is not officially supported by Camunda. Everybody is invited to contribute! A connector to evaluate scripts (i.e. script tasks) that are not written in FEEL. Scripts are useful for prototyping, to do (simple) calculations, or creating/modifying variables.

Usage

Legacy

The legacy connector provides compatibility with the previous implementation zeebe-script-worker.

The context does not offer access to job or zeebeClient anymore.

Example BPMN with service task:

<bpmn:serviceTask id="scripting" name="Evaluate the Script">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="script" />
    <zeebe:taskHeaders>
      <zeebe:header key="language" value="javascript" />
      <zeebe:header key="script" value="a + b" />
      <zeebe:header key="resultVariable" value="result" />
    </zeebe:taskHeaders>
  </bpmn:extensionElements>
</bpmn:serviceTask>

• the worker is registered for the type script
• required custom headers:
  • language - the name of the script language
  • script - the script to evaluate
  • resultVariable - the result of the evaluation is passed to this variable

Connector

The connector provides an element template that can be used to configure it.

Script languages

Available script languages are by default:

• javascript (GraalVM JS)
• groovy
• mustache
• kotlin

To register new script languages, you can use the ScriptEngineFactory to register any JSR-223 compliant script engine.

If you want to provide a non-compliant implementation, you can use the ScriptEvaluatorExtension SPI.

To register custom file extensions, you can use the LanguageProviderExtension SPI.

Install

Docker

For a local setup, the repository contains a docker-compose file. It starts a Zeebe broker and both (standalone and bundled) containers.

mvn clean package
cd docker
docker-compose up

Standalone Runtime

The docker image for the connector runtime is published as GitHub package.

docker pull ghcr.io/camunda-community-hub/script-connector/runtime:latest

Configure the connection to the Zeebe broker by setting the environment property ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS (default: localhost:26500)

The docker-compose file shows an example how this works.

Bundled Runtime

To run the connector inside the bundle, you can use the shaded jar.

The docker-compose file shows an example how this works.

Manual

Standalone Runtime

1. Download the runtime jar script-connector-runtime-{VERSION}.jar
2. Start the connector runtime java -jar script-connector-runtime-{VERSION}.jar

Bundled Runtime

1. Download the shaded connector jar script-connector-{VERSION}-shaded.jar
2. Copy it to your connector runtime.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

script-connector's Issues

Providing a Docker image

Build a docker image for easier setup. Try to use GraalVM as runtime.

• https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#quickstart
• https://www.graalvm.org/docs/getting-started/#docker-containers

Update to Zeebe Client 1.0.0

I think that we need to update the zeebe libs to 1.0.0. Why the dependabot is not working?

Add support for Kotlin Scripting (JSR223)

I'm thinking about adding support for the Kotlin script. Kotlin Scripting Engine supports JSR223, see an example there: https://github.com/JetBrains/kotlin/tree/master/libraries/examples/kotlin-jsr223-local-example

Docker pull - Access denied

Having trouble pulling and/or building an image

docker pull ghcr.io/camunda-community-hub/script-connector/runtime:latest

Need help in getting the docket image running successfully.

Thanks in advance!

Evolve zeebe-script-worker to connector-script

The use case of externally executing a script is perfect for a connector.

Here are the goals I would like to achieve:

• The original configuration should still work with the new connector and runtime (a deprecation warning should be displayed somehow)
• There is a connector template in place
• The execution logic is migrated to connector-sdk
• The repo is renamed to connector-script

Create a dependabot for github-actions

Integrate Ammonite

Support scripting in Scala with Ammonite.

http://ammonite.io/#InstantiatingAmmonite

JavaScript doesn't return an Array in zeebe

When you try to return a array in zeebe using JavaScript, it doesn't return an Array. Here is an example:
return ["a", "b"];
in zeebe, it returns {"0": "a", "1": "b"};, he put the index of the array inside a json and doesn't return a array.
This only happens in JavaScript, in Groovy, it gives back the array as it is.

Remove feel script engine to reflect latest platform features

Since 8.2, zeebe can evaluate feel scripts embedded. We can safely remove the feel engine from this project.

Use GraalVM to provide more language support + es6 support

GraalVm has a larger selection of scripts languages that are supported, and their GraalJS supports es6 , so there is better node package support.

Also, specifically for JS, Graal is several times faster in execution of JS, compared to nashorn.

Introduce formatter

How to transfer？

Does our "Zeebe script worker" support parameter transfer? Similar to "Zeebe HTTP worker", it supports {{XXX}} and ${XXX}

Move to Java 17

ScriptEvaluator is not thread-safe

Cached script engines stored as a singletone Map. All the threads, reusing the same cached script engines, may bump into the problem of undesired reset of the context input variables. It happens when we have BPMN process with two parallel ScriptTasks having the same set of the input variables. It happens, that two parallel threads are initializing the engine-wide variables, which corrupts the execution of the script by unpredictable change of the variable value of the script is being already executed by other thread.
Pieces of the code causing the problem:

private final Map<String, ScriptEngine> cachedScriptEngines = new HashMap<>();
and this:

final ScriptContext context = scriptEngine.getContext();
    final Bindings bindings = context.getBindings(ScriptContext.ENGINE_SCOPE);
    bindings.putAll(variables);

Proposed solution
to make the Map ThreadLocal, guaranteeing that each instance of the cached ScriptEngines will perform one script at the time.

Update github actions

Camunda Cloud disconnected after a few hours

Hi, about an hour and a half after starting this worker to Camunda Cloud, the connection gets reseted:

13:28:01.234 [grpc-default-executor-0] INFO  io.zeebe.client.job.poller - Activated 1 jobs for worker script-worker and job type script
13:28:01.320 [pool-3-thread-1] INFO  org.camunda.feel.FeelEngine - Engine created. [value-mapper: CompositeValueMapper(List(org.camunda.feel.spi.JavaValueMapper@13e7eca1)), function-provider: org.camunda.feel.interpreter.FunctionProvider$EmptyFunctionProvider$@1f82136c]
15:03:10.551 [grpc-default-executor-1] WARN  io.zeebe.client.job.poller - Failed to activated jobs for worker script-worker and job type script
io.grpc.StatusRuntimeException: UNAVAILABLE: io exception
	at io.grpc.Status.asRuntimeException(Status.java:533) ~[grpc-api-1.26.0.jar:1.26.0]
...
Caused by: java.io.IOException: Connection reset by peer
	at sun.nio.ch.FileDispatcherImpl.read0(Native Method) ~[?:?]
...

After that, it never reconnects again. It continuously fails with:

15:03:12.599 [grpc-default-executor-0] WARN  io.zeebe.client.job.poller - Failed to activated jobs for worker script-worker and job type script
io.grpc.StatusRuntimeException: UNAUTHENTICATED: HTTP status code 401
invalid content-type: text/html
headers: Metadata(:status=401,server=nginx/1.17.7,date=Tue, 10 Mar 2020 18:03:12 GMT,content-type=text/html,content-length=179,strict-transport-security=max-age=15724800; includeSubDomains)
DATA-----------------------------
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.17.7</center>
</body>
</html>

	at io.grpc.Status.asRuntimeException(Status.java:533) ~[grpc-api-1.26.0.jar:1.26.0]
...

It uses zeebe-client-java version 0.22.1 and its configured with the following env variables:

• zeebe.client.broker.contactPoint = XXXXXXX.zeebe.camunda.io:443
• ZEEBE_INSECURE_CONNECTION= false
• ZEEBE_CLIENT_ID = XXXXXX
• ZEEBE_CLIENT_SECRET = XXXXXXX

Camunda Cloud cluster info:

• Generation: Zeebe 0.22.1
• Type: Development
• Status: Healthy

If I manually stop and start the worker again, it reconnects successfully and works as expected.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Package lookup failures

---

Warning

Renovate failed to look up the following dependencies: Failed to look up maven package io.camunda.connectors.community:script-connector-parent.

Files affected: connector/pom.xml, runtime/pom.xml

---

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update version.camunda-connectors to v8.3.12 (patch) (io.camunda.connector:element-template-generator-maven-plugin, io.camunda.connector:spring-boot-starter-camunda-connectors, io.camunda.connector:connector-core)
• fix(deps): update dependency io.camunda:zeebe-bom to v8.5.2
• chore(deps): update version.camunda-connectors to v8.5.3 (minor) (io.camunda.connector:element-template-generator-maven-plugin, io.camunda.connector:spring-boot-starter-camunda-connectors, io.camunda.connector:connector-core)
• fix(deps): update dependency io.camunda.spring:spring-boot-starter-camunda-test to v8.5.3
• fix(deps): update dependency org.codehaus.groovy:groovy-all to v2.5.23
• fix(deps): update dependency org.graalvm.js:js-scriptengine to v23.1.3
• fix(deps): update dependency org.codehaus.groovy:groovy-all to v3
• fix(deps): update dependency org.graalvm.js:js-scriptengine to v24
• fix(deps): update kotlin monorepo to v2 (major) (org.jetbrains.kotlin:kotlin-scripting-jsr223, org.jetbrains.kotlin:kotlin-bom)
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

docker-compose

docker/docker-compose.yml

• camunda/zeebe 8.5.2
• camunda/connectors-bundle 8.5.3

github-actions

.github/workflows/build.yml

• actions/checkout v4
• actions/setup-java v4
• docker/login-action v3
• EnricoMi/publish-unit-test-result-action v2

.github/workflows/deploy.yml

• actions/checkout v4
• actions/setup-java v4
• docker/login-action v3
• docker/login-action v3
• camunda-community-hub/community-action-maven-release v1
• actions/upload-release-asset v1
• EnricoMi/publish-unit-test-result-action v2

maven

connector/pom.xml

• io.camunda.connectors.community:script-connector-parent 1.2.1-SNAPSHOT

pom.xml

• org.camunda.community:community-hub-release-parent 1.4.4
• io.camunda:zeebe-bom 8.5.1
• org.jetbrains.kotlin:kotlin-bom 1.9.24
• org.springframework.boot:spring-boot-dependencies 3.3.0
• io.camunda.connector:connector-core 8.3.0
• io.camunda.connector:element-template-generator 8.3.0
• io.camunda.spring:spring-boot-starter-camunda-test 8.3.6
• io.camunda.connector:spring-boot-starter-camunda-connectors 8.3.0
• org.codehaus.groovy:groovy-all 2.4.21
• org.graalvm.js:js 23.0.4
• org.graalvm.js:js-scriptengine 23.0.4
• org.jetbrains.kotlin:kotlin-scripting-jsr223 1.9.24
• io.camunda.connector:element-template-generator-maven-plugin 8.3.0
• org.sonatype.plugins:nexus-staging-maven-plugin 1.7.0
• org.apache.maven.plugins:maven-source-plugin 3.3.1
• org.apache.maven.plugins:maven-assembly-plugin 3.7.1
• org.apache.maven.plugins:maven-resources-plugin 3.3.1
• org.apache.maven.plugins:maven-site-plugin 3.12.1
• org.apache.maven.plugins:maven-dependency-plugin 3.6.1
• org.graalvm.buildtools:native-maven-plugin 0.10.2
• org.apache.maven.plugins:maven-compiler-plugin 3.13.0
• org.springframework.boot:spring-boot-maven-plugin 3.3.0
• org.apache.maven.plugins:maven-install-plugin 3.1.2
• org.apache.maven.plugins:maven-shade-plugin 3.6.0
• org.apache.maven.plugins:maven-surefire-plugin 3.2.5
• org.apache.maven.plugins:maven-enforcer-plugin 3.5.0
• com.diffplug.spotless:spotless-maven-plugin 2.43.0
• com.google.cloud.functions:function-maven-plugin 0.11.0
• org.apache.maven.plugins:maven-release-plugin 3.0.1
• com.github.eirslett:frontend-maven-plugin 1.15.0

runtime/pom.xml

• io.camunda.connectors.community:script-connector-parent 1.2.1-SNAPSHOT

---

• Check this box to trigger a request for Renovate to run again on this repository

no script engine found with name 'JavaScript

What is the reason for reporting "no script engine found with name 'JavaScript'"?

Support a template engine

Add support for a template engine, like Mustache or Thymeleaf.

Feature: Allow execution of scripts from a referenced resource

Idea

Instead of providing a script header, I can also provide a scriptSource header that contains a reference towards the actual script, for example:

classpath:scripts/my-script.js, file:/opt/app/resources/my-script.js, https://some-github-raw-url