> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ingestly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline editor

> Build visual processing pipelines with the drag-and-drop editor.

The pipeline editor is a visual canvas where you design your pipeline by adding nodes and connecting them with edges.

## Node rail

The **node rail** is a compact icon strip on the left edge of the editor. It groups nodes into three categories:

* **Triggers**
* **Actions**
* **Outputs**

Hover any category icon to expand the rail into a floating palette listing every node in that category, along with a **Search nodes** field that filters by name or description. The palette stays open while your cursor is over it and collapses when you move away.

Within each category (**Triggers**, **Actions**, **Outputs**), nodes are listed alphabetically by name. The edge-drag node picker (shown when you drag an edge to empty canvas) is likewise sorted alphabetically.

To add a node, drag a card from the expanded palette onto the canvas. A highlighted ring appears on the canvas while you drag to confirm the drop target.

<Tip>When the canvas is empty, an inline hint reads "Drag a trigger from the left to begin." Start there, then connect actions and outputs as you build out the pipeline.</Tip>

See [node types](/nodes/introduction) for a complete reference of all available nodes.

## Connecting nodes

Click the output handle of one node and drag to the input handle of another node to create an edge. Edges define the flow of data through your pipeline.

Rules for connections:

* Data flows from left to right (trigger → action → output)
* You cannot create circular connections
* Some node types support multiple input or output connections
* Edges between incompatible node types are prevented

When you connect two nodes, Ingestly creates the edge with the default **On success** condition. To change it, click the edge and edit the **Condition** in the properties panel. See [conditional routing](/guides/conditional-routing) for the full set of edge condition types and operators.

### Branch from a node

To author multiple outgoing branches in one shot, click the **branch** action in a node's hover toolbar. The **Add branches** modal lets you list several rules and optionally add an **Otherwise** edge. Ingestly creates one outgoing edge per rule, each wired to a placeholder target that you can replace with a real node.

## Properties panel

Click a node or edge to open the **properties panel** on the right side of the editor. The panel stays open as you click between nodes so you can step through the graph without reopening it. Click outside the panel or use the close button to dismiss it.

When you select a node, Ingestly pans it to the center of the visible canvas and zooms in to a focus level so it reads clearly even with the side panels open. This accounts for the space taken by the properties panel and data picker. Deselecting restores the previous position and zoom.

Field help is shown via a help icon next to each field's label. Click it to open a popover describing the field and its options, instead of always-visible description text. Toggle fields render inline with their label.

**Resize** the panel by dragging its left edge. The panel width is constrained between a minimum and maximum so your canvas stays usable.

## Data picker

When you select a node, a **Data picker** column opens beside the properties panel and lists every upstream node's output as a tree of fields. The picker helps you discover what is available to reference without leaving the editor.

* **Browse:** expand any upstream node to see its `payload`, `metadata`, and nested fields. Object and array fields nest inline with proper indentation, so `items[].amount` appears under `items` rather than as a flat key.
* **Insert a token:** click any field to insert its template token (`{{nodeName.payload.field}}`) into the focused template editor, or drag the field onto the editor.
* **Sample values:** select a document from the toolbar to see real values from that document's latest run beside each field. Without a document, the picker shows the field schema only.
* **Loop iteration:** when the selected node sits inside a [Loop](/nodes/loop) body, the picker exposes the per-item iteration token alongside the loop source array so you can reference `item.path` instead of the full collection.

Drag the picker's left edge to resize it. Click the hide button in the picker header to collapse it to a single show-button column and reclaim canvas width; click the show button to bring the picker back.

## Code editors

Some node configurations include code editors, such as the [validation node](/nodes/validation) script mode and JSON Schema fields. The editors are powered by Monaco and provide:

* **Syntax highlighting** for JavaScript and JSON
* **Autocomplete suggestions** including template variable autocomplete. Type `{{` to see available variables from upstream nodes
* **Inline error reporting** with underlined errors and hover details
* **JSON validation** for schema fields, showing errors when the JSON structure is invalid

### Editor toolbar

Above each code editor, a toolbar provides formatting buttons for common operations like indenting, commenting, and wrapping selections.

### Fullscreen editing

Click the **expand** button in the top-right corner of any code editor to open it in fullscreen mode. This gives you a larger workspace for complex scripts or schemas. Press **Escape** or click the collapse button to return to the inline view.

## Canvas toolbar

The toolbar sits above the canvas at full width and contains the primary editing controls:

* **Environment badge**: shows the pipeline's [environment](/pipelines/stages), a neutral badge for **Development** and an amber badge for **Production**
* **Save** (`Ctrl+S`): save the current pipeline. An amber indicator appears if the pipeline saved but has validation errors
* **Activate** / **Active**: activate or deactivate the pipeline directly from the editor
* **Undo** (`Ctrl+Z`) and **Redo** (`Ctrl+Shift+Z`): step through edit history for your current session
* **Auto layout** (`Ctrl+L`): reorganize nodes into a clean left-to-right layout. After arranging the nodes, it rescales the view to fit the whole pipeline in the canvas, rather than keeping your prior zoom
* **Pipeline versions**: open the version history drawer (see below)
* **More actions** menu: **Revert to saved**, **Revert to last valid** (when the current save is invalid), **Use template** to populate the canvas from a saved template, **Export to file**, **Import from file**, **Copy to Production** or **Copy to Development** to copy the saved graph to the other [environment](/pipelines/stages), and **Validate pipeline**

## Editing shortcuts and node controls

The editor supports keyboard shortcuts and a right-click context menu for fast editing. Shortcuts are suppressed while your cursor is inside a text or code field.

