Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Connector evolution #343

Merged
merged 13 commits into from
Oct 31, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ jobs:
with:
upload_url: ${{ github.event.release.upload_url }}
asset_path: ${{ steps.release.outputs.artifacts_archive_path }}
asset_name: camunda-7-to-8-migration.zip
asset_name: script-connector.zip
asset_content_type: application/zip
- name: Publish Unit Test Results
id: publish
Expand Down
12 changes: 6 additions & 6 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
/.classpath
/.project
/.settings
/target

# intellij
target
.idea
*.iml

#eclipse
**.project
**.classpath
**.settings
84 changes: 45 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,22 @@
# zeebe-script-worker
# Skript Connector

[![](https://img.shields.io/badge/Community%20Extension-An%20open%20source%20community%20maintained%20project-FF4700)](https://github.com/camunda-community-hub/community)
[![](https://img.shields.io/badge/Lifecycle-Stable-brightgreen)](https://github.com/Camunda-Community-Hub/community/blob/main/extension-lifecycle.md#stable-)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![Compatible with: Camunda Platform 8](https://img.shields.io/badge/Compatible%20with-Camunda%20Platform%208-0072Ce)](https://github.com/camunda-community-hub/community/blob/main/extension-lifecycle.md#compatiblilty)


_This is a community project meant for playing around with Zeebe. It is not officially supported by the Zeebe Team (i.e. no gurantees). Everybody is invited to contribute!_
A Zeebe worker to evaluate scripts (i.e. script tasks). Scripts are useful for prototyping, to do (simple) calculations, or creating/modifying variables.
_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:

```xml
Expand All @@ -21,6 +26,7 @@ Example BPMN with service task:
<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>
Expand All @@ -30,67 +36,67 @@ Example BPMN with service task:
* required custom headers:
* `language` - the name of the script language
* `script` - the script to evaluate
* available context/variables in script:
* `job` (ActivatedJob) - the current job
* `zeebeClient` (ZeebeClient) - the client of the worker
* the result of the evaluation is passed as `result` variable
* `resultVariable` - the result of the evaluation is passed to this variable

### Connector

Available script languages:
The connector provides an [element template](./connector/element-templates/script-connector.json) that can be used to configure it.

### Script languages

Available script languages are by default:
* [javascript](https://www.graalvm.org/) (GraalVM JS)
* [groovy](http://groovy-lang.org/)
* [mustache](http://mustache.github.io/mustache.5.html)
* [kotlin](https://kotlinlang.org/)

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`](./connector/src/main/java/io/camunda/community/connector/script/spi/ScriptEvaluatorExtension.java) SPI.

To register custom file extensions, you can use the [`LanguageProviderExtension`](./connector/src/main/java/io/camunda/community/connector/script/spi/LanguageProviderExtension.java) SPI.

## Install

### Docker

The docker image for the worker is published on [GitHub Packages](https://github.com/orgs/camunda-community-hub/packages/container/package/zeebe-script-worker).
For a local setup, the repository contains a [docker-compose file](docker/docker-compose.yml). It starts a Zeebe broker and both (standalone and bundled) containers.

```
docker pull ghcr.io/camunda-community-hub/zeebe-script-worker:1.2.0
mvn clean package
cd docker
docker-compose up
```
* configure the connection to the Zeebe broker by setting `zeebe.client.broker.contactPoint` (default: `localhost:26500`)

For a local setup, the repository contains a [docker-compose file](docker/docker-compose.yml). It starts a Zeebe broker and the worker.
#### Standalone Runtime

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

```
cd docker
docker-compose up
docker pull ghcr.io/camunda-community-hub/script-connector/runtime:latest
```

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

1. Download the latest [worker JAR](https://github.com/zeebe-io/zeebe-script-worker/releases) _(zeebe-script-worker-%{VERSION}.jar
)_
The docker-compose file shows an example how this works.

1. Start the worker
`java -jar zeebe-script-worker-{VERSION}.jar`
#### Bundled Runtime

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

The worker is a Spring Boot application that uses the [Spring Zeebe Starter](https://github.com/zeebe-io/spring-zeebe). The configuration can be changed via environment variables or an `application.yaml` file. See also the following resources:
* [Spring Zeebe Configuration](https://github.com/zeebe-io/spring-zeebe#configuring-zeebe-connection)
* [Spring Boot Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config)
The docker-compose file shows an example how this works.

```
zeebe:
client:
worker:
defaultName: script-worker
defaultType: script
threads: 3

job.timeout: 10000
broker.contactPoint: 127.0.0.1:26500
security.plaintext: true
```
### Manual

#### Standalone Runtime

## Build from Source
1. Download the runtime jar `script-connector-runtime-{VERSION}.jar`
2. Start the connector runtime `java -jar script-connector-runtime-{VERSION}.jar`

Build with Maven
#### Bundled Runtime

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

## Code of Conduct

Expand Down
163 changes: 163 additions & 0 deletions connector/element-templates/script-connector.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
{
"$schema" : "https://unpkg.com/@camunda/zeebe-element-templates-json-schema/resources/schema.json",
"name" : "Script Connector",
"id" : "io.camunda.community:script-connector",
"description" : "A connector to execute a script",
"version" : 1,
"category" : {
"id" : "connectors",
"name" : "Connectors"
},
"appliesTo" : [ "bpmn:Task" ],
"elementType" : {
"value" : "bpmn:ServiceTask"
},
"groups" : [ {
"id" : "default",
"label" : "Properties"
}, {
"id" : "output",
"label" : "Output mapping"
}, {
"id" : "error",
"label" : "Error handling"
}, {
"id" : "retries",
"label" : "Retries"
} ],
"properties" : [ {
"value" : "io.camunda.community:script-connector",
"binding" : {
"type" : "zeebe:taskDefinition:type"
},
"type" : "Hidden"
}, {
"id" : "script.type",
"label" : "Type",
"group" : "default",
"binding" : {
"name" : "script.type",
"type" : "zeebe:input"
},
"type" : "Dropdown",
"choices" : [ {
"name" : "Embedded",
"value" : "embedded"
}, {
"name" : "Resource",
"value" : "resource"
} ]
}, {
"id" : "script.embedded",
"label" : "Script",
"description" : "The script to be executed",
"optional" : false,
"constraints" : {
"notEmpty" : true
},
"feel" : "optional",
"group" : "default",
"binding" : {
"name" : "script.embedded",
"type" : "zeebe:input"
},
"condition" : {
"property" : "script.type",
"equals" : "embedded"
},
"type" : "String"
}, {
"id" : "script.language",
"label" : "Script Language",
"description" : "The language the script uses. By default, the ones available are: javascript, groovy, kotlin, mustache",
"optional" : false,
"constraints" : {
"notEmpty" : true
},
"feel" : "optional",
"group" : "default",
"binding" : {
"name" : "script.language",
"type" : "zeebe:input"
},
"condition" : {
"property" : "script.type",
"equals" : "embedded"
},
"type" : "String"
}, {
"id" : "script.resource",
"label" : "Script resource",
"description" : "The resource that should be executed. Should be prefixed with 'classpath:' for a classpath resource, 'file:' for a file system resource. If none of these prefixes matches, it will attempt to load the provided resource as URL.",
"optional" : false,
"constraints" : {
"notEmpty" : true
},
"feel" : "optional",
"group" : "default",
"binding" : {
"name" : "script.resource",
"type" : "zeebe:input"
},
"condition" : {
"property" : "script.type",
"equals" : "resource"
},
"type" : "String"
}, {
"id" : "context",
"label" : "Script context",
"description" : "The context that is available to the script",
"optional" : false,
"feel" : "required",
"group" : "default",
"binding" : {
"name" : "context",
"type" : "zeebe:input"
},
"type" : "String"
}, {
"id" : "resultVariable",
"label" : "Result variable",
"description" : "Name of variable to store the response in",
"group" : "output",
"binding" : {
"key" : "resultVariable",
"type" : "zeebe:taskHeader"
},
"type" : "String"
}, {
"id" : "resultExpression",
"label" : "Result expression",
"description" : "Expression to map the response into process variables",
"feel" : "required",
"group" : "output",
"binding" : {
"key" : "resultExpression",
"type" : "zeebe:taskHeader"
},
"type" : "Text"
}, {
"id" : "errorExpression",
"label" : "Error expression",
"description" : "Expression to handle errors. Details in the <a href=\"https://docs.camunda.io/docs/components/connectors/use-connectors/\" target=\"_blank\">documentation</a>.",
"feel" : "required",
"group" : "error",
"binding" : {
"key" : "errorExpression",
"type" : "zeebe:taskHeader"
},
"type" : "Text"
}, {
"id" : "retryBackoff",
"label" : "Retry backoff",
"description" : "ISO-8601 duration to wait between retries",
"value" : "PT0S",
"group" : "retries",
"binding" : {
"key" : "retryBackoff",
"type" : "zeebe:taskHeader"
},
"type" : "Hidden"
} ]
}
Loading