⚠️ This repository has been moved into https://github.com/camunda/connectors

Camunda Connector SDK

The Connector SDK allows you to develop custom Camunda 8 Connectors in Java.

You can focus on the logic of the Connector, test it locally, and reuse its runtime logic in multiple environments. The SDK achieves this by abstracting from Camunda Platform 8 internals that usually come with job workers.

Head over to our template repositories for a head start:

Create a Connector
- Outbound Connector
- Inbound Connector
Connector Validation
Start a Connector
Build
Build a release

Create a Connector

Include the connector-core, e.g. via Maven:

<dependency>
  <groupId>io.camunda.connector</groupId>
  <artifactId>connector-core</artifactId>
  <version>0.11.0</version>
  <scope>provided</scope>
</dependency>

Set the dependency to a provided scope as the runtimes that execute Connectors provide the necessary classes already.

Outbound Connector

Define your Connector logic through the OutboundConnectorFunction interface:

@OutboundConnector(
    name = "PING",
    inputVariables = {"caller"},
    type = "io.camunda.example.PingConnector:1"
)
public class PingConnector implements OutboundConnectorFunction {

  @Override
  public Object execute(OutboundConnectorContext context) throws Exception {

    var request = context.bindVariables(PingRequest.class);
    var caller = request.getCaller();

    return new PingResponse("Pong to " + caller);
  }
}

Inbound Connector

Define your Connector logic through the InboundConnectorExecutable interface:

@InboundConnector(
    name = "SUBSCRIPTION",
    type = "io.camunda.example.SubscriptionConnector:1"
)
public class SubscriptionConnector implements InboundConnectorExecutable {

  private MockSubscription subscription; // imitates some real-world subscription

  @Override
  public void activate(InboundConnectorContext context) throws Exception {

    var properties = context.bindProperties(SubscriptionProperties.class);

    // subscribe to events
    subscription = new MockSubscription(properties.getTopic());
    subscription.subscribe(event -> {
      context.correlate(event);
    });
  }

  @Override
  public void deactivate() throws Exception {
    // unsubscribe from events
    subscription.shutdown();
  }
}

Connector Discovery

The SDK provides a default implementation for Connector discovery using Java ServiceLoader with the connector-runtime-util module.

To make your Connector discoverable, expose the OutboundConnectorFunction or InboundConnectorExecutable implementation as an SPI implementation. Alternatively, you can use the manual discovery mechanism via properties.

Connector Validation

If you want to validate your Connector input, the SDK provides a default implementation using Jakarta Bean Validation with the connector-validation module. You can include it via maven with the following dependency:

<dependency>
  <groupId>io.camunda.connector</groupId>
  <artifactId>connector-validation</artifactId>
  <version>0.11.0</version>
  <scope>provided</scope>
</dependency>

Set the dependency to a provided scope as the runtimes that execute Connectors provide the necessary classes already.

Find more details in the validation module.

Start a Connector

Spring Zeebe Connector runtime supports running outbound Connectors as job workers and manages the lifecycle of the inbound Connectors. You can also build your own runtime, tailored towards your environment.

Build

mvn clean package

Build a release

Trigger the release action manually with the version x.y.z you want to release. This can be done on the main branch as well as stable/.x.y maintenance branches. You can choose the branch to execute the action on as described in the GitHub documentation.

When triggered from the main branch, a maintenance branch stable/x.y will be created based on the release version x.y.z that you specified.

Pre-releases

If you apply further classifiers like x.y.z-rc1 or x.y.z-alpha1, no maintenance branch will be created. Furthermore, no commits will be pushed to the branch you release from. A tag will be created on a detached commit that sets the release version on top of the current HEAD of the branch.

camunda/connector-sdk