Skip to main content

How an Automation Runs

Every run of an Automation 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 produces one file item for each file action that started the run, and files uploaded together are processed in one run with many items. A Scheduled or Manual trigger with a folder path produces one file item for each matching file, and 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 for each JSON object in the request. 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 Scheduled or Manual trigger's folder path and pattern match no files, the run ends with the status Skipped and no node runs.

Files and Data

An item is either a file or data. A file item refers to a file by its path, 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.

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 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.

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.

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 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.