n8n Convert to File Node: Build CSV, JSON, Excel, XML, and Text Files from Workflow Data [Free Workflow JSON]

By Codcompass Team·2026-07-03·8 min read

Binary Serialization in n8n Workflows: Structuring Data Exports for Downstream Systems

Current Situation Analysis

Automation platforms natively process data as JSON arrays. This design enables seamless node-to-node communication but creates a friction point when external systems demand structured documents, flat reports, or binary payloads. Engineers frequently encounter broken email attachments, corrupted spreadsheet imports, or silent data degradation when transitioning from workflow memory to file-based exports.

The core issue stems from treating file generation as a terminal step rather than a serialization pipeline. Most teams configure the export node with default settings, unaware that format selection directly impacts type fidelity, memory consumption, and downstream parsing logic. For instance, CSV exports silently coerce all values to strings, while XML generators struggle with unstructured arrays. Additionally, n8n’s Convert to File node materializes the entire dataset in memory before writing. Workflows processing more than 10,000 items without upstream chunking routinely trigger heap limits or execution timeouts.

This problem is systematically overlooked because workflow builders prioritize data transformation over output formatting. The result is a fragile handoff between automation logic and external consumers, requiring manual rework or custom scripting to resolve. Without explicit serialization strategy, teams accumulate technical debt in the form of inconsistent file structures, encoding artifacts, and unpredictable downstream failures.

WOW Moment: Key Findings

Selecting the appropriate serialization format is not merely a preference; it dictates data integrity, system performance, and integration complexity. The following comparison highlights how format choice impacts real-world workflow behavior:

Format	Type Fidelity	Memory Overhead	Downstream Compatibility	Optimal Use Case
CSV	Low (strings only)	Minimal	High (universal)	Flat tabular data, legacy systems
JSON	High (native)	Moderate	High (APIs, modern apps)	Nested structures, programmatic consumption
XLSX	High (typed cells)	High	High (business users)	Financial reports, multi-sheet exports
XML	Medium (schema-dependent)	Moderate	Medium (enterprise/SOAP)	Legacy integrations, structured feeds

This finding matters because it shifts the conversation from "how do I export this?" to "what does the consumer expect, and how will it parse the payload?" Choosing XLSX over CSV for monetary values prevents rounding errors. Opting for JSON over XML reduces parsing overhead in modern microservices. Understanding these trade-offs eliminates post-export data cleaning and ensures reliable automation handoffs.

Core Solution

Building a reliable file export pipeline requires three architectural decisions: data preparation, format configuration, and binary routing. The following implementation demonstrates how to structure this workflow using n8n’s native capabilities.

Step 1: Data Preparation and Flattening

File serialization nodes expect predictable structures. Nested objects or arrays will either flatten incorrectly or trigger parsing errors. Before serialization, normalize the payload using expression-based mapping.

// Example: Normalizing nested transaction data for flat export
const normalizedItems = inputItems.map(item => ({
  json: {
    transacti

onId: item.json.id, customerName: ${item.json.client.firstName} ${item.json.client.lastName}, regionCode: item.json.client.location.region, netAmount: Number(item.json.finance.total), processedDate: item.json.finance.timestamp.split('T')[0] } }));


**Rationale:** Flattening upstream prevents `[object Object]` artifacts in CSV and ensures consistent column mapping. This approach also reduces memory pressure by stripping unused nested fields before serialization. Explicit type casting (`Number()`) guarantees numerical precision survives the transformation pipeline.

### Step 2: Format Configuration
Configure the serialization node based on consumer requirements. Each format exposes distinct parameters that control output structure.

