zeebe-http-worker

A Zeebe worker to make HTTP calls (e.g. invoking a REST service). It is based on the built-in Java HttpClient.

Requirements: Java 11

Usage

BPMN Task

Example BPMN with service task:

<bpmn:serviceTask id="http-get" name="stargazers check">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="http" />
    <zeebe:taskHeaders>
      <zeebe:header key="url" value="https://api.github.com/user/starred/zeebe-io/zeebe-http-worker" />
    </zeebe:taskHeaders>
  </bpmn:extensionElements>
</bpmn:serviceTask>

• the worker is registered for the type http

• required custom headers/variable:

  • url - the url to invoke

• optional custom headers:

  • method - the HTTP method to use (default: GET, allowed: post | get | put | delete | patch)
  • statusCodeCompletion - Status codes that lead to completion of the service task (default: 1xx,2xx, allowed: comma separated list of codes including 1xx, 2xx, 3xx, 4xx and 5xx)
  • statusCodeFailure - Status codes that lead to the job failing (default: 3xx,4xx,5xx, allowed: comma separated list of codes including 1xx, 2xx, 3xx, 4xx and 5xx)

• optional variables:

  • body - the request body as JSON
  • authorization - the value of the authorization header (e.g. token 6bac4..)

• jobs are completed with variables:

  • statusCode - the response status code
  • body - the response body, if present

Placeholders

Please note that the current way of handling placeholders is subject to change in the future, especially with camunda/camunda#3417.

You can use placeholders in the form of {{PLACEHOLDER}} at all places, they will be replaced by

• custom headers from the BPMN model
• Workflow variables
• Configuration Variables from URL (see below)

Mustache is used for replacing the placeholders, refer to their docs to check possibilities.

Example:

<bpmn:serviceTask id="http-get" name="stargazers check">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="http" />
    <zeebe:taskHeaders>
      <zeebe:header key="url" value="https://{{BASE_URL}}/order?id={{orderId}}" />
      <zeebe:header key="method" value="GET" />
    </zeebe:taskHeaders>
  </bpmn:extensionElements>
</bpmn:serviceTask>

BASE_URL could be configured by the configuration variables from the URL and the orderId might be a workflow variable.

To support some legacy scenarios the worker at the moment still also understands placeholders in the form of ${PLACEHOLDER}. This is subject to be removed in later releases.

HTTP Response codes

As described you can set the statusCodeCompletion and statusCodeFailure header to control the behavior depending on the HTTP Status. If the status code is in neither of the lists Zeebe will just keep waiting in the service task, allowing for asynchronous callbacks.

A common example is

• Service returns HTTP 202 (ACCEPTED)
• Zeebe keeps waiting in the Service Task
• Until the external service somehow returns success and invokes the Zeebe API to complete the Job at hand

To allow this, the jobKey can be passed to the external service.

Install

JAR

• Download the JAR file

• Execute the JAR via

  java -jar target/zeebe-http-worker-{VERSION}.jar

Docker

`docker run camunda/zeebe-http-worker`

Readiness probes

You can check health of the worker:

http://localhost:8080/actuator/health

This uses the Spring Actuator, so other metrics are available as well

Configuration of Zeebe Connection

The connection to the broker Zeebe can be changed by setting the environment variables

• ZEEBE_CLIENT_BROKER_CONTACTPOINT (default: 127.0.0.1:26500).
• ZEEBE_CLIENT_SECURITY_PLAINTEXT (default: true).
• ZEEBE_WORKER_NAME (default http-worker)

This worker uses Spring Zeebe underneath, so all configuration options available there are also available here.

Configuration Variables from URL

You can load additional configuration values used to substitute placeholders. Therefor the worker will query an HTTP endpoint and expects a JSON back:

[
  {
    "key": "someValue",
    "value": 42
  },
  {
    "key": "anotherValue",
    "value": 42
  }
]

To load additional config variables from an URL set these environment variables:

• ENV_VARS_URL (e.g. http://someUrl/config, default: null)
• ENV_VARS_RELOAD_RATE (default 15000)
• ENV_VARS_M2M_BASE_URL
• ENV_VARS_M2M_CLIENT_ID
• ENV_VARS_M2M_CLIENT_SECRET
• ENV_VARS_M2M_AUDIENCE

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].