Migrate to the Camunda Java Client

Migrate to the Camunda Java Client from the Zeebe Java Client.

About this guide

This guide provides an overview of the process for migrating to the Camunda Java Client.

• The Camunda Java Client is the official Java library for connecting to Orchestration Cluster, automating processes, and implementing job workers.
• The Zeebe Java Client remains available until Camunda 8.10.

tip

Plan and start your migration early to ensure compatibility, access to latest features, and future support.

Before you begin

• Review project dependencies and identify where io.camunda.zeebe:zeebe-client-java is used.
• Catalog code referencing Zeebe classes, interfaces, and APIs (for example, ZeebeClient, Zeebe workers).

Update Maven/Gradle dependencies

Replace the Zeebe Java Client dependency with the Camunda Java Client dependency in your pom.xml or build.gradle file.

Maven:

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-client-java</artifactId>
  <version>${camunda.version}</version>
</dependency>

Gradle:

implementation 'io.camunda:camunda-client-java:${camunda.version}'

Update imports

Update all imports statement in your Java files to use the new Camunda Java Client package structure.

Change from:

import io.camunda.zeebe.client.*;

to:

import io.camunda.client.*;

Configuration and environment variable changes

• All old Java client property names are refactored to more general ones. For example, zeebe.client.tenantId to camunda.client.tenantId.
• Environment variables are also updated accordingly. For example, ZEEBE_CLIENT_TENANT_ID to CAMUNDA_CLIENT_TENANT_ID.
• The former deprecated gatewayAddress property and usePlainText have been removed and superseded by restAddress and grpcAddress which require explicit URI schemes (for example, http:// or https://).

Update client initialization

Update the client initialization code to use the new CamundaClient class.

For example, change:

ZeebeClient client = ZeebeClient.newClientBuilder()
    .gatewayAddress("localhost:26500")
    .usePlaintext()
    .build();

to:

CamundaClient client = CamundaClient.newClientBuilder()
    .grpcAddress(URI.create("http://localhost:26500"))
    .restAddress(URI.create("http://localhost:8080"))
    .build();

info

• Refer to the CamundaClientBuilder documentation for more details on available configuration options.
• The construction for OAuth, Basic Auth, or custom providers remains conceptually the same, but you must ensure you use the classes from the new package. Refer to the Camunda Java Client bootstrapping for more details.

Renamed API classes and commands

The following API classes have been changed in the Camunda Java Client:

Old	New
ZeebeClientBuilder	CamundaClientBuilder
ZeebeClientClouldBuilderStep1	CamundaClientClouldBuilderStep1
ZeebeClientConfiguration	CamundaClientConfiguration
ZeebeFuture	CamundaFuture

The following commands have been renamed in the Camunda Java Client:

Old	New
newClockPinCommand()	newPinClockCommand()
newClockResetCommand()	newResetClockCommand()
newUserCreateCommand()	newCreateUserCommand()
newUserTaskAssignCommand()	newAssignUserTaskCommand()
newUserTaskCompleteCommand()	newCompleteUserTaskCommand()
newUserTaskUnassignCommand()	newUnassignUserTaskCommand()
newUserTaskUpdateCommand()	newUpdateUserTaskCommand()

Protocol and connection: REST vs gRPC selection

Zeebe Java Client used gRPC by default. The Camunda Java Client uses REST by default. If you want to use gRPC, you need to explicitly set the grpcAddress in the client builder and configure preferRestOverGrpc=false to make gRPC the default.

To use gRPC, add the following to your client builder:

CamundaClient client = CamundaClient.newClientBuilder()
        .grpcAddress(URI.create("http://localhost:26500"))
        .restAddress(URI.create("http://localhost:8080"))
        .preferRestOverGrpc(false)
    .build();