Save To File - Synthreo Builder

---

Purpose

The Save To File node persists data from your workflow to files on the DCS (Data and Content Store). It can collect data across multiple workflow items and accumulate everything into one file, or create a separate file for each item that flows through the workflow. Use it to generate reports, export AI-processed data, back up records, or produce files for other systems to consume.

The node performs a side-effect write operation and then passes the original input through to subsequent nodes, so the rest of the workflow can continue using the data as normal.

---

Inputs

• One or more items from upstream nodes (as objects or arrays).
• Optionally, a specific property of each item selected via the Property Name field.

---

Outputs

• Pass-through: The original input item is passed to the next node unchanged (controlled by the Option field).
• Side effect: One or more files are created or appended to on the DCS.

---

Parameters

Name	Type	Required	Default	Description
File Write Mode	Dropdown	Yes	Accumulate	Accumulate appends all inputs from a workflow run (or across multiple runs) into a single file. Write each creates one separate file per input item.
Property Name	String (expression)	No	(empty)	The specific property path within the input item to save (e.g., reportContent, items, summary). Leave empty to save the entire item. Supports dot-notation for nested properties (e.g., order.total).
Directory Path	String (expression)	No	(empty)	The DCS folder path where files are saved. Supports dynamic variable expressions (e.g., Exports/{{date}} or Reports/{{customerSegment}}/{{yyyy}}). The folder is created if it does not already exist.
File Name	String (expression)	No	(system-generated)	The name of the file to create or append to. Supports dynamic expressions (e.g., orders_{{date}}.csv, {{customerId}}.json, report_{{timestamp}}.txt). Use a dynamic value in Write each mode to ensure each item produces a uniquely named file.
Output Format	Dropdown	Yes	Text	The format in which data is written: Text writes a plain string, JSON serializes the data as JSON, CSV formats the data as comma-separated values with a header row.
CSV Delimiter	String	Conditional	,	The column separator used when Output Format is CSV. Change to ; for European locale compatibility or \t for tab-separated output. Only visible when Output Format is set to CSV.
Option	Dropdown	Yes	Pass Input Data	Controls what the node passes to downstream nodes. Currently Pass Input Data passes the original input item unchanged.

---

File Write Mode Details

Accumulate mode collects all items that flow through this node and writes them all to the same file. If the file already exists from a previous run, new data is appended. This is useful for:

• Building up a daily report incrementally as records are processed.
• Creating a running log of all workflow executions.
• Collecting AI-generated summaries into a single document.

Write each mode creates one file per item. Every time an item flows through this node, a new file is written. The File Name expression should include a dynamic value (such as an item ID or timestamp) to ensure each file has a unique name. Duplicate file names in Write each mode will overwrite the previous file with the same name. Use this mode for:

• Generating per-customer or per-order export files.
• Creating individual receipts, reports, or documents for each item.
• Exporting AI results as separate artifacts per input record.

---

Dynamic Expression Examples

Both Directory Path and File Name support variable expressions using the same {{variableName}} syntax used throughout Builder. Built-in date/time variables and upstream workflow variables can both be used.

Expression	Example result
orders_{{date}}.csv	orders_2025-03-27.csv
{{customerId}}.json	12345.json
receipt_{{order.id}}.txt	receipt_ORD-9901.txt
Reports/{{yyyy}}/{{MM}}/{{dd}}	Reports/2025/03/27
Exports/{{customerSegment}}	Exports/Enterprise

---

Output Format Details

Text - Writes the data as a plain string. If the data is an object or array, it is converted to its string representation. Best for pre-formatted content like AI-generated prose, receipts, or Markdown reports.

JSON - Serializes the data as a properly formatted JSON structure. Best for machine-readable exports and data that will be consumed by other systems or APIs. Object structure and array nesting are preserved.

CSV - Converts array data into rows with a header row derived from the property names. Each array item becomes a row. The CSV Delimiter controls column separation. Best for spreadsheet-compatible exports and data destined for Excel or database import.

---

Example Usage

Daily Orders CSV (Accumulate)

• File Write Mode = Accumulate
• Output Format = CSV
• File Name = orders_{{date}}.csv
• Directory Path = Reports/Daily
• Property Name = orders

Appends all orders processed in the day into a single CSV file. Each workflow run adds its records to the same file.

Per-Customer JSON Export (Write Each)

• File Write Mode = Write each
• Output Format = JSON
• File Name = {{customer.id}}.json
• Directory Path = Exports/Customers/{{segment}}
• Property Name = (empty - saves the entire item)

Writes one JSON file per customer with the full customer record.

Text Receipts for Email or PDF Rendering

• File Write Mode = Write each
• Output Format = Text
• File Name = receipt_{{order.id}}.txt
• Directory Path = Receipts/{{yyyy}}/{{MM}}
• Property Name = receiptText

Saves pre-formatted text receipts to a date-organized folder for downstream email or PDF generation steps.

European Locale CSV

• Output Format = CSV
• CSV Delimiter = ;
• File Name = inventory_{{warehouse}}_{{date}}.csv

Produces semicolon-delimited CSV for compatibility with European spreadsheet applications that use semicolons as the default delimiter.

---

Best Practices

• Deterministic naming: Include timestamps or IDs in file names to avoid unintended overwrites in Write each mode.
• Directory organization: Partition exports by date or entity using expressions like Exports/{{yyyy}}/{{MM}}/{{dd}} to keep the DCS organized.
• CSV stability: Keep header order consistent across runs. Use ISO date formats in date fields. Set the correct delimiter for the consuming application.
• Accumulate file size: Monitor accumulated file sizes over time. Rotate filenames daily or weekly using date expressions to prevent single files from growing too large.
• Security: Use Property Name to save only the fields required rather than entire objects that may contain sensitive data. Write to paths with appropriate access controls.
• Testing: Always verify the output format and file content with a test run before deploying to production, especially for CSV exports where column order matters.

---

Troubleshooting

• Overwritten files in Write each mode: The file name expression is probably resolving to the same value for multiple items. Add a unique identifier (such as {{id}} or {{timestamp}}) to the file name.
• Malformed CSV: Verify that all items share the same fields in the same order. Set the correct delimiter to match what the consuming application expects.
• Wrong data saved: Confirm the Property Name path is correct. Dot-notation must match the exact structure of the input object. Leave blank to save the full object if you are unsure of the path.
• Large accumulated files: Rotate file names by date to split the accumulation across multiple files. Alternatively, switch to Write each mode and archive files periodically.

---

Test Cases

• Single item to JSON: Input {id: 1, name: "A"}, Output Format = JSON, File Name = test.json - Expected: test.json contains the exact JSON structure; the node passes the original item to downstream nodes.
• Multiple items to CSV (Accumulate): 3 items with identical structure, File Write Mode = Accumulate, File Name = all.csv - Expected: One CSV with a header row plus 3 data rows; a second run appends more rows.
• Per-item text files (Write Each): 2 items, File Write Mode = Write each, File Name = {{id}}.txt, Property Name = note - Expected: Two separate text files, each containing the note value from its corresponding item.
• Semicolon-delimited CSV: Output Format = CSV, CSV Delimiter = ; - Expected: Columns are separated by semicolons with no commas used as separators.