Skill: droidhackzor/n8n-session-relay-management-requires-selfbuilt-relay-docker (version 0.1.0)

--- name: n8n description: Manage n8n workflows and automations via API. Use when working with n8n workflows, executions, or automation tasks - listing workflows, activating/deactivating, checking execution status, manually triggering workflows, or debugging automation issues. metadata: {"openclaw":{"emoji":"\u2699\ufe0f","requires":{"env":["N8N_API_KEY","N8N_BASE_URL"]},"primaryEnv":"N8N_API_KEY"}} --- # n8n Workflow Management Comprehensive workflow automation management for n8n platform with creation, testing, execution monitoring, and performance optimization capabilities. ## ⚠️ CRITICAL: Workflow Creation Rules **When creating n8n workflows, ALWAYS:** 1. ✅ **Generate COMPLETE workflows** with all functional nodes 2. ✅ **Include actual HTTP Request nodes** for API calls (ImageFX, Gemini, Veo, Suno, etc.) 3. ✅ **Add Code nodes** for data transformation and logic 4. ✅ **Create proper connections** between all nodes 5. ✅ **Use real node types** (n8n-nodes-base.httpRequest, n8n-nodes-base.code, n8n-nodes-base.set) **NEVER:** - ❌ Create "Setup Instructions" placeholder nodes - ❌ Generate workflows with only TODO comments - ❌ Make incomplete workflows requiring manual node addition - ❌ Use text-only nodes as substitutes for real functionality **Example GOOD workflow:** ``` Manual Trigger → Set Config → HTTP Request (API call) → Code (parse) → Response ``` **Example BAD workflow:** ``` Manual Trigger → Code ("Add HTTP nodes here, configure APIs...") ``` Always build the complete, functional workflow with all necessary nodes configured and connected. ## Setup **Required environment variables:** - `N8N_API_KEY` — Your n8n API key (Settings → API in the n8n UI) - `N8N_BASE_URL` — Your n8n instance URL **Configure credentials via OpenClaw settings:** Add to `~/.config/openclaw/settings.json`: ```json { "skills": { "n8n": { "env": { "N8N_API_KEY": "your-api-key-here", "N8N_BASE_URL": "your-n8n-url-here" } } } } ``` Or set per-session (do **not** persist secrets in shell rc files): ```bash export N8N_API_KEY="your-api-key-here" export N8N_BASE_URL="your-n8n-url-here" ``` **Verify connection:** ```bash python3 scripts/n8n_api.py list-workflows --pretty ``` > **Security note:** Never store API keys in plaintext shell config files (`~/.bashrc`, `~/.zshrc`). Use the OpenClaw settings file or a secure secret manager. ## Quick Reference ### Workflow Management #### List Workflows ```bash python3 scripts/n8n_api.py list-workflows --pretty python3 scripts/n8n_api.py list-workflows --active true --pretty ``` #### Get Workflow Details ```bash python3 scripts/n8n_api.py get-workflow --id <workflow-id> --pretty ``` #### Create Workflows ```bash # From JSON file python3 scripts/n8n_api.py create --from-file workflow.json ``` #### Activate/Deactivate ```bash python3 scripts/n8n_api.py activate --id <workflow-id> python3 scripts/n8n_api.py deactivate --id <workflow-id> ``` ### Testing & Validation #### Validate Workflow Structure ```bash # Validate existing workflow python3 scripts/n8n_tester.py validate --id <workflow-id> # Validate from file python3 scripts/n8n_tester.py validate --file workflow.json --pretty # Generate validation report python3 scripts/n8n_tester.py report --id <workflow-id> ``` #### Dry Run Testing ```bash # Test with data python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data '{"email": "[REDACTED_SECRET]"}' # Test with data file python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json # Full test report (validation + dry run) python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test.json --report ``` #### Test Suite ```bash # Run multiple test cases python3 scripts/n8n_tester.py test-suite --id <workflow-id> --test-suite test-cases.json ``` ### Execution Monitoring #### List Executions ```bash # Recent executions (all workflows) python3 scripts/n8n_api.py list-executions --limit 10 --pretty # Specific workflow executions python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 20 --pretty ``` #### Get Execution Details ```bash python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty ``` #### Manual Execution ```bash # Trigger workflow python3 scripts/n8n_api.py execute --id <workflow-id> # Execute with data python3 scripts/n8n_api.py execute --id <workflow-id> --data '{"key": "value"}' ``` ### Performance Optimization #### Analyze Performance ```bash # Full performance analysis python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --pretty # Analyze specific period python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty ``` #### Get Optimization Suggestions ```bash # Priority-ranked suggestions python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty ``` #### Generate Optimization Report ```bash # Human-readable report with metrics, bottlenecks, and suggestions python3 scripts/n8n_optimizer.py report --id <workflow-id> ``` #### Get Workflow Statistics ```bash # Execution statistics python3 scripts/n8n_api.py stats --id <workflow-id> --days 7 --pretty ``` ## Python API ### Basic Usage ```python from scripts.n8n_api import N8nClient client = N8nClient() # List workflows workflows = client.list_workflows(active=True) # Get workflow workflow = client.get_workflow('workflow-id') # Create workflow new_workflow = client.create_workflow({ 'name': 'My Workflow', 'nodes': [...], 'connections': {...} }) # Activate/deactivate client.activate_workflow('workflow-id') client.deactivate_workflow('workflow-id') # Executions executions = client.list_executions(workflow_id='workflow-id', limit=10) execution = client.get_execution('execution-id') # Execute workflow result = client.execute_workflow('workflow-id', data={'key': 'value'}) ``` ### Validation & Testing ```python from scripts.n8n_api import N8nClient from scripts.n8n_tester import WorkflowTester client = N8nClient() tester = WorkflowTester(client) # Validate workflow validation = tester.validate_workflow(workflow_id='123') print(f"Valid: {validation['valid']}") print(f"Errors: {validation['errors']}") print(f"Warnings: {validation['warnings']}") # Dry run result = tester.dry_run( workflow_id='123', test_data={'email': '[REDACTED_SECRET]'} ) print(f"Status: {result['status']}") # Test suite test_cases = [ {'name': 'Test 1', 'input': {...}, 'expected': {...}}, {'name': 'Test 2', 'input': {...}, 'expected': {...}} ] results = tester.test_suite('123', test_cases) print(f"Passed: {results['passed']}/{results['total_tests']}") # Generate report report = tester.generate_test_report(validation, result) print(report) ``` ### Performance Optimization ```python from scripts.n8n_optimizer import WorkflowOptimizer optimizer = WorkflowOptimizer() # Analyze performance analysis = optimizer.analyze_performance('workflow-id', days=7) print(f"Performance Score: {analysis['performance_score']}/100") print(f"Health: {analysis['execution_metrics']['health']}") # Get suggestions suggestions = optimizer.suggest_optimizations('workflow-id') print(f"Priority Actions: {len(suggestions['priority_actions'])}") print(f"Quick Wins: {len(suggestions['quick_wins'])}") # Generate report report = optimizer.generate_optimization_report(analysis) print(report) ``` ## Common Workflows ### 1. Validate and Test Workflow ```bash # Validate workflow structure python3 scripts/n8n_tester.py validate --id <workflow-id> --pretty # Test with sample data python3 scripts/n8n_tester.py dry-run --id <workflow-id> \ --data '{"email": "[REDACTED_SECRET]", "name": "Test User"}' # If tests pass, activate python3 scripts/n8n_api.py activate --id <workflow-id> ``` ### 2. Debug Failed Workflow ```bash # Check recent executions python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 10 --pretty # Get specific execution details python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty # Validate workflow structure python3 scripts/n8n_tester.py validate --id <workflow-id> # Generate test report python3 scripts/n8n_tester.py report --id <workflow-id> # Check for optimization issues python3 scripts/n8n_optimizer.py report --id <workflow-id> ``` ### 3. Optimize Workflow Performance ```bash # Analyze current performance python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty # Get actionable suggestions python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty # Generate comprehensive report python3 scripts/n8n_optimizer.py report --id <workflow-id> # Review execution statistics python3 scripts/n8n_api.py stats --id <workflow-id> --days 30 --pretty # Test optimizations with dry run python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json ``` ### 4. Monitor Workflow Health ```bash # Check active workflows python3 scripts/n8n_api.py list-workflows --active true --pretty # Review recent execution status python3 scripts/n8n_api.py list-executions --limit 20 --pretty # Get statistics for each critical workflow python3 scripts/n8n_api.py stats --id <workflow-id> --pretty # Generate health reports python3 scripts/n8n_optimizer.py report --id <workflow-id> ``` ## Validation Checks The testing module performs comprehensive validation: ### Structure Validation - ✓ Required fields present (nodes, connections) - ✓ All nodes have names and types - ✓ Connection targets exist - ✓ No disconnected nodes (warning) ### Configuration Validation - ✓ Nodes requiring credentials are configured - ✓ Required parameters are set - ✓ HTTP nodes have URLs - ✓ Webhook nodes have paths - ✓ Email nodes have content ### Flow Validation - ✓ Workflow has trigger nodes - ✓ Proper execution flow - ✓ No circular dependencies - ✓ End nodes identified ## Optimization Analysis The optimizer analyzes multiple dimensions: ### Execution Metrics - Total executions - Success/failure rates - Health status (excellent/good/fair/poor) - Error patterns ### Performance Metrics - Node count and complexity - Connection patterns - Expensive operations (API calls, database queries) - Parallel execution opportunities ### Bottleneck Detection - Sequential expensive operations - High failure rates - Missing error handling - Rate limit issues ### Optimization Opportunities - **Parallel Execution:** Identify nodes that can run concurrently - **Caching:** Suggest caching for repeated API calls - **Batch Processing:** Recommend batching for large datasets - **Error Handling:** Add error recovery mechanisms - **Complexity Reduction:** Split complex workflows - **Timeout Settings:** Configure execution limits ## Performance Scoring Workflows receive a performance score (0-100) based on: - **Success Rate:** Higher is better (50% weight) - **Complexity:** Lower is better (30% weight) - **Bottlenecks:** Fewer is better (critical: -20, high: -10, medium: -5) - **Optimizations:** Implemented best practices (+5 each) Score interpretation: - **90-100:** Excellent - Well-optimized - **70-89:** Good - Minor improvements possible - **50-69:** Fair - Optimization recommended - **0-49:** Poor - Significant issues ## Best Practices ### Development 1. **Plan Structure:** Design workflow nodes and connections before building 2. **Validate First:** Always validate before deployment 3. **Test Thoroughly:** Use dry-run with multiple test cases 4. **Error Handling:** Add error nodes for reliability 5. **Documentation:** Comment complex logic in Code nodes ### Testing 1. **Sample Data:** Create realistic test data files 2. **Edge Cases:** Test boundary conditions and errors 3. **Incremental:** Test each node addition 4. **Regression:** Retest after changes 5. **Production-like:** Use staging environment that mirrors production ### Deployment 1. **Inactive First:** Deploy workflows in inactive state 2. **Gradual Rollout:** Test with limited traffic initially 3. **Monitor Closely:** Watch first executions carefully 4. **Quick Rollback:** Be ready to deactivate if issues arise 5. **Document Changes:** Keep changelog of modifications ### Optimization 1. **Baseline Metrics:** Capture performance before changes 2. **One Change at a Time:** Isolate optimization impacts 3. **Measure Results:** Compare before/after metrics 4. **Regular Reviews:** Schedule monthly optimization reviews 5. **Cost Awareness:** Monitor API usage and execution costs ### Maintenance 1. **Health Checks:** Weekly execution statistics review 2. **Error Analysis:** Investigate failure patterns 3. **Performance Monitoring:** Track execution times 4. **Credential Rotation:** Update credentials regularly 5. **Cleanup:** Archive or delete unused workflows ## Troubleshooting ### Authentication Error ``` Error: N8N_API_KEY not found in environment ``` **Solution:** Set environment variable: ```bash export N8N_API_KEY="your-api-key" ``` ### Connection Error ``` Error: HTTP 401: Unauthorized ``` **Solution:** 1. Verify API key is correct 2. Check N8N_BASE_URL is set correctly 3. Confirm API access is enabled in n8n ### Validation Errors ``` Validation failed: Node missing 'name' field ``` **Solution:** Check workflow JSON structure, ensure all required fields present ### Execution Timeout ``` Status: timeout - Execution did not complete ``` **Solution:** 1. Check workflow for infinite loops 2. Reduce dataset size for testing 3. Optimize expensive operations 4. Set execution timeout in workflow settings ### Rate Limiting ``` Error: HTTP 429: Too Many Requests ``` **Solution:** 1. Add Wait nodes between API calls 2. Implement exponential backoff 3. Use batch processing 4. Check API rate limits ### Missing Credentials ``` Warning: Node 'HTTP_Request' may require credentials ``` **Solution:** 1. Configure credentials in n8n UI 2. Assign credentials to node 3. Test connection before activating ## API Reference For detailed n8n REST API documentation, see [references/api.md](references/api.md) or visit: https://docs.n8n.io/api/ ## References - `references/api.md` — n8n API reference - `scripts/n8n_api.py` — core API client - `scripts/n8n_tester.py` — validation and dry-run testing - `scripts/n8n_optimizer.py` — performance analysis and suggestions

