TransformScript in Automations

In an Automation, TransformScript is the language for node settings that use values from the item the node is processing. A destination path such as exports/{{ payload.customer }}/ is built from each item, an If condition such as payload.status == "approved" is evaluated against each item, and a Transform node runs a whole script over each item. The same language and the same inputs apply in all three places.

Templates, Conditions, and Scripts

A template is ordinary text with expressions in double braces, evaluated once for each item. Destination paths, the fields of Send Email, the values in Set Metadata and the arguments of Agent Compute, and the URL, request content, and header values of Import File are templates. In a list, each entry is a template. In a list of keys and values, only the values are templates, because the keys name the fields and must be known when the Automation is saved.

A condition is a bare expression with no braces. The If and Filter conditions and each Switch rule are expressions that evaluate to true or false, and the Left Key and Right Key of Join are expressions that produce the value to match on.

A script is a complete TransformScript with a header, a --- separator, and a body, in the shape described in Writing a TransformScript, and only the Transform node takes one.

Settings that Files.com validates at save, before any item exists, are static and do not accept expressions: the trigger's folder path and patterns, the Agent Compute command, the Import File method, the keys in header and metadata lists, and every checkbox, choice, and referenced resource. A double brace in one of these fields fails at save rather than being used as literal text.

What an Expression Can Read

payload is the item's contents. For a data item it is the object itself. For a file item it is the file's contents parsed by format, the same way a TransformScript reads a file, using the formats and detection rules in Input and Output Formats. A JSON file is an object, a CSV file is a list of rows, and an X12 or HL7 file is a structure of segments.

attributes is the information Files.com records about the item. For a file item, that is its name as attributes.name, its path as attributes.path, its size, modified time, content type, the Remote Server it is on, and its Custom Metadata, read as attributes.custom_metadata.<field>. For a file received through an Incoming Email trigger, the sender, subject, and received time are recorded as well. After an Extract node, attributes.extract contains the text and metadata Extract read from the file.

Custom Metadata lets an Automation route a file without reading its contents. Files.com stores the AS2 headers of a file received over AS2 as Custom Metadata, so the condition attributes.custom_metadata.as2_from == "Acme-AS2" selects the files from one partner, and attributes.custom_metadata.as2_subject == "Invoice" selects the invoices.

Data Shape

A data item is a JSON object, and every expression or script that produces data must produce one. An object is one item, a list of objects is one item per element, an empty list is no items, and a single value, null, or a list containing anything other than objects is an error. A Transform over a parsed CSV returns a list of rows and produces one data item per row, so the nodes after it route row by row with no splitting node. To keep a list together as one item, wrap it in an object, for example { rows: payload }.

Writing a File From a Transform Node

A Transform node with a Destination Path writes its result as a file instead of producing data. The script's output directive sets the format and the destination sets the path, so a script with output csv and a destination of exports/orders.csv writes a CSV file. A destination requires the script to declare an output directive, because the directive is what names the file format. Nothing is split, and the whole result is written to one file.

Errors

An expression that does not parse fails at save, and the message gives the position of the failing field in the JSON definition, for example definition is invalid at /nodes/1/config/condition (invalid_fts). A script whose result is known at save to be a single value rather than an object or a list also fails at save. A script that fails while running fails that item with the error processing-failure/transform-error, which the node's Error Handling rules route like any other error.