```json
{
  "nodeType": "n8n-nodes-base.convertToFile",
  "name": "SerializePayload",
  "parameters": {
    "operation": "csv",
    "options": {
      "fileName": "={{ $now.format('yyyy-MM-dd') }}_transaction-export.csv",
      "includeHeaderRow": true,
      "includeBOM": true,
      "delimiter": ","
    }
  }
}

Rationale: Dynamic filenames prevent overwrite collisions in storage systems. Enabling UTF-8 BOM ensures Windows-based spreadsheet applications correctly interpret non-ASCII characters. Explicit delimiter configuration avoids locale-dependent parsing failures. The operation field acts as the primary switch, routing the node’s internal serializer to the correct engine.

Step 3: Binary Routing and Downstream Consumption

The serialization node outputs binary data under a configurable property name. Downstream nodes must reference this exact property to attach or transmit the file.

{
  "nodeType": "n8n-nodes-base.httpRequest",
  "name": "UploadToStorage",
  "parameters": {
    "url": "https://api.storage-provider.com/v1/uploads",
    "method": "POST",
    "bodyContentType": "formdata",
    "sendBinaryData": true,
    "binaryPropertyName": "exportPayload"
  }
}

Rationale: Decoupling the binary property name from defaults prevents routing failures when multiple files are generated in parallel. Explicit property mapping ensures deterministic behavior across complex workflows. When chaining multiple export nodes, semantic naming (reportBinary, feedPayload, archiveData) eliminates collision risks.

Architecture Decisions

Chunking Strategy: For datasets exceeding 10,000 items, implement a SplitInBatches node upstream. Serialize each chunk independently, then use a Merge node with a concatenate strategy to assemble the final payload. This prevents heap exhaustion and enables resumable exports.
Type Preservation: When numerical precision or date formatting matters, avoid CSV. XLSX maintains cell-level type metadata, while JSON preserves native JavaScript types. Choose based on downstream parsing capabilities.
Binary Property Naming: Always override the default data property when workflows generate multiple file types. Use semantic names to prevent collision in parallel branches and simplify debugging.

Pitfall Guide

Binary Property Mismatch
- Explanation: The serialization node defaults to data as the binary property name. If the downstream node expects attachment or filePayload, the connection fails silently or throws a missing property error.
- Fix: Explicitly set Put Output File in Field to match the consumer’s expected property, or insert a MoveBinaryData node to rename the payload before routing.
Silent Type Coercion in Flat Formats
- Explanation: CSV and TSV formats serialize all values as strings. Downstream systems importing these files may misinterpret dates, strip leading zeros from IDs, or apply locale-specific number formatting.
- Fix: Use XLSX for typed data, or prepend CSV values with a tab character (\t) to force string interpretation in spreadsheet applications. Validate import mappings in the target system.
Nested Object Serialization Failure
- Explanation: File formats like CSV cannot represent hierarchical data. Objects and arrays render as [object Object] or [object Array], corrupting the export.
- Fix: Flatten structures upstream using expression mapping or a Code node. For JSON exports, ensure the Format option is set to All Items to preserve array boundaries.
Memory Exhaustion on Large Payloads
- Explanation: The serialization node materializes the entire dataset in memory before writing. Workflows processing >10,000 items frequently trigger JavaScript heap out of memory errors.
- Fix: Implement batch processing with SplitInBatches. Serialize chunks independently, write to temporary storage, and concatenate downstream. Monitor execution memory via n8n’s built-in metrics.
Missing File Extensions in HTTP Responses
- Explanation: Returning a file via Respond to Webhook without a proper extension causes browsers to misinterpret the payload, triggering download failures or incorrect MIME type detection.
- Fix: Always append the correct extension to the fileName parameter. Set Content-Type headers explicitly in the webhook response node to match the format (e.g., application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for XLSX).
XML Array Nesting Ambiguity
- Explanation: When a JSON field contains an array, the XML generator may create inconsistent tag structures or duplicate root elements, breaking schema validation.
- Fix: Pre-process arrays into a consistent object structure. Define explicit Item Element and Root Element names. Validate output against the target XSD before production deployment.
BOM Omission Causing Encoding Artifacts
- Explanation: Windows applications often misinterpret UTF-8 files without a Byte Order Mark, resulting in garbled characters in the first column or row.
- Fix: Enable Include BOM for CSV exports targeting Excel or legacy Windows systems. For cross-platform APIs, omit BOM to prevent parsing errors in strict JSON/XML consumers.

Production Bundle

Action Checklist

Audit downstream consumer requirements: Determine expected format, type fidelity, and parsing constraints before selecting an export format.
Flatten nested structures upstream: Use expression mapping or a transformation node to ensure all data aligns with the target format’s schema.
Configure binary property names explicitly: Override default data names to prevent routing collisions in multi-file workflows.
Implement chunking for large datasets: Use batch splitting to keep memory usage under 512MB per execution cycle.
Validate encoding and BOM settings: Enable UTF-8 BOM for Windows spreadsheet targets; disable for API consumers.
Test with edge-case payloads: Include null values, special characters, and large strings to verify serialization stability.
Set explicit MIME types in webhook responses: Match Content-Type headers to the exported format to ensure correct browser handling.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Financial reporting with precise decimals	XLSX export	Preserves cell-level type metadata and prevents rounding errors	Moderate (higher memory usage)
Legacy system integration requiring flat tables	CSV with BOM	Universal compatibility; BOM ensures Windows encoding correctness	Low (minimal overhead)
API-driven microservice data exchange	JSON (All Items)	Native type preservation; zero parsing transformation needed	Low (efficient serialization)
Enterprise SOAP/EDI feed generation	XML with explicit root/item tags	Schema compliance; predictable tag nesting	Moderate (requires strict validation)
High-volume log archival (>50k rows)	Chunked CSV + S3 multipart upload	Prevents heap exhaustion; enables resumable transfers	High (requires orchestration logic)

Configuration Template

{
  "name": "DataExportPipeline",
  "nodes": [
    {
      "parameters": {
        "rule": {
          "interval": [
            { "field": "days", "hoursInterval": 24 }
          ]
        }
      },
      "name": "DailyTrigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1
    },
    {
      "parameters": {
        "jsCode": "return items.map(i => ({\n  json: {\n    id: i.json.id,\n    customer: i.json.customer.name,\n    amount: Number(i.json.transaction.total),\n    date: i.json.transaction.date.toISOString().split('T')[0]\n  }\n}));"
      },
      "name": "NormalizePayload",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2
    },
    {
      "parameters": {
        "operation": "xlsx",
        "options": {
          "fileName": "={{ $now.format('yyyy-MM-dd') }}_transactions.xlsx",
          "sheetName": "DailySummary"
        }
      },
      "name": "SerializeToExcel",
      "type": "n8n-nodes-base.convertToFile",
      "typeVersion": 1
    },
    {
      "parameters": {
        "operation": "send",
        "subject": "={{ $now.format('yyyy-MM-dd') }} Transaction Report",
        "attachmentsUi": {
          "attachmentsBinary": [
            { "property": "spreadsheetData" }
          ]
        }
      },
      "name": "NotifyStakeholders",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2
    }
  ],
  "connections": {
    "DailyTrigger": { "main": [{ "node": "NormalizePayload", "type": "main", "index": 0 }] },
    "NormalizePayload": { "main": [{ "node": "SerializeToExcel", "type": "main", "index": 0 }] },
    "SerializeToExcel": { "main": [{ "node": "NotifyStakeholders", "type": "main", "index": 0 }] }
  }
}

Quick Start Guide

Prepare your data source: Connect your database, API, or spreadsheet node to fetch the target dataset. Ensure timestamps and IDs are formatted consistently.
Insert a transformation step: Add a Code or Set node to flatten nested objects, cast numerical types, and remove unused fields. This prevents serialization artifacts.
Configure the export node: Add the Convert to File node. Select your target format, set a dynamic filename with the current date, and explicitly name the binary output property (e.g., exportPayload).
Route the binary data: Connect the export node to your destination (email, storage, or webhook). Verify that the destination node references the exact binary property name you configured.
Execute and validate: Run the workflow with a small sample dataset. Download the generated file and verify type preservation, encoding, and structure before scaling to production volumes.

🎉 Mid-Year Sale — Unlock Full Article

Base plan from just $4.99/mo or $49/yr

7-day free trial · Cancel anytime · 30-day money-back