split

Processor that splits a collection payload into fragments and sends each fragment as a separate message to one target flow.

Processing is not considered complete until a response has been received for every fragment.

If the payload is a collection, each element becomes one fragment by default. Use chunkSize to group elements into list-fragments of up to N elements each — for example, chunkSize = 3 on a collection of 10 orders produces 4 fragments: three containing 3 orders each and one containing the remaining 1. Use this when the target system accepts small batches but not individual records. If the payload is not a collection, the whole payload is used as a single fragment.

The flow referenced by flowId must be either a Headless flow or a flow whose source is a handoff-family processor ( handoff, scheduledHandoff, or windowedAggregationHandoff). Flows with outward-facing sources such as restApi cannot be used as target flows.

The two most common choices are:

Headless flow: All fragment processing is inlined into the main flow, which waits for all fragments to complete. No additional message persistence occurs, making this the higher-performance option. Use this approach when all fragment processing must complete before the main flow continues, or when high-performance inline processing is required. If an aggregate processor is placed at the end of the target pipeline, split additionally returns a composite result: { "numberOfFragments": N, "fragments": [...] }. Use this approach when the main flow must collect the results from all fragments.
OneWay + handoff flow: The main flow receives handoff receipts as soon as each fragment is handed off to the target source. Target processing continues independently, with its own persistence, delivery guarantee, redelivery, and dead letter handling. Each handoff target flow persists every fragment independently. This additional persistence is the tradeoff for independent delivery guarantees and is the preferred approach when fragment processing must be decoupled from the main flow.

Processing is not considered complete until all fragments have received a response. The split processor maintains non-persistent state to track which fragments have received a response. If redelivery is triggered from the source, the processor skips fragments that have already received a response. However, because this state is non-persistent, a flow server restart between the original delivery and redelivery attempt causes all fragments to be delivered again.

This has the following connotations:

Message processing is considered successful only when all fragments report success.
Any delivery guarantee must be implemented upstream in the main flow unless handoff target flows are used, in which case each target flow provides its own delivery guarantees.
Because state is non-persistent, target flows that are not idempotent must implement any required guarantees themselves.

Properties

Name Summary

Name	Summary
`splitterExpiryMillis`	The amount of time after splitting is initiated the splitter maintains state of delivery.
`flowId`	The flow that the fragments will be forwarded to.
`chunkSize`	Optional integer that splits the collection into list-fragments, where each fragment contains a list of at most `chunkSize` elements from the original collection. Note that the last list-fragment could have fewer elements than the configured chunk size. If not set, the incoming collection will be split into one fragment per collection element.
`splitterExpiryCheckMillis`	The frequency of which the splitter checks for and evicts its internal state for abandoned/failed splittings.
`splitterMaxMessages`	The maximum number of active messages that the splitter processor can handle simultaneously. This refers to the number of incoming messages, not the number of message fragments produced by the splitter. If this threshold is reached, the splitter will replace an existing entry by using an undefined strategy.
`allowEmptyPayload`	Optional flag indicating whether the splitter allows empty payloads or not. If `true`, the message exchange will succeed when there are no elements in the payload. If `false`, the message exchange will fail. Defaults to `true`.
`retainPayloadOnFailure`	Whether the incoming payload is available for error processing on failure. Defaults to `false`.
`name`	Optional, descriptive name for the processor.
`id`	Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern `[a-zA-Z][a-zA-Z0-9_-]{2,29}`.
`exchangeProperties`	Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

splitterExpiryMillis

The amount of time after splitting is initiated the splitter maintains state of delivery.

flowId

The flow that the fragments will be forwarded to.

chunkSize

Optional integer that splits the collection into list-fragments, where each fragment contains a list of at most chunkSize elements from the original collection. Note that the last list-fragment could have fewer elements than the configured chunk size. If not set, the incoming collection will be split into one fragment per collection element.

splitterExpiryCheckMillis

The frequency of which the splitter checks for and evicts its internal state for abandoned/failed splittings.

splitterMaxMessages

The maximum number of active messages that the splitter processor can handle simultaneously. This refers to the number of incoming messages, not the number of message fragments produced by the splitter. If this threshold is reached, the splitter will replace an existing entry by using an undefined strategy.

allowEmptyPayload

Optional flag indicating whether the splitter allows empty payloads or not. If true, the message exchange will succeed when there are no elements in the payload. If false, the message exchange will fail. Defaults to true.

retainPayloadOnFailure

Whether the incoming payload is available for error processing on failure. Defaults to false.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

Sub-builders

Name	Summary
inboundTransformationStrategy	Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.

Name

Summary

inboundTransformationStrategy

Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

Details

Results

The split processor produces a result only after the target flow responds to every element in the collection. The processor does not aggregate the responses. Instead, it returns the processing response from one element. The processor selects the response in the following order of precedence:

Message failure from a non-transient error
Message failure from a transient error
Successful message
Filtered message

For example, if the main flow (a REST endpoint) receives a JSON array of two objects and the second object causes a script error in the target flow, the split processor returns the script error. If both objects process successfully, the split processor returns only one of their responses. The processor does not define which response it returns.

For design guidance and a pattern decision table, see Splitting Collections and Choosing the Right Pattern.

Was this page helpful?