Aggregate Binary

Collect binary data from multiple items into a single output item

Overview

The Aggregate Binary tool reads binary data from N input items and produces a single output item containing all binary properties merged together. Each input item’s binary data is re-stored under a new property name based on the chosen naming mode (indexed, originalFileName, or inputFieldName). The output item includes a metadata array listing all collected files with their property names, original file names, MIME types, and sizes. No external API or credentials are required — this is a pure data transformation tool.

Category: Core Nodes
Tool Name: aggregate_binary
Version: 1

Appearance: Icon: aggregate | Color: #7722CC

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Parameters

Parameter	Type	Required	Default	Description
Binary Property	string	No	data	Name of the binary property to read from each input item. Items without this binary property are silently skipped. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.
Output Property Prefix	string	No	file	Prefix used for naming output binary properties in “indexed” naming mode. Each property will be named {prefix}_0, {prefix}_1, etc. (shown when Naming Mode is indexed)
Naming Mode	options	No	indexed	How to name each binary property in the output item.
				Options: indexed (name properties as {prefix}_0, {prefix}_1, etc.), originalFileName (use the original file name from binary metadata, sanitized and deduplicated), inputFieldName (use a value from a JSON field on each input item as the property name)
Name Source Field	string	No	name	JSON field on each input item to use as the binary property name. The value is sanitized (non-alphanumeric characters replaced with underscores). (shown when Naming Mode is inputFieldName)
Include Metadata Array	boolean	No	true	Whether to include a metadata array in the output JSON listing all collected files with their property names, file names, MIME types, and sizes.
Metadata Field Name	string	No	files	Name of the metadata array field in the output JSON. (shown when Include Metadata Array is true)
Max Concurrency	number	No	10	Maximum number of input items to hydrate concurrently from the store.

Output Data

Every input item is collapsed into one output item on the main port. That item carries all of the collected binary properties together, named according to Naming Mode. The input JSON does not pass through — the output JSON contains only the fields listed below.

{
  "files": [
    {
      "index": 0,
      "propertyName": "file_0",
      "fileName": "invoice.pdf",
      "mimeType": "application/pdf",
      "fileSize": 48213,
      "sourcePointer": "..."
    }
  ],
  "totalFiles": 1
}

• totalFiles is always present and counts the binaries that were actually collected.
• The metadata array is written under the name given by Metadata Field Name (files by default) and is present only when Include Metadata Array is on. Each entry describes one collected file; sourcePointer is an internal reference to the input item it came from.
• Input items that do not carry the named Binary Property are skipped silently — they produce no metadata entry and are not counted in totalFiles.
• In originalFileName and inputFieldName modes, names are sanitized and duplicates get a numeric suffix (report, report_1, report_2), so no file is lost to a name collision.

Reference a collected file downstream by its property name, and the metadata by expression, e.g. {{ $json.files[0].fileName }}.

Usage Examples

• Aggregate downloaded files into a single item for email attachment
• Merge binary outputs from parallel branches
• Collect images from multiple API responses into one item
• Combine PDF files from multiple sources before compression
• Gather attachments for a multi-file upload

Example Configuration

Collects all data binary properties and names them file_0, file_1, etc. Includes a metadata array under aggregated_files:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "indexed",
    "outputPropertyPrefix": "file",
    "includeMetadataArray": true,
    "metadataFieldName": "aggregated_files",
    "maxConcurrency": 10
  }
}

Uses the original file name stored in each binary item’s metadata (sanitized and deduplicated) as the property name:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "originalFileName",
    "includeMetadataArray": true,
    "metadataFieldName": "file_index",
    "maxConcurrency": 5
  }
}

Each input item has a JSON field (e.g. reportId) whose value becomes the binary property name in the output:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "attachment",
    "namingMode": "inputFieldName",
    "nameSourceField": "reportId",
    "includeMetadataArray": true,
    "metadataFieldName": "reports_metadata",
    "maxConcurrency": 8
  }
}

Collects binaries without producing a metadata array in the output JSON. Metadata Field Name is omitted because Include Metadata Array is off:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "indexed",
    "outputPropertyPrefix": "asset",
    "includeMetadataArray": false,
    "maxConcurrency": 10
  }
}

Minimal configuration — reads from data, uses indexed naming with the default file prefix, writes the metadata array to files, concurrency of 10. Set Output Property Prefix only when you want a prefix other than file:

{
  "type": "aggregate_binary",
  "parameters": {
    "namingMode": "indexed"
  }
}

When a previous node downloads multiple files, aggregate them into one item before passing to a compression or upload node:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "data",
    "namingMode": "originalFileName",
    "includeMetadataArray": true,
    "metadataFieldName": "file_list",
    "maxConcurrency": 10
  }
}

Each input item carries a jobId field and a PDF binary under report. Aggregate all PDFs, naming each by its job ID:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "report",
    "namingMode": "inputFieldName",
    "nameSourceField": "jobId",
    "includeMetadataArray": true,
    "metadataFieldName": "reports",
    "maxConcurrency": 4
  }
}

When processing many images in a pipeline where metadata is not needed downstream, disable the metadata array to reduce output size:

{
  "type": "aggregate_binary",
  "parameters": {
    "binaryPropertyName": "image",
    "namingMode": "indexed",
    "outputPropertyPrefix": "img",
    "includeMetadataArray": false,
    "maxConcurrency": 20
  }
}

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

Aggregate Binary collects binary data from multiple input items and merges them into a single output item with distinctly named binary properties. Use it when a workflow produces several binary files across separate items and a downstream node requires all files consolidated under one item. The output item contains merged binary properties named by index, original file name, or input field name, plus a metadata array detailing each file with its property name, MIME type, and size.