path: references/api.md
content: # n8n API Reference

## Authentication

The n8n API uses API key authentication via the `X-N8N-API-KEY` header.

API keys are managed in the n8n UI:
- Settings → API
- User profile → API

## Base URL

`N8N_BASE_URL`

Default: `${N8N_BASE_URL}$/api/v1`

## Endpoints

### Workflows

#### List Workflows
```
GET /workflows
Query params: ?active=true|false
```

Response:
```json
{
  "data": [
    {
      "id": "123",
      "name": "My Workflow",
      "active": true,
      "createdAt": "2026-01-14T10:00:00.000Z",
      "updatedAt": "2026-01-14T12:00:00.000Z"
    }
  ]
}
```

#### Get Workflow
```
GET /workflows/{id}
```

#### Create Workflow
```
POST /workflows
Body: workflow JSON
```

#### Update Workflow
```
PATCH /workflows/{id}
Body: partial workflow JSON
```

#### Activate/Deactivate
```
PATCH /workflows/{id}
Body: {"active": true|false}
```

#### Delete Workflow
```
DELETE /workflows/{id}
```

### Executions

#### List Executions
```
GET /executions?limit=20&workflowId={id}
```

Response:
```json
{
  "data": [
    {
      "id": "456",
      "finished": true,
      "mode": "trigger",
      "startedAt": "2026-01-14T12:00:00.000Z",
      "stoppedAt": "2026-01-14T12:00:05.000Z",
      "workflowId": "123",
      "status": "success"
    }
  ]
}
```

#### Get Execution
```
GET /executions/{id}
```

#### Delete Execution
```
DELETE /executions/{id}
```

#### Manual Execution
```
POST /workflows/{id}/execute
Body: {"data": {...}}
```

## Common Patterns

### List Active Workflows
```bash
python3 scripts/n8n_api.py list-workflows --active true --pretty
```

### Get Workflow Details
```bash
python3 scripts/n8n_api.py get-workflow --id <workflow-id> --pretty
```

### Activate/Deactivate Workflow
```bash
python3 scripts/n8n_api.py activate --id <workflow-id>
python3 scripts/n8n_api.py deactivate --id <workflow-id>
```

### List Recent Executions
```bash
python3 scripts/n8n_api.py list-executions --limit 10 --pretty
```

### Manually Execute Workflow
```bash
python3 scripts/n8n_api.py execute --id <workflow-id>
```

With data:
```bash
python3 scripts/n8n_api.py execute --id <workflow-id> --data '{"key": "value"}'
```

## Error Handling

HTTP status codes:
- `200` - Success
- `400` - Bad request
- `401` - Unauthorized (invalid API key)
- `404` - Not found
- `500` - Server error

## Environment Variables

Required:
- `N8N_API_KEY` - n8n API key
- `N8N_BASE_URL` - Base URL 

