Skip to main content

Update 0.2 to 0.3

Intermediate

The following sections explain which adjustments must be made to migrate from Connector SDK 0.2.x to 0.3.0.

caution

Be aware that the update from 0.2 to 0.3 requires manual migration steps as described below.

Connector function​

With SDK version 0.3.0, we introduce the following structural changes:

  • Input validation moves from Jakarta Bean Validation API version 3.0 to 2.0.
  • SDK artifacts have to be in scope provided.

Update to Validation API 2.0​

To better integrate in the current Java ecosystem and widely used frameworks like Spring 5 and Spring Boot 2, the connector-validation module now operates on Jakarta Bean Validation API version 2.0 instead of version 3.0. Adjust your Connector input objects using validation as follows:

Replace all class imports starting with jakarta.validation by javax.validation. A Connector input class on SDK 0.2.x with the following imports:

import io.camunda.connector.api.annotation.Secret;
import jakarta.validation.constraints.NotEmpty;
import java.io.IOException;
import java.util.Objects;

changes to the following:

import io.camunda.connector.api.annotation.Secret;
import javax.validation.constraints.NotEmpty;
import java.io.IOException;
import java.util.Objects;

This way, the Connector runtime environments are able to pick up your validations correctly.

Provided SDK artifacts​

The Connector runtime environments can execute multiple Connectors at once. The environments also provide the base SDK artifacts and their classes to any Connector they execute. This comprises runtime-specific classes related to the Connector context as well as the Connector core and the validation classes. To minimize the possibility of incompatible classes being on the same classpath, Connectors are required to depend on connector-core and connector-validation in Maven's dependency scope provided. Other dependency management frameworks like Gradle offer similar scopes.

As a result, you need to include the SDK artifacts as follows in Maven:

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

Connector runtime environment​

The SDK provides a pre-packaged runtime environment that you can start manually. With version 0.3.0, this runtime moves from the SDK repository to Connector Runtime. This also means that the provided runtime now is a Spring Boot application, based on Spring Zeebe. Thus, it offers all out-of-the-box capabilities Spring Zeebe provides.

The Connector runtime JAR for manual installation can now be fetched from https://repo1.maven.org/maven2/io/camunda/spring-zeebe-connector-runtime/ (starting with version 8.1.3) instead of https://repo1.maven.org/maven2/io/camunda/connector/connector-runtime-job-worker/. You can start the runtime environment with the following command:

java -cp 'spring-zeebe-connector-runtime-VERSION-with-dependencies.jar:connector-http-json-VERSION-with-dependencies.jar' \
    io.camunda.connector.runtime.ConnectorRuntimeApplication

The Docker image is still accessible at https://hub.docker.com/r/camunda/connectors/tags.

Custom runtime environments​

If you are building a custom runtime environment, note the following adjustments:

  • The runtime-util artifact replaces the runtime-job-worker artifact.
  • The io.camunda.connector.runtime.jobworker.api.outbound.ConnectorJobHandler has moved to import io.camunda.connector.runtime.util.outbound.ConnectorJobHandler.
  • The io.camunda.connector.impl.outbound.AbstractOutboundConnectorContext has moved to io.camunda.connector.impl.context.AbstractConnectorContext.
  • To build your own context class, we recommend using the following signature:
public class MyContext extends AbstractConnectorContext implements OutboundConnectorContext {}
  • The SecretStore class has been removed. Initialize your context class with a super(SecretProvider) call. Remove the getSecretStore method if you used it.
public class MyContext extends AbstractConnectorContext implements OutboundConnectorContext {

  public MyContext(final SecretProvider provider) {
    super(provider);
    ...
  }
}