Academy · Reference
XFlow node reference
In one line. Every block you can drop on an XFlow canvas, and every control around it. You’ll be able to. Pick the right block, fill in the Add/Edit and Execute dialogs, and read a run well enough to find what failed. Where this lives.
Studio > Agents > Agent Toolkit > Agents— flows appear in the same list as agents, so use the list filter to see them. + XFlow creates one; opening a flow opens the canvas.
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 block, field, or control.
How to read this
- An XFlow is a processing pipeline — a directed graph of nodes that does work on documents or data. It is not a document Lifecycle (those are the review stages a document moves through). The word “workflow” gets used for both in places — keep the two ideas apart.
- Each node has an Operator Type that decides which config form it opens. Some nodes show a warning badge until their required parameters are filled.
- In Mesh mode the palette is restricted to exactly three blocks — Xflow Operator, Queue and Service — because a mesh composes whole runnables wired together, rather than individual steps.
The node palette
The Library button on the toolbar shows and hides the blocks panel. It is headed Add to flow (Mesh blocks in Mesh mode), groups the blocks, and has a search box for narrowing them by name. Drag a block onto the canvas — or focus its chip and press Enter or Space to drop it in place.
| Node | What it does | Notes |
|---|---|---|
| Agent Operator | Calls a configured Agent as a pipeline step (the agent-to-pipeline bridge — see Your first agent). | Pass it input; capture its output downstream. |
| Bash Operator | Runs a shell command step. | |
| Python Library | Runs your own Python logic. | Authored as a reusable asset under Studio > Agents > Assets > Library. |
| API Fetch | Makes an outbound API call and captures the response. | |
| SQL Operator | Runs a SQL query (for example against a Datasheet). | Datasheets live under Studio > Data > Datasheets. |
| Send Email | Sends an email (To / Subject / Message, with placeholder tokens). | |
| Move To State | Advances a document to a lifecycle stage — the bridge from pipeline to Lifecycle. | This is how an XFlow touches a Lifecycle; the XFlow itself is still not a Lifecycle. |
| Conditional Operator | Branches the pipeline on a condition. | |
| Xflow Operator | Calls another XFlow as a sub-step. | Reuse a pipeline you already built. |
| Iterator Operator | Loops a sub-step over a collection of items. | |
| Bot Operator | Invokes a Bot as a step. | Bots live under Studio > Agents > Assets > Bots. |
| Vector Ingestion | Chunks, embeds and indexes text so a knowledge collection can be searched. | Powers Knowledge collections. |
| Agent Finetuning | Kicks off an agent / model fine-tuning step. | |
| Queue | A durable queue hop — work waits here until the next step picks it up. | One of the three Mesh blocks. |
| Service | Hands work to an external long-running Service and waits for it without holding the pipeline open. | One of the three Mesh blocks. Services are registered under Studio > Agents > Agent Toolkit > Services. |
| Subscribe to Topic | Starts a step when a message arrives on a topic. | |
| Publish to Topic | Publishes a message to a topic for other flows to react to. |
The seeded ingestion flow. Every collection is created with a standard ingestion flow already in place. You rarely edit it — build your own flows for downstream processing and point a collection or a schedule at them. A Knowledge collection’s ingestion adds the Vector Ingestion step so its documents become searchable.
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 | Start-connection (arrow-right) · cancel-connection (arrow-left) · edit (or double-click → node config) · delete. Which of these you see depends on the access you have. |
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 |
|---|---|---|
| Fit to window | bottom-right | Scale the canvas so the whole graph is visible. |
| Switch Orientation | bottom-right | Toggle horizontal / vertical layout. |
| Zoom In / Zoom Out | bottom-right | Scale the canvas. |
| Maximize / Normal view | canvas | Expands the canvas to fill the screen, and back again. |
| 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.”
Toolbar reference (above the canvas)
| Control | What it does | Disabled when |
|---|---|---|
| Enable toggle | Turns the XFlow’s scheduled run on/off. Not shown in Mesh mode — a mesh has no scheduled run. | While there are unsaved changes. |
| Auto Refresh toggle | Live-refreshes the Runs tab (with a pulsing spinner). | Outside the Runs tab. |
| Open editor | Opens the full-page editor. | Already in the full-page editor. |
| Library | Shows or hides the blocks panel. | Outside the full-page editor, or on an empty flow. |
| 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. Which entries appear depends on the access you have. | — |
Watch out — system flows. Some flows are system flows and cannot be edited. Give your own flows ordinary names.
Add / Edit XFlow dialog
Opened from + XFlow, or from an existing flow’s action-menu Edit.
| Field | Notes |
|---|---|
| Name (required) | Duplicate names are rejected. |
| Description | Free text. |
| Show Advanced Settings → | |
| Concurrency Limit | Max simultaneous in-flight items. |
| Execution Profile | How much resource each run gets. |
| Repeat Every | Value + unit — the schedule interval (works with the Enable toggle). |
| Retries / Retry Delay (Minutes) | Auto-retry policy on failure. |
| Trigger (multi-select event types) | How the XFlow fires. Choosing a collection-ingestion trigger reveals a collection picker; choosing a stage trigger reveals a stage picker. |
| 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 | a document link (or pick one from the drive picker) | Run the pipeline against one specific document. |
| Custom Run | a free-text Run Input box | Pass your own parameters for a one-off run. |
Execute queues the run, and the XFlow Progress overlay streams live status. In Mesh mode all three modes start a mesh run.
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 | — |
Click a row and a detail panel opens on the right:
- Header chips carry the run’s identifiers — quote them when you raise a query about a specific run.
- 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: 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 stays queued and never starts, nothing is picking the work up — that is not something you can fix from the flow. Contact your administrator.
Mesh-mode runs
In Mesh mode the Runs tab reads as a mesh rather than a single pipeline. It becomes two panes: a Mesh run list (status, run id, document, hops) and a Run trace. The trace shows a timeline of every member — done, failed, running, or awaiting a service — with Show output and View full logs on each, a queue-health banner telling you whether work is moving or stalled, and a Baton trail of the hops between members (delivered / queued / failed), each expandable to see what was passed and how many attempts it took.
Prefer learning inside the product? The same academy lives in the platform's Learn menu — every screen links to the chapter that explains it.
See the platform live