Workflow orchestration

On the Flow canvas, you design visual pipelines that move data from source to outcome. The workflow engine runs them on the server: when a run executes, nodes whose inputs or configuration changed re-run, while independent branches execute in parallel. You reuse work through templates and subgraphs, and every run can leave audit and lineage metadata for compliance review. See Compliance evidence for data lineage and Data for connectors, storage, and file formats.

What is a workflow?

A directed graph of nodes connected by edges. Each node performs one step and passes typed dataset ports downstream. Runs are server-side when files, connectors, or document parsing require the workflow engine.

Visual pipeline model

A workflow is a directed graph of nodes connected by edges. Each node performs one step and passes typed dataset ports downstream.

File / REST / Connector→Input Schema(s)→Operations (Validations and Transformations)→Output Schema(s)→Save file / API

Execution engine

You start a run from the canvas Run control. You can also enable Auto run changes in the workflow ⋯ menu so Flow schedules a run when the canvas is stale. Your browser tab for an open workspace is {workspace name} | Workspaces | Fontana AI (the Graph or Simple view query is not in the tab). You open a Workspace workflow from Workspaces or from a link that names the workspace and the .wf.json file. A Fontana Files administrator (files:admin) can open any workspace file. If you can read a workspace, you see the same run data as everyone else with access. If you can edit it, you can Run any workflow in it. If you cannot read that file, Flow stays on Workspaces and tells you so. When a run executes, the engine:

• Reacts to change - each node hashes its configuration, incoming edges, and input data. Nodes whose hash matches the last successful run reuse prior output; others re-run. Frozen nodes keep their last output until you unfreeze them. If a node hash cannot be calculated, the run fails with an error for that node instead of treating the node as up to date.
• Runs in parallel - independent branches execute concurrently where the graph allows
• Executes server-side - large files, PDF parsing, connector fetch, and PyAirbyte jobs run on the workflow engine
• Persists run-scoped data - uploads, Arrow datasets, exports, and audit sidecars survive pod restarts within your workspace boundary. After the workflow engine restarts, Explore can restore published node outputs that still have rows.

Auto run and freshness

From the workflow ⋯ menu, Auto run changes schedules a run when the workflow is stale relative to the last comparable completed run, instead of leaving the Stale badge. Stale covers graph and file-input changes, and cell or header edits that change results. Expanding or collapsing operation badges does not mark the workflow stale.

When the last completed run has no comparable fingerprint (for example a run stored before the current fingerprint format), the Run control shows Unknown freshness. Unknown does not Auto-run. You run once to establish a baseline; later Stale and Auto-run compare against that run.

Opening a workflow or refreshing the page does not schedule a run for load-only fingerprint churn. A genuine edit during that short settle window still shows Stale, or schedules a run when Auto-run is on.

Validations

Apply schema, business-rule, and tolerance checks as deterministic steps; failures route to owners with full context attached.

Transformations

Reshape, normalise, and map payloads between source formats and target schemas with versioned transformation logic.

Compute

Run grouping, filtering, aggregations, enrichment, and other compute steps on governed datasets inside the workflow boundary.

Node editor

When you open a node for editing, Settings Display lets you set Title, Description, Theme, then Icon. Icon opens Library, Generate, or Paste SVG. Until you pick an override, the node keeps its type glyph. Skills use the same picker and keep accent colour. Lineage indicator decides how this node marks the cells it contributed to in the Explore views of nodes downstream of it: Colour dot or Icon add a marker at the right of the cell, Background washes the cell in a pale tint of the node’s theme, Bottom border and Left border draw an edge in the theme colour (the wash yields to conditional colour and to row selection; the edges stay). A sample cell beside the dropdown shows the selected mode in the node’s theme and icon. It changes nothing about the run. Editors for nodes that output a dataset have an Explore tab right after the primary tab (first when the node has no primary tab); File Input and REST API enable it once a file is loaded or output rows exist. Explore lists that output as named views: table, board, list, JSON, Details, and a chart when the rows can be queried. Filters and sorts run on the server over the published rows. The view layout, filters, and header are saved on the node. In a Workspace workflow, Explore reads the rows the last run published to the workspace through Fontana Files (before a run, a File Input’s own workspace file), and a picker in its toolbar switches between the outputs that run published for the node, one entry per sheet for a workbook. Opening that published file, or a Save File export, from the workspace shows this same Explore view in Preview. The open grid follows changes that reach the workspace while you look at it: a run started by an agent or a schedule brings its rows in, and a view layout an agent saves appears without reopening the file. Next to the picker, a toggle switches between the rows, the schema the run published for that output as a tree, and the same schema as JSON. A cell shows one marker per upstream node with a lineage indicator that produced it; hover the markers to see where the value came from, hop by hop, with the value at each step. A green dot marks a value this node changed from what it read upstream (hover for the old and new value); a yellow dot marks a cell someone edited. Click a cell to select it and use the arrow keys to move; Enter or a double-click edits a node’s own output rows, and the edit is saved to the workspace and applied to that row on the next run. See Data lineage. The Settings tab ends with a Raw Config section that shows the full workflow-config object for that node. Valid edits apply when the editor loses focus; invalid JSON or changes to id / type keep your draft and show an error. Marker stroke nodes stay canvas-only and do not include this tab. Escape closes dismissible layers one at a time, most recently opened first. Escape closes the editor when its fields are empty after trim. If a field in the editor still has text, Escape does not close the editor and does not clear your draft, even after a menu on top has already closed. Open menus, dialogs, and Monaco suggest or find keep Escape until they close.

