<!-- BusyBot node reference — https://busybot.net/tools/item-lists/ -->

> Node: Item Lists (`item_lists`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Item Lists

> Sort, limit, deduplicate, split, concatenate, and summarize items

## Overview

The Item Lists tool provides 6 bulk operations on item collections: sort (simple or random), limit (first/last N), removeDuplicates (by all/selected/excluded fields), splitOutItems (explode arrays into separate items), concatenateItems (merge fields from all items into one), and summarize (aggregate with count, sum, min, max, average, concatenate, append, countUnique — grouped by split-by fields). These are bulk operations that process ALL input items at once.

**Category:** Core Nodes  
**Tool Name:** `item_lists`  
**Version:** 1

**Appearance:** Icon: `lucide-List` | Color: `#ff6d5a`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Concatenate Items | `concatenateItems` | Merge fields from all items into one |
| Limit | `limit` | Remove items if there are too many |
| Remove Duplicates | `removeDuplicates` | Remove duplicate items |
| Sort | `sort` | Change the order of items |
| Split Out Items | `splitOutItems` | Turn array into separate items |
| Summarize | `summarize` | Aggregate items (pivot table) |

### Parameters

#### Concatenate Items (`concatenateItems`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Aggregate | `options` | No | `aggregateIndividualFields` | How the items are merged together. |
| | | | | Options: `aggregateIndividualFields` (collect named fields into arrays), `aggregateAllItemData` (put every input item into one field) |
| Fields To Aggregate | `fixedCollection` | No | `{}` | The fields to collect from every item, and how to name them on the output. _(shown when Aggregate is `aggregateIndividualFields`)_ |
| — Input Field Name | `string` | No | — | Name of the field to read from each item. Supports dot-notation for nested fields. |
| — Rename Field | `boolean` | No | `false` | Give the collected values a different name on the output item. |
| — Output Field Name | `string` | No | — | The name to write the collected values under. _(shown when Rename Field is `true`)_ |
| — Merge Lists | `boolean` | No | `false` | If the field is an array, merge into the aggregate instead of nesting. |
| Destination Field Name | `string` | No | `data` | Name of the field that receives the full list of input items. _(shown when Aggregate is `aggregateAllItemData`)_ |

#### Limit (`limit`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Items | `number` | No | `10` | The maximum number of items to keep. |
| Keep | `options` | No | `firstItems` | Which items to keep when there are more than Max Items. |
| | | | | Options: `firstItems`, `lastItems` |

#### Remove Duplicates (`removeDuplicates`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Compare | `options` | No | `allFields` | How two items are compared to decide whether they are duplicates. |
| | | | | Options: `allFields`, `allFieldsExcept`, `selectedFields` |
| Fields To Compare | `string` | No | — | Comma-separated list of the only fields to compare. _(shown when Compare is `selectedFields`)_ |
| Fields To Exclude | `string` | No | — | Comma-separated list of fields to ignore when comparing. _(shown when Compare is `allFieldsExcept`)_ |

#### Sort (`sort`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Sort Type | `options` | No | `simple` | Sort by field values, or shuffle the items into a random order. |
| | | | | Options: `simple`, `random` |
| Sort Fields | `fixedCollection` | No | `{}` | The fields to sort by, applied in the order you list them. _(shown when Sort Type is `simple`)_ |
| — Field Name | `string` | No | — | Name of the field to sort on. Supports dot-notation for nested fields. |
| — Order | `options` | No | `ascending` | Sort direction for this field. |
| | | | | Options: `ascending`, `descending` |

#### Split Out Items (`splitOutItems`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Field To Split Out | `string` | Yes | — | The field holding the array (or object) to turn into separate items. |
| Include | `options` | No | `noOtherFields` | Which of the item's other fields to carry onto each new item. |
| | | | | Options: `noOtherFields`, `allOtherFields`, `selectedOtherFields` |
| Fields To Include | `string` | No | — | Comma-separated list of the other fields to carry over. _(shown when Include is `selectedOtherFields`)_ |

#### Summarize (`summarize`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Fields to Summarize | `fixedCollection` | No | `{}` | The aggregations to compute for each group. |
| — Aggregation | `options` | No | `count` | The aggregation to apply to the field. |
| | | | | Options: `append`, `average`, `concatenate`, `count`, `countUnique`, `max`, `min`, `sum` |
| — Field | `string` | No | — | Field to aggregate (leave empty for count). |
| Fields to Split By | `string` | No | — | Group items by these fields before summarizing. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Options | `collection` | No | `{}` | Extra settings; which ones apply depends on the operation. |
| — Disable Dot Notation | `boolean` | No | `false` | If true, field names with dots are treated literally. |
| — Remove Other Fields | `boolean` | No | `false` | When deduplicating by selected fields, only keep those fields. _(shown when Operation is `removeDuplicates` and Compare is `selectedFields`)_ |
| — Destination Field Name | `string` | No | — | Write each split-out element under this name instead of the original field name. _(shown when Operation is `splitOutItems`)_ |
| — Put Output in Field | `string` | No | — | Write the merged list under this name instead of Destination Field Name. _(shown when Operation is `concatenateItems`)_ |
| — Output Format | `options` | No | `separateItems` | Whether each group becomes its own item or all groups land on one item. _(shown when Operation is `summarize`)_ |
| | | | | Options: `separateItems`, `singleItem` |
| — Separator | `string` | No | `,` | Separator for concatenate aggregation. _(shown when Operation is `summarize`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

This node is a **bulk** node: it reads every input item, applies the operation to the whole collection in memory, and writes a fresh set of output items. Output items carry JSON only — **binary data is not forwarded**, so attach files after this node, not before it.

How many items come out depends on the operation:

| Operation | Output items |
|-----------|--------------|
| `sort` | The same items, reordered. Count is unchanged. |
| `limit` | At most Max Items — the first or last of them, per Keep. |
| `removeDuplicates` | One item per distinct value. Duplicates after the first are dropped. |
| `splitOutItems` | One item per element of the split field, so one input item can become many. An item whose field is neither an array nor an object passes through untouched. |
| `concatenateItems` | Exactly one item for the whole run. |
| `summarize` | One item per group with `separateItems`, or a single item with `singleItem`. |

Field naming, per operation:

- **`concatenateItems` with `aggregateIndividualFields`** — the single output item has one field per entry in Fields To Aggregate, each holding an array of the values found across all items. The field keeps its input name unless Rename Field is on, in which case Output Field Name is used. With Merge Lists on, an array value is spread into the aggregate rather than nested. If Fields To Aggregate is empty the items pass through unchanged.
- **`concatenateItems` with `aggregateAllItemData`** — the single output item is `{ "<Destination Field Name>": [ …every input item… ] }`, or the name from Put Output in Field when that is set.
- **`splitOutItems`** — each element is written to Destination Field Name when set, otherwise to the name of Field To Split Out. With `allOtherFields` the rest of the item is copied alongside it; with `selectedOtherFields` only Fields To Include are copied; with `noOtherFields` the element is the only field.
- **`summarize`** — each output item carries the Fields to Split By values plus one field per aggregation, named `<aggregation>_<field>` (for example `sum_revenue`, `average_score`). An aggregation with no Field is named after the aggregation alone (`count`). `min`, `max`, `sum` and `average` consider numeric values only and return `null` when a group has none. With `singleItem` the whole set is wrapped as `{ "results": [ … ] }` on one item.
- **`removeDuplicates`** — the surviving item is the original item, unless Remove Other Fields is on with `selectedFields`, in which case only the compared fields are kept.

## Usage Examples

- Sort items by price descending
- Keep only first 10 items
- Remove duplicate contacts
- Split array field into separate items
- Summarize sales by region

## Example Configuration

Sort by two fields, most important first:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "sort",
    "sortType": "simple",
    "sortFieldsUi": {
      "sortField": [
        {
          "fieldName": "priority",
          "order": "descending"
        },
        {
          "fieldName": "name",
          "order": "ascending"
        }
      ]
    }
  }
}
```

Keep only the first five items:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "limit",
    "maxItems": 5,
    "keep": "firstItems"
  }
}
```

