For example the 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 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.

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.

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.

  2.   .createBatchStatisticsQuery()
  3.   .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION)
  4.   .list();
  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 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.

Delete a Batch

A running batch can be deleted using the management service.

  1. // Delete a batch preserving the history of the batch
  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()

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.

As all batch jobs are executed using the job executor, it is possible to use the 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 using 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

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 = ...;
  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:

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 ). 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 will 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 :

  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 .

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: