File Input Node

Overview

File Input loads data into a workflow run from a file upload or from pasted plaintext.

• Supports CSV, JSON, XML, Excel (.xls / .xlsx), fixed-width text, and other formats with configurable import settings (record format, delimiter, field widths, encoding, headers, skip empty rows)
• PDF and document text extraction modes on the engine
• Paste mode for email or other plaintext: one row with a body column

Canvas tile

On the workflow canvas, File Input is a square icon-led tile. Empty tiles show the file-type icon and the File Input title; hover reveals Choose source. Loaded tiles show the icon plus an editable title, with filename and row/column stats on hover. When the file is a workbook with more than one sheet, hover also shows the sheet count. Change source and Clear live on the selection toolbar (not as a permanent row on the tile). See Workflow orchestration (Square canvas tiles).

Source modes

You choose a source on the canvas tile (Choose source) or in the node editor (File | Paste). The modes are mutually exclusive: switching clears the other source so a single clear owner feeds _input.

Mode	What you provide	How the engine builds _input
File	Upload (CSV, JSON, XML, Excel, PDF, and supported types)	Existing parse / Docling paths
Paste	Full email or plaintext	Text blob (pasted-email.txt by default) → one row { body }

Paste mode stores the body as run data (engine file + inputFileRefs). Node config holds sourceMode only; you do not persist the pasted body in the workflow template.

Paste row shape

When sourceMode is paste, preload emits one row:

• body: full pasted text (including any email headers)

Extract From, Sent, Subject, and body-specific fields in a downstream Template node (string operations on row.body).

File-mode .txt uploads stay on the generic text/CSV path unless you set Record format to Fixed width. Use Paste when you want the email body row schema.

Fixed-width records

On the File Input Settings tab, Tabular Data includes Record format. The default is Delimited (CSV, TSV, PSV), which keeps the existing comma, tab, and pipe path.

Choose Fixed width when each field occupies a fixed number of characters (for example Multifonds migration files). File Input detects column widths from positions where a value starts on every row, so a title like Fund Code stays one field when the data does not start a new value there. Leave Field widths blank to use that layout. Type counts such as 10, 20, 8 to override. Leave Field names blank to use the title row, or type labels to override. With names set, Use first row as header skips that first line so a shorter title row is not measured as data.

A row that is shorter or longer than the sum of the widths fails with the file row number and the field or width that did not match.

Excel dates

When you upload an Excel workbook, date-formatted cells import as ISO dates (YYYY-MM-DD, or YYYY-MM-DDTHH:mm:ss when the cell includes a time). Numeric cells that are not dates stay numbers.

Excel headers

Use first row as header applies to Excel the same way it applies to CSV. The engine uses the same node setting on Run, so a header-off upload is not re-parsed as if the tick were on.

When the setting is on, File Input uses the first spreadsheet row as column names. Empty header cells become __EMPTY, __EMPTY_1, and so on. A merged group title is written into every cell of that merge so a later Subgrid flatten can see the span (H2:L2 Capital Flow, not only H2).

When the setting is off, File Input names columns Column 1, Column 2, and so on, and keeps the first row as data. A banner cell such as Portfolio: Maple Foundation stays in that first row; it does not become the first column name.

When a later row holds a text label in a mostly numeric column (for example Beginning Market Value on the same row as Start Date), File Input keeps that text on the grid. A Schema node that declares the column as number only still treats non-numeric cells as missing. Use Subgrid on the Source Data tab to slice the real table and flatten one or more leading rows as headers. On a region card you can drag a span or use Select Corners… (top-left cell, then bottom-right).

Empty rows

Skip empty rows is on by default. File Input then omits blank Excel rows (SheetJS sheet_to_json skips them) and blank CSV lines.

Turn Skip empty rows off on the File Input Settings tab when you need spacer rows to stay in the table, for example so Subgrid A1 coordinates match the spreadsheet (rows 9 and 10 empty, data still on row 11). Re-run the node after you change the setting.

When the setting is off, a blank Excel row becomes a row of empty cells (null). A blank CSV line becomes a row of empty strings.

Excel workbooks with several sheets

A single-sheet workbook still loads as tabular rows (one row per spreadsheet row).

When the workbook has two or more populated sheets, File Input emits one output row keyed by sheet name. Each value is { _sheetName, _sheetData }, and _sheetData keeps that sheet’s own columns. Create input from schema can then type each sheet separately instead of merging every sheet into one array schema.

On a Schema node, wire the item port under _sheetData (the {} row, path ending in .0) to get that sheet as a table (one row per spreadsheet row, columns such as Col A and Col B). The _sheetData field port itself stays one cell containing the nested array.

The File Input Output Data tab (and the output port grid) shows sheet tabs named as they are in the workbook. Switching a tab shows that sheet’s table. Cell edits stay off for this preview because the stored payload is one nested workbook row. File Info is metadata only (filename, size, type, row and column counts, and sheet badges). It does not show a row preview grid.

Empty sheets are skipped. Re-upload workbooks that you ingested before this shape existed.

XML records

When you upload .xml, File Input parses the document into structured rows (not one row per line). Repeating sibling elements become one row each with dotted nested paths. Invalid XML is rejected. See Supported formats (XML parsing). Re-upload files that were ingested before this parse path existed.

Downstream extract

Wire a Template node in entry mode and emit a JSON object string so output columns are flat (same pattern as PDF text extract). The Template node owns headers and body fields via string splits on row.body. Place a Schema node after Template so the typed columns show clearly on the canvas (Paste → extract → typed shape).

Paste an email into File Input, then ask the agent to analyse it and extract structured data. You do not need to mention Template or Schema; the email-structured-data-extract skill builds Paste → Template → Schema by default from the corpus (structured digital+hedge tickets and freeform strike/price/punched notes). Explore ships Template-only visual references (email-paste-hsbc-digital, email-paste-strike-note) plus a dual-path reference (email-paste-dual-path): one Operation SWITCH (step output ports) sends recognised confirmations through Template and routes everything else to an AI exception node.

Scheduled runs

Cron triggers currently fire with empty inputFileRefs, so File Input (upload or paste) does not preload on a pure cron path. Manual and agent-inherited runs that attach refs remain the supported path for paste.

Copying workflow JSON

When you paste another workflow’s config JSON into this workflow and save, File Input nodes keep graph structure and import settings. Files stay on the source workflow. Graph edges stay idle until you upload or attach a file here. Use Clone when you want File Input files copied with the template.

Related

• Workflow schema – Full schema reference
• Subgrid – Slice a rectangular band and optionally flatten one or more leading rows as headers