Canvas preferences

Open the bottom omni toolbar Preferences control to adjust canvas display. Among fit view, lock, layout direction (LR / TB), and full vs data-only mode, you can switch node corner radius with an icon-only split control (rounded or square). The choice is stored on the workflow display config and applies to standard workflow node cards. The omni dock is canvas tools and Preferences only. You add nodes and operations from the right-hand tools rail, Quick add on a selected node, and My Components.

Node size on the canvas

Select a graph node and drag the bottom-right corner to change both width and height. Flow saves that size with the workflow, so leave, re-enter, and refresh restore it. The card stays at least as tall as its content, and you cannot shrink below the designed minimum width for that node type. Historical run canvases stay read-only. Panel nodes keep their own edge resizer for width and height.

Workflow tools rail

The right-hand tools rail (Overview, Nodes, Operations, Errors, My Components, and related panels) docks as a column that takes width from the canvas. The graph and other workflow views shrink; the run toolbar recenters in the remaining space. The panel keeps rounded-left card chrome and a left-edge resize handle. Keyboard N toggles Nodes and O toggles Operations when you are not typing in a field. Overview is the inspector: with nothing selected it shows the mini map, workflow info, stats, and node list; a selected node shows that node’s data; a selected edge shows that connection (title Edge, merge strategy, payload counts, and an Enabled switch); a selected data-grid cell shows that cell’s lineage. Canvas Audit log lives on the Errors rail (severity totals under the title). Header Graph / Simple / Analysis menus do not open a main-window Audit view; a leftover ?view=audit URL opens Simple and the Audit log rail. Save a panel to My Components with a name dialog (default My component). Escape closes dismissible layers one at a time, most recently opened first. Escape closes the panel when draft fields are empty after trim, including an empty search box. Committed chrome such as the workflow name does not keep the panel open. A typed draft still blocks Escape and is not cleared, even after a menu on top of it. Open menus, dialogs, and Monaco suggest or find keep Escape until they close. Auto run changes lives in the workflow ⋯ menu; Run on the header is a single button.

Square canvas tiles

Common input and API tiles (File Input, Email Import, REST and GraphQL inputs and APIs, Data Connector, Email Export, Save File, Subgrid, Template, AI, Query) drop as square icon-led faces: large centered type icon and title under it. Extra status copy appears on hover. Source actions such as File Input Change/Clear, Email Import pause, Subgrid Auto Select, REST Fetch, and Data Connector Change/Clear live on the selection toolbar when the node is selected, so the default tile stays quiet.

Node families

The sidebar under Workflows → Nodes documents each node type. Representative families:

Operations and validations

The Operations node exposes column-level transforms (strings, dates, decimals, conditionals, lookups) plus dataset-wide Query, Group, and Sort. You combine visual operation stacks in the UI or use natural-language compile (Governed AI) to generate row-wise operations from plain English. Query, Sort, and Group are not NL-composable; you add them on the Operation node.

The sidebar catalogues Transformations, Validations, and Conditions you attach to Operations nodes. Use them to enforce data quality before data leaves a pipeline branch.

Dashboards

Each workflow can have a dashboard: a masonry board of tiles. In edit mode you drag the right edge to set how wide that board is. Cards you stretch across every column stay the full width of that board when the window or pane resizes. See Workflow dashboards.

Exception management

Configure On error on operations and nodes to raise error or raise exception. Exceptions persist for the workflow and appear on the Exception Management board. See Exception management.

Document processing

PDF and office documents uploaded to File Input are parsed server-side via Docling, a shared document-parse service for all workspaces. Optional AI structuring enriches results for review in the UI.

Subgraphs and templates

• Save workflows as templates and share them within teams or the community catalog
• Encapsulate reusable fragments as subgraphs and graft them onto larger pipelines

