SaveToFile

---

🎯 Purpose

SaveToFile node allows you to automatically save data from your workflow to files on the DCS. This powerful node can collect data over time and save it all to one file, or create separate files for each piece of data that flows through your workflow. It's perfect for creating reports, backing up data, or generating files for other systems to use.

📥 Inputs

• Item(s) from upstream nodes (object or array).
• Optionally, a specific property selected via Property Name.

📤 Outputs

• Pass-through of the original input (configurable via Option).
• Side effect: file(s) created on DCS.

⚙️ Parameters

Name	Type	Required	Default	Description
File Write Mode	Dropdown	Yes	Accumulate	Accumulate all inputs into one file, or Write each item to a separate file.
Property Name	String (expression)	No	(empty)	Property path to save (e.g., reportContent, items). Empty saves the entire item.
Directory Path	String (expression)	No	(empty)	Target folder (can be dynamic, e.g., Exports/{{date}}). Created if missing (if supported).
File Name	String (expression)	No	(system-generated)	File name (e.g., orders_{{date}}.csv, {{customerId}}.json).
Output Format	Dropdown	Yes	Text	Output format: Text, JSON, CSV.
CSV Delimiter	String	Conditional	,	CSV column separator (only when format = CSV).
Option	Dropdown	Yes	Pass Input Data	Controls downstream output (currently Pass Input Data).

Notes
• Accumulate appends sequential runs to the same file.
• Write each creates one file per item (fileName should be unique per item).

💡 Example Usage

• 📦 Daily Orders CSV (Accumulate)

  • File Write Mode=Accumulate, writeFormatId=CSV, fileName="orders_{{date}}.csv", directoryPath="Reports/Daily", Property Name="orders"
  • Appends all orders of the day into a single CSV.

• 👤 Per-Customer JSON Export (One File Per Item)

  • File Write Mode=Write each, writeFormatId=JSON, fileName="{{customer.id}}.json", directoryPath="Exports/Customers/{{segment}}", Property Name=""
  • Writes one JSON file per customer with full record.

• 🧾 Text Receipts For Email Rendering

  • File Write Mode=Write each, writeFormatId=Text, fileName="receipt_{{order.id}}.txt", directoryPath="Receipts/{{yyyy}}/{{MM}}", Property Name="receiptText"
  • Saves preformatted text receipts for downstream email/PDF steps.

• 📊 Locale-Specific CSV

  • writeFormatId=CSV, csvDelimiter=";", fileName="inventory_{{warehouse}}_{{date}}.csv"
  • Produces semicolon-delimited CSV for EU spreadsheet compatibility.

📘 Best Practices

• Deterministic naming: Include timestamps/IDs to avoid overwrites in Write each mode.
• Directory hygiene: Partition by date or entity (e.g., Exports/{{yyyy}}/{{MM}}/{{dd}}).
• CSV at scale: Keep header order stable; prefer ISO date formats; set csvDelimiter to match consumers.
• Accumulate with care: Monitor file size; rotate daily/weekly via filename patterns.
• Security: Save only needed fields via Property Name; write to secured, backed-up paths.
• Observability: Log the final resolved path/filename (if available in run logs) for easy traceability.

🧪 Test Cases

• Single Item → JSON

  • Input: {id:1, name:"A"}; writeFormatId=JSON, fileName="test.json"
  • Expected: test.json with exact JSON structure; node output passes original item.

• Multiple Items → CSV (Accumulate)

  • Input: 3 items with same shape; File Write Mode=Accumulate, fileName="all.csv"
  • Expected: One CSV with header + 3 rows; subsequent run appends more rows.

• Per-Item Text Files (Write Each)

  • Input: 2 items; File Write Mode=Write each, fileName="{{id}}.txt", Property Name="note"
  • Expected: 1.txt and 2.txt each containing the corresponding note.

• EU CSV Delimiter

  • writeFormatId=CSV, csvDelimiter=";"
  • Expected: Semicolon-separated columns; no commas as separators.

🔧 Troubleshooting

• Overwritten files: In Accumulate, expected; in Write each, ensure fileName is unique (include {{timestamp}} or an ID).
• Malformed CSV: Ensure all items share the same fields/order; set the correct delimiter for the consumer.
• Wrong data saved: Confirm Property Name path; leave empty to persist the entire item.
• Large files: Rotate filenames by date, or switch to Write each and archive periodically.