n8n-workflow-builder

name	n8n-workflow-builder
description	Expert n8n workflow automation covering self-hosted deployment, node configuration, trigger types, webhook handling, data transformation with expressions, error handling patterns, credential management, sub-workflow composition, database operations, API integration, and production monitoring for reliable automation pipelines. Use when the user asks about n8n workflow builder, n8n workflow builder best practices, or needs guidance on n8n workflow builder implementation. Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"automation shell-scripting guide","category":"software-engineering","subcategory":"developer-tools","depends":"","disclaimer":"none","difficulty":"intermediate"}

n8n Workflow Builder

You are an expert in n8n workflow automation. You guide teams through building, deploying, and maintaining production-grade automation workflows using n8n's visual editor and code nodes, with emphasis on self-hosted reliability, error handling, and scalable workflow design.

Core Concepts

n8n Architecture

n8n Components:
├── Workflow Engine
│   ├── Executes node graphs sequentially or in parallel
│   ├── Handles data passing between nodes (items/JSON)
│   ├── Manages execution state and history
│   └── Supports webhook, cron, and event-based triggers
│
├── Node Types
│   ├── Trigger nodes (start workflows)
│   ├── Action nodes (perform operations)
│   ├── Logic nodes (IF, Switch, Merge, Split)
│   ├── Code node (custom JavaScript/Python)
│   ├── Sub-workflow node (compose workflows)
│   └── Community nodes (extend via npm packages)
│
├── Data Model
│   ├── Each node outputs an array of items
│   ├── Each item has JSON payload and optional binary data
│   └── Expressions access data: {{ $json.fieldName }}
│
└── Deployment
    ├── Self-hosted (Docker, Kubernetes) or n8n Cloud
    ├── Queue mode for horizontal scaling
    └── PostgreSQL for production (SQLite for dev)

Trigger Types

Webhook Trigger

{
  "name": "Receive Order Webhook",
  "type": "n8n-nodes-base.webhook",
  "parameters": {
    "path": "incoming-order",
    "httpMethod": "POST",
    "authentication": "headerAuth",
    "responseMode": "responseNode"
  }
}

Common Trigger Patterns

Trigger	Use Case	Configuration
Webhook	Receive external events	Path, auth, response mode
Schedule	Periodic tasks	Cron expression or interval
Email Trigger (IMAP)	Process incoming emails	Mailbox, folder, filters
Database Trigger	React to data changes	Poll interval, query
n8n Trigger	Called by other workflows	Sub-workflow invocation
Chat Trigger	Conversational AI workflows	Message input, memory

Data Transformation

Expression Syntax

n8n Expression Reference:
├── Access current item
│   ├── {{ $json.fieldName }}
│   ├── {{ $json["field with spaces"] }}
│   └── {{ $json.nested.field }}
│
├── Access items from other nodes
│   ├── {{ $('Node Name').item.json.field }}
│   ├── {{ $('Node Name').first().json.field }}
│   └── {{ $('Node Name').all()[0].json.field }}
│
├── Built-in variables
│   ├── {{ $now }}, {{ $today }}, {{ $runIndex }}, {{ $itemIndex }}
│   ├── {{ $workflow.id }}, {{ $workflow.name }}, {{ $execution.id }}
│
├── String methods
│   ├── {{ $json.name.toUpperCase() }}
│   ├── {{ $json.email.split('@')[1] }}
│   └── {{ $json.text.replace(/\s+/g, '-') }}
│
├── Date methods
│   ├── {{ $now.format('yyyy-MM-dd') }}
│   ├── {{ $now.minus(7, 'days').toISO() }}
│   └── {{ DateTime.fromISO($json.date).toFormat('dd/MM/yyyy') }}
│
└── Conditional expressions
    ├── {{ $json.status === 'active' ? 'Yes' : 'No' }}
    └── {{ $json.name || 'Unknown' }}

Code Node Patterns

// Code Node: Transform and enrich data (Run Once for All Items)
const items = $input.all();
const results = [];

for (const item of items) {
  const data = item.json;
  const fullName = `${data.first_name} ${data.last_name}`.trim();
  let tier = 'standard';
  if (data.total_spend > 10000) tier = 'enterprise';
  else if (data.total_spend > 1000) tier = 'premium';

  const daysSinceLastOrder = Math.floor(
    (Date.now() - new Date(data.last_order_date).getTime()) / 86400000
  );

  results.push({
    json: { ...data, full_name: fullName, tier, days_since_last_order: daysSinceLastOrder,
            is_at_risk: daysSinceLastOrder > 90, processed_at: new Date().toISOString() }
  });
}
return results;

// Code Node: Aggregate and summarize
const data = $input.all().map(i => i.json);
const grouped = {};
for (const record of data) {
  const key = record.category;
  if (!grouped[key]) grouped[key] = { count: 0, total: 0, items: [] };
  grouped[key].count++;
  grouped[key].total += record.amount;
  grouped[key].items.push(record.id);
}

return Object.entries(grouped).map(([category, stats]) => ({
  json: { category, count: stats.count, total: stats.total,
          average: Math.round(stats.total / stats.count * 100) / 100 }
}));

Error Handling

Error Handling Strategy

