Skip to main content
Iterates over the members of a batch group message, exposing each member as _message while the call body runs. This operation is only supported in Script connector templates.

​
Required Parameters

  • messageId: The Id of the batch group message to iterate. Typically referenced as [MessageId].

​
Optional Parameters

  • messageType: The message type to use when reading batch members. Accepted values are Auto, Input, Output, and Temp. The default is Auto, but read Always Set messageType to Input for best practice recommendations. Output and Temp target the script’s output and temporary message stores respectively; these are rarely needed.

​
Output Attributes

The following attributes are available on _message within the call body for each batch member:
  • _message.body: The content of the batch member message.
  • _message.header:*: The message headers of the batch member. For example, [_message.header:filename] returns the filename header.
  • _message.isBatchGroup: Available on any _message in Script context. Returns true if the current message is a batch group; returns false if it is a standard message. Useful for conditionally calling connectorBatchGroupRead only when the incoming message is a batch group.

​
Script Connector Usage

​
Always Set messageType to Input

When calling connectorBatchGroupRead in a Script connector, always explicitly set messageType to Input:
If you omit messageType, the operation searches for the message Id among both the input message and any output messages the script is creating in the current run. If the script pushes output with a batchGroupKey before the call completes, an output batch group can be assigned the same message Id as the input. When that happens, the operation cannot determine which message you mean and fails with an error like the following:
Whether this error appears depends on the order of your output pushes, so a script can pass testing and then fail on real data.

​
Clear the Output Item Before Each Push

Output attributes are not cleared by arc:push; they carry over to the next push. Call <arc:unset item="output" /> before each push to avoid unexpected behavior. Without clearing, a value set on one push can affect the next: arc:unset also clears output.batchGroupKey. On the push that finalizes a batch group with output.isBatchGroup=true, set output.batchGroupKey again after the arc:unset.

​
Producing Batch Groups on Output

To send output as a batch group, set output.batchGroupKey on each member push. Members that share the same key are grouped together. If no explicit finalizer push is made, the Script connector creates the batch group automatically at the end of the run. To define group-level properties (such as the group’s filename or headers), make an explicit finalizer push by setting output.isBatchGroup to true along with the same batchGroupKey. The finalizer emits the group at that point in the run rather than at the end. Constraints on the finalizer push:
  • output.batchGroupKey must match the key of an existing, non-empty pending group.
  • output.data and output.filepath are invalid and return an error because the group’s content is defined by its members. output.filename and other message metadata remain valid.

​
Emission Order

  • Regular output messages are emitted in push order.
  • An explicit isBatchGroup=true push emits its group at that point in the run.
  • Any remaining implicit groups are emitted at the end of the run.

​
Examples

​
Read Batch Members as Regular Messages

Reads each member of the input batch group and emits it as a regular output message:

​
Regroup Members into a New Batch Group

Reads each member, renames it, and emits all members as one new batch group named batch01:
If the finalizer push (the last block) is omitted, the batch group is still emitted when the script finishes, named after its batchGroupKey.