BMAD-METHOD/src/modules/bmm/workflows/n8n-expert/_shared/n8n-helpers.md

n8n Workflow Helpers

Node Creation Guidelines

Basic Node Structure

{
  "id": "unique-node-id",
  "name": "Node Name",
  "type": "n8n-nodes-base.nodeName",
  "typeVersion": 1,
  "position": [x, y],
  "parameters": {},
  "credentials": {}
}

Node Positioning

• Start node: [250, 300]
• Horizontal spacing: 220px between nodes
• Vertical spacing: 100px for parallel branches
• Grid alignment: Snap to 20px grid for clean layout

Common Node Types

Trigger Nodes:

• n8n-nodes-base.webhook - HTTP webhook trigger
• n8n-nodes-base.scheduleTrigger - Cron/interval trigger
• n8n-nodes-base.manualTrigger - Manual execution trigger
• n8n-nodes-base.emailTrigger - Email trigger

Action Nodes:

• n8n-nodes-base.httpRequest - HTTP API calls
• n8n-nodes-base.set - Data transformation
• n8n-nodes-base.code - Custom JavaScript/Python code
• n8n-nodes-base.if - Conditional branching
• n8n-nodes-base.merge - Merge data from multiple branches
• n8n-nodes-base.splitInBatches - Process data in batches

Integration Nodes:

• n8n-nodes-base.googleSheets - Google Sheets
• n8n-nodes-base.slack - Slack
• n8n-nodes-base.notion - Notion
• n8n-nodes-base.airtable - Airtable
• n8n-nodes-base.postgres - PostgreSQL
• n8n-nodes-base.mysql - MySQL

Connection Guidelines

Connection Structure

{
  "node": "Source Node Name",
  "type": "main",
  "index": 0
}

Connection Rules

1. Each connection has a source node and target node
2. Main connections use type: "main"
3. Index 0 is default output, index 1+ for conditional branches
4. IF nodes have index 0 (true) and index 1 (false)
5. Always validate that referenced node names exist

Connection Patterns

Linear Flow:

Trigger → Action1 → Action2 → End

Conditional Branch:

Trigger → IF Node → [true: Action1, false: Action2] → Merge

Parallel Processing:

Trigger → Split → [Branch1, Branch2, Branch3] → Merge

Error Handling Best Practices

Error Workflow Pattern

{
  "name": "Error Handler",
  "type": "n8n-nodes-base.errorTrigger",
  "parameters": {
    "errorWorkflows": ["workflow-id"]
  }
}

Retry Configuration

{
  "retryOnFail": true,
  "maxTries": 3,
  "waitBetweenTries": 1000
}

Data Transformation Patterns

Using Set Node

{
  "name": "Transform Data",
  "type": "n8n-nodes-base.set",
  "parameters": {
    "mode": "manual",
    "values": {
      "string": [
        {
          "name": "outputField",
          "value": "={{ $json.inputField }}"
        }
      ]
    }
  }
}

Using Code Node

{
  "name": "Custom Logic",
  "type": "n8n-nodes-base.code",
  "parameters": {
    "language": "javaScript",
    "jsCode": "return items.map(item => ({ json: { ...item.json, processed: true } }));"
  }
}

Credentials Management

Credential Reference

{
  "credentials": {
    "httpBasicAuth": {
      "id": "credential-id",
      "name": "My API Credentials"
    }
  }
}

Common Credential Types

• httpBasicAuth - Basic authentication
• oAuth2Api - OAuth2
• httpHeaderAuth - Header-based auth
• httpQueryAuth - Query parameter auth

Workflow Metadata

Required Fields

{
  "name": "Workflow Name",
  "nodes": [],
  "connections": {},
  "active": false,
  "settings": {
    "executionOrder": "v1"
  },
  "tags": []
}

Validation Checklist

• All node IDs are unique
• All node names are unique
• All connections reference existing nodes
• Trigger node exists and is properly configured
• Node positions don't overlap
• Required parameters are set for each node
• Credentials are properly referenced
• Error handling is configured where needed
• JSON syntax is valid