How an Automation Runs (v2)

Every run of an Automation v2 starts at its trigger and passes files or data through the nodes you connected, in the order of their connections. Knowing what each node receives, what it passes on, and what happens when a path has no items lets you predict a run before you start it and read its run detail after it finishes.

The Trigger Produces the First Items

Each run begins with the items its trigger produces. A File Action trigger supplies existing regular files in file mode, or action data in event mode. Files uploaded together are processed in one run with many items.

A Scheduled or Manual trigger with a folder path produces the matching files, or the matched folders themselves when the incoming pattern is .. A Manual run started through the API can instead produce the files or data supplied in the call.

A Webhook trigger produces one data item per JSON object, or selects files or folders when a folder path is configured. An Incoming Email trigger produces one file item for each attachment, and one for the message body when Save Body is on.

A Scheduled or Manual trigger with no folder path produces one empty data item, so the nodes after the trigger always run. A Transform node that follows it runs once on that item and can generate a report with no incoming file.

When a trigger's selection produces no items, the run ends with the status Skipped and no later node runs. In File Action file mode, this includes actions on folders or files that no longer exist.

Files and Data

An item is either a file or data. A file item can refer to a file stored in a folder or to temporary content within the run, such as an Incoming Email attachment.

Stored files use the same path the Web App and the API use. A file on a Remote Server Mount is referred to by its Files.com path, which includes the mount folder.

Files.com reads a file's contents only when a node processes them. A data item is one JSON object.

Every node accepts file items, data items, or both, and the Builder shows what each node accepts and produces. Move File, Delete File, Set Metadata, Extract, Convert Document, Convert Image, Unzip, and Decrypt With GPG accept only files, because a JSON object cannot be moved, deleted, converted, unzipped, or decrypted as a file, and a connection that would deliver data to one of them fails at save.

Copy File, Zip, Encrypt With GPG, Send via AS2, and Agent Compute accept data by writing the JSON to a temporary .json file and processing that file. Create Folder, Import File, Run Sync, Send Email, Wait, and Run Automation accept either kind, because their operation does not depend on whether the item is a file or data.

If, Switch, Filter, Join, and Transform accept either kind and read the item's contents through the expressions you write. Aggregate accepts only data, because it combines the JSON objects it receives into one object.

A file item's contents are available to an expression as payload, parsed by format, and the information Files.com records about the item is available as attributes. A selected folder is also a file-kind item, with attributes.is_directory set to true; it has no file contents for an expression to parse. A Filter can select one item kind before evaluating its condition, so mixed input can feed a node that accepts only files or only data.

Every Node Processes Every Item

A node runs once for the whole collection of items it receives and processes each one. A Copy File node that receives 40 files performs 40 copies. There is no loop to configure, and items keep their order from node to node.

Most nodes pass on one item for each item they receive. These nodes change the count:

• Zip combines every file it receives into one archive.
• Aggregate combines every data item it receives into one data item.
• Unzip outputs one item for each file it extracts from an archive.
• Transform outputs one data item for each element when the script returns a list.
• Filter passes on only the items of its selected kind, when set, that match its condition, unchanged.
• Join outputs data items that pair items from its two inputs by key.
• Copy File and Move File with several destinations produce one item per destination for each file, and Create Folder produces one item for each folder it creates.
• Import File makes a separate request and upload for each destination for each incoming item, and passes on each successfully saved file. One data item with three targets can therefore become three file items. To distribute one downloaded response, use one Import destination followed by Copy File.

Send via AS2, Run Sync, Send Email, If, Switch, and Wait pass their items on unchanged and record the outcome for each item. Set Metadata passes on the same file with its custom metadata replaced, and Extract passes on the same file with the text and metadata it read added to the item's attributes. A node that creates files passes on the files it created, not the originals, so a Copy File node passes on the copies.

To use the original file after a copy, connect the node before the Copy File node to the next node as well. Delete File passes on a data item that records the deleted file's path, size, and deletion time, because the file no longer exists.

The Current Item

Expressions describe the file or data entering the current node. When a node copies, moves, imports, or writes a transformed file, later expressions use its resulting file's name, path, and contents. For example, a workflow prepares a copy of an upload and then moves that copy to a delivery folder:

At Move File, attributes.name is prepared.csv. The file has left the trigger's source selection, so the relative destination uses /staging/. The original /incoming/report.csv remains in place. Destination rules explain when Copy and Move retain the selected source tree and when the current folder becomes the base.

A Transform that returns data makes that output the new item, with attributes describing its new source in the workflow. It does not carry forward the input file's attributes automatically.

Return any values the next node needs within the new data. V2 provides no automatic snapshot of the original triggering file; preserve that file on a separate branch when the workflow also needs to act on it.

Branches

Connecting one node's output to two nodes sends the same items to both, and the two branches run in parallel. One branch can archive a file while the other delivers it.

If and Switch route items instead of sending the same items to every path. An If node routes each item to its True path or its False path. A Switch node routes each item to the path of the first rule that matches it, or to the Default path when no rule matches.

A node with several incoming connections waits until the node at the other end of every connection has finished, then processes all of their items together. Join is the one node that does not merge its inputs. It has two named inputs, Left and Right, and matches items across them.

An If, Switch, or Filter node can send zero items down a path. A node whose inputs are all empty does not run and is marked Skipped in run detail, because it processed no items.

When two branches receive the same file stored in a folder and one branch moves or deletes it, the other branch's reference to the file no longer resolves, and that item fails with a not-found error when its node reads the file, which the node's Error Handling rules can route to its Error path. Place a Move File or Delete File node after the branches that read the original, or copy the file before the branch that removes it.