Skip to main content
Version: 8.8 (unreleased)

Java client

The Camunda Java Client is the official Java library for building process applications that integrate with Camunda 8. Whether you are orchestrating microservices, managing human tasks, or visualizing process data, this client provides everything needed to interact with the Orchestration Cluster programmatically.

The Camunda Java Client is part of the Camunda 8 public API and follows Semantic Versioning (except for alpha features). Minor and patch releases will not introduce breaking changes.

What is the Camunda Java Client?​

The Camunda Java Client is a comprehensive library enabling Java developers to:

  • Deploy processes and decisions to Camunda 8 clusters
  • Start and manage processes programmatically
  • Implement job workers to handle automated tasks within your processes
  • Query and manage process data via the Orchestration Cluster API

It supports both REST and gRPC protocols, authentication setup, and provides robust error handling with retry mechanisms.

Migration from Zeebe Java Client

The Camunda Java Client replaces the Zeebe Java Client as of version 8.8.

  • Provides improved structure and full Orchestration Cluster API support
  • The Zeebe Java Client will be removed in version 8.10
  • Migrate before upgrading to 8.10 to avoid breaking changes

See our migration guide for details.

What can you build with it?​

Use the Camunda Java Client to build:

  • Job workers that perform automated tasks and call external systems (APIs, databases, file systems)
  • Integration services that connect Camunda processes with existing systems or third-party services
  • Data processing applications that leverage process data for visualization, analytics, or business intelligence

Getting started in three steps​

Step 1: Add the dependency​

Add the Camunda Java Client to your project:

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}'

Use the latest version from Maven Central.

Step 2: Connect to your Camunda 8 cluster​

Instantiate a client to connect to your Camunda 8 cluster. Choose the authentication method based on your environment:

Use for: Local development when security is not required.

private static final String CAMUNDA_GRPC_ADDRESS = "[Address of Zeebe API (gRPC) - default: http://localhost:26500]";
private static final String CAMUNDA_REST_ADDRESS = "[Address of the Orchestration Cluster API - default: http://localhost:8080]";

public static void main(String[] args) {

    try (CamundaClient client = CamundaClient.newClientBuilder()
            .grpcAddress(URI.create(CAMUNDA_GRPC_ADDRESS))
            .restAddress(URI.create(CAMUNDA_REST_ADDRESS))
            .usePlaintext()
            .build()) {

        // Test the connection
        client.newTopologyRequest().send().join();
        System.out.println("Connected to Camunda 8!");
    }
}

What this code does

  1. Creates a no-authentication provider – Configures the client to skip authentication.
  2. Builds an unencrypted client – Uses plaintext communication for local development.
  3. Connects to both APIs – Configures access to the Zeebe gRPC and Orchestration Cluster REST APIs.
  4. Tests the connection – Verifies connectivity by requesting cluster topology information.

Environment variables option
You can also set connection details via environment variables to create the client more simply:

export CAMUNDA_GRPC_ADDRESS='[Address of Zeebe API (gRPC) - default: http://localhost:26500]'
export CAMUNDA_REST_ADDRESS='[Address of the Orchestration Cluster API - default: http://localhost:8080]'
CamundaClient client = CamundaClient.newClientBuilder().usePlaintext().build();

The client will automatically read the environment variables and configure the appropriate authentication method.

note

Ensure addresses are in absolute URI format: scheme://host(:port).

Step 3: Start building your process application​

With a connected client, you are ready to build your process application. Below are the core operations you’ll typically perform, along with guidance on the next steps.

Essential operations​

Deploy a process:

final DeploymentEvent deploymentEvent = client.newDeployResourceCommand()
    .addResourceFromClasspath("process.bpmn")
    .send()
    .join();

This deploys your BPMN process definition to the cluster. Place your .bpmn files in src/main/resources and reference them by filename.

Start a process instance:

final ProcessInstanceEvent processInstanceEvent = client.newCreateInstanceCommand()
    .bpmnProcessId("my-process")
    .latestVersion()
    .variables(Map.of("orderId", "12345", "amount", 100.0))
    .send()
    .join();

This creates a new instance of your process. The bpmnProcessId should match the Process ID from your BPMN file, and you can pass initial variables as a Map.

For a comprehensive example demonstrating these steps, see the DeployAndComplete example in the Camunda 8 examples repository. This example illustrates a complete workflow from process deployment to job completion.

Key features and capabilities​

  • Full Orchestration Cluster 8 API support: Access all Orchestration Cluster API capabilities, including process deployment, management, job handling, and querying process data.
  • Multiple authentication methods: Supports no authentication (development), basic authentication, and OIDC access tokens for production environments.
  • Automatic token management: Handles authentication token acquisition and renewal automatically—no manual token management required.
  • Protocol flexibility: Choose between REST and gRPC protocols depending on your requirements and infrastructure.

Next steps and resources​

Learn the fundamentals

Advanced topics

Need help?