Batch is a concept to offload workload from the current execution to beprocessed in the background. This allows to run a process engine commandasynchronously on a large set of instances without blocking. It also decouplesthe separate command invocations from each other.

For example the process instance migration command can beexecuted using a batch. This allows to migrateprocess instances asynchronously. In a synchronous process instance migration,all migrations are executed in a single transaction. First of all, thisrequires all of them to succeed to commit the transaction. For alarge set of process instances, the transaction can also become too large to even becommitted to the database. With batch migration both of these traits change.A batch executes the migration in smaller chunks, each using a singletransaction.

Benefits:

  • asynchronous (non-blocking) execution
  • execution can utilize multiple threads and job executors

  • decoupling of execution, i.e., every batch execution job uses its owntransaction
    Disadvantages:

  • manual polling for completion of the batch

  • contention with other jobs executed by the process engine
  • a batch can fail partially while a subset was already executed, e.g., someprocess instances were migrated where others failed
    Technically, a batch represents a set of jobs which execute a command in the context of theprocess engine.

The batch utilizes the job executor of the process engine to execute thebatch jobs. A single batch consists of three job types:

  • Seed job: creates all batch execution jobs required to complete the batch
  • Execution jobs: the actual execution of the batch command, e.g., the processinstance migration
  • Monitor job: after the seed job finished, it monitors the progress of thebatch execution and completion

    API

The following gives an overview of the Java API for batches.

Creating a Batch

A batch is created by executing a process engine command asynchronously.

Currently supported batch types:

Query a Batch

You can query a running batch by the id and the type, for example to queryfor all running process instance migration batches.

  1. List<Batch> migrationBatches = processEngine.getManagementService()
  2.   .createBatchQuery()
  3.   .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION)
  4.   .list();

Batch Statistics

You can query for statistics of batches by using the management service.The batch statistics will contain information about the remaining,completed and failed batch execution jobs.

  1. List<BatchStatistics> migrationBatches = processEngine.getManagementService()
  2.   .createBatchStatisticsQuery()
  3.   .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION)
  4.   .list();

History of a Batch

For the history level FULL a historic batch entry is created. Youcan query it using the history service.

  1. HistoricBatch historicBatch = processEngine.getHistoryService()
  2.   .createHistoricBatchQuery()
  3.   .batchId(batch.getId())
  4.   .singleResult();

The history also contains job log entries for the seed, monitor and executionjobs. You can query the corresponding job log entries by the specific jobdefinition id.

  1. HistoricBatch historicBatch = ...
  3. List<HistoricJobLog> batchExecutionJobLogs = processEngine.getHistoryService()
  4.   .createHistoricJobLogQuery()
  5.   .jobDefinitionId(historicBatch.getBatchJobDefinitionId())
  6.   .orderByTimestamp()
  7.   .list();

You can make a configuration for history cleanup of the finished historic batch operations.

Suspend a Batch

To pause the execution of a batch and all corresponding jobs, a batchcan be suspended using the management service.

  1. processEngine.getManagementService()
  2.   .suspendBatchById("myBatch");

A suspended batch can then be activated again, also using the managementservice.

  1. processEngine.getManagementService()
  2.   .activateBatchById("myBatch");

Delete a Batch

A running batch can be deleted using the management service.

  1. // Delete a batch preserving the history of the batch
  2. processEngine.getManagementService()
  3.   .deleteBatch("myBatch", false);
  5. // Delete a batch include history of the batch
  6. processEngine.getManagementService()
  7.   .deleteBatch("myBatch", true);

A historic batch can be deleted using the history service.

  1. processEngine.getHistoryService()
  2.   .deleteHistoricBatch("myBatch");

For a running batch which still executes jobs it is recommendedto suspend the batch before deleting it.See the Suspend a Batch section for details.

Priority of a Batch

As all batch jobs are executed using the job executor, it is possible to use thejob prioritization feature to adjust the priority of batch jobs. Thedefault batch job priority is set by the process engine configurationbatchJobPriority.

It is possible to adjust the priority of a specific batch jobdefinition or even a single batch jobusing the management service.

  1. Batch batch = ...;
  3. String batchJobDefinitionId = batch.getBatchJobDefinitionId();
  5. processEngine.getManagementService()
  6.   .setOverridingJobPriorityForJobDefinition(batchJobDefinitionId, 100, true);

Operation log

Please note that a user operation log is written for Batch creation itself only, executionof the seed job as well as individual jobs that perform operations are performed by Job Executorand therefore are not considered to be user operations.

Job Definitions

Seed Job

A batch initially creates a seed job. This seed will be repeatedly executed tocreate all batch execution jobs. For example if a user starts a processinstance migration batch for 1000 process instances. With thedefault process engine configuration the seed job will create 10 batchexecution jobs on every invocation. Every execution job will migrate 1 processinstance. In sum the seed job will be invoked 100 times, until it has created the1000 execution jobs required to complete the batch.

The number of jobs created by every seed job invocation batchJobsPerSeed(default: 100) and the number of invocations per batch execution jobinvocationsPerBatchJob (default: 1) can be configured on the process engineconfiguration.

The Java API can be used to get the job definition for the seed job of a batch:

  1. Batch batch = ...;
  3. JobDefinition seedJobDefinition = processEngine.getManagementService()
  4.   .createJobDefinitionQuery()
  5.   .jobDefinitionId(batch.getSeedJobDefinitionId())
  6.   .singleResult();

To pause the creation of further batch execution jobs, the seed job definitioncan be suspended with the management service:

  1. processEngine.getManagementService()
  2.   .suspendJobByJobDefinitionId(seedJobDefinition.getId());

Execution Jobs

The execution of a batch is split into several execution jobs. The specificnumber of jobs depends on the total jobs of the batch and the process engineconfiguration (see seed job). Every execution job executes the actual batchcommand for a given number of invocations, e.g., migrate a number of processinstances. The execution jobs will be executed by the job executor. Theybehave like other jobs which means they can fail and the job executor willretry failed batch execution jobs. Also, there will be incidentsfor failed batch execution jobs with no retries left.

The Java API can be used to get the job definition for the execution jobs of abatch, e.g., for a process instance migration batch:

  1. Batch batch = ...;
  3. JobDefinition executionJobDefinition = processEngine.getManagementService()
  4.   .createJobDefinitionQuery()
  5.   .jobDefinitionId(batch.getBatchJobDefinitionId())
  6.   .singleResult();

To pause the execution of further batch execution jobs, the batch job definitioncan be suspended with the management service:

  1. processEngine.getManagementService()
  2.   .suspendJobByJobDefinitionId(executionJobDefinition.getId());

Monitor Job

After all batch execution jobs were created by the seed job a monitor jobis created for the batch. This job regularly polls if the batch has been completed,i.e., all batch execution jobs were completed. The polling intervalcan be configured by the batchPollTime (default: 30 seconds) property of the process engine configuration.

The Java API can be used to get the job definition for the monitor job of abatch:

  1. Batch batch = ...;
  3. JobDefinition monitorJobDefinition = processEngine.getManagementService()
  4.   .createJobDefinitionQuery()
  5.   .jobDefinitionId(batch.getMonitorJobDefinitionId())
  6.   .singleResult();

To prevent the completion of the batch, i.e., deletion of the runtime data, themonitor job definition can be suspended with the management service:

  1. processEngine.getManagementService()
  2.   .suspendJobByJobDefinitionId(monitorJobDefinition.getId());

原文: https://docs.camunda.org/manual/7.9/user-guide/process-engine/batch/