TransformScript in Automations v2

In Automations v2, 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. The incoming file patterns of Manual, Scheduled, and path-selecting Webhook triggers also accept templates, evaluated before files are selected.

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.

Each expression must produce a scalar value, which is converted to text and inserted into the setting. Objects and arrays are not valid template results.

TransformScript is the only expression language: percent placeholders in v2 settings are literal text. Inserted text is not evaluated again as a template or a placeholder, even when it contains braces or percent characters. This also applies to calculated URLs, headers, and request content used by Import File.

When request content needs JSON text, use toJson to encode the value rather than inserting it between hand-written JSON quotes. For example, {{ toJson({ order: payload.order_id }) }} produces JSON text with any necessary quoting and escaping.

In a path field, {{ expression }} supplies one folder or file name. A value containing / or \, or equal to ., .., or empty, fails the item through the node's Error Handling rules.

The check applies to each value inside a larger path too: reports/{{ payload.folder }}/file.csv fails when the value is . or ... Use {{{ expression }}} when the value intentionally supplies a path fragment, such as {{{ attributes.path }}} for a Send Email attachment. Destinations and Templates explains how the completed path resolves.

The single-name check applies to fields the node treats as paths. Other fields, including email subjects and recipients, Import File URLs, headers and request content, Set Metadata values, and Agent Compute arguments, insert template values as text without this path check. An Agent argument containing a path is still an argument to the approved program, rather than a Files.com path field.

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.

Static settings do not accept expressions: the trigger's folder path and exclude pattern, File Action, Folder Creation, and Incoming Email name patterns, the Agent Compute command, the Import File method, the keys in header and metadata lists, and every checkbox, choice, and referenced resource. Use a calculated incoming file pattern on a Manual, Scheduled, or path-selecting Webhook trigger when selection depends on a date or request parameter. Before selection there is no current file, so that template uses the run context rather than file attributes or file contents.

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 describes the current item. For a file item, that includes its name as attributes.name, its path as attributes.path, its size, modified time, content type, whether it is a folder as attributes.is_directory, the Remote Server it is on, and its Custom Metadata, read as attributes.custom_metadata.<field>.

A folder item has directory information but no file contents to parse as payload. For a file received through an Incoming Email trigger, the sender's email address is attributes.sender, the subject is attributes.subject, and the message's date and time is attributes.received_at, an ISO 8601 value from the email's Date header.

After an Extract node, attributes.extract contains the text and metadata Extract read from the file. The run's variables are available as vars.

Copy, Move, Import, and a Transform that writes a file make their result the current file. Later expressions read that file's path, name, and contents.

There is no automatic snapshot or separate expression binding for the original triggering file. A Transform that produces data replaces the previous item's attributes with information about its new output.

Include any earlier values needed downstream in the data you return, or keep the original item on a separate branch. How an Automation Runs illustrates the change in file identity.

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.

Run Time and Parameters

context.parameters holds the webhook's query and form parameters as strings, separately from its JSON body. context.parameters.batch reads the batch request parameter; payload.batch reads the current item's contents, which are the JSON body only while that body is still the current item. Parameters remain available after nodes replace the item.

context.time is the run's execution time and context.time_zone is its time zone: the trigger's Path Time Zone when set, otherwise the schedule's time zone, otherwise UTC. Use these values for a dated selection or destination that belongs to the run, such as a daily archive.

context.evaluated_at and context.evaluated_time_zone describe when an expression is evaluated. Use that clock when the date should reflect the processing step rather than the run's execution time. An expression evaluated after midnight can therefore give a different date depending on the clock and zone you choose.

Date formats inside FTS and the %files script header retain their percent syntax. Destinations and Templates gives a dated path example; the general Dates & Times and Types and Coercion references explain date calculations and formatting.

Letting Data Choose a Setting

The administrator decides which incoming values may control the workflow. File contents, names, metadata, webhook fields, and email subjects can contain values chosen by another person or system. A trigger's access controls establish who may submit work; they do not validate every submitted value for every later use.

For example, reports/{{ payload.customer }}/ accepts a customer value as one name, but it does not establish that the submitting source is allowed to select that customer's folder. A fragment such as reports/{{{ payload.subfolder }}}/ permits a value to change the folder structure as well. With ../archive as the fragment, the completed path resolves outside reports to archive/.

When data needs to select a route, use an If, Filter, or Switch condition before the action to accept only the intended cases. A Switch can match a recognized customer identifier and send each accepted branch to a Copy File node with a fixed destination. Handle unknown or missing identifiers separately, and check that the submitting source is allowed to select that customer; recognizing the identifier alone does not establish that relationship.

Apply the same reasoning to Send Email recipients, Import File URLs and headers, and Agent Compute arguments. A valid expression is a calculation, not permission to use its result for any purpose. The Automations v2 Security Reference explains input checks, destinations, and the permissions that apply to the resulting work.

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.