AI Workflow Node Guide

Welcome to the AI Workflow Editor! Use this guide to understand how each node works, what data it expects, and how to configure it for your automation needs.

🤖 AI & Logic Nodes

1. AI Agent

System Prompt: Instructions for the AI (e.g., "Summarize this text"). Model: One of the AI models enabled for your workspace.

• Purpose: The AI reasoning step in your workflow. It processes information using the model you select.
• Input: Receives text or data from the previous node.
• Config:
• Output: The text generated by the AI.
• Use Case: Writing a blog post based on research data or analyzing customer sentiment.

2. Code Tool

Language: JavaScript or PHP. Source Code: Your custom logic.

• Purpose: Runs custom JavaScript or PHP code for complex transformations.
• Input: Accessible via the input object in your code.
• Config:
• Output: Whatever value your code returns/assigns to result.
• Use Case: Calculating a custom risk score or reformatting a complex JSON object.

3. Loop (Iterator)

* Loop Over Array: Path to the array variable (e.g., {{nodes.scrape.links}}).

Loop Branch: Fires once for every item in the list. Done Branch: Fires once after all items are finished.

• Purpose: Runs branches of your workflow multiple times for a list of items.
• Input: A JSON array of items.
• Config:
• Runtime Limits: Loop iterations and nesting depth are capped by your plan to prevent runaway executions.
• Output:
• Use Case: Sending an individual email to every person in a list.

4. Approval (Human Gate)

Delivery: Notification via UI or Email. Message: Instructions for the reviewer. Comments: Optional or required comments on rejection or request changes. Request Changes: Optional correction path with a revision limit.

• Purpose: Pauses the workflow until a human reviews and approves the data.
• Input: Any data that needs verification.
• Config:
• Output: Branches to "Approve", "Reject", or "Request Changes" when that action is enabled.
• Use Case: Reviewing an AI-generated invoice before it is sent to a client.

5. Approval Group

Reviewers: Static reviewer list, dynamic reviewer path, or approval policy path. Review Mode: All reviewers, any reviewer, or quorum. Fallback Reviewers: Used when policy mode resolves no valid reviewers. Request Changes: Optional correction path with a revision limit.

• Purpose: Pauses the workflow for multiple reviewers, quorum decisions, or policy-driven reviewer routing.
• Input: Any payload that needs a grouped decision.
• Config:
• Output: Completed approval summary plus the approved, rejected, or changes-requested branch.
• Use Case: Finance plus manager approval for larger purchases.

🚦 Flow Control Nodes

6. Trigger

Manual: Triggered by clicking "Run" in the editor. Schedule: Runs automatically (e.g., every hour, daily). * Email: In live mode, runs when an email matches your filter.

{{trigger.from_email}}: Sender email address {{trigger.from_name}}: Sender display name when available {{trigger.subject}}: Incoming email subject {{trigger.body}}: Cleaned email body text

• Purpose: The starting point of every workflow.
• Config:
• Output: Initial trigger data (e.g., Email subject, current timestamp).
• Email Trigger fields:
• Tip: For email auto-replies, connect Email Trigger → AI Agent → Gmail/SMTP Email.

7. Webhook

URL Slug: Custom endpoint name. Auth: Optional Basic Auth or API Key.

• Purpose: Triggers your workflow from an external app (via URL).
• Config:
• Output: The full JSON data sent by the external app.
• Use Case: Starting a workflow when a Stripe payment is successful.

8. Switch (If/Condition)

Logical Operator: AND (all must match) or OR (any can match). Conditions: Set rules (e.g., {{price}} > 100).

• Purpose: Routes the workflow based on data values.
• Config:
• Output: Branches to "True" or "False".
• Use Case: Sending "High Value" leads to a different AI Agent.

9. Merge

* Strategy: Consolidate results into a single list or merge objects.

• Purpose: Waits for parallel paths to finish and combines their data.
• Config:
• Output: A combined set of all data from connected branches.
• Use Case: Scraping two different sites and merging the results before summarizing.

⚠️ Error Handling (All Nodes)

• Continue on error: Each node has a toggle in the editor to keep the workflow running even if the node fails.
• When enabled: The step is marked Failed (continued) in execution history, and downstream nodes still run.
• When disabled: The workflow stops on that node’s error.
• Retries: HTTP, Tool, Agent, and CMS Action nodes can retry transient failures.
• Write safety: For create/update/delete/send actions, retries are skipped unless you provide an Idempotency Key.

🛠️ Data & Utility Nodes

10. Sync (Diff/Merge)

Key Field: Unique identifier in each record (e.g., id or sku). Source Path / Target Path: Where to read datasets from the input. Conflict Policy: source_wins, target_wins, or latest (by updated_at field). Delete on Missing: If enabled, records missing in source are marked for deletion. * Ignore Fields: Comma‑separated list to exclude from diffs (e.g., updated_at).

• Purpose: Compare two datasets (source vs target), detect creates/updates/deletes, and output a structured change plan.
• Input: An object with source and target arrays (or custom paths).
• Config:
• Output: creates, updates, deletes, conflicts, stats.
• Use Case: Sync Airtable → Google Sheets, or keep two databases in alignment with a diff first.

11. HTTP Request

Max Retries: Retries transient failures up to 3 times. Retry Delay: Wait time between retry attempts. * Idempotency Key: Recommended for POST/PUT/PATCH/DELETE when retries must be safe.

• Purpose: Connects to any website or API.
• Config: Method (GET/POST), URL, Headers, and Body.
• Reliability:
• Output: The raw response from the requested server.
• Use Case: Fetching live stock prices or posting data to a custom CRM.

