Package io.camunda.zeebe.client

Interface ZeebeClient

All Superinterfaces:
AutoCloseable, JobClient
All Known Implementing Classes:
ZeebeClientImpl
public interface ZeebeClient extends AutoCloseable, JobClient
The client to communicate with a Zeebe broker/cluster.

  • Method Details

    • newClient

      static ZeebeClient newClient()
      Returns:
      a new Zeebe client with default configuration values. In order to customize configuration, use the methods newClientBuilder() or newClient(ZeebeClientConfiguration). See ZeebeClientBuilder for the configuration options and default values.

    • newClient

      static ZeebeClient newClient(ZeebeClientConfiguration configuration)
      Returns:
      a new ZeebeClient using the provided configuration.

    • newClientBuilder

      static ZeebeClientBuilder newClientBuilder()
      Returns:
      a builder to configure and create a new ZeebeClient.

    • newCloudClientBuilder

      static ZeebeClientCloudBuilderStep1 newCloudClientBuilder()
      Returns:
      a builder with convenient methods to connect to the Camunda Cloud cluster.

    • newTopologyRequest

      TopologyRequestStep1 newTopologyRequest()
      Request the current cluster topology. Can be used to inspect which brokers are available at which endpoint and which broker is the leader of which partition. 
       List<BrokerInfo> brokers = zeebeClient
  .newTopologyRequest()
  .send()
  .join()
  .getBrokers();

  InetSocketAddress address = broker.getSocketAddress();

  List<PartitionInfo> partitions = broker.getPartitions();
      Returns:
      the request where you must call send()

    • getConfiguration

      ZeebeClientConfiguration getConfiguration()
      Returns:
      the client's configuration

    • close

      void close()
      Specified by:
      close in interface AutoCloseable

    • newDeployCommand

      DeployProcessCommandStep1 newDeployCommand()
      Deprecated.
      since 8 for removal with 8.1, replaced by newDeployResourceCommand()
      Command to deploy new processes. 
       zeebeClient
  .newDeployCommand()
  .addResourceFile("~/wf/process1.bpmn")
  .addResourceFile("~/wf/process2.bpmn")
  .send();
      Returns:
      a builder for the command

    • newDeployResourceCommand

      DeployResourceCommandStep1 newDeployResourceCommand()
      Command to deploy new resources, i.e. BPMN process models and DMN decision models. 
       zeebeClient
  .newDeployCommand()
  .addResourceFile("~/wf/process1.bpmn")
  .addResourceFile("~/wf/process2.bpmn")
  .addResourceFile("~/dmn/decision.dmn")
  .send();
      Returns:
      a builder for the command

    • newCreateInstanceCommand

      CreateProcessInstanceCommandStep1 newCreateInstanceCommand()
      Command to create/start a new instance of a process. 
       zeebeClient
  .newCreateInstanceCommand()
  .bpmnProcessId("my-process")
  .latestVersion()
  .variables(json)
  .send();
      Returns:
      a builder for the command

    • newModifyProcessInstanceCommand

      ModifyProcessInstanceCommandStep1 newModifyProcessInstanceCommand(long processInstanceKey)
      Command to modify a process instance. 
         zeebeClient
    .newModifyProcessInstanceCommand(processInstanceKey)
    .activateElement("element1")
    .and()
    .activateElement("element2")
    .withVariables(globalScopedVariables)
    .withVariables(localScopedVariables, "element2")
    .and()
    .terminateElement("element3")
    .send();
      Parameters:
      processInstanceKey - the key which identifies the corresponding process instance
      Returns:
      a builder for the command

    • newMigrateProcessInstanceCommand

      @ExperimentalApi("https://github.com/camunda/camunda/issues/14907") MigrateProcessInstanceCommandStep1 newMigrateProcessInstanceCommand(long processInstanceKey)
      Command to migrate a process instance to a different process definition.

      The migration command contains a migration plan. Migration plan contains targetProcessDefinitionKey to indicate which process definition to use for the migration. Mapping instructions for the migration describe how to map elements from the source process definition to the target process definition.

      For example, let's consider we want to migrate process instance with key 1, target process definition key 2, a source process definition with a service task with id "task1" and the target process definition with a service task with id "task2". The migration command could be: 

      
 {
  "processInstanceKey": 1,
  "migrationPlan": {
   "targetProcessDefinitionKey": 2,
   "mappingInstructions": [
    {
     "sourceElementId": "task1",
     "targetElementId": "task2"
    }
   ]
  }
 }
 
      
 zeebeClient
  .newMigrateProcessInstanceCommand(1L)
  .migrationPlan(2L)
  .addMappingInstruction("element1", "element2")
  .addMappingInstruction("element3", "element4")
  .send();
 
       final MigrationPlan migrationPlan =
         MigrationPlan.newBuilder()
             .withTargetProcessDefinitionKey(2L)
             .addMappingInstruction("element1", "element2")
             .addMappingInstruction("element3", "element4")
             .build();
 zeebeClient
  .newMigrateProcessInstanceCommand(1L)
  .migrationPlan(migrationPlan)
  .send();
      Parameters:
      processInstanceKey - the key which refers to the process instance to migrate
      Returns:
      a builder for the command

    • newCancelInstanceCommand

      CancelProcessInstanceCommandStep1 newCancelInstanceCommand(long processInstanceKey)
      Command to cancel a process instance. 
       zeebeClient
  .newCancelInstanceCommand(processInstanceKey)
  .send();
      Parameters:
      processInstanceKey - the key which identifies the corresponding process instance
      Returns:
      a builder for the command

    • newSetVariablesCommand

      SetVariablesCommandStep1 newSetVariablesCommand(long elementInstanceKey)
      Command to set and/or update the variables of a given flow element (e.g. process instance, task, etc.) 
       zeebeClient
  .newSetVariablesCommand(elementInstanceKey)
  .variables(json)
  .send();
      Parameters:
      elementInstanceKey - the key of the element instance to set/update the variables for
      Returns:
      a builder for the command

    • newEvaluateDecisionCommand

      EvaluateDecisionCommandStep1 newEvaluateDecisionCommand()
      Command to evaluate a decision. 
       zeebeClient
  .newEvaluateDecisionCommand()
  .decisionKey("my-decision")
  .variables(json)
  .send();
      Returns:
      a builder for the command

    • newPublishMessageCommand

      PublishMessageCommandStep1 newPublishMessageCommand()
      Command to publish a message which can be correlated to a process instance. 
       zeebeClient
  .newPublishMessageCommand()
  .messageName("order canceled")
  .correlationKey(orderId)
  .variables(json)
  .send();
      Returns:
      a builder for the command

    • newCorrelateMessageCommand

      CorrelateMessageCommandStep1 newCorrelateMessageCommand()
      Command to correlate a message and wait for it to be correlated against a process instance. 
       zeebeClient
  .newCorrelateMessageCommand()
  .messageName("order canceled")
  .correlationKey(orderId)
  .variables(json)
  .tenantId("tenant")
  .send();
      Returns:
      a builder for the command

    • newBroadcastSignalCommand

      BroadcastSignalCommandStep1 newBroadcastSignalCommand()
      Command to broadcast a signal. 
       zeebeClient
  .newBroadcastSignalCommand()
  .signalName("signal")
  .variables(json)
  .send();
      Returns:
      a builder for the command

    • newResolveIncidentCommand

      ResolveIncidentCommandStep1 newResolveIncidentCommand(long incidentKey)
      Command to resolve an existing incident. 
       zeebeClient
  .newResolveIncidentCommand(incidentKey)
  .send();
      Parameters:
      incidentKey - the key of the corresponding incident
      Returns:
      the builder for the command

    • newUpdateRetriesCommand

      UpdateRetriesJobCommandStep1 newUpdateRetriesCommand(long jobKey)
      Command to update the retries of a job. 
       long jobKey = ..;

 zeebeClient
  .newUpdateRetriesCommand(jobKey)
  .retries(3)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Parameters:
      jobKey - the key of the job to update
      Returns:
      a builder for the command

    • newUpdateRetriesCommand

      UpdateRetriesJobCommandStep1 newUpdateRetriesCommand(ActivatedJob job)
      Command to update the retries of a job. 
       ActivatedJob job= ..;

 zeebeClient
  .newUpdateRetriesCommand(job)
  .retries(3)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newUpdateTimeoutCommand

      UpdateTimeoutJobCommandStep1 newUpdateTimeoutCommand(long jobKey)
      Command to update the timeout of a job. 
       long jobKey = ..;

 zeebeClient
  .newUpdateTimeoutCommand(jobKey)
  .timeout(100)
  .send();

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Parameters:
      jobKey - the key of the job to update
      Returns:
      a builder for the command

    • newUpdateTimeoutCommand

      UpdateTimeoutJobCommandStep1 newUpdateTimeoutCommand(ActivatedJob job)
      Command to update the timeout of a job. 
       ActivatedJob job= ..;

 zeebeClient
  .newUpdateTimeoutCommand(job)
  .timeout(100)
  .send();

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newWorker

      JobWorkerBuilderStep1 newWorker()
      Registers a new job worker for jobs of a given type.

      After registration, the broker activates available jobs and assigns them to this worker. It then publishes them to the client. The given worker is called for every received job, works on them and eventually completes them. 

       JobWorker worker = zeebeClient
  .newWorker()
  .jobType("payment")
  .handler(paymentHandler)
  .open();

 ...
 worker.close();
      Example JobHandler implementation: 
       public final class PaymentHandler implements JobHandler
 {
   @Override
   public void handle(JobClient client, JobEvent jobEvent)
   {
     String json = jobEvent.getVariables();
     // modify variables

     client
      .newCompleteCommand()
      .event(jobEvent)
      .variables(json)
      .send();
   }
 };
      Returns:
      a builder for the worker registration

    • newDeleteResourceCommand

      DeleteResourceCommandStep1 newDeleteResourceCommand(long resourceKey)
      Command to delete a resource. 
       zeebeClient
  .newDeleteResourceCommand(resourceKey)
  .send();
      Parameters:
      resourceKey - the key of the resource
      Returns:
      the builder for the command

    • newUserTaskCompleteCommand

      CompleteUserTaskCommandStep1 newUserTaskCompleteCommand(long userTaskKey)
      Command to complete a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskCompleteCommand(userTaskKey)
  .variables(map)
  .send();

      If the user task is linked to a process instance then this command will complete the related activity and continue the flow.

      This command is only sent via REST over HTTP, not via gRPC

      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskAssignCommand

      AssignUserTaskCommandStep1 newUserTaskAssignCommand(long userTaskKey)
      Command to assign a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskAssignCommand(userTaskKey)
  .assignee(newAssignee)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskUpdateCommand

      UpdateUserTaskCommandStep1 newUserTaskUpdateCommand(long userTaskKey)
      Command to update a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskUpdateCommand(userTaskKey)
  .candidateGroups(newCandidateGroups)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskUnassignCommand

      UnassignUserTaskCommandStep1 newUserTaskUnassignCommand(long userTaskKey)
      Command to unassign a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskUnassignCommand(userTaskKey)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUpdateJobCommand

      UpdateJobCommandStep1 newUpdateJobCommand(long jobKey)
      Command to update the retries and/or the timeout of a job. 
       JobChangeset changeset= ..;

 zeebeClient
  .newUpdateCommand(jobKey)
  .update(changeset)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Parameters:
      jobKey - the key of the job to update
      Returns:
      a builder for the command

    • newUpdateJobCommand

      UpdateJobCommandStep1 newUpdateJobCommand(ActivatedJob job)
      Command to update the retries and/or the timeout of a job. 
       ActivatedJob job= ..;
 JobChangeset changeset= ..;

 zeebeClient
  .newUpdateCommand(job)
  .update(changeset)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newClockPinCommand

      @ExperimentalApi("https://github.com/camunda/camunda/issues/21647") ClockPinCommandStep1 newClockPinCommand()
      Command to pin the Zeebe engine's internal clock to a specific time.

      This method initiates a command to pin the clock to a specified time. You can specify the time using either an epoch timestamp in milliseconds or an Instant object.

      Once pinned, the clock will remain at the specified time and will not advance until another pin or reset command is issued. This is useful for scenarios where you need to simulate process execution at a specific point in time.

      Example usage: 

      
 final long pinnedTime = 1742461285000L; // Thu, Mar 20, 2025 09:01:25 GMT+0000
 zeebeClient
  .newClockPinCommand()
  .time(pinnedTime)
  .send();

 final Instant futureInstant = Instant.now().plus(Duration.ofDays(7));
 zeebeClient
  .newClockPinCommand()
  .time(futureInstant)
  .send();

      The command is marked as experimental and may undergo changes or improvements in future releases.

      Returns:
      a builder for the command that allows setting either a timestamp or an instant

    • newClockResetCommand

      @ExperimentalApi("https://github.com/camunda/camunda/issues/21647") ClockResetCommandStep1 newClockResetCommand()
      Command to reset the Zeebe engine's internal clock to the system time.

      This command allows you to reset the clock to the current system time, effectively undoing any previous pin command that may have set the clock to a specific, static time. 

      
 zeebeClient
  .newClockResetCommand()
  .send();

      The command is marked as experimental and may undergo changes or improvements in future releases.

      Returns:
      a builder for the command

    • newProcessInstanceQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") ProcessInstanceQuery newProcessInstanceQuery()
      Executes a search request to query process instances. 
       long processInstanceKey = ...;

 zeebeClient
  .newProcessInstanceQuery()
  .filter((f) -> f.processInstanceKeys(processInstanceKey))
  .sort((s) -> s.startDate().asc())
  .page((p) -> p.limit(100))
  .send();

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. The respective API on compatible clusters is not enabled by default. Thus, this method doesn't work out of the box with all clusters. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Returns:
      a builder for the process instance query

    • newFlownodeInstanceQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") FlownodeInstanceQuery newFlownodeInstanceQuery()
      Executes a search request to query flow node instances. 
       long flownodeInstanceKey = ...;

 zeebeClient
  .newFlownodeInstanceQuery()
  .filter((f) -> f.processInstanceKeys(processInstanceKey))
  .sort((s) -> s.flowNodeName().asc())
  .page((p) -> p.limit(100))
  .send();

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. The respective API on compatible clusters is not enabled by default. Thus, this method doesn't work out of the box with all clusters. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Returns:
      a builder for the process instance query

    • newUserTaskQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") UserTaskQuery newUserTaskQuery()
      Executes a search request to query user tasks. 
       zeebeClient
  .newUserTaskQuery()
  .filter((f) -> f.userTaskKey(userTaskKey))
  .sort((s) -> s.creationDate().asc())
  .page((p) -> p.limit(100))
  .send();

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. The respective API on compatible clusters is not enabled by default. Thus, this method doesn't work out of the box with all clusters. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Returns:
      a builder for the user task query

    • newDecisionRequirementsQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") DecisionRequirementsQuery newDecisionRequirementsQuery()
      Executes a search request to query Decision Requirements. 
         zeebeClient
   .newDecisionRequirementsQuery()
   .filter((f) -> f.decisionRequirementsKey(decisionRequirementsKey))
   .sort((s) -> s.version().asc())
   .page((p) -> p.limit(100))
   .send();

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. The respective API on compatible clusters is not enabled by default. Thus, this method doesn't work out of the box with all clusters. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Returns:
      a builder for the decision requirements query

    • newDecisionDefinitionQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") DecisionDefinitionQuery newDecisionDefinitionQuery()

    • newDecisionDefinitionGetXmlRequest

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") DecisionDefinitionGetXmlRequest newDecisionDefinitionGetXmlRequest(long decisionKey)

    • newIncidentQuery

      @ExperimentalApi("https://github.com/camunda/camunda/issues/20596") IncidentQuery newIncidentQuery()

    • newUserCreateCommand

      CreateUserCommandStep1 newUserCreateCommand()
      Command to create a user. 
      

 zeebeClient
  .newUserCreateCommand()
  .username(username)
  .email(email)
  .name(name)
  .password(password)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Returns:
      a builder for the command

    • newAddPermissionsCommand

      AddPermissionsCommandStep1 newAddPermissionsCommand(long ownerKey)
      Command to add permissions to an owner. 
       zeebeClient
  .newAddPermissionsCommand(ownerKey)
  .resourceType(resourceType)
  .permission(permissionType)
  .resourceIds(resourceIds)
  .permission(permissionType)
  .resourceId(resourceId)
  .resourceId(resourceId)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Parameters:
      ownerKey - the key of the owner
      Returns:
      a builder for the command