Building an Automation
You build an Automation in the Builder, which shows the workflow as a graph with the trigger at the top and each node below the node it receives items from. You choose the trigger first, add and configure nodes, and save. Files.com validates the whole graph when you save. The same workflow can be built by editing its JSON definition instead, in the Builder or through the Files.com API, because the graph and the definition are the same thing.
The Builder computes the layout from the connections, so there are no positions to arrange and the same graph always displays the same way. Run detail displays the same layout.
The trigger is the first choice you make, and the item kind it produces determines which nodes can follow it. A Scheduled trigger with no folder path produces a data item, so nodes that accept only files are marked as not available until a folder path is set.
Adding and Connecting Nodes
You add a node at an insertion point on a connection or below the last node in a path. The Builder offers the actions and controls that accept the item kind the previous node produces and marks the rest as not available for that connection.
An If node has a True path and a False path, and a Switch node has a path for each rule plus a Default path. Each path has its own insertion point, so a branch is built the same way as a chain. Every node after the trigger also has an Error path, where you connect the nodes that process the items the node could not process, according to its Error Handling rules.
Connecting one output to two nodes creates two parallel branches that receive the same items.
Configuring a Node
Each node shows which item kinds it accepts and produces, its settings, and two sections every node after the trigger shares. Error Handling contains the rules for items the node could not process. Return From Automation marks the node's output as what this Automation returns when another Automation runs it with Run Automation. Each node names the fields that accept a TransformScript template or expression, and TransformScript in Automations lists those fields for every node and what an expression can read.
Each node has a Node ID that identifies it in Run Logs, in run detail, and in the JSON definition. The ID defaults to a short name for the node type, for example copy_file.
A node whose required settings are missing is flagged on the graph.
Saving and Validation
Saving validates the whole graph. Files.com checks that there is exactly one trigger, that every required setting is present, that the item kinds match on every connection, and that every TransformScript expression is valid. It also checks that every referenced Sync, AS2 Station, AS2 Partner, GPG key, On-Premise Agent, and Automation belongs to the same site or Workspace as this Automation, because the Automation runs with its owner's permissions and can use only that owner's resources. A graph that fails validation is not saved, and the message gives the position of the failing field in the JSON definition and ends with a code, for example definition is invalid at /nodes/1/config/condition (invalid_fts).
While you build, Undo and Redo step through your changes. Nothing is stored until you select Save, and Cancel discards the unsaved changes.
Allow Automation to Run sets whether the Automation can run once it is created. Leave it off to finish building first, then enable the Automation when it is ready.
The Automation's Description and its Retry Handling are set in Automation Settings, shown when no node is selected.
The table below lists every check that returns a code, including the graph's shape, the nesting and node limits, and the requirements of individual nodes.
| Code | Meaning |
|---|---|
cyclic_graph | A connection leads back to a node earlier in the graph. |
invalid_outlet, invalid_inlet | A connection uses an output or an input the node does not have. |
invalid_fts | A TransformScript expression, template, or script does not parse. |
incompatible_item_kind | A connection delivers data to a node that accepts only files, or files to Aggregate. |
invalid_join_inputs | A Join input has no connection or more than one. |
invalid_sync_reference, invalid_agent_reference, invalid_gpg_key_reference, invalid_as2_station_reference, invalid_as2_partner_reference | A referenced Sync, Agent, GPG key, AS2 Station, or AS2 Partner does not exist or does not belong to the Automation's site or Workspace. |
invalid_flow_reference | The Automation selected in a Run Automation node does not exist or does not belong to the same site or Workspace. |
recursive_flow_reference | A Run Automation node selects an Automation that, directly or through other Automations, runs this one. |
flow_nesting_too_deep | Automations are nested more than five deep through Run Automation. |
expanded_node_limit | The graph has more than 100 nodes once every selected Automation's nodes are counted. |
transform_output_required | A Transform node has a destination and its script has no output directive. |
invalid_transform_output_shape | A Transform script is known to return a single value rather than an object or a list. |
custom_smtp_required | The graph contains a Send Email node and the site has no Custom SMTP. |
extract_output_required | An Extract node has both Include Metadata and Include Content turned off. |
invalid_config_value | A setting has a value the node does not accept. |
Editing an Existing Automation
An Automation's Builder opens read-only. Editing shows the same settings as creation, and each save of a changed graph creates a new Revision. A run uses the Revision it started with, which is why an edit never changes a run in progress. Changing the name, description, or enabled state does not create a Revision. The current Revision number is shown with the Automation, and each run records the Revision it used.
The JSON Definition
Every Automation is a JSON definition of its trigger, its nodes and their settings, and the connections between them. The definition contains the workflow's structure and nothing about its appearance, so a definition written outside Files.com opens in the Builder unchanged, and a definition copied out of the Builder is the whole workflow.
In the Builder, Builder JSON shows the definition when no node is selected, along with the number of nodes and connections in the graph, which is how to tell how close the graph is to the limit of 50 nodes. Copy JSON copies the definition. You can edit it there and apply it to update the graph, and the change is stored when you save the Automation, the same as a change made node by node.
Use the definition to review a change as text before saving it, to keep a copy before an edit so you can return to an earlier graph, and to build a workflow outside the Builder.
The API reads and writes the same definition, so Automations can be created, updated, and run from your own code, and each saved change to the definition creates a Revision, which the API reports as the Automation's version. Files.com publishes the JSON Schema of the definition, which names every node type, its settings, and their allowed values, and the Files.com API and SDKs documentation covers the calls.