Skip to content
TinyConductorTinyConductorTinyConductor

Connectors

A connector calls an outside system (for example an HTTP API) from a process. TinyConductor does not include a connector runtime. You run one yourself, as a separate process. It talks to the engine over the v2-compatible REST API, just like any other job worker.

This page shows how to configure a stock, unmodified connector runtime container, and what has been tested with one. Compatibility lists the runtime versions covered.

What works

Section titled “What works”

Verified against the stock connector runtime image, unmodified, pointed at two Cluster nodes, with the connectors’ jars mounted into it:

camunda/connectors:8.9.12

This image is the runtime alone; it contains no connectors. You add the connectors you need as jars in /opt/custom. Pick connectors under licences you accept: some connectors are published under their own licence terms.

  • Health. The runtime’s health, readiness and liveness endpoints report UP; the runtime sees every engine node.
  • Outbound connectors. The runtime activates connector jobs (for example the HTTP JSON connector’s job type), calls the target system and completes the job with the connector’s result. The result variable and the result expression are applied, and the instance continues as normal.
  • Failures. A call that fails is reported to the engine and becomes an incident carrying the connector’s message.
  • Inbound connectors. The runtime discovers the deployed processes that declare an inbound connector and activates the connector. A message-start connector’s messages start new instances, which run to completion.
  • Secrets. {{secrets.NAME}} placeholders are resolved entirely inside the connector runtime (for example from environment variables with a configured prefix). The engine only ever sees the placeholder.
  • Result and error expressions. Connector control headers such as resultVariable, resultExpression and errorExpression are passed to the runtime literally, including their leading =, so the runtime evaluates them as it expects.

Documents

Section titled “Documents”

The engine offers the documents API, so connectors that store or read files are supported: an HTTP call with storeResponse=true keeps the response as a document and puts its reference into the result, and connectors that take a document reference as input download the file. A check with the stock connector runtime is still to come.

  • Configure a document store first. Embedded mode has one by default; Bundled and Cluster mode need CONDUCTOR_DOCUMENT_STORE, and a Cluster of more than one node needs the S3 store, because the runtime may reach any node (Documents).
  • Give the runtime’s client document:create and document:read in addition to the permissions below.
  • Documents belong to the tenant of the runtime’s client, like everything else it does.

Configuration

Section titled “Configuration”

Point the connector runtime at the engine’s REST address and give it OAuth client credentials. The runtime reads its standard client environment variables:

CAMUNDA_CLIENT_RESTADDRESS=http://<engine>:8080
CAMUNDA_CLIENT_AUTH_CLIENTID=<client id>
CAMUNDA_CLIENT_AUTH_CLIENTSECRET=<client secret>
CAMUNDA_CLIENT_AUTH_TOKENURL=http://<engine>:8080/oauth/token
CAMUNDA_CLIENT_WORKER_DEFAULTS_STREAMENABLED=false

  • Turn job streaming off, as shown. Unlike the plain clients, the connector runtime turns it on by default; the engine does not offer it, and the runtime would keep trying and logging errors.

  • The tenant is taken from the bearer principal. The tenant ids the runtime sends in its requests are accepted only when they match the principal’s tenant. Give the runtime a client of one tenant; a principal of several tenants would have to name the tenant of every request in X-Tenant-Id.

  • Obtain the access token with the OAuth2 client-credentials grant. The engine issues such tokens itself: create a client in the console’s Access area and give it the permissions the runtime needs:

    • job:activate, job:complete and job:fail for the job types it runs;
    • history:read, because finding inbound connectors reads the deployed process definitions;
    • message:publish when you use inbound connectors: they publish messages to the engine, and without this permission each publication is refused with 403.

    Then point the runtime’s OAuth token URL at <engine>/oauth/token (see Identity and access). A client-credentials flow against your own identity provider, mapped to a service role, works too (see mapping rules).

Next to the engine with Docker Compose

Section titled “Next to the engine with Docker Compose”

The connector runtime runs as its own container next to the engine’s. With Bundled mode:

services:
  tinyconductor:
    image: registry.tinyfactory.ai/tinyblox/tinyconductor-bundled:0.1.0
    ports: ["127.0.0.1:8080:8080"]
    volumes: ["tinyconductor-data:/var/lib/postgresql/data"]


  connectors:
    image: camunda/connectors:8.9.12
    depends_on: [tinyconductor]
    # The connector jars you chose, for example the Apache-licensed
    # HTTP JSON connector; the runtime loads every jar in /opt/custom.
    volumes: ["./connectors:/opt/custom:ro"]
    environment:
      CAMUNDA_CLIENT_RESTADDRESS: http://tinyconductor:8080
      CAMUNDA_CLIENT_AUTH_CLIENTID: <client id>
      CAMUNDA_CLIENT_AUTH_CLIENTSECRET: <client secret>
      CAMUNDA_CLIENT_AUTH_TOKENURL: http://tinyconductor:8080/oauth/token
      CAMUNDA_CLIENT_WORKER_DEFAULTS_STREAMENABLED: "false"


volumes:
  tinyconductor-data: {}

In Cluster mode, point CAMUNDA_CLIENT_RESTADDRESS at your engine nodes’ load balancer instead.

Licensing

Section titled “Licensing”

Connector runtimes, connector templates and connector images are third-party software under their own licences, and some out-of-the-box connectors carry licence terms of their own. TinyConductor ships none of them. Obtain and licence the runtime you use yourself; nothing in this page is a licence opinion.