Skip to main content

Transform

A Transform node runs a TransformScript against each item it receives and passes on the result as data, or as a file when you set a destination. Use it to convert a partner's CSV into the layout your bank requires, to split a file of orders into one item per row so that the nodes after it route each row, to build a report from the data items an earlier node produced, or to turn the text an Extract node read from a document into structured fields.

Transform accepts file items and data items. For a file, the script reads the file's contents parsed by format, and for a data item it reads the object itself, as described in TransformScript in Automations.

Settings

Transform Script is a complete script, and it runs once for each item, with the item's contents as payload and the information Files.com records about it as attributes.

Destination Path is optional. When it is set, the node writes the script's result to that path as a file, in the format named by the script's output directive, and the path is a template evaluated for each item. When it is empty, the node passes the result on as data.

What the Next Node Receives

With no destination, the next node receives the script's result under the data shape rule. An object is one data item, a list of objects is one data item per element, and an empty list is no items. A script that returns the parsed rows of a CSV file produces one data item per row, and a script that returns { rows: payload } produces one item holding every row.

With a destination, the next node receives one file item for each item the node received, the file the node wrote for that item. Nothing is split. A Copy File, Send via AS2, or Encrypt With GPG node after it processes that file like any other.

The script below reads an orders file, selects the approved rows, and returns them as CSV:

%files 1.0
output csv
---
payload filter (r) -> r.status == "approved"

With Destination Path set to /bank/approved/{{ attributes.name }}, one CSV file is written for each incoming file. With no destination, the same script passes on one data item per approved row.

Errors

A script that fails while running fails that item with the error processing-failure/transform-error, and the Error Handling rules on the node determine what happens to a failed item.

At save, Files.com rejects a script that does not parse. It rejects a script whose result is known to be a single value rather than an object or a list, because every data item is a JSON object. It also rejects a destination set on a node whose script has no output directive, because the directive names the file format. Each message gives the position of the failing field in the JSON definition and ends with one of the save-time codes.

Convert Document and Extract also work with a file's contents.

Transform vs. Convert Document

Convert Document converts a document, spreadsheet, or presentation file to another format of the same kind, for example DOCX to PDF or CSV to XLSX, and does not change the content. Transform parses structured data and produces new data, and the output formats it can write are the structured ones: JSON, NDJSON, CSV, XLSX, XML, YAML, URL-encoded form, HL7, EDIFACT, and X12. Use Convert Document when only the file format changes, and for PDF or DOCX output. Use Transform when rows, fields, or values change, or when the input is an interchange format like X12 or HL7.

Transform vs. Extract

Extract reads the text and document metadata out of a document file, adds them to the item's attributes, and passes the file on unchanged. Transform parses structured data formats and produces new data or a new file. Use Extract to route a document by the text or metadata inside it. Use Transform to reshape structured data. To structure the text of a document, connect Extract to a Transform node whose script reads attributes.extract.content_text.