path: scripts/n8n_api.py
content: #!/usr/bin/env python3
"""
n8n API client for Clawdbot
Manages workflows, executions, and credentials via n8n REST API
"""

import os
import sys
import json
import argparse
import requests
from pathlib import Path
from typing import Optional, Dict, Any, List


class N8nClient:
    """n8n API client"""
    
    def __init__(self, base_url: str = None, api_key: str = None):
        self.base_url = base_url or os.getenv('N8N_BASE_URL')
        self.[REDACTED_SECRET] or os.getenv('N8N_API_KEY')
        
        if not self.api_key:
            raise ValueError("N8N_API_KEY not found in environment")
        
        self.session = requests.Session()
        self.session.headers.update({
            'X-N8N-API-KEY': self.api_key,
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        })
    
    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        """Make API request"""
        url = f"{self.base_url}/api/v1/{endpoint.lstrip('/')}"
        response = self.session.request(method, url, **kwargs)
        
        try:
            response.raise_for_status()
            return response.json() if response.content else {}
        except requests.exceptions.HTTPError as e:
            error_msg = f"HTTP {response.status_code}: {response.text}"
            raise Exception(error_msg) from e
    
    # Workflows
    def list_workflows(self, active: bool = None) -> List[Dict]:
        """List all workflows"""
        params = {}
        if active is not None:
            params['active'] = str(active).lower()
        return self._request('GET', 'workflows', params=params)
    
    def get_workflow(self, workflow_id: str) -> Dict:
        """Get workflow details"""
        return self._request('GET', f'workflows/{workflow_id}')
    
    def create_workflow(self, workflow_data: Dict) -> Dict:
        """Create new workflow"""
        # Remove read-only fields that n8n API doesn't accept on create
        clean_data = workflow_data.copy()
        clean_data.pop('active', None)
        clean_data.pop('id', None)
        return self._request('POST', 'workflows', json=clean_data)
    
    def update_workflow(self, workflow_id: str, workflow_data: Dict) -> Dict:
        """Update existing workflow"""
        return self._request('PATCH', f'workflows/{workflow_id}', json=workflow_data)
    
    def delete_workflow(self, workflow_id: str) -> Dict:
        """Delete workflow"""
        return self._request('DELETE', f'workflows/{workflow_id}')
    
    def activate_workflow(self, workflow_id: str) -> Dict:
        """Activate workflow"""
        return self._request('PATCH', f'workflows/{workflow_id}', json={'active': True})
    
    def deactivate_workflow(self, workflow_id: str) -> Dict:
        """Deactivate workflow"""
        return self._request('PATCH', f'workflows/{workflow_id}', json={'active': False})
    
    # Executions
    def list_executions(self, workflow_id: str = None, limit: int = 20) -> List[Dict]:
        """List workflow executions"""
        params = {'limit': limit}
        if workflow_id:
            params['workflowId'] = workflow_id
        return self._request('GET', 'executions', params=params)
    
    def get_execution(self, execution_id: str) -> Dict:
        """Get execution details"""
        return self._request('GET', f'executions/{execution_id}')
    
    def delete_execution(self, execution_id: str) -> Dict:
        """Delete execution"""
        return self._request('DELETE', f'executions/{execution_id}')
    
    # Manual execution
    def execute_workflow(self, workflow_id: str, data: Dict = None) -> Dict:
        """Manually trigger workflow execution"""
        payload = {'workflowId': workflow_id}
        if data:
            payload['data'] = data
        return self._request('POST', f'workflows/{workflow_id}/execute', json=payload)
    
    # Testing & Validation
    def validate_workflow(self, workflow_data: Dict) -> Dict:
        """Validate workflow structure and configuration"""
        issues = {
            'errors': [],
            'warnings': [],
            'valid': True
        }
        
        # Check required fields
        if 'nodes' not in workflow_data:
            issues['errors'].append("Missing 'nodes' field")
            issues['valid'] = False
            return issues
        
        nodes = workflow_data.get('nodes', [])
        connections = workflow_data.get('connections', {})
        
        # Validate nodes
        node_names = set()
        for node in nodes:
            if 'name' not in node:
                issues['errors'].append("Node missing 'name' field")
                issues['valid'] = False
            else:
                node_names.add(node['name'])
            
            if 'type' not in node:
                issues['errors'].append(f"Node '{node.get('name', 'unknown')}' missing 'type' field")
                issues['valid'] = False
            
            # Check for required credentials
            if node.get('type', '').startswith('n8n-nodes-base'):
                credentials = node.get('credentials', {})
                if not credentials and node['type'] not in ['n8n-nodes-base.start', 'n8n-nodes-base.set']:
                    issues['warnings'].append(f"Node '{node['name']}' may require credentials")
        
        # Validate connections
        for source_node, targets in connections.items():
            if source_node not in node_names:
                issues['errors'].append(f"Connection references non-existent source node: {source_node}")
                issues['valid'] = False
            
            for output_type, output_connections in targets.items():
                for conn_list in output_connections:
                    for conn in conn_list:
                        target_node = conn.get('node')
                        if target_node and target_node not in node_names:
                            issues['errors'].append(f"Connection references non-existent target node: {target_node}")
                            issues['valid'] = False
        
        # Check for disconnected nodes
        connected_nodes = set(connections.keys())
        for targets in connections.values():
            for output_connections in targets.values():
                for conn_list in output_connections:
                    for conn in conn_list:
                        connected_nodes.add(conn.get('node'))
        
        disconnected = node_names - connected_nodes
        if disconnected and len(nodes) > 1:
            for node in disconnected:
                issues['warnings'].append(f"Node '{node}' appears to be disconnected")
        
        return issues
    
    def dry_run_workflow(self, workflow_id: str, test_data: Dict = None) -> Dict:
        """Test workflow execution with mock data (creates temp execution)"""
        # Execute workflow with test data and return results
        result = self.execute_workflow(workflow_id, data=test_data)
        return {
            'execution_id': result.get('data', {}).get('executionId'),
            'status': 'initiated',
            'test_data': test_data
        }
    
    # Optimization & Analytics
    def get_workflow_statistics(self, workflow_id: str, days: int = 7) -> Dict:
        """Get workflow execution statistics"""
        executions = self.list_executions(workflow_id=workflow_id, limit=100)
        
        stats = {
            'total_executions': len(executions),
            'successful': 0,
            'failed': 0,
            'execution_times': [],
            'error_patterns': {}
        }
        
        for execution in executions:
            status = execution.get('finished')
            if status:
                stats['successful'] += 1
            else:
                stats['failed'] += 1
                error = execution.get('data', {}).get('resultData', {}).get('error', {}).get('message', 'Unknown error')
                stats['error_patterns'][error] = stats['error_patterns'].get(error, 0) + 1
            
            # Execution time
            start = execution.get('startedAt')
            stop = execution.get('stoppedAt')
            if start and stop:
                # Calculate duration (simplified)
                stats['execution_times'].append({'start': start, 'stop': stop})
        
        # Calculate success rate
        if stats['total_executions'] > 0:
            stats['success_rate'] = (stats['successful'] / stats['total_executions']) * 100
        else:
            stats['success_rate'] = 0
        
        return stats
    
    def analyze_workflow_performance(self, workflow_id: str) -> Dict:
        """Analyze workflow performance and identify bottlenecks"""
        workflow = self.get_workflow(workflow_id)
        executions = self.list_executions(workflow_id=workflow_id, limit=10)
        
        analysis = {
            'node_count': len(workflow.get('nodes', [])),
            'connection_count': sum(len(conns) for conns in workflow.get('connections', {}).values()),
            'parallel_opportunities': [],
            'bottlenecks': [],
            'optimization_suggestions': []
        }
        
        # Analyze node structure for parallel opportunities
        nodes = workflow.get('nodes', [])
        connections = workflow.get('connections', {})
        
        # Find nodes that could be parallelized
        for node in nodes:
            node_name = node['name']
            if node_name in connections:
                outputs = connections[node_name]
                # If node has multiple outputs, suggest parallel execution
                total_connections = sum(len(conn_list) for output in outputs.values() for conn_list in output)
                if total_connections > 1:
                    analysis['parallel_opportunities'].append({
                        'node': node_name,
                        'connection_count': total_connections,
                        'suggestion': 'Consider using Split In Batches for parallel processing'
                    })
        
        # Analyze execution patterns
        if executions:
            analysis['optimization_suggestions'].append({
                'type': 'monitoring',
                'suggestion': 'Enable execution data retention for better debugging'
            })
        
        # Check for common anti-patterns
        for node in nodes:
            if node.get('type') == 'n8n-nodes-base.httpRequest':
                analysis['optimization_suggestions'].append({
                    'type': 'caching',
                    'node': node['name'],
                    'suggestion': 'Consider caching HTTP responses for frequently accessed data'
                })
        
        return analysis


