Skip to main content

Batching

process-automation-component2.0.0+

The Schedule and FlowEngine triggers work in batches. Every time such a trigger fires, it collects the elements waiting in the transition's begin state and processes them as one run, spread over a handful of parallel jobs.

This gives you three things a plain queue does not: a run cannot overlap with itself, you can limit its concurrency, and you can follow the progress of a run while it happens.

A single transition gets scheduled as a single TaskJob. This taskjob will manage its own retry on failure.
A BatchJob is another element which manages the execution of many elements at once. Multiple TaskJobs are scheduled
to contribute to the batch. Failures are retried by the next execution of a batch with the same key.

As a consequence of the batching, TaskJobs targeting processAutomation::BatchJob contain a transition and a list of targets as their payload. All targets within one TaskJob are executed sequentially. The number of TaskJobs determines the level of concurrency a batch allows.

One run at a time​

A new run only starts once the previous one has completed or timed out. Triggers that fire in between are skipped, with a warning naming the transition.

Batches can define a timeout. Once the timeout is reached, the batch is considered stuck and aborted. Note that this does not abort the tasks, but frees up the batch key to start a new execution.

Option
batch.timeout TransitionWorkflowComponentApplicationCascading

Set the window in which a batch must complete. A batch which is still active after this window is invalidated and no longer blocks a new batch for the same key. (Default: 1h)

<options>
<batch.timeout>15m</batch.timeout>
</options>

A number followed by h, m or s. Use 0s to drop the window entirely, in which case a stalled run blocks its transition until it finishes.

How much runs in parallel​

The elements of a run are divided over a number of parallel TaskJobs, and each job works through its own share one element after another. The number of TaskJobs in a batch is what decides how many elements can be executed at the same time.

You do not set that number directly. You set how many elements one job should handle, and the number of jobs follows from the size of the run — 100 elements at the default of ten per job give 10 jobs. Raise the share per job when the elements are quick to process and the per-job overhead starts to dominate.

Option
batch.jobSize TransitionWorkflowComponentApplicationCascading

Set the targeted number of elements in a single batch job (default: 10). The number of jobs is ceil(#elements / jobSize), limited by batch.maxConcurrentJobs.

<options>
<batch.jobSize>30</batch.jobSize>
</options>

A batch with fewer elements than the declared jobSize still uses a single job.

On top of that sits a hard ceiling on the number of jobs, for when a transition takes too much of the queue away from the rest of the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.. Lowering it makes each job larger rather than dropping work. Some tasks may not be implemented to handle concurrent execution. Set maxConcurrentJobs to 1 to guarantee exclusive access, even across nodes.

Option
batch.maxConcurrentJobs TransitionWorkflowComponentApplicationCascading

Set the maximum number of task jobs which may be created to perform this batch. This guarantees concurrency limits across multiple worker nodes.

<options>
<batch.maxConcurrentJobs>4</batch.maxConcurrentJobs>
</options>

This is a limit for the whole applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution., not per worker node: a BatchJob is only created once. Each TaskJob contributing to the batch can be picked up by any of the available WorkerNodes.

With 100 targets in a run, the two options combine as follows. The targets are distributed evenly over the jobs, not greedily: batch.jobSize = 30 gives four jobs of 25, not three jobs of 30 and one of 10.

OptionsTaskJobsTargets per job
none1010
batch.jobSize = 30425
batch.jobSize = 5001100
batch.maxConcurrentJobs = 4425
batch.jobSize = 50, batch.maxConcurrentJobs = 4250

How much work per run​

By default a run takes every element waiting in the begin state. A large backlog then has to be held in memory at once, on top of the rows it loads from the database. Limiting the fetch size bounds that cost. The next trigger will pick up remaining work.

Option
batch.maxFetchSize TransitionWorkflowComponentApplicationCascading

previously schedule.maxFetchSize

Defines a maximum number of jobs which may be fetched in a single batch trigger. (Default: unlimited)

<options>
<batch.maxFetchSize>150</batch.maxFetchSize>
</options>

Following a run​

Each run is visible as a BatchJob, available in the process automation UI. The list hides Done runs by default. It shows which transition the run belongs to, how many elements it covers, how many of its jobs have finished, and how many of them hit a failure. This should give you enough information to decide if everything is okay.

Finished runs are cleaned up automatically every night at 00:00. How long a run is kept depends on how it ended: Done runs are removed after 24 hours, Failed and Cancelled runs after 7 days. For a record of what went wrong, see Retries and Job Failures instead. A single element failing does not fail the batch. The failure is recorded, the job carries on with its remaining elements, and the failed element is offered again on a later run of the same transition.

Failures are recorded per task, not per batch: a run in which three elements fail creates three JobFailure records, one for each failed task, rather than a single record for the entire batch.

Running without batches​

A transition can opt out of batching altogether and submit its elements to the queue individually, the way the non-batching triggers do.

Option
batch.unmanaged TransitionWorkflowComponentApplicationCascading

Submit tasks directly to the queue instead of grouping them into a batch. No parent batch is created and no batch progress tracking is available for these tasks.

<options>
<batch.unmanaged/>
</options>

Doing so gives up everything described above. There is no progress to follow, batch.timeout, batch.jobSize and batch.maxConcurrentJobs no longer apply, and — most importantly — runs are no longer mutually exclusive. A trigger that fires faster than its elements are processed will submit the same elements again.

batch.maxFetchSize does still limit how many elements a single trigger picks up.

Older FlowEngine options​

The FlowEngine trigger has its own, older options that cover some of the same ground. They still work, and a batch.* option always wins where both are set.

OptionSuperseded by
flowEngine.engineService.batchSizebatch.maxFetchSize
flowEngine.stateTask.maxConcurrentTasksbatch.maxConcurrentJobs
flowEngine.engineService.batchTimeoutbatch.timeout

Mind the difference in units when moving over: flowEngine.engineService.batchTimeout is a plain number of seconds.