Skip to content

Exports and Delivery

themarioga edited this page Nov 8, 2026 · 1 revision

Exports and Delivery

Exporting records

ExportResult result = tie.exportRecords(definition, records, ExportContext.builder()
        .variable("tenant", "ACME")
        .build());
  • records is an Iterator<Map<String, Object>>: typed values per field name, read one at a time.
  • An export has exactly one root layout that allows exactly one format, an outputChannel and an outputNamePattern (without extension).
  • Each record runs through the export field engine. Valid records are written in streaming to a file in the working directory; rejected ones are listed in the result and never written.
  • At the end the file is delivered with the delivery rules, and the working file is deleted.
ExportContext Meaning
variables Values for the {variable} markers of outputNamePattern
listener onLineRejected and onWarning
cancellation Checked before each record
providedOutput Supplier<OutputStream> for a ProvidedStreamChannel output
workingDirectory Where the file is written before delivery

When nothing is delivered

  • Rejections exceed maxRejected: FAILED with THRESHOLD.
  • The export is cancelled: CANCELLED.
  • Writing or delivering fails: FAILED with the error.

In every case the destination is untouched.

Nested records

A child layout's records are a List<Map<String, Object>> under its nestedKey (JSON and XML only):

Map.of("id", 1L, "lines", List.of(Map.of("sku", "A"), Map.of("sku", "B")))

A rejected child is not written, while its parent is. The children of a rejected parent are not processed. Records are numbered like imports: children right after their parent.

outputAs: native values or text

In JSON and XLSX a typed value can keep its type:

outputAs JSON XLSX
NATIVE 42, 1.50, true, "2026-12-31" Numeric, boolean or date cell
TEXT "42" Text cell

Without outputAs, a field is NATIVE unless it has a typeFormat, text transforms, translations or a transformer, which all produce text. NATIVE together with any of them is a configuration error. CSV and XML are always text.

Result

ExportResult
status SUCCESS, FAILED or CANCELLED
written Records written, children included
rejected Every LineRejection
fileName The delivered name, with its collision suffix if any
destination Where it went (a directory, sftp://user@host:port/dir, or the provided stream)
error, warnings

Delivering an existing file

DeliveryResult result = tie.deliverFile(channel, Path.of("/tmp/result.csv"), "result_1.csv",
        DeliveryContext.EMPTY);

The file is uploaded as is, with the same delivery rules as an export. The local file is never modified, moved or deleted. A configuration error throws ConfigurationException:

  • the channel is a ProvidedStreamChannel, or invalid;
  • remoteName contains /, \ or ..;
  • the local file does not exist or cannot be read.

Every delivery failure (connection, host key, NAME_COLLISION…) is returned as a FAILED result, never thrown.

Clone this wiki locally