12. Set Node

• Purpose: Hardcode or rename variables in your workflow.
• Config: A JSON object of fields you want to set.
• Use Case: Initializing a "Status" field to "Pending" at the start of a flow.

13. Sort

• Purpose: Organizes lists of data.
• Config: Path to the key to sort by and Sort Order (ASC/DESC).
• Use Case: Sorting a list of products by price from lowest to highest.

14. Memory (v2)

• Purpose: Durable workflow memory with optional history and sessions.
• Config: Action (auto, get, set, append, delete, list, clear), Key, Session ID (defaults to global), Storage (Database/File), History/TTL/Tags.
• Use Case: Store a cursor, append daily results, or recall previous state across runs.

15. Context Memory

• Purpose: Persist explicit context blocks and auto‑inject them into AI Agent prompts.
• Config: Title, Mode (Replace/Append), Text/JSON content, Tags, Session ID, Inject toggle.
• Use Case: Keep brand voice, SEO rules, or customer constraints available in every run.

16. Wait

• Purpose: Delays execution for a set amount of time.
• Config: Duration in seconds.
• Use Case: Waiting 30 seconds for a third-party report to generate.

17. Output

• Purpose: Formats the final answer shown to the user.
• Config: Format (Text, JSON, or Markdown).
• Use Case: Formatting technical data into a beautiful Markdown report.

✅ Workflow Validation & Safety

NeuronFlow includes built-in validation to keep workflows safe, predictable, and easy to debug. The Validation panel auto‑opens when blocking errors first appear. The same panel now includes a Preflight view so you can see whether the workflow is ready for:

• test runs
• publishing
• live traffic
• per-node setup completion
• environment promotion (Development / Staging / Production)

What the validator enforces

1. Single Trigger: Only one Trigger/Webhook is allowed per workflow.
2. No cycles: Cyclic connections are blocked to prevent infinite loops.
3. No edges into triggers: Triggers are start points only.
4. Valid tool wiring: Tool handles must connect Tool → Agent tool input.
5. Workflow size limits: Max nodes, max edges, max outgoing branches per node, and max tools per agent are enforced by plan/system limits.

What the validator warns about

1. Unreachable nodes (not connected to the trigger)
2. Nodes with no incoming connections
3. Nodes with no outgoing connections (except Output)
4. Tool nodes missing required inputs (warning unless the tool is marked critical)
5. Retries on write actions without an idempotency key
6. Typed handoff checks for obvious mismatches, such as a text-only node feeding a list-processing node

In the editor, invalid nodes/edges are highlighted, and hovering them shows the exact issue. This makes it fast to fix broken flows before execution. Draft workflows can still be tested in the editor, but live runs, schedules, webhooks, and event triggers only work after publishing. Even after publishing, only workflows in the Production environment can receive real live traffic. Development and Staging stay safe for testing.

🔌 Integration Tools (Powered by Tool Node)

The Tool node allows you to use pre-built integrations:

* Telegram needs a reachable chat target: a numeric chat ID, a public channel username such as @publicchannel, or a valid -100... channel/group ID.

• WordPress: Create posts and manage pages.
• Google Analytics: Fetch site traffic data.
• Google Search Console: Fetch keyword rankings.
• Google PageSpeed: Run PageSpeed Insights for performance, SEO, and Core Web Vitals.
• Chrome UX Report (CrUX): Fetch real-user Core Web Vitals data for a URL or origin.
• SMTP Email: Send professional emails via your own server.
• Telegram/WhatsApp: Send instant messages to chats/phones.
• News/Weather: Fetch live global information.

Connections & Accounts

• Use Integrations to connect one or more accounts per tool.
• In the Tool node panel, choose a Connection (or leave empty to use the default).
• If you enter credentials directly in the node, they override the selected connection.
• Use Verify Setup to confirm the node has the right connection or inline credentials before running.
• Use Dry Run for safe read/list/check actions when you want to test configuration without changing live systems.

Tool Input (Optional)

• Every Tool node includes a Tool Input panel where you can set required parameters.
• If a required field is missing, the panel auto‑opens and shows what’s missing.
• You can still pass values from upstream nodes — the warning is just a safety check.

Email Reply Shortcuts

• For Gmail and SMTP Email, you can reply to an incoming email without manually typing the recipient every time.
• Use {{trigger.from_email}} in To Email to respond to the original sender.
• Use Re: {{trigger.subject}} in Subject to keep the conversation clear.
• For reply content, either leave Body empty to use the previous node output, or set Body to {{input}}.

PageSpeed & CrUX Configuration

url: Full page URL to analyze. strategy: mobile or desktop. * categories: Comma-separated list (e.g., performance,seo,accessibility).

url or origin: URL for a specific page, or origin for a domain. form_factor: PHONE, DESKTOP, or TABLET (optional). * metrics: Comma-separated list (e.g., largest_contentful_paint,cumulative_layout_shift).

• Google PageSpeed:
• Chrome UX Report (CrUX):

🧭 Reliability Features

NeuronFlow includes several production-safety features for workflows:

• Secure node secrets: Passwords and tokens entered into nodes are stored outside workflow JSON.
• Workflow Versions: Every save, generate, and restore creates a snapshot. You can restore older versions from the editor.
• Retry Observability: Execution history now tracks step duration, retry count, attempt count, and idempotency usage.
• Environment Promotion: Workflows now move through Development, Staging, and Production. Only Production receives live traffic.
• Tool Reliability Audit: Admins can review tool contract health so broken integrations are caught before they affect workflow builders.
• Setup Verification: Tool nodes can be checked before execution so missing config is caught early.