def main():
    parser = argparse.ArgumentParser(description='n8n API Client')
    parser.add_argument('action', choices=[
        'list-workflows', 'get-workflow', 'create', 'activate', 'deactivate',
        'list-executions', 'get-execution', 'execute', 'validate', 'stats'
    ])
    parser.add_argument('--id', help='Workflow or execution ID')
    parser.add_argument('--active', type=lambda x: x.lower() == 'true', help='Filter by active status')
    parser.add_argument('--limit', type=int, default=20, help='Limit results')
    parser.add_argument('--data', help='JSON data for execution')
    parser.add_argument('--from-file', help='Create workflow from JSON file')
    parser.add_argument('--from-template', help='Create workflow from template name')
    parser.add_argument('--days', type=int, default=7, help='Days for statistics')
    parser.add_argument('--pretty', action='store_true', help='Pretty print JSON output')
    
    args = parser.parse_args()
    
    try:
        client = N8nClient()
        result = None
        
        if args.action == 'list-workflows':
            result = client.list_workflows(active=args.active)
        elif args.action == 'get-workflow':
            if not args.id:
                raise ValueError("--id required for get-workflow")
            result = client.get_workflow(args.id)
        elif args.action == 'create':
            if args.from_file:
                with open(args.from_file, 'r') as f:
                    workflow_data = json.load(f)
                result = client.create_workflow(workflow_data)
            elif args.from_template:
                # Load template
                template_path = Path(__file__).parent.parent / 'templates' / f'{args.from_template}.json'
                if not template_path.exists():
                    raise ValueError(f"Template not found: {args.from_template}")
                with open(template_path, 'r') as f:
                    workflow_data = json.load(f)
                result = client.create_workflow(workflow_data)
            else:
                raise ValueError("--from-file or --from-template required for create")
        elif args.action == 'activate':
            if not args.id:
                raise ValueError("--id required for activate")
            result = client.activate_workflow(args.id)
        elif args.action == 'deactivate':
            if not args.id:
                raise ValueError("--id required for deactivate")
            result = client.deactivate_workflow(args.id)
        elif args.action == 'list-executions':
            result = client.list_executions(workflow_id=args.id, limit=args.limit)
        elif args.action == 'get-execution':
            if not args.id:
                raise ValueError("--id required for get-execution")
            result = client.get_execution(args.id)
        elif args.action == 'execute':
            if not args.id:
                raise ValueError("--id required for execute")
            data = json.loads(args.data) if args.data else None
            result = client.execute_workflow(args.id, data=data)
        elif args.action == 'validate':
            if args.from_file:
                with open(args.from_file, 'r') as f:
                    workflow_data = json.load(f)
            elif args.id:
                workflow_data = client.get_workflow(args.id)
            else:
                raise ValueError("--id or --from-file required for validate")
            result = client.validate_workflow(workflow_data)
        elif args.action == 'stats':
            if not args.id:
                raise ValueError("--id required for stats")
            result = client.get_workflow_statistics(args.id, days=args.days)
        
        # Output
        if args.pretty:
            print(json.dumps(result, indent=2))
        else:
            print(json.dumps(result))
            
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == '__main__':
    main()


path: scripts/n8n_tester.py
content: #!/usr/bin/env python3
"""
n8n Workflow Testing & Validation
Test workflows before activation with validation and dry-runs
"""

import sys
import json
import argparse
import time
from pathlib import Path
from typing import Dict, List, Any

# Import N8nClient - handle both direct and module imports
try:
    from n8n_api import N8nClient
except ImportError:
    from scripts.n8n_api import N8nClient


class WorkflowTester:
    """Workflow testing and validation"""
    
    def __init__(self, client: N8nClient = None):
        self.client = client  # Only initialize when needed
    
    def validate_workflow(self, workflow_id: str = None, workflow_file: str = None) -> Dict:
        """Validate workflow structure and configuration"""
        if workflow_id:
            if not self.client:
                self.client = N8nClient()
            workflow_data = self.client.get_workflow(workflow_id)
        elif workflow_file:
            with open(workflow_file, 'r') as f:
                workflow_data = json.load(f)
        else:
            raise ValueError("Either workflow_id or workflow_file required")
        
        # Perform validation - use standalone validation for files
        validation = self._perform_validation(workflow_data)
        
        # Additional validation checks
        self._check_credentials(workflow_data, validation)
        self._check_node_configurations(workflow_data, validation)
        self._check_execution_flow(workflow_data, validation)
        
        return validation
    
    def _perform_validation(self, workflow_data: Dict) -> Dict:
        """Perform standalone workflow validation"""
        issues = {
            'errors': [],
            'warnings': [],
            'valid': True
        }
        
        # Check required fields
        if 'nodes' not in workflow_data:
            issues['errors'].append("Missing 'nodes' field")
            issues['valid'] = False
            return issues
        
        nodes = workflow_data.get('nodes', [])
        connections = workflow_data.get('connections', {})
        
        # Validate nodes
        node_names = set()
        for node in nodes:
            if 'name' not in node:
                issues['errors'].append("Node missing 'name' field")
                issues['valid'] = False
            else:
                node_names.add(node['name'])
            
            if 'type' not in node:
                issues['errors'].append(f"Node '{node.get('name', 'unknown')}' missing 'type' field")
                issues['valid'] = False
        
        # Validate connections
        for source_node, targets in connections.items():
            if source_node not in node_names:
                issues['errors'].append(f"Connection references non-existent source node: {source_node}")
                issues['valid'] = False
            
            for output_type, output_connections in targets.items():
                for conn_list in output_connections:
                    for conn in conn_list:
                        target_node = conn.get('node')
                        if target_node and target_node not in node_names:
                            issues['errors'].append(f"Connection references non-existent target node: {target_node}")
                            issues['valid'] = False
        
        # Check for disconnected nodes
        connected_nodes = set(connections.keys())
        for targets in connections.values():
            for output_connections in targets.values():
                for conn_list in output_connections:
                    for conn in conn_list:
                        connected_nodes.add(conn.get('node'))
        
        disconnected = node_names - connected_nodes
        if disconnected and len(nodes) > 1:
            for node in disconnected:
                issues['warnings'].append(f"Node '{node}' appears to be disconnected")
        
        return issues
    
    def _check_credentials(self, workflow_data: Dict, validation: Dict):
        """Check for missing or invalid credentials"""
        nodes = workflow_data.get('nodes', [])
        
        # Nodes that typically require credentials
        credential_nodes = [
            'n8n-nodes-base.httpRequest',
            'n8n-nodes-base.googleSheets',
            'n8n-nodes-base.slack',
            'n8n-nodes-base.twitter',
            'n8n-nodes-base.stripe',
            'n8n-nodes-base.postgres',
            'n8n-nodes-base.mysql',
            'n8n-nodes-base.emailSend'
        ]
        
        for node in nodes:
            node_type = node.get('type', '')
            if node_type in credential_nodes:
                credentials = node.get('credentials', {})
                if not credentials:
                    validation['warnings'].append(
                        f"Node '{node['name']}' ({node_type}) likely requires credentials"
                    )
    
    def _check_node_configurations(self, workflow_data: Dict, validation: Dict):
        """Check for invalid node configurations"""
        nodes = workflow_data.get('nodes', [])
        
        for node in nodes:
            node_type = node.get('type', '')
            parameters = node.get('parameters', {})
            
            # Check HTTP Request nodes
            if node_type == 'n8n-nodes-base.httpRequest':
                if not parameters.get('url'):
                    validation['errors'].append(
                        f"Node '{node['name']}' missing required URL parameter"
                    )
                    validation['valid'] = False
            
            # Check webhook nodes
            elif node_type == 'n8n-nodes-base.webhook':
                if not parameters.get('path'):
                    validation['errors'].append(
                        f"Node '{node['name']}' missing required path parameter"
                    )
                    validation['valid'] = False
            
            # Check email nodes
            elif node_type == 'n8n-nodes-base.emailSend':
                if not parameters.get('subject') and not parameters.get('text'):
                    validation['warnings'].append(
                        f"Node '{node['name']}' missing subject or text"
                    )
    
    def _check_execution_flow(self, workflow_data: Dict, validation: Dict):
        """Check workflow execution flow for issues"""
        nodes = workflow_data.get('nodes', [])
        connections = workflow_data.get('connections', {})
        
        # Check for trigger nodes
        trigger_types = [
            'n8n-nodes-base.webhook',
            'n8n-nodes-base.scheduleTrigger',
            'n8n-nodes-base.manualTrigger',
            'n8n-nodes-base.start'
        ]
        
        has_trigger = any(node.get('type') in trigger_types for node in nodes)
        if not has_trigger and len(nodes) > 0:
            validation['warnings'].append(
                "Workflow has no trigger node. It can only be executed manually."
            )
        
        # Check for end nodes (nodes with no outgoing connections)
        node_names = {node['name'] for node in nodes}
        connected_as_source = set(connections.keys())
        end_nodes = node_names - connected_as_source
        
        if not end_nodes and len(nodes) > 1:
            validation['warnings'].append(
                "Workflow has no end nodes. This may indicate circular dependencies."
            )
    
    def dry_run(self, workflow_id: str, test_data: Dict = None, test_data_file: str = None) -> Dict:
        """Execute workflow with test data"""
        # Load test data if from file
        if test_data_file:
            with open(test_data_file, 'r') as f:
                test_data = json.load(f)
        
        print(f"Running workflow {workflow_id} with test data...")
        
        # Execute workflow
        execution_result = self.client.execute_workflow(workflow_id, data=test_data)
        execution_id = execution_result.get('data', {}).get('executionId')
        
        if not execution_id:
            return {
                'status': 'failed',
                'error': 'No execution ID returned',
                'result': execution_result
            }
        
        print(f"Execution started: {execution_id}")
        print("Waiting for execution to complete...")
        
        # Poll for execution completion
        max_attempts = 30
        attempt = 0
        
        while attempt < max_attempts:
            time.sleep(2)
            attempt += 1
            
            try:
                execution = self.client.get_execution(execution_id)
                finished = execution.get('finished', False)
                
                if finished:
                    # Execution completed
                    success = execution.get('data', {}).get('resultData', {}).get('error') is None
                    
                    result = {
                        'status': 'success' if success else 'failed',
                        'execution_id': execution_id,
                        'finished': True,
                        'started_at': execution.get('startedAt'),
                        'stopped_at': execution.get('stoppedAt'),
                        'mode': execution.get('mode'),
                        'data': execution.get('data', {})
                    }
                    
                    if not success:
                        error_data = execution.get('data', {}).get('resultData', {}).get('error', {})
                        result['error'] = {
                            'message': error_data.get('message'),
                            'description': error_data.get('description')
                        }
                    
                    return result
            except Exception as e:
                print(f"Error checking execution status: {e}")
                continue
        
        return {
            'status': 'timeout',
            'execution_id': execution_id,
            'message': 'Execution did not complete within expected time'
        }
    
    def test_suite(self, workflow_id: str, test_cases: List[Dict]) -> Dict:
        """Run multiple test cases against workflow"""
        results = {
            'workflow_id': workflow_id,
            'total_tests': len(test_cases),
            'passed': 0,
            'failed': 0,
            'test_results': []
        }
        
        for i, test_case in enumerate(test_cases, 1):
            print(f"\nRunning test case {i}/{len(test_cases)}: {test_case.get('name', 'Unnamed')}")
            
            test_data = test_case.get('input', {})
            expected_output = test_case.get('expected', {})
            
            # Run test
            result = self.dry_run(workflow_id, test_data=test_data)
            
            # Check result
            passed = result.get('status') == 'success'
            
            test_result = {
                'test_name': test_case.get('name'),
                'passed': passed,
                'input': test_data,
                'output': result,
                'expected': expected_output
            }
            
            results['test_results'].append(test_result)
            
            if passed:
                results['passed'] += 1
                print(f"✓ Test passed")
            else:
                results['failed'] += 1
                print(f"✗ Test failed: {result.get('error', 'Unknown error')}")
        
        return results
    
    def generate_test_report(self, validation: Dict, dry_run: Dict = None) -> str:
        """Generate human-readable test report"""
        report = []
        report.append("=" * 60)
        report.append("n8n Workflow Test Report")
        report.append("=" * 60)
        
        # Validation results
        report.append("\n## Validation Results")
        report.append(f"Status: {'✓ VALID' if validation['valid'] else '✗ INVALID'}")
        
        if validation['errors']:
            report.append(f"\nErrors ({len(validation['errors'])}):")
            for error in validation['errors']:
                report.append(f"  ✗ {error}")
        
        if validation['warnings']:
            report.append(f"\nWarnings ({len(validation['warnings'])}):")
            for warning in validation['warnings']:
                report.append(f"  ⚠ {warning}")
        
        if not validation['errors'] and not validation['warnings']:
            report.append("\n✓ No issues found")
        
        # Dry run results
        if dry_run:
            report.append("\n## Dry Run Results")
            report.append(f"Status: {dry_run.get('status', 'unknown').upper()}")
            report.append(f"Execution ID: {dry_run.get('execution_id', 'N/A')}")
            
            if dry_run.get('started_at'):
                report.append(f"Started: {dry_run['started_at']}")
            if dry_run.get('stopped_at'):
                report.append(f"Stopped: {dry_run['stopped_at']}")
            
            if dry_run.get('error'):
                report.append(f"\nError: {dry_run['error'].get('message', 'Unknown error')}")
                if dry_run['error'].get('description'):
                    report.append(f"Description: {dry_run['error']['description']}")
        
        report.append("\n" + "=" * 60)
        
        return "\n".join(report)


