XFlow node reference

This reference enumerates every node in the XFlow palette, the anatomy of a node card, the canvas and toolbar controls, the Add/Edit and Execute dialogs, and the run-inspection surfaces. The concepts — what an XFlow is, the shape of the editor, how runs work — are taught in XFlows & pipelines; come here when you need the exact node, field, or control.

How to read this

An XFlow is a processing pipeline — a directed graph (DAG) of nodes that does work on documents or data. It is not a document Lifecycle/Stateflow (those are the review stages a document moves through). The codebase overloads the word “workflow” for both — keep them strictly apart.
The editor is the workflow-activity canvas. It opens from the unified Agents list in Agent Builder (the + Agent picker offers XFlow), and the same editor also has its own Studio home under Automation ▸ XFlow (automation/xflow).
Under the hood, an XFlow is persisted to bm.workflows + bm.workflow_tasks and runs in the Agent-Orchestrator as a Prefect flow. You never see Prefect; you see nodes, edges, and runs.
Each node has an Operator Type that determines its config form (the node config dialog). Some nodes show a warning badge until their required parameters are filled.
A handful of nodes relate to Mesh / pub-sub. In mesh mode the palette is restricted to exactly XFlow Operator + Queue + Service. Subscribe to Topic and Publish to Topic are XFlow-mode pub-sub operators that are not mesh-designer tiles; they are listed here for completeness.

The full node palette

The palette (top-right of the canvas, draggable; expand/collapse via the expand icon) groups into three kinds: stage nodes (big phase-shaped blocks), activity nodes, and functional / operator nodes.

Surfaced vs present-but-filtered. This reference enumerates the whole node catalogue the engine supports — but the live editor filters the palette. Today only the functional / operator nodes plus a single Python Library activity are rendered as draggable tiles; the Stage group renders empty and the remaining Activity nodes are not surfaced. Each table below marks whether a node is In palette (you can drag it now) or Filtered (defined in the model, not currently offered). Build real pipelines from the In-palette rows.

Stage nodes — coarse pipeline phases

All Stage nodes are Filtered — the Stage group renders empty in the current palette.

Node	What it represents
Manual Review	A human-review checkpoint inside the pipeline (work pauses for a person).
Sources (Ingestion)	Pulls documents in from a connector/source as the pipeline’s intake (see Connectors).
RPA Bots	Hands work to an RPA Bot.
Agent Flow	A phase that runs an agent over the documents.
AI Pipeline	Runs a chained AI-model prediction pipeline (Asset/AI Builder’s chainer).

Activity nodes — common processing steps

Only Python Library is surfaced; every other Activity node is Filtered today.

Node	What it does	Surfaced
Python Library	Runs a Studio-authored Python Library snippet.	In palette
Export	Writes documents/extracted data out to a configured Export target (Connector ▸ Output — see Connectors).	Filtered
Data Feeds	Pulls from / pushes to an external data feed.	Filtered
Conditional	Branches the pipeline on a condition (a coarse, stage-level branch).	Filtered
Rescore Models	Re-runs scoring against the trained AI models.	Filtered
Regroup Summary	Re-groups / summarises documents (e.g. recombine split pages).	Filtered
User Allocation	Allocates documents to users / review queues.	Filtered

Functional / operator nodes — the fine-grained operators

These are the workhorses. Each has an Operator Type and a parameter form. This whole group is surfaced in the normal (non-mesh) palette — except the Mesh rows at the bottom, which only appear in mesh mode (and even then only Queue + Service; Subscribe/Publish are XFlow-mode pub-sub operators, not mesh-designer tiles).

Operator node	What it does	Notes
Agent Operator	Calls a configured Agent as a pipeline step (the agent-to-pipeline bridge — see Your first agent).	In palette. Pass it input; capture its output downstream.
Bash Operator	Runs a shell/bash command step.	In palette.
Python step (via Python Library)	Runs your Python logic.	In palette. Authored as a Library asset.
API Fetch	Makes an outbound HTTP/API call and captures the response.	In palette.
SQL Operator	Runs a SQL query (e.g. against a Datasheet).	In palette.
Send Email	Sends an email (To / Subject / Message, with placeholder tokens).	In palette.
Move To State	Advances a document to a lifecycle stage — the bridge from pipeline to Stateflow.	In palette. This is how an XFlow touches a Lifecycle; the XFlow itself is still not a Lifecycle.
Conditional Operator	Fine-grained conditional branch at the operator level.	In palette.
Xflow Operator	Calls another XFlow as a sub-step (compose pipelines).	In palette. Reuse a pipeline you already built.
Iterator Operator	Loops a sub-step over a collection of items.	In palette.
Bot Operator	Invokes an RPA Bot at operator granularity.	In palette.
Vector Ingestion	Chunks → embeds → indexes text for Knowledge retrieval (the knowledge-spine core step).	In palette. `TaskType 14`; default 16 chunks per batch, 1 parallel batch, 429-aware. Powers Knowledge collections.
Agent Finetuning	Kicks off an agent / model fine-tuning step.	In palette.
Queue	A durable queue hop.	Mesh-mode only.
Service (async/parked)	Hands work to an external long-running Service and parks (holds no worker slot).	Mesh-mode only; Service is flag-gated.
Subscribe to Topic	Receives messages from a pub/sub topic.	Filtered — XFlow-mode pub-sub operator; not a mesh-designer tile.
Publish to Topic	Emits messages to a pub/sub topic.	Filtered — XFlow-mode pub-sub operator; not a mesh-designer tile.

Under the hood. The default ingestion XFlow every collection gets is a 5-task pipeline: route-by-job-kind → block-fetch → upload-to-jupiter → construct-document → write-to-Postgres. A Knowledge collection adds the Vector Ingestion operator as its core step. You rarely edit the seeded ingestion XFlow — you build your own XFlows for downstream processing and point a collection or schedule at them.

The node card (anatomy of one node)

When a node sits on the canvas it shows:

Region	What it is
Icon tile (coloured)	The node-kind glyph.
Label	Inline-editable name — click to rename.
Description	Inline-editable subtitle.
Warning badge	Appears when required params are missing. Fix before running.
Doc-count footer (optional)	How many documents this node touches; deep-links to those docs.
Expandable detail	“Can be viewed by” roles + the Operator Type.
Hover actions (permission-gated)	Start-connection (arrow-right) · cancel-connection (arrow-left) · edit (or double-click → node config) · delete.

Edges (connecting nodes)

Draw an edge: hover a node, click its start-connection arrow, then click the target node.
Edit an edge: click the edge line → Edit Edge dialog with Name and Description; edit or delete the edge there.
Disconnect: click the line to remove it. Edges carry arrowheads and optional labels.

Canvas controls

Control	Location	What it does
Switch Orientation	bottom-right	Toggle horizontal / vertical layout.
Zoom In / Zoom Out	bottom-right	Scale the canvas.
Zoom-to-window	legend bar	Fit the whole graph.
Maximize / Normal	legend bar	Toggles palette visibility / full-canvas mode.
Auto-zoom	—	One-click auto-fit on first interaction.
Mesh run-status chip	bottom-left	In Mesh mode, shows per-segment states while running.

Empty canvas shows “No task found in flow. Drag and drop any task to get started.”

Control	What it does	Disabled when
Enable toggle	Turns the XFlow’s scheduled run on/off.	While there are unsaved (dirty) changes.
Auto Refresh toggle	Live-refreshes the Runs tab (with a pulsing spinner).	Outside the Runs tab.
Save	Persists the graph + dialog settings.	Unless there are unsaved changes.
Discard changes (trash icon)	Reverts to the last saved version.	—
Execute (hover-menu)	Quick Run / Document Run / Custom Run.	—
Header action-menu	Publish · Edit · Duplicate · Pin / Unpin · Delete (permission-gated).	—

Watch out — reserved names. XFlows whose name starts and ends with __ are system-reserved (e.g. the seeded ingestion spine). Non-super-admins don’t see edit affordances on them. Don’t name your own XFlows that way.

Add / Edit XFlow dialog

Opened from + XFlow or the action-menu’s Edit.

Field	Notes
Name (required)	Duplicate-name and reserved-`__` validation.
Description	Free text.
Show Advanced Settings →
Concurrency Limit	Max simultaneous in-flight items.
Execution Profile (SizeClass)	Resource size class for the run.
Repeat Every	Value + unit — the schedule interval (works with the Enable toggle).
Retries / Retry Delay (min)	Auto-retry policy on failure.
Trigger (multi-select event types)	How the XFlow fires. Selecting Entity Ingestion (value 19) reveals an Entity multi-select; selecting a Stage trigger (value 2) reveals a Stage multi-select.
On Failure Notification toggle	Reveals an Email action (To / Subject / Message, with Placeholder menus).

Save label: Save XFlow (or Save Mesh in Mesh mode).

Execute dialog

The Execute menu picks the mode:

Mode	Input	Use it for
Quick Run	none	Fire the whole pipeline immediately with no per-run input.
Document Run	`document_url` (or a `drive_url` via the embedded drive picker)	Run the pipeline against one specific document.
Custom Run	a free-text Run Input textarea (help code `AXF013`)	Pass arbitrary JSON/parameters for a one-off run.

Execute → the run is queued → the XFlow Progress overlay streams live status (runId, AO base URL). In Mesh mode all three delegate to a runMesh() path.

Runs tab — inspecting and debugging runs

Filter bar: Tags chip input · Stage multi-select · Date Range picker (Start/End time + quick radios Today / Yesterday / Week / Month / Custom “N units ago”) · Clear / Search.

Bulk-select toolbar (appears on selection): Retry · Pause · Resume · Cancel · Delete chips. Paginator: 5 / 10 / 20 / 50.

Run table columns:

Column	Notes
Flow Name	Plus copy run-id / copy document-id.
Status pill	completed / failed / running / paused / cancelled — each with an inline action icon by state (Retry / Resume / Cancel / Suspend / rerun).
Start Time	Sortable.
Total Duration	—

Row click → right sidenav (60% width):

Header chips: parent_run_id, flow_run_id, deployment_id.
State badge + created time + duration + “N Task runs”.
Tab Task Logs — expandable per-task rows → timestamped, level-coded log lines (this is where you read which operator failed and why).
Tab Logs — infinite-scroll raw log stream with date separators (“All logs loaded”).
Panel menu: Copy Parameters (super-admin) · Delete.

Empty → “No Runs Executed”.

Debugging a failed run — the loop

Open the Runs tab; the failed run shows a red Status pill.
Click the row → Task Logs in the sidenav; expand the task with the failure (it’s the one that stopped the chain).
Read the level-coded lines for the error; cross-check the operator’s config in the node dialog.
Fix the node config (or the upstream data), Save, then use the inline Retry icon on the run — or re-Execute.

Tip. If a run sits at queued forever and never starts, the Prefect worker likely isn’t running. Locally that means the stack’s worker container is down (see the launch runbook).

Mesh-mode runs (forward reference)

When the editor is in Mesh mode (palette + Save/Run + Runs repurposed to mesh artifacts), the Runs tab becomes a two-pane Mesh run list (status / run-id / doc / hops) plus a Run trace pane: a member timeline (dot states done / failed / running / awaiting service), per-member “Show output” / “View full logs”, a queue-health banner (queued vs stalled), and a Baton trail of pub/sub hops (delivered / queued / failed, with expandable payloads + attempt counts).