Write file

Writes an incoming ViaFileStream, or a stream of TextRecords, to a file in a local folder of the environment data folder. Typically the last step after Read file, Stream compress/decompress, an encoder or any component producing a file stream.

Pins

Pin	Kind	Types	Description
Input	input	Viaducta.Plugins.Files.Types.ViaFileStream, Viaducta.Plugins.TextPlugin.Types.TextRecord	The stream to write (Name is the file name), or text records: the records of one batch go into one file, a record without a batch into a file of its own.

The plugin has no output pin.

Configuration

Field	Type	Default	Description
LocalFileGroup	folder (FolderExplorer)		Required. Target folder relative to the environment data folder, e.g. /outbound/reports. Created if missing; must stay inside the data folder.
ExistingFileOption	dropdown: 1 OnlyNew, 2 Overwrite, 3 Append	1	What to do if the target file exists. Validated at start.
NameOption	dropdown: 1 StreamName, 2 NamePattern	1	How the file name is built.
NamePattern	string	OUT%BN%-%TS%.dat	Name template for NameOption 2: %SN% stream name, %BN% stream name without extension, %TS% yyyyMMdd-HHmmss, %DATE% yyyyMMdd, %TIME% HHmmss (UTC, one clock read per file), %SEQ% / %SEQ5% / %SEQ10% component sequence number (plain, 5 or 10 digits). Required with NameOption 2.
RecordSeparator	dropdown: 1 LF, 2 CRLF, 3 None	1	TextRecord input only: written after each record value.
BatchScope	batch scope selector	empty	TextRecord input only: which batch goes into one file. Empty = the closest batch producer upstream (e.g. one file per file read by Read file, per Sql query execution). A component id of a batch producer upstream = one file per batch of that producer. None = ignore batches, every record into a file of its own.

Behaviour

• The file path is <data folder>/<LocalFileGroup>/<name>. Subfolders in the name (e.g. entries from Stream decompress) are created; names that resolve outside LocalFileGroup are refused.
• A ViaFileStream without Name (with NameOption 1) is written as <yyyyMMdd-HHmmss>-<component sequence, 10 digits><Extension> (.dat when Extension is empty).
• The input stream is rewound to the beginning (if seekable) and copied in 64 KB blocks. The input stream is not closed.
• 1 OnlyNew and 2 Overwrite write to <name>.<guid>.tmp and rename it to the final name at the end, so readers never see a half-written file and a .tmp left by a crash never blocks a later write. 1 OnlyNew fails if the target exists, also when it appeared during the write. 3 Append appends directly to the target (created if missing).
• Text records in a batch (see BatchScope): all records of the batch go into one file, opened on the first record. The file is committed when the whole batch has been processed and deleted when the batch failed. Records may arrive in parallel (Fork). If the selected producer is not upstream of a record, the record fails. Name: TextRecord.Name, else the metadata file name, else the batch label (e.g. the source file name).
• Text records without a batch (or BatchScope None): every record is written to a file of its own and committed right away (with ExistingFileOption 3 Append: appended to the target). Name: TextRecord.Name, else the metadata file name, else <yyyyMMdd-HHmmss>-<sequence>.txt. Put a batch producer upstream to collect records into one file. Text is UTF-8 without BOM.
• If writing a batch file fails, the error is raised, the partial file is deleted and the remaining records of that batch are dropped; at the batch end one error with the dropped count is logged. A failed single record file is deleted and the error raised.
• Errors (file locked, target exists for OnlyNew, invalid configuration) are raised to the flow.

Notes

• Append mode writes in place: after a failure the data written so far stays in the target file.
• On flow stop, files of open batches are deleted (the batch is aborted).
• Folder watchers on the target folder should ignore *.tmp.

Example

{ "LocalFileGroup": "/outbound/archive", "ExistingFileOption": 2, "NameOption": 1 }

Read file → Stream compress → Write file