def main():
    parser = argparse.ArgumentParser(description='n8n Workflow Testing & Validation')
    parser.add_argument('action', choices=['validate', 'dry-run', 'test-suite', 'report'])
    parser.add_argument('--id', help='Workflow ID')
    parser.add_argument('--file', help='Workflow JSON file')
    parser.add_argument('--data', help='Test data JSON string')
    parser.add_argument('--data-file', help='Test data JSON file')
    parser.add_argument('--test-suite', help='Test suite JSON file')
    parser.add_argument('--pretty', action='store_true', help='Pretty print output')
    parser.add_argument('--report', action='store_true', help='Generate human-readable report')
    
    args = parser.parse_args()
    
    try:
        tester = WorkflowTester()
        result = None
        
        if args.action == 'validate':
            result = tester.validate_workflow(workflow_id=args.id, workflow_file=args.file)
            
            if args.report:
                print(tester.generate_test_report(result))
            else:
                print(json.dumps(result, indent=2 if args.pretty else None))
        
        elif args.action == 'dry-run':
            if not args.id:
                raise ValueError("--id required for dry-run")
            
            test_data = None
            if args.data:
                test_data = json.loads(args.data)
            
            result = tester.dry_run(
                workflow_id=args.id,
                test_data=test_data,
                test_data_file=args.data_file
            )
            
            if args.report:
                validation = tester.validate_workflow(workflow_id=args.id)
                print(tester.generate_test_report(validation, result))
            else:
                print(json.dumps(result, indent=2 if args.pretty else None))
        
        elif args.action == 'test-suite':
            if not args.id:
                raise ValueError("--id required for test-suite")
            if not args.test_suite:
                raise ValueError("--test-suite required for test-suite")
            
            with open(args.test_suite, 'r') as f:
                test_cases = json.load(f)
            
            result = tester.test_suite(args.id, test_cases)
            print(json.dumps(result, indent=2 if args.pretty else None))
        
        elif args.action == 'report':
            if not args.id:
                raise ValueError("--id required for report")
            
            validation = tester.validate_workflow(workflow_id=args.id)
            print(tester.generate_test_report(validation))
        
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == '__main__':
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)