Batch operations

A high-level overview of batch operations in Camunda 8.

About batch operations

If a single process instance encounters an incident, or you need to update the instance for any other reason, you can perform an instance operation. However, if you need to perform the same operation on multiple instances, a batch operation:

• Optimizes the performance of operations that need to be performed across many process instances.
• Provides insights into the progress of the operation across all affected instances.
• Gives you control over operation execution, with the ability to suspend, resume, and cancel operations.

A batch operation is an operation on a selection, or batch, of process instances. Instead of manually operating on each instance, you can specify filter criteria and automatically identify and process matching instances across your cluster in parallel. The individual operation in the batch applied to a process instance is called a batch item.

Example use cases include:

• Many process instances have encountered a critical bug.
• You need to skip an activity across multiple instances.
• There was in issue when executing a process that corrupted many or all instances of that process.

Types

Here are the types of available batch operations:

Type	Description
Resolve incidents	Resolves the incidents associated with a batch of process instances.
Modify process instances	Moves a batch of process instances from one node to another.
Migrate process instances	Migrates a batch of process instances to a new process version.
Suspend process instances	Suspends a batch of process instances.
Resume process instances	Resumes a batch of suspended process instances.
Cancel process instances	Cancels a batch of process instances.
Delete process instances	Deletes a batch of process instances.
Delete decision instances	Deletes a batch of decision instances.

Furthermore, depending on the status of the batch operation, you may be able to suspend, cancel, or resume the operation.

warning

Canceling a batch operation does not rollback any changes that have already been produced.

Filter process instances for batch operations

Batch process instance operations only act on instances in a state the operation supports. The following rules apply to the modify, migrate, resolve incidents, suspend, resume, and cancel operations, but not to the delete operations.

Operation	Required state
Modify	ACTIVE
Migrate	ACTIVE
Resolve incidents	ACTIVE
Suspend	ACTIVE
Resume	SUSPENDED
Cancel	ACTIVE and SUSPENDED

Your filter only narrows the batch. Camunda narrows your state filter with the required state, so the batch never includes instances outside the required state.

• A top-level state filter that uses $eq or $in with a state the operation doesn't support is rejected with 400 Bad Request.
• States inside $or branches aren't validated. A branch that conflicts with the required state matches no instances.
• The $neq, $exists, and $like operators on a top-level state are applied as given, and the batch remains limited to the required states.
• A parentProcessInstanceKey filter is applied as given. Cancel only acts on root instances, so a filter that matches only child instances selects no instances.

To resolve a rejected request, remove the conflicting top-level state filter or move it into an $or branch.

States

A batch operation can have one of the following statuses:

Type	Description
Created	The batch operation was created, but the filter hasn't been used yet to determine the affected process instances.
Active	The batch operation is actively being processed.
Completed	All items in the batch operation were processed, regardless of whether the individual operations succeeded or failed.
Partially completed	The batch operation successfully processed at least one partition and failed to process at least one partition.
Suspended	The batch operation was temporarily stopped. Suspended batch operations can be resumed.
Canceled	The batch operation was permanently stopped. Canceled batch operations can't be resumed.
Failed	The batch operation failed on all partitions.

info

Learn more about batch partitions in our implementation overview.

Authorization

When executing a batch operation, there are two sets of permissions involved:

• Batch operation permissions.
• Item-level, or process definition, permissions.

To create a batch operation, you always need both the permission to create batch operations as well as permissions to read process instances and execute specific operations on each targeted process instance.

To suspend, resume, or cancel an operation, you only need the relevant batch operation permissions.

The system stores authorization claims with the batch operation and uses them throughout its lifecycle.

info

Read more about authorizations and how to create them in the Admin UI.

Next steps

• Learn how batch operations work.
• Use batch operations in the Camunda 8 web interface.
• Use the batch operations APIs:
  • Search batch operations.
  • Cancel process instances (batch).
  • Resolve related incidents (batch).
  • Migrate process instances (batch).
  • Modify process instances (batch).
  • Delete process instances (batch).
  • Delete decision instances (batch).