Workspaces hub

Open Workspaces in Flow for the hub landing. Bare /workflows shows a welcome (capability icons and Create workspace) and Recent only, vertically centered as one stack when the pane is taller than that content. Open My Workspaces or Team Workspaces from the sidebar group headers (?section=…, permission-gated). Sidebar Recently Opened filters to Recent alone (?section=recent, no welcome). The Workspaces title clears the filter back to welcome + Recent. You can also type a title in the header omnibar search to jump to owned and team workspaces.

Simple view lists workflows, agents, skills, tables, and dashboards under headings you can collapse. Choose the workspace name in the sidebar to open its welcome. When the workspace has a home dashboard you open it there; otherwise you create one. The namespace add menu leads with New Workflow and New Dashboard. Files from the input and output folders sit in a Data heading at the end, as ordinary file rows. A table in the tables folder is a small workflow that reads a starter sheet and writes the table when you run it. Open the table to see it in the database explorer. Open the file menu and choose Canvas to open the workflow canvas beside the explorer.

The Workspaces explorer list starts with Mine on, so you see workspace namespaces you own. Turn Mine off to list every workspace you can read. Community Templates and Learn Fontana are Fontana Files Workspace namespaces. Turn on the Community or Learn chip (both start off) to show those catalogs in full, including when Mine is on. Catalog rows show only those chips. When at least one workspace is starred, a star chip sits last on that row. Turn it on with Mine, Community, or Learn to keep those lists and add starred workspaces. Turn it on alone to list only starred workspaces. Star a workspace from the row menu (Add to favourites). A filled star stays on that row while it is starred. Open a catalog .wf.json read-only, or choose Copy namespace on any readable row, including your own, to get a working copy. The workspace row menu also has Create Restore Point, just above Delete namespace. Create Restore Point names the current workspace. Restore Point appears on that menu only when an earlier named point exists. It compares the current workspace to that point, then Restore returns the workspace to it and discards versions after it. A file that existed at that point no longer shows as deleted. A workflow on the canvas no longer shows a run from after that point. You need editor or admin. See File System. Click a .wf.json to open it on the canvas. The row menu also has View graph, which opens that file’s graph in the content pane, and Open in JSON editor when you want the source file. Choosing the file in the tree opens the canvas again. A new Workspace is ingested into the Knowledge Graph, and it stays off the Knowledge Graph list until you turn on Show Workspaces. A new Workspace starts with a .fontanaconfig.yaml that sets where new workflows, agents, skills, uploads and Save File outputs go; see Namespace configuration.

Hover a file or folder in the Workspaces explorer and choose the star beside the row menu. That item is pinned in the content header, ahead of the file name and Preview, Source, and History. The first pin is blue. Later pins are grey. Click a pin to open that file or folder, and drag pins to change their order. Double-click a pin to set a display name for the tab; the file or folder on disk keeps its real name. Right-click a pin and choose Remove to unstar it, which also drops the display name. Choose the star again to remove a pin the same way. You can also star Dashboards, Exception Management, and each dashboard or exception view under any .wf.json. Those pins are shared with everyone who can open the workspace, and they open that workflow, not whichever canvas is on screen. They stay in the header on workspace home, folders, files, and the open workflow. That header is the favourite tabs only: it does not repeat the workflow name. The page you are viewing stays as the active tab, and the star on that tab pins it. The underlined tab is the view you are on. When you open Exception Management, that pin is underlined, not the starred .wf.json, even if both are pinned. Double-click a starred workflow tab to set a display name for everyone in the workspace. A blank name restores the original label. Right-click those tabs and choose Remove to unstar them.

On the Workspaces landing, Favourite workspaces sits above Recent workspaces when you have at least one starred workspace you can still see. Click a Favourite tile to open that workspace home. A workspace that is both starred and recently opened appears in both sections. Recent shows up to six compact tiles so one row fills at wide width. Catalog panes use the larger tile layout. There is no Full / Compact density toggle. Group titles stay pinned to the top of the hub pane while you scroll that section. Truncated titles show the full name in a delayed tooltip. Owned, team, and recently opened cards expose the same workspace ⋯ menu as on the canvas header (copy, save as, move, enable/disable, delete where permitted). Sidebar group headers and workspace rows share the same width as the Search workspaces field.

Related documentation

• Security - platform security controls and SOC 2 summary
• Compliance evidence - atomic data lineage and workflow file store
• Data - File Input, PyAirbyte connectors, Arrow storage, REST triggers, exports
• Governed AI - AI transforms and natural-language operation compile
• Observability - run telemetry; canvas port audit items vs security audit ledger