Batching
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.
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.
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.
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.
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.
| Options | TaskJobs | Targets per job |
|---|---|---|
| none | 10 | 10 |
batch.jobSize = 30 | 4 | 25 |
batch.jobSize = 500 | 1 | 100 |
batch.maxConcurrentJobs = 4 | 4 | 25 |
batch.jobSize = 50, batch.maxConcurrentJobs = 4 | 2 | 50 |
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.
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.
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.
| Option | Superseded by |
|---|---|
flowEngine.engineService.batchSize | batch.maxFetchSize |
flowEngine.stateTask.maxConcurrentTasks | batch.maxConcurrentJobs |
flowEngine.engineService.batchTimeout | batch.timeout |
Mind the difference in units when moving over: flowEngine.engineService.batchTimeout is a plain number of seconds.