├── Node-level: Continue on Fail
│   ├── Downstream nodes receive error in $json.error
│   ├── Use IF node to branch on error vs success
│   └── Good for: non-critical steps, fallback logic
│
├── Workflow-level: Error Workflow
│   ├── Configure in Workflow Settings -> Error Workflow
│   ├── Separate workflow receives error details
│   └── Good for: centralized alerting, logging
│
└── Retry logic
    ├── Built-in retry on node settings (1-3 retries)
    └── Custom retry with Loop and Wait nodes

Error Notification Workflow

{
  "name": "Error Handler - Send Alert",
  "nodes": [
    {
      "name": "Error Trigger",
      "type": "n8n-nodes-base.errorTrigger"
    },
    {
      "name": "Format Error",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const error = $input.first().json;\nreturn [{ json: { message: `Workflow: ${error.workflow.name}\\nNode: ${error.execution.lastNodeExecuted}\\nError: ${error.execution.error.message}\\nExecution: ${error.execution.id}`, severity: 'error' } }];"
      }
    },
    {
      "name": "Send Slack Alert",
      "type": "n8n-nodes-base.slack",
      "parameters": { "channel": "#automation-alerts",   
    
  

Workflow Composition

Sub-Workflow Pattern

Sub-Workflow Architecture:
├── Parent workflow handles orchestration
│   ├── Calls sub-workflows via "Execute Workflow" node
│   ├── Passes data as input items
│   └── Receives results from sub-workflow output
│
├── Sub-workflow design rules
│   ├── Single responsibility per sub-workflow
│   ├── Handle own errors (do not leak to parent)
│   └── Reusable across multiple parents
│
└── Example: Customer Onboarding
    ├── [Sub] Validate Customer Data
    ├── [Sub] Create CRM Record
    ├── [Sub] Send Welcome Email
    └── [Sub] Notify Sales Team

Database Operations

Batch Processing Pattern

// Code Node: Batch items for database insertion
const items = $input.all();
const batchSize = 100;
const batches = [];

for (let i = 0; i < items.length; i += batchSize) {
  const batch = items.slice(i, i + batchSize);
  batches.push({
    json: { batch_index: Math.floor(i / batchSize),
            records: batch.map(item => item.json), count: batch.length }
  });
}
return batches;

Upsert Pattern

{
  "name": "Upsert Contacts",
  "type": "n8n-nodes-base.postgres",
  "parameters": {
    "operation": "executeQuery",
    "query": "INSERT INTO contacts (email, name, company, updated_at) VALUES ($1, $2, $3, NOW()) ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name, company = EXCLUDED.company, updated_at = NOW()",
    "options": { "queryParams": "={{ $json.email }}, ={{ $json.name }}, ={{ $json.company }}" }
  }
}

Self-Hosted Deployment

Docker Compose Production Setup

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports: ["5678:5678"]
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=${N8N_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD}
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=[reference URL]
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=${DB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168
      - N8N_METRICS=true
      - QUEUE_BULL_REDIS_HOST=redis
    volumes: [n8n_data:/home/node/.n8n]
    depends_on: [postgres, redis]

  postgres:
    image: postgres:16-alpine
    restart: 
    
       
       
       
     []

  
     
     
     []

  
     
     
     
    
       
       
       
       
       
       
       
     [, ]


  
  
  

Queue Mode for Scaling

Main process: Serves UI/API, receives webhooks, enqueues jobs to Redis
Worker processes: Dequeue and execute, scale horizontally, stateless
Configuration: EXECUTIONS_MODE=queue, workers run "n8n worker" command

Credential Management

├── Storage: Encrypted at rest, key from N8N_ENCRYPTION_KEY env var
│   Back up encryption key securely (loss = credentials lost)
├── Access Control: Scoped to owner, sharable, use service accounts
└── Best Practices: One credential per service per environment,
    prefer OAuth2, test before activating, audit via execution logs

Monitoring and Observability

├── Prometheus Metrics: N8N_METRICS=true, endpoint /metrics
│   n8n_workflow_executions_total, n8n_workflow_execution_duration_seconds
├── Execution Pruning: EXECUTIONS_DATA_PRUNE=true, MAX_AGE=168 hours
├── Alerting: Error workflow -> Slack, queue depth, duration spikes
└── Health: GET /healthz for liveness probes

Production Checklist

• Deploy with PostgreSQL (not SQLite)
• Set N8N_ENCRYPTION_KEY and back it up securely
• Enable basic auth or SSO for UI access
• Configure WEBHOOK_URL to match your public domain
• Set up error workflow for centralized failure alerting
• Enable execution data pruning to manage storage
• Use queue mode with Redis for multi-worker scaling
• Implement sub-workflows for reusable logic
• Add retry settings on nodes calling external APIs
• Enable Prometheus metrics for monitoring
• Document each workflow's purpose and trigger conditions

When to Use

Use this skill when:

• Designing or implementing n8n workflow builder solutions
• Reviewing or improving existing n8n workflow builder approaches
• Making architectural or implementation decisions about n8n workflow builder
• Learning n8n workflow builder patterns and best practices
• Troubleshooting n8n workflow builder-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# N8n Workflow Builder Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement n8n workflow builder for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended n8n workflow builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When n8n workflow builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities