Add n8n Workflow Automation Connector

[sambhavnoobcoder]

Issue

Issue #914 requested integration with n8n, a popular open-source workflow automation platform. Users wanted the ability to search and retrieve their n8n workflow definitions and execution history through Airweave, enabling AI agents to understand and query their automation workflows.

The issue was initially vague - it simply requested "n8n connector" without specifying:

• What data should be synced
• How authentication should work
• What use cases to support

Problem Identification

After analyzing the request, I identified the following requirements:

1. Data to Index: n8n stores two primary types of data worth searching:

   • Workflows: Automation definitions with nodes (integrations), connections, and settings
   • Executions: Historical logs of workflow runs, including successes and failures

2. Authentication: n8n uses API key authentication via the X-N8N-API-KEY header, requiring:

   • Base instance URL (self-hosted or cloud)
   • API key generated from n8n settings

3. Key Use Cases:

   • "Find all workflows that use Stripe integration"
   • "Show me failed workflow executions from last week"
   • "What automations trigger when a customer signs up?"

4. Technical Challenges:

   • n8n API is only available in paid cloud plans or self-hosted instances
   • Need to handle large execution histories efficiently
   • URL normalization (users might include /api/v1 or trailing slashes)

Solution Design

I designed a solution following Airweave's existing connector patterns:

Architecture Decisions

1. Two Entity Types:

   • N8nWorkflowEntity: Captures workflow definitions, nodes, connections, and metadata
   • N8nExecutionEntity: Captures execution history with status, errors, and timing

2. Hierarchical Structure:

   • Workflows as top-level entities
   • Executions as children of workflows (using breadcrumbs)
   • Enables queries like "show executions for workflow X"

3. Configuration Options:

   • Toggle execution sync on/off (some users may only want workflow definitions)
   • Configurable execution limit per workflow (default: 100 to prevent massive syncs)

4. Authentication Strategy:

   • Direct auth with URL + API key
   • URL validation and normalization
   • Support for both http and https

5. Error Handling:

   • Graceful degradation if executions endpoint fails
   • Retry logic with exponential backoff
   • Detailed error messages for failed executions (searchable!)

Implementation

Components Delivered

1. Entity Schemas

Created two entity schemas that define the data structure:

• Workflow entity with searchable nodes array (enables "find workflows using X integration")
• Execution entity with searchable error messages (enables "find failed runs")
• Proper timestamp handling for temporal queries

2. Authentication Config

Implemented URL + API key authentication with:

• URL validation (must start with http:// or https://)
• Automatic normalization (removes /api/v1 suffix, trailing slashes)
• Clear error messages for invalid configurations

3. Source Configuration

Added configurable options:

• Enable/disable execution sync
• Set maximum executions per workflow (1-1000)
• Prevents overwhelming syncs for workflows with thousands of runs

4. Source Connector

Built the main connector with:

• Workflow fetching (all active and inactive workflows)
• Execution history retrieval per workflow
• Proper breadcrumb hierarchy
• API endpoint construction with n8n REST API v1
• Rate limiting support at organization level

5. Comprehensive Testing

Wrote 13 unit tests covering:

• Entity creation from API responses
• Workflow and execution sync logic
• Authentication and validation
• Error handling (HTTP errors, missing fields)
• URL normalization edge cases
• All tests use exact API response mocks matching n8n's actual format

6. Frontend Integration

• Added n8n icon (SVG) to app icons
• Updated README with n8n in supported integrations list

Testing Strategy

Since n8n API requires a paid plan or self-hosted instance, I:

1. Researched n8n's REST API v1 documentation thoroughly
2. Created exact mock responses matching their API format
3. Tested all functionality with these mocks
4. Achieved 100% test pass rate (13/13 tests)
5. Verified syntax and imports compile correctly

The mocked API responses include:

• Complete workflow objects with nodes, connections, settings
• Execution objects with status, timestamps, error details
• Edge cases (empty responses, tag formats, missing fields)

✅ Results

What Works

• ✅ Syncs all workflows (active + inactive)
• ✅ Syncs recent execution history per workflow
• ✅ Searchable workflow nodes (find workflows using specific tools)
• ✅ Searchable execution errors (find failed runs with error messages)
• ✅ Configurable execution limits
• ✅ Self-hosted n8n instance support
• ✅ URL validation and normalization
• ✅ Comprehensive error handling

Test Coverage

• 13/13 unit tests passing
• ~1.5 second test runtime
• Covers all core functionality
• Exact API response mocks

Related

• Fixes : [Connector Request] n8n #914
• API Reference: https://docs.n8n.io/api/api-reference/
• n8n Website: https://n8n.io/

---

Summary by cubic

Adds an n8n connector that syncs workflows and optional execution history into Airweave for search and analysis. Implements direct API key auth with URL normalization and supports common queries like “find workflows using X” and “show failed runs.” Fixes #914.

• New Features
  • Direct auth: instance URL + X-N8N-API-KEY with validation and /api/v1 and trailing slash normalization.
  • Entities: N8nWorkflowEntity and N8nExecutionEntity with searchable nodes and error messages; executions linked to parent workflows via breadcrumbs.
  • Source: fetches all workflows; optional execution sync; per-workflow execution limit (default 100); retries and graceful error handling.
  • Config: include_executions and max_executions_per_workflow (1–1000).
  • Extras: n8n icon added; README updated; 13 unit tests with mocked API responses.

^{Written for commit c7290d5. Summary will update automatically on new commits.}

[cubic-dev-ai]

1 issue found across 7 files

Prompt for AI agents (all 1 issues)

Understand the root cause of the following 1 issues and fix them.


<file name="backend/airweave/platform/entities/n8n.py">

<violation number="1" location="backend/airweave/platform/entities/n8n.py:17">
Rule violated: **Check for Cursor Rules Drift**

The n8n workflow/execution entities introduce a brand-new source connector, but `.cursor/rules/source-connector-implementation.mdc` (and the rest of `.cursor/rules`) still lack any n8n entry—`grep -R -n -F &#39;n8n&#39; .cursor/rules` returns nothing—so Cursor remains unaware of this integration. Please add an n8n-specific Cursor rule section covering its entities, auth inputs, and sync behavior to keep developer guidance in sync.

(Based on your team&#39;s feedback about keeping Cursor-rule updates provider-specific, this comment only calls out the missing n8n entry.) [FEEDBACK_USED]</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[sambhavnoobcoder]

cc : @felixschmetz @orhanrauf