Deduplicate on two fields only:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "removeDuplicates",
    "compare": "selectedFields",
    "fieldsToCompare": "email,phone"
  }
}
```

Explode an array field, carrying two other fields onto each new item:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "splitOutItems",
    "fieldToSplitOut": "skills",
    "include": "selectedOtherFields",
    "fieldsToInclude": "name,department"
  }
}
```

Collect one field from every item into a single list:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "concatenateItems",
    "aggregate": "aggregateIndividualFields",
    "fieldsToAggregate": {
      "fieldToAggregate": [
        {
          "fieldToAggregate": "tags",
          "renameField": true,
          "outputFieldName": "allTags",
          "mergeLists": true
        }
      ]
    }
  }
}
```

Put every input item into one field:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "concatenateItems",
    "aggregate": "aggregateAllItemData",
    "destinationFieldName": "allData"
  }
}
```

Build a pivot table grouped by two fields:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "summarize",
    "fieldsToSplitBy": "department,status",
    "fieldsToSummarize": {
      "values": [
        {
          "aggregation": "count",
          "field": "employeeId"
        },
        {
          "aggregation": "sum",
          "field": "salary"
        }
      ]
    }
  }
}
```

Deduplicate while ignoring volatile fields:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "removeDuplicates",
    "compare": "allFieldsExcept",
    "fieldsToExclude": "id,createdAt",
    "options": {
      "disableDotNotation": false
    }
  }
}
```

Report on revenue by region and quarter:

```json
{
  "type": "item_lists",
  "parameters": {
    "operation": "summarize",
    "fieldsToSplitBy": "region,quarter",
    "fieldsToSummarize": {
      "values": [
        {
          "aggregation": "count",
          "field": "orderId"
        },
        {
          "aggregation": "sum",
          "field": "revenue"
        },
        {
          "aggregation": "average",
          "field": "customerSatisfaction"
        }
      ]
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Sort, limit, deduplicate, split, concatenate, and summarize item arrays — bulk operations on all items at once.

### Behavior notes

- **This is a whole-branch operation.** The node collects every item that reaches it before it does anything, so it cannot start producing output until the upstream branch has finished. Field names are read once for the node run, not per item.
- **Field names are literal, not expressions.** Fields To Compare, Field To Split Out, Fields to Split By and the rest take plain field names — with dot-notation for nested paths — rather than `{{ … }}` expressions.
- **Dot-notation is on by default.** A field whose name genuinely contains a dot is only reachable with Options → Disable Dot Notation turned on, which then applies to every field name in the node.
- **Deduplication compares values, not identity.** Two items match when the compared portion is deeply equal, so field order does not matter but a differing timestamp or id does — use `allFieldsExcept` to ignore those.
- **Attach files after this node.** Binary data does not survive the operation, so put Item Lists before the node that fetches or builds the file, not after it.