Camunda Connectors

This is the repository for Camunda Connectors. It manages all parts of the Connectors ecosystem, including the Connector SDK, out-of-the-box Connectors available in Camunda, the Connector Runtime, and the Docker images.

For more information on Connectors, refer to the Camunda documentation.

Contents

• License
• Setup
• Create a Connector
  • Outbound Connector
  • Inbound Connector
• Connector Validation
• Start a Connector
• Integration Tests
• Build
• Build a release

License

This is a multi-module project with different licenses applied to different modules.

Modules available under Apache 2.0 license

• Connector SDK including all supporting libraries
• Connector Secret providers implementations
• Connector Runtime and all its submodules
• Http Json Outbound Connector
• Element Template Generator and its submodules

Modules available under Camunda Self-Managed Free Edition license

• All Out-of-the-Box Connectors except for REST Connector (see above)
• Docker images of the out-of-the-box Connectors for Camunda, bundled with a runtime

When in doubt, refer to the LICENSE file in the respective module.

Setup

Download asdf, install the required plugins with asdf plugin add <tool> where <tool> is java, maven and pre-commit and run asdf install to install our tools. Afterwards, run pre-commit install to set up the pre-commit hooks.

The Connector SDK uses Java 17, unlike the rest of this repository.

Create a Connector

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

<dependency>
    <groupId>io.camunda.connector</groupId>
    <artifactId>connector-core</artifactId>
    <version>${version.connectors}</version>
    <scope>provided</scope>
</dependency>

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

To find the latest version, check the Maven Central repository.

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 -> {
            var result = context.correlateWithResult(event);
            // handleResult(result);
        });
    }

    @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-core 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>${version.connectors}</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

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. For more details, refer to the connector-runtime module.

Build

mvn clean package

Integration Tests

To run the integration tests, you need to have Docker installed and running. We use Testcontainers to manage the lifecycle of the containers. Remember to add the @SlowTest annotation to your integration tests to avoid them being run with the unit tests.

Create a docker-images.properties file in the test/resources folder of the module where you want to run the tests. List all Docker images that need to be pulled before running the tests in this file, using the format <key>=<imageWithTag> like this:

rabbitmq=rabbitmq:4.1.1-management-alpine
kafka=confluentinc/cp-kafka:7.4.0

Then, in your test, use io.camunda.connector.test.utils.DockerImages.get("<key>") to get the image name with tag. This allows us to control the versions of the Docker images (using Renovate) we use in our tests centrally.

Build a release

1. For minor releases (x.y.0), create a new branch release/x.y from main in advance and rebase it onto main from time to time. This can be done using the CREATE_RELEASE_BRANCH workflow.
2. To trigger the release, publish a new GitHub release and name the tag according to the version you want to release ( e.g. 1.0.0). This will trigger a GitHub workflow that builds and publishes the release artifacts, generates a changelog and bundles the element templates into an archive.

Backport a PR to an older release

We use backport-action to backport PRs to older releases. For example, add a label backport release/8.3 to backport a PR to the release/8.3 branch. This will take effect when the PR is meged.

You can also trigger this for already merged PRs by posting a comment on the PR containing /backport.