Nodes and Edges

Nodes and edges are the building blocks of flows. Understanding how to work with them effectively is key to building powerful automations.

Nodes

A node is an instance of a component placed on the flow canvas. Each node performs a specific operation.

Node Anatomy

              ⚙️ Settings Port
              │
    ┌─────────┴─────────┐
    │                   │
📥 ─┤   Component Name  ├─ 📤
    │                   │
    └─────────┬─────────┘
              │
              ⚠️ Error Port

Adding Nodes

From Palette:

1. Open the node palette (left sidebar)
2. Find the component you need
3. Drag it onto the canvas

Via Search:

1. Press / or click search
2. Type component name
3. Click to add at cursor

Keyboard Shortcut:

1. Press N to open quick-add
2. Type to filter
3. Enter to add

Configuring Nodes

Click a node to select it, then use the properties panel:

1. Settings Port: Core configuration
2. Input Ports: Default input values
3. Output Ports: View output schema

Node States

Visual indicators show node status:

State	Indicator	Meaning
Idle	Gray outline	Not processing
Active	Blue pulse	Processing message
Success	Green flash	Completed successfully
Error	Red outline	Error occurred
Disabled	Faded	Node is disabled

Renaming Nodes

1. Double-click the node label
2. Enter a descriptive name
3. Press Enter to confirm

Good names describe what the node does:

• "Validate Input" instead of "Modify"
• "Route by Type" instead of "Router"

Disabling Nodes

Temporarily disable without deleting:

1. Right-click the node
2. Select "Disable"
3. The node is bypassed during execution

Re-enable via the same menu.

Edges

Edges are connections between node ports. They define how data flows through your automation.

Creating Edges

1. Hover over a source port (output)
2. Click and drag
3. Release on a target port (input)

┌──────────┐              ┌──────────┐
│  Node A  │──────────────▶  Node B  │
│          │ output    input         │
└──────────┘              └──────────┘

Edge Appearance

Style	Meaning
Solid line	Active connection
Dashed line	Optional/conditional
Thick line	High volume
Pulsing	Currently active

Edge Colors

Color	Meaning
Blue	Data flow
Purple	Settings
Orange	Control
Red	Error path

Editing Edges

Click an edge to:

• Configure data mapping
• Set conditions
• View schema

Deleting Edges

1. Click the edge to select
2. Press Delete or Backspace

Or right-click and select "Delete".

Rerouting Edges

To change an edge's target:

1. Click the edge
2. Drag the endpoint
3. Drop on new target port

Ports

Ports are the connection points on nodes.

Port Types

Position	Type	Purpose
Left	Input	Receive data
Right	Output	Emit data
Top	Settings/Control	Configuration
Bottom	Error/Status	Errors, status

Port Properties

Each port has:

• Name: Unique identifier
• Label: Display text
• Schema: Expected data format
• Required: Whether connection is needed

Viewing Port Schema

Click a port to see its schema:

{
  "type": "object",
  "properties": {
    "method": { "type": "string" },
    "path": { "type": "string" },
    "body": { "type": "object" }
  }
}

Port Compatibility

Not all ports can connect:

Source	Target	Compatible?
Output	Input	✅ Yes
Output	Settings	⚠️ Usually no
Output	Output	❌ No
Input	Input	❌ No

The editor shows green (compatible) or red (incompatible) when dragging.

Data Flow

Single Path

Simple linear flow:

A ──▶ B ──▶ C ──▶ D

Data moves from A through each node to D.

Branching

One output to multiple inputs:

     ┌──▶ B
A ───┤
     └──▶ C

Both B and C receive the same data from A.

Merging

Multiple inputs to one node:

A ───┐
     ├──▶ C
B ───┘

C receives messages from both A and B (not merged, separate executions).

Conditional Paths

Router component creates conditional branches:

         ┌──▶ Success Handler
Input ───┤
         └──▶ Error Handler

Only one path executes based on condition.

Edge Configuration

Data Mapping

Configure how data transforms between nodes:

# Simple pass-through
data: "{{$}}"

# Select specific fields
userId: "{{$.user.id}}"
email: "{{$.user.email}}"

# Transform data
fullName: "{{$.firstName}} {{$.lastName}}"
timestamp: "{{now()}}"

Static Values

Set constant values:

environment: "production"
version: "1.0.0"
enabled: true

Mixed Values

Combine static and dynamic:

message: "User {{$.userName}} logged in"
metadata:
  source: "login-flow"
  userId: "{{$.userId}}"

Working with Complex Flows

Organizing Nodes

Keep flows readable:

✅ Good Layout:
┌───┐     ┌───┐     ┌───┐
│ A │────▶│ B │────▶│ C │
└───┘     └───┘     └───┘

❌ Messy Layout:
┌───┐
│ A │──────┐
└───┘      │     ┌───┐
     ┌───┐ └────▶│ C │
     │ B │───────┘
     └───┘

Using Comments

Add comment nodes to document:

┌─────────────────────────────────────┐
│ 💡 This section validates input     │
│    before processing                │
└─────────────────────────────────────┘
     │
     ▼
┌──────────┐     ┌──────────┐
│ Validate │────▶│ Process  │
└──────────┘     └──────────┘

Grouping Nodes

Visually group related nodes:

┌─────────────────────────────────┐
│ Validation Section              │
│  ┌───┐    ┌───┐    ┌───┐       │
│  │ A │───▶│ B │───▶│ C │       │
│  └───┘    └───┘    └───┘       │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│ Processing Section              │
│  ...                            │
└─────────────────────────────────┘

Best Practices

1. Name Everything

Give descriptive names to nodes:

• What does this node do?
• What data does it handle?

2. Keep Edges Short

Minimize crossing edges:

• Rearrange nodes for clarity
• Use left-to-right flow
• Group related nodes

3. Document Complex Mappings

Add comments in edge configuration:

# Extract user info for notification
userId: "{{$.data.user.id}}"
email: "{{$.data.user.email}}"
# Format timestamp for display
timestamp: "{{RFC3339($.createdAt)}}"

4. Validate Connections

Before deploying:

• Check all required ports are connected
• Verify schemas match
• Test with sample data

5. Handle All Paths

Ensure all execution paths complete:

• Connect error ports
• Add fallback handlers
• Don't leave dangling outputs

Next Steps

• Data Mapping - Transform data between nodes
• Flow Revisions - Version your flows
• Expression Syntax - Write transformations