* **Copy** (`Ctrl+C`), **Cut** (`Ctrl+X`), and **Paste** (`Ctrl+V`): copy, cut, and paste the selected nodes and their edges, including across pipelines.
* **Delete** or **Backspace**: delete the current selection. Select several nodes first to delete them together.
* **Escape**: clear the selection.
* **Save** (`Ctrl+S`), **Undo** (`Ctrl+Z`), **Redo** (`Ctrl+Y` or `Ctrl+Shift+Z`), **Revert to saved** (`Ctrl+R`), and **Auto layout** (`Ctrl+L`).

Right-click a node for **Copy**, **Duplicate**, **Copy reference**, **Disable / enable**, **Rename**, and **Delete**. Right-click empty canvas for **Paste** and **Fit view**, and right-click an edge to **Delete edge**.

Open the app command palette with `Ctrl+K` to run editor commands such as **Save pipeline**, **Validate pipeline**, **Auto layout**, **Fit view**, **Pipeline versions**, and add-node commands by name.

### Pin a mock output

Each non-trigger node's hover toolbar has a **Pin output** action. It opens a dialog where you author a fixed JSON payload for the node to return, so you can build and test downstream nodes without running that node for real. Once a value is pinned, the action becomes **Edit pinned output**, and an **Unpin** action clears it.

## Minimap

A **minimap** in the corner of the canvas gives an overview of the whole graph and lets you pan and zoom quickly. Use the minimap control to **show** or **hide** it.

A small **Unsaved changes** badge appears in the top-left of the canvas whenever you have pending edits. Hover it to see a list of the added, modified, and removed nodes and edges.

## Pipeline versions

Ingestly snapshots the pipeline on every save. Click the **history** icon in the toolbar to open the **Pipeline versions** drawer. The drawer has three regions:

* **Version list** on the left: every saved version, newest first, with the version number, commit message, and timestamp.
* **Diff panel** on the right: when you select a version, the panel shows what differs between that version and the current draft (added, modified, and removed nodes and edges).
* **Restore vN** button at the bottom: replaces the current draft with the selected version. A new entry titled `Restored from vN` is appended to history, so the restore itself is reversible. Unsaved draft changes are lost when you confirm.

Use versions to recover from a bad change, compare two states, or review what shipped on a given date.

## Export and import

To move a pipeline between workspaces or share it with another Ingestly account:

* **Export to file** in the **More actions** menu downloads the current pipeline (nodes, edges, and node configuration) as a JSON file.
* **Import from file** lets you pick a previously exported JSON file. The contents replace the current draft, so save first or accept the confirmation dialog when you have unsaved changes.

Connectors, stores, and forward targets are exported by name, not by ID. On import, Ingestly rebinds each reference to the resource with the same name in the destination workspace. Anything that does not match is cleared, and the pipeline imports with a warning listing the **unbound** connectors, stores, and forward targets together, so you can open the affected nodes and reconfigure them.

## Saving and validating

* Click **Save** to save your current pipeline configuration
* The editor validates your pipeline automatically and shows errors if the configuration is invalid
* Common validation errors: missing trigger, disconnected nodes, missing required configuration

## Testing runs

Use the run controls in the toolbar to test your pipeline with a document from the current pipeline.

* The document picker only shows documents from the current pipeline
* You can test with documents in `Uploaded`, `Completed`, or `Failed` status
* The run button's dropdown lets you pick **Dry run** or **Live run** for the run

### Test step

To test a single node without re-executing the whole pipeline, hover any node and click the **Test step** action in its floating toolbar, or click **Test step** in the properties panel header for the selected node. Ingestly creates a partial run that records its result on a new run row tagged as a partial run, so the original full run is never modified.

How the inputs are produced depends on whether the node has run before:

* **Already run** (warm): Ingestly re-runs just that node, reading predecessor outputs from the most recent run for the selected document so the node receives the same inputs it saw before. Descendants stay frozen and do not run.
* **Never run** (cold, first try): Ingestly runs the pipeline from the trigger up to and including the selected node against the **test document** chosen in the run controls, then stops. Everything downstream of the node is skipped, so no downstream side effects fire. This lets you test a brand-new node, such as a freshly added Extract, before the pipeline has ever run end to end.

The cold first-try test needs a test document selected in the document picker, and it works even on a draft or paused (disabled) pipeline. If the pipeline has unsaved changes when you click **Test step**, Ingestly prompts you to save first so the partial run reflects what is on screen. The button shows a spinner while the run is dispatching.

A test run charges credits for the steps it actually executes, billed at each step's real per-page cost. Steps whose inputs and configuration are unchanged are served from cache and cost nothing, so re-testing a node after tweaking a downstream schema, prompt, or template only pays for the work that actually re-ran.

### Dry run

Use a **Dry run** when you want to inspect output deliveries without sending callback requests or emails.

* Callback nodes show a request preview instead of sending the request
* Email output nodes show an email preview instead of sending the email
* The run output clearly shows that the result is a dry run preview

<Note>A dry run only changes callback and email output delivery. Action nodes such as [HTTP action](/nodes/http-action) and validation endpoint checks still run normally.</Note>

### Live run

Use a **Live run** when you want output nodes to send real requests and emails.

<Warning>On a **Live run**, callback and email output nodes send real external outputs during the run.</Warning>

If you start a **Live run**, Ingestly asks you to confirm before it begins. The default mode follows the pipeline [environment](/pipelines/stages), and your choice is per run, not saved on the pipeline. See [dry runs](/guides/test-mode) for the full picker.

## Activating

After saving a valid pipeline, click **Activate** to start accepting documents. You can also activate from the pipeline's settings tab.

## Undo and redo

Use **Ctrl+Z** to undo and **Ctrl+Shift+Z** to redo changes in the editor. The undo history is maintained within your current editing session.