From 9edc699a8fb22bffbba6cef1585b5edca2ad4f15 Mon Sep 17 00:00:00 2001 From: mrsaifullah52 Date: Mon, 17 Nov 2025 14:21:35 +0500 Subject: [PATCH] feat(n8n-expert): add shared resources for workflow creation - Add n8n-helpers.md with node creation guidelines - Add n8n-templates.yaml with 8 reusable workflow templates - Add platform-mappings.yaml for Zapier/Make/HubSpot/Power Automate migration - Include connection patterns and best practices --- .../n8n-expert/_shared/n8n-helpers.md | 201 ++++++++++++ .../n8n-expert/_shared/n8n-templates.yaml | 299 ++++++++++++++++++ .../n8n-expert/_shared/platform-mappings.yaml | 282 +++++++++++++++++ 3 files changed, 782 insertions(+) create mode 100644 src/modules/bmm/workflows/n8n-expert/_shared/n8n-helpers.md create mode 100644 src/modules/bmm/workflows/n8n-expert/_shared/n8n-templates.yaml create mode 100644 src/modules/bmm/workflows/n8n-expert/_shared/platform-mappings.yaml diff --git a/src/modules/bmm/workflows/n8n-expert/_shared/n8n-helpers.md b/src/modules/bmm/workflows/n8n-expert/_shared/n8n-helpers.md new file mode 100644 index 00000000..d46aa1d6 --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/_shared/n8n-helpers.md @@ -0,0 +1,201 @@ +# n8n Workflow Helpers + +## Node Creation Guidelines + +### Basic Node Structure + +```json +{ + "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 + +```json +{ + "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 + +```json +{ + "name": "Error Handler", + "type": "n8n-nodes-base.errorTrigger", + "parameters": { + "errorWorkflows": ["workflow-id"] + } +} +``` + +### Retry Configuration + +```json +{ + "retryOnFail": true, + "maxTries": 3, + "waitBetweenTries": 1000 +} +``` + +## Data Transformation Patterns + +### Using Set Node + +```json +{ + "name": "Transform Data", + "type": "n8n-nodes-base.set", + "parameters": { + "mode": "manual", + "values": { + "string": [ + { + "name": "outputField", + "value": "={{ $json.inputField }}" + } + ] + } + } +} +``` + +### Using Code Node + +```json +{ + "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 + +```json +{ + "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 + +```json +{ + "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 diff --git a/src/modules/bmm/workflows/n8n-expert/_shared/n8n-templates.yaml b/src/modules/bmm/workflows/n8n-expert/_shared/n8n-templates.yaml new file mode 100644 index 00000000..6e3ee4b1 --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/_shared/n8n-templates.yaml @@ -0,0 +1,299 @@ +# n8n Workflow Templates + +# Basic webhook workflow template +webhook_workflow: + name: "Webhook Workflow" + nodes: + - id: "webhook_trigger" + name: "Webhook" + type: "n8n-nodes-base.webhook" + typeVersion: 1 + position: [250, 300] + parameters: + httpMethod: "POST" + path: "webhook-path" + responseMode: "onReceived" + - id: "process_data" + name: "Process Data" + type: "n8n-nodes-base.set" + typeVersion: 1 + position: [470, 300] + parameters: + mode: "manual" + values: {} + connections: + Webhook: + - - node: "Process Data" + type: "main" + index: 0 + +# Scheduled workflow template +scheduled_workflow: + name: "Scheduled Workflow" + nodes: + - id: "schedule_trigger" + name: "Schedule Trigger" + type: "n8n-nodes-base.scheduleTrigger" + typeVersion: 1 + position: [250, 300] + parameters: + rule: + interval: + - field: "hours" + hoursInterval: 1 + - id: "execute_action" + name: "Execute Action" + type: "n8n-nodes-base.httpRequest" + typeVersion: 1 + position: [470, 300] + parameters: + method: "GET" + url: "" + connections: + Schedule Trigger: + - - node: "Execute Action" + type: "main" + index: 0 + +# Conditional workflow template +conditional_workflow: + name: "Conditional Workflow" + nodes: + - id: "manual_trigger" + name: "Manual Trigger" + type: "n8n-nodes-base.manualTrigger" + typeVersion: 1 + position: [250, 300] + parameters: {} + - id: "if_condition" + name: "IF" + type: "n8n-nodes-base.if" + typeVersion: 1 + position: [470, 300] + parameters: + conditions: + boolean: [] + number: [] + string: [] + - id: "true_branch" + name: "True Branch" + type: "n8n-nodes-base.noOp" + typeVersion: 1 + position: [690, 200] + parameters: {} + - id: "false_branch" + name: "False Branch" + type: "n8n-nodes-base.noOp" + typeVersion: 1 + position: [690, 400] + parameters: {} + connections: + Manual Trigger: + - - node: "IF" + type: "main" + index: 0 + IF: + - - node: "True Branch" + type: "main" + index: 0 + - - node: "False Branch" + type: "main" + index: 0 + +# API integration workflow template +api_integration_workflow: + name: "API Integration Workflow" + nodes: + - id: "webhook_trigger" + name: "Webhook" + type: "n8n-nodes-base.webhook" + typeVersion: 1 + position: [250, 300] + parameters: + httpMethod: "POST" + path: "api-webhook" + responseMode: "onReceived" + - id: "http_request" + name: "HTTP Request" + type: "n8n-nodes-base.httpRequest" + typeVersion: 1 + position: [470, 300] + parameters: + method: "POST" + url: "" + jsonParameters: true + options: {} + - id: "transform_response" + name: "Transform Response" + type: "n8n-nodes-base.set" + typeVersion: 1 + position: [690, 300] + parameters: + mode: "manual" + values: {} + connections: + Webhook: + - - node: "HTTP Request" + type: "main" + index: 0 + HTTP Request: + - - node: "Transform Response" + type: "main" + index: 0 + +# Database workflow template +database_workflow: + name: "Database Workflow" + nodes: + - id: "schedule_trigger" + name: "Schedule Trigger" + type: "n8n-nodes-base.scheduleTrigger" + typeVersion: 1 + position: [250, 300] + parameters: + rule: + interval: + - field: "minutes" + minutesInterval: 15 + - id: "postgres_query" + name: "Postgres" + type: "n8n-nodes-base.postgres" + typeVersion: 1 + position: [470, 300] + parameters: + operation: "executeQuery" + query: "" + - id: "process_results" + name: "Process Results" + type: "n8n-nodes-base.code" + typeVersion: 1 + position: [690, 300] + parameters: + language: "javaScript" + jsCode: "return items;" + connections: + Schedule Trigger: + - - node: "Postgres" + type: "main" + index: 0 + Postgres: + - - node: "Process Results" + type: "main" + index: 0 + +# Error handling workflow template +error_handling_workflow: + name: "Error Handling Workflow" + nodes: + - id: "manual_trigger" + name: "Manual Trigger" + type: "n8n-nodes-base.manualTrigger" + typeVersion: 1 + position: [250, 300] + parameters: {} + - id: "risky_operation" + name: "Risky Operation" + type: "n8n-nodes-base.httpRequest" + typeVersion: 1 + position: [470, 300] + parameters: + method: "GET" + url: "" + continueOnFail: true + retryOnFail: true + maxTries: 3 + waitBetweenTries: 1000 + - id: "check_error" + name: "Check for Error" + type: "n8n-nodes-base.if" + typeVersion: 1 + position: [690, 300] + parameters: + conditions: + boolean: + - value1: "={{ $json.error !== undefined }}" + value2: true + - id: "handle_error" + name: "Handle Error" + type: "n8n-nodes-base.set" + typeVersion: 1 + position: [910, 200] + parameters: + mode: "manual" + values: + string: + - name: "status" + value: "error" + - id: "success_path" + name: "Success Path" + type: "n8n-nodes-base.noOp" + typeVersion: 1 + position: [910, 400] + parameters: {} + connections: + Manual Trigger: + - - node: "Risky Operation" + type: "main" + index: 0 + Risky Operation: + - - node: "Check for Error" + type: "main" + index: 0 + Check for Error: + - - node: "Handle Error" + type: "main" + index: 0 + - - node: "Success Path" + type: "main" + index: 0 + +# Batch processing workflow template +batch_processing_workflow: + name: "Batch Processing Workflow" + nodes: + - id: "manual_trigger" + name: "Manual Trigger" + type: "n8n-nodes-base.manualTrigger" + typeVersion: 1 + position: [250, 300] + parameters: {} + - id: "get_data" + name: "Get Data" + type: "n8n-nodes-base.httpRequest" + typeVersion: 1 + position: [470, 300] + parameters: + method: "GET" + url: "" + - id: "split_batches" + name: "Split In Batches" + type: "n8n-nodes-base.splitInBatches" + typeVersion: 1 + position: [690, 300] + parameters: + batchSize: 10 + - id: "process_batch" + name: "Process Batch" + type: "n8n-nodes-base.code" + typeVersion: 1 + position: [910, 300] + parameters: + language: "javaScript" + jsCode: "return items;" + connections: + Manual Trigger: + - - node: "Get Data" + type: "main" + index: 0 + Get Data: + - - node: "Split In Batches" + type: "main" + index: 0 + Split In Batches: + - - node: "Process Batch" + type: "main" + index: 0 + Process Batch: + - - node: "Split In Batches" + type: "main" + index: 0 diff --git a/src/modules/bmm/workflows/n8n-expert/_shared/platform-mappings.yaml b/src/modules/bmm/workflows/n8n-expert/_shared/platform-mappings.yaml new file mode 100644 index 00000000..059bed6c --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/_shared/platform-mappings.yaml @@ -0,0 +1,282 @@ +# Platform Migration Mappings +# Maps common automation platform concepts to n8n equivalents + +# Zapier to n8n mappings +zapier: + triggers: + "New Email": + n8n_node: "n8n-nodes-base.emailTrigger" + notes: "Configure IMAP/POP3 credentials" + "Webhook": + n8n_node: "n8n-nodes-base.webhook" + notes: "Use POST method by default" + "Schedule": + n8n_node: "n8n-nodes-base.scheduleTrigger" + notes: "Convert Zapier schedule format to cron" + "New Row in Google Sheets": + n8n_node: "n8n-nodes-base.googleSheetsTrigger" + notes: "Requires Google OAuth credentials" + "New Slack Message": + n8n_node: "n8n-nodes-base.slackTrigger" + notes: "Configure channel and event type" + + actions: + "Send Email": + n8n_node: "n8n-nodes-base.emailSend" + notes: "Configure SMTP credentials" + "HTTP Request": + n8n_node: "n8n-nodes-base.httpRequest" + notes: "Map method, URL, headers, and body" + "Create Google Sheets Row": + n8n_node: "n8n-nodes-base.googleSheets" + parameters: + operation: "append" + "Send Slack Message": + n8n_node: "n8n-nodes-base.slack" + parameters: + operation: "post" + resource: "message" + "Delay": + n8n_node: "n8n-nodes-base.wait" + notes: "Convert delay duration to milliseconds" + "Filter": + n8n_node: "n8n-nodes-base.if" + notes: "Convert filter conditions to IF node logic" + "Formatter": + n8n_node: "n8n-nodes-base.set" + notes: "Use Set node for data transformation" + "Code": + n8n_node: "n8n-nodes-base.code" + notes: "JavaScript or Python code execution" + + concepts: + "Multi-step Zap": + n8n_equivalent: "Linear workflow with connected nodes" + "Paths": + n8n_equivalent: "IF node with multiple branches" + "Filters": + n8n_equivalent: "IF node with conditions" + "Formatter": + n8n_equivalent: "Set node or Code node" + "Looping": + n8n_equivalent: "Split In Batches node" + +# Make (Integromat) to n8n mappings +make: + triggers: + "Webhook": + n8n_node: "n8n-nodes-base.webhook" + notes: "Direct equivalent" + "Watch Records": + n8n_node: "n8n-nodes-base.scheduleTrigger" + notes: "Combine with polling logic in Code node" + "Custom Webhook": + n8n_node: "n8n-nodes-base.webhook" + notes: "Configure response mode" + + actions: + "HTTP Request": + n8n_node: "n8n-nodes-base.httpRequest" + notes: "Map all HTTP parameters" + "Router": + n8n_node: "n8n-nodes-base.switch" + notes: "Multiple conditional branches" + "Iterator": + n8n_node: "n8n-nodes-base.splitInBatches" + notes: "Process array items individually" + "Aggregator": + n8n_node: "n8n-nodes-base.merge" + notes: "Combine data from multiple sources" + "Data Store": + n8n_node: "n8n-nodes-base.redis" + notes: "Use Redis or database node for storage" + "JSON Parser": + n8n_node: "n8n-nodes-base.code" + notes: "Parse JSON in Code node" + "Text Parser": + n8n_node: "n8n-nodes-base.set" + notes: "Use expressions for text manipulation" + + concepts: + "Scenario": + n8n_equivalent: "Workflow" + "Module": + n8n_equivalent: "Node" + "Route": + n8n_equivalent: "Connection" + "Filter": + n8n_equivalent: "IF node" + "Router": + n8n_equivalent: "Switch node or multiple IF nodes" + "Iterator": + n8n_equivalent: "Split In Batches node" + "Aggregator": + n8n_equivalent: "Merge node" + +# HubSpot Workflows to n8n mappings +hubspot: + triggers: + "Contact Property Change": + n8n_node: "n8n-nodes-base.hubspotTrigger" + notes: "Configure webhook for property updates" + "Deal Stage Change": + n8n_node: "n8n-nodes-base.hubspotTrigger" + notes: "Monitor deal pipeline changes" + "Form Submission": + n8n_node: "n8n-nodes-base.hubspotTrigger" + notes: "Webhook for form submissions" + "List Membership": + n8n_node: "n8n-nodes-base.scheduleTrigger" + notes: "Poll HubSpot API for list changes" + + actions: + "Update Contact Property": + n8n_node: "n8n-nodes-base.hubspot" + parameters: + resource: "contact" + operation: "update" + "Create Deal": + n8n_node: "n8n-nodes-base.hubspot" + parameters: + resource: "deal" + operation: "create" + "Send Email": + n8n_node: "n8n-nodes-base.hubspot" + parameters: + resource: "email" + operation: "send" + "Add to List": + n8n_node: "n8n-nodes-base.hubspot" + parameters: + resource: "contact" + operation: "addToList" + "Create Task": + n8n_node: "n8n-nodes-base.hubspot" + parameters: + resource: "task" + operation: "create" + + concepts: + "Enrollment Trigger": + n8n_equivalent: "Trigger node (webhook or schedule)" + "If/Then Branch": + n8n_equivalent: "IF node" + "Delay": + n8n_equivalent: "Wait node" + "Goal": + n8n_equivalent: "IF node checking completion criteria" + "Re-enrollment": + n8n_equivalent: "Workflow settings with loop detection" + +# Microsoft Power Automate to n8n mappings +power_automate: + triggers: + "When an item is created": + n8n_node: "n8n-nodes-base.webhook" + notes: "Configure webhook for item creation events" + "Recurrence": + n8n_node: "n8n-nodes-base.scheduleTrigger" + notes: "Convert recurrence pattern to cron" + "When a HTTP request is received": + n8n_node: "n8n-nodes-base.webhook" + notes: "Direct equivalent" + + actions: + "HTTP": + n8n_node: "n8n-nodes-base.httpRequest" + notes: "Map all HTTP parameters" + "Condition": + n8n_node: "n8n-nodes-base.if" + notes: "Convert condition logic" + "Apply to each": + n8n_node: "n8n-nodes-base.splitInBatches" + notes: "Process array items" + "Compose": + n8n_node: "n8n-nodes-base.set" + notes: "Data transformation" + "Parse JSON": + n8n_node: "n8n-nodes-base.code" + notes: "Parse JSON in Code node" + "Delay": + n8n_node: "n8n-nodes-base.wait" + notes: "Convert delay duration" + + concepts: + "Flow": + n8n_equivalent: "Workflow" + "Action": + n8n_equivalent: "Node" + "Condition": + n8n_equivalent: "IF node" + "Switch": + n8n_equivalent: "Switch node" + "Scope": + n8n_equivalent: "Error handling with try/catch in Code node" + "Apply to each": + n8n_equivalent: "Split In Batches node" + +# Common patterns across platforms +common_patterns: + conditional_logic: + description: "If/then/else branching" + n8n_implementation: "IF node with true/false branches" + + loops: + description: "Iterate over array items" + n8n_implementation: "Split In Batches node" + + data_transformation: + description: "Transform, format, or map data" + n8n_implementation: "Set node or Code node" + + error_handling: + description: "Handle errors and retries" + n8n_implementation: "Node settings: continueOnFail, retryOnFail, maxTries" + + delays: + description: "Wait before next action" + n8n_implementation: "Wait node with duration" + + webhooks: + description: "Receive HTTP requests" + n8n_implementation: "Webhook node with response configuration" + + api_calls: + description: "Make HTTP requests to APIs" + n8n_implementation: "HTTP Request node" + + parallel_execution: + description: "Execute multiple actions simultaneously" + n8n_implementation: "Multiple connections from single node" + + merge_data: + description: "Combine data from multiple sources" + n8n_implementation: "Merge node" + +# Migration considerations +migration_notes: + authentication: + - "Recreate all credentials in n8n" + - "OAuth flows may need re-authorization" + - "API keys and tokens must be securely stored" + + scheduling: + - "Convert platform-specific schedules to cron expressions" + - "Consider timezone differences" + - "Test schedule triggers before going live" + + data_formats: + - "Verify JSON structure compatibility" + - "Check date/time format conversions" + - "Validate data type mappings" + + error_handling: + - "Implement retry logic where needed" + - "Add error notification workflows" + - "Test failure scenarios" + + testing: + - "Test with sample data first" + - "Verify all integrations work correctly" + - "Monitor initial executions closely" + - "Compare outputs with original platform"