> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# connectorBatchGroupRead

> Iterates over the members of a batch group message, exposing each member as _message while the call body runs.

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](https://docs.arc.cdata.com/26.4/self-hosted/en/connectors/script.md) 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](#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.

## Related Attributes

* **\_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`:

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  ...
</arc:call>
```

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:

```
The message <MessageId> is ambiguous between the Temp and the Input.
```

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](https://docs.arc.cdata.com/26.4/self-hosted/en/scripting/keyword-reference/op-arc-push.md); 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:

| Carried-Over Attribute | Result |
| - | - |
| `output.data` or `output.filepath` on a push that also sets `isBatchGroup=true` | Error: body payload is invalid on a batch group finalizer |
| `output.batchGroupKey` | A push intended as a standalone message is added to the batch group instead |
| `output.isBatchGroup` | The next push attempts to finalize the group a second time and fails |
| `output.header:*` | Headers from one member appear on the next member or on the batch group message |
| `output.filename` | Later messages may receive the wrong name |

`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:

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  <arc:unset item="output" />
  <arc:set attr="output.data" value="[_message.body]" />
  <arc:set attr="output.filename" value="[_message.header:filename]" />
  <arc:push item="output" />
</arc:call>
```

### Regroup Members into a New Batch Group

Reads each member, renames it, and emits all members as one new batch group named `batch01`:

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  <arc:unset item="output" />
  <arc:set attr="output.batchGroupKey" value="group1024" />
  <arc:set attr="output.data" value="[_message.body]" />
  <arc:set attr="output.filename" value="x-[_message.header:filename].txt" />
  <arc:push item="output" />
</arc:call>

<arc:unset item="output" />
<arc:set attr="output.batchGroupKey" value="group1024" />
<arc:set attr="output.isBatchGroup" value="true" />
<arc:set attr="output.filename" value="batch01" />
<arc:push item="output" />
```

If the finalizer push (the last block) is omitted, the batch group is still emitted when the script finishes, named after its `batchGroupKey`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.