File Storage Connector

What this connector is for

Uploads, reads, deletes, and lists files in the platform's own managed file storage — scoped to your store, not a third-party integration, so no connection is needed. Every file you work with here lives at a relative path (e.g. invoices/march.csv) under your store's own namespace.

Uploading or deleting a file through this connector can fire a File Event trigger elsewhere in the store, if that trigger's File Pattern matches the file's relative path — it's the same underlying storage either way. When it fires, the trigger's data includes {{trigger.event}} (created_or_updated or deleted — the storage can't distinguish a brand-new file from an overwrite, so both count as created_or_updated), {{trigger.key}} (the file's relative path), {{trigger.size}}, and {{trigger.eventTime}}.

Most storage-level errors resolve normally, not as a failed step. If the underlying storage call itself fails in a recognizable way (e.g. reading or deleting a file that doesn't exist), Read File, Delete File, and List File typically resolve the step normally with an HTTP-shaped error you can branch on — {{<stepReference>.response.status}} (e.g. 404) and {{<stepReference>.response.data.error}} — rather than failing the step outright. The one guaranteed exception is Upload File's file-size-limit check (below), which always fails the step.

Upload File

Configuring it

• File Name — required. The relative path to write to, e.g. invoices/march.csv. Can't start with /, can't contain a .. path segment, and is capped at 1024 characters.
• Body — required. The file's content — plain text, or base64-encoded data for binary content.
• Content Type — optional, e.g. text/csv, application/pdf.
• On Conflict — overwrite (default) replaces any existing file at that exact path; createNew instead writes a new file with a timestamp appended before the extension (e.g. march.csv → march_1700000000000.csv), leaving the original untouched.
• Retention — 7, 30, 90, or 365 days, or never (default). After the chosen number of days the file is automatically deleted; never keeps it indefinitely.

Size limit: enforced independently per store and per parent organisation, each defaulting to 25MB unless configured otherwise — exceeding either fails the step with an error naming which limit was hit and the actual size involved. This is the one Upload File failure that always fails the step rather than resolving as an error response (see above).

Reading the response

• {{<stepReference>.response.data.fileName}} — the name actually written (differs from the File Name you set only when On Conflict is createNew).
• {{<stepReference>.response.data.size}} — bytes written.
• {{<stepReference>.response.data.ETag}} — the stored object's ETag.

For example, a step named "Save Invoice" (reference saveInvoice) — {{saveInvoice.response.data.fileName}}.

Example

File Name: invoices/march.csv
Body: {{generateInvoiceCsv.response.data.base64Content}}
Content Type: text/csv
On Conflict: createNew
Retention: 90

Delete File

Configuring it

• File Name — required. The relative path to delete.

Reading the response

• {{<stepReference>.response.data.success}} — true on success. Deleting a path that doesn't exist still succeeds (S3's delete is idempotent) — this isn't a reliable way to check whether a file existed first; use List Files for that.

For example, a step named "Remove Processed File" (reference removeProcessedFile) — {{removeProcessedFile.response.data.success}}.

Example

File Name: invoices/march.csv

List Files

Configuring it

• Prefix — optional. Limits results to files whose relative path starts with this (folder-like), e.g. invoices/.
• Max Files — 1 to 1000, default 1000.
• Continuation Token — pass a previous call's nextContinuationToken to fetch the next page.

Reading the response

• {{<stepReference>.response.data.files}} — an array of { fileName, lastModified, size, ETag }.
• {{<stepReference>.response.data.isTruncated}} — true if more files exist beyond Max Files.
• {{<stepReference>.response.data.nextContinuationToken}} — present when isTruncated is true; pass it back as Continuation Token for the next page.

For example, a step named "List Invoices" (reference listInvoices) — {{listInvoices.response.data.files}}.

Example

Prefix: invoices/
Max Files: 100

Read File

Configuring it

• File Name — required unless Cursor is set. The relative path to read.
• Format — raw (default, base64 content as-is), json (parsed; a top-level array becomes batchable rows), csv (parsed rows, batchable), or xml (parsed into a JSON object tree — never batched, always returned whole in one call).
• Cursor — pass a previous call's nextCursor to continue a batched read. When set, File Name/Format/CSV options are all ignored — the cursor already carries what's needed.
• Batch Size — 1 to 5000, default 500. Only relevant for csv or a json file whose top-level content is an array.
• CSV Has Header Row — default true (first row becomes column names, each row an object); false makes each row a plain array of values.
• CSV Delimiter — default ,.

Reading the response

The shape depends on Format and whether the content needed batching:

• raw — {{<stepReference>.response.data.content}} (base64 string).
• xml — {{<stepReference>.response.data.content}} (the full parsed object tree, never batched — Batch Size is ignored for xml).
• json, non-array top level — {{<stepReference>.response.data.content}} (the parsed value).
• json array or csv, fits within Batch Size — {{<stepReference>.response.data.rows}} (every row), .hasMore}} = false, no nextCursor.
• json array or csv, larger than Batch Size — {{<stepReference>.response.data.rows}} (only the first Batch Size rows), .hasMore}} = true, .nextCursor}} (feed back into Cursor to continue), .totalRows}} (the overall count).

For example, a step named "Read Invoice Rows" (reference readInvoiceRows) reading a 2,000-row CSV with the default Batch Size — the first call returns {{readInvoiceRows.response.data.rows}} (500 rows), {{readInvoiceRows.response.data.hasMore}} = true, and {{readInvoiceRows.response.data.nextCursor}}; a Loop step re-runs Read File with Cursor set to {{readInvoiceRows.response.data.nextCursor}} until hasMore is false.

Example

File Name: invoices/march.csv
Format: csv
Batch Size: 500
CSV Has Header Row: true