@n8n/ai-workflow-builder 1.3.1 → 1.4.0

package/dist/tools/best-practices/data-persistence.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataPersistenceBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class DataPersistenceBestPractices {
+    technique = categorization_1.WorkflowTechnique.DATA_PERSISTENCE;
+    version = '1.0.0';
+    documentation = `# Best Practices: Data Persistence
+
+## Overview
+
+Data persistence involves storing, updating, or retrieving records from durable storage systems. This technique is essential when you need to maintain data beyond the lifetime of a single workflow execution, or when you need to access existing data that users have stored in their spreadsheets, tables, or databases as part of your workflow logic.
+
+## When to Use Data Persistence
+
+Use data persistence when you need to:
+- Store workflow results for later retrieval or audit trails
+- Maintain records that multiple workflows can access and update
+- Create a centralized data repository for your automation
+- Archive historical data for reporting or compliance
+- Build data that persists across workflow executions
+- Track changes or maintain state over time
+- Store raw form inputs
+
+## Choosing the Right Storage Node
+
+### Data Table (n8n-nodes-base.dataTable) - PREFERRED
+
+**Best for:** Quick setup, small to medium amounts of data
+
+Advantages:
+- No credentials or external configuration required
+- Built directly into n8n
+- Fast and reliable for small to medium datasets
+- Ideal for prototyping and internal workflows
+- No additional costs or external dependencies
+
+When to use:
+- Internal workflow data storage
+- Temporary or staging data
+- Admin/audit trails
+- Simple record keeping
+- Development and testing
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Best for:** Collaboration, reporting, easy data sharing
+
+Advantages:
+- Familiar spreadsheet interface for non-technical users
+- Easy to share and collaborate on data
+- Built-in visualization and formula capabilities
+- Good for reporting and dashboards
+- Accessible from anywhere
+
+When to use:
+- Data needs to be viewed/edited by multiple people
+- Non-technical users need access to data
+- Integration with other Google Workspace tools
+- Simple data structures without complex relationships
+- Workflow needs access to existing spreadsheets in Google Sheets
+
+Pitfalls:
+- API rate limits can affect high-volume workflows
+- Not suitable for frequently changing data
+- Performance degrades with very large datasets (>10k rows)
+
+### Airtable (n8n-nodes-base.airtable)
+
+**Best for:** Structured data with relationships, rich field types
+
+Advantages:
+- Supports relationships between tables
+- Rich field types (attachments, select, links, etc.)
+- Better structure than spreadsheets
+
+When to use:
+- Data has relationships or references between records
+- Need structured database-like features
+- Managing projects, tasks, or inventory
+- Workflow needs access to existing data in Airtable
+
+Pitfalls:
+- Requires Airtable account and API key
+- Schema changes require careful planning
+
+## Storage Patterns
+
+### Immediate Storage Pattern
+
+Store data immediately after collection or generation:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Process_Data["Process Data"]
+    Process_Data --> Storage_Node["Storage Node"]
+    Storage_Node --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Raw data preservation, audit trails, form submissions
+
+### Batch Storage Pattern
+
+Collect multiple items and store them together:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Loop_Split["Loop/Split"]
+    Loop_Split --> Process["Process"]
+    Process --> Aggregate["Aggregate"]
+    Aggregate --> Storage_Node["Storage Node"]
+\`\`\`
+
+Best for: Processing lists, batch operations, scheduled aggregations
+
+### Update Pattern
+
+Retrieve, modify, and update existing records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Retrieve["Retrieve from Storage"]
+    Retrieve --> Modify["Modify"]
+    Modify --> Update_Storage["Update Storage Node"]
+\`\`\`
+
+Best for: Maintaining state, updating records, tracking changes
+
+### Lookup Pattern
+
+Query storage to retrieve specific records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Query_Storage["Query Storage Node"]
+    Query_Storage --> Use_Data["Use Retrieved Data"]
+    Use_Data --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Enrichment, validation, conditional logic based on stored data
+
+## Key Considerations
+
+### Data Structure
+
+- **Plan your schema ahead:** Define what fields you need before creating storage
+- **Use consistent field names:** Match field names across your workflow for easy mapping
+- **Consider data types:** Ensure your storage supports the data types you need
+- **Think about relationships:** If data is related, consider Airtable or use multiple tables
+
+### Performance
+
+- **Batch operations when possible:** Multiple small writes are slower than batch operations
+- **Use appropriate operations:** Use "append" for new records, "update" for modifications
+- **Consider API limits:** Google Sheets has rate limits; plan accordingly for high-volume workflows
+
+### Data Integrity
+
+- **Store raw data first:** Keep unmodified input before transformations
+- **Handle errors gracefully:** Use error handling to prevent data loss on failures
+- **Validate before storing:** Ensure data quality before persistence
+- **Avoid duplicates:** Use unique identifiers or upsert operations when appropriate
+
+## Important Distinctions
+
+### Storage vs. Transformation
+
+- **Set/Merge nodes are NOT storage:** They transform data in memory only
+- **Storage happens explicitly:** Data won't persist unless you explicitly write it to storage
+
+### Temporary vs. Persistent Storage
+
+- **NOT covered by this technique:** Redis, caching, session storage, in-memory operations
+- **This technique covers:** Durable storage that persists beyond workflow execution
+- **Focus on permanence:** Use these nodes when you need data to survive restarts and be queryable later
+
+## Common Pitfalls to Avoid
+
+### Not Handling Duplicates
+
+Without proper unique identifiers or upsert logic, you may create duplicate records. Use unique IDs or check for existing records before inserting.
+
+### Ignoring Storage Limits
+
+Each storage system has limits (row counts, API rates, file sizes). Design your workflow to work within these constraints or implement pagination/batching.
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataPersistenceBestPractices = DataPersistenceBestPractices;
+//# sourceMappingURL=data-persistence.js.map

package/dist/tools/best-practices/data-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-persistence.js","sourceRoot":"","sources":["../../../src/tools/best-practices/data-persistence.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,4BAA4B;IAC/B,SAAS,GAAG,kCAAiB,CAAC,gBAAgB,CAAC;IAC/C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkLjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA3LD,oEA2LC"}

package/dist/tools/best-practices/data-transformation.js

@@ -69,22 +69,6 @@ class DataTransformationBestPractices {
 
 #### Code Node (n8n-nodes-base.code)
 
-**Built-in Nodes vs. Code Node**
-- Prefer basic built-in nodes (Edit Fields, Filter, Split Out, Summarize, Aggregate, etc.) over Code node. Use Code only for complex logic that can't be achieved otherwise.
-- Rule of thumb: if the goal can be achieved with fewer than 5 basic nodes, use basic nodes
-
-**When NOT to Use**: Code node may be slower than core nodes (like Edit Fields, If, Switch, Split Out, Aggregate, etc.) as Code nodes run in a sandboxed environment. Avoid the code node where possible — it should only be used for complex transformations that can't be done with other nodes. For example, DO NOT use it for:
-- Adding or removing fields from items (use the 'edit fields' node instead)
-- Single-line data transformations of item fields (use the 'edit fields' node instead)
-- Filtering items based on their fields (use the 'filter' node instead)
-- Pivoting or summarizing data across multiple items (use the 'summarize' node instead)
-- Splitting arrays inside items out into multiple items (use the 'split out' node instead)
-- Aggregating multiple items into a single item (use the 'aggregate' node instead)
-- Sorting items in an array based on their fields (use the 'Sort' node instead)
-- Generating HTML from text or formatting text as HTML (use the 'HTML' node set to operation 'Generate HTML Template' or 'Convert to HTML Table' instead)
-
-**When to Use**: Complex transformations impossible with built-in nodes
-
 **Execution Modes**:
 - "Run Once per Item": Process each item independently
 - "Run Once for All Items": Access entire dataset (for aggregation)

package/dist/tools/best-practices/data-transformation.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-transformation.js","sourceRoot":"","sources":["../../../src/tools/best-practices/data-transformation.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,+BAA+B;IAClC,SAAS,GAAG,kCAAiB,CAAC,mBAAmB,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7JD,0EA6JC"}
+{"version":3,"file":"data-transformation.js","sourceRoot":"","sources":["../../../src/tools/best-practices/data-transformation.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,+BAA+B;IAClC,SAAS,GAAG,kCAAiB,CAAC,mBAAmB,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7ID,0EA6IC"}

package/dist/tools/best-practices/document-processing.js

@@ -103,14 +103,12 @@ For varied or complex documents:
 Option 1 - Using Document Loader (Recommended for binary files):
 1. Pass binary data directly to Document Loader node (set Data Source to "Binary")
 2. Connect to AI Agent or LLM Chain for processing
-3. Use Structured Output Parser to ensure consistent JSON
-4. Validate extracted fields before processing
+3. Validate extracted fields before processing
 
 Option 2 - Using text extraction:
 1. Extract raw text using Extract from File or OCR
 2. Pass to AI Agent or LLM Chain with structured prompt
-3. Use Structured Output Parser to ensure consistent JSON
-4. Validate extracted fields before processing
+3. Validate extracted fields before processing
 
 Example system prompt structure:
 "Extract the following fields from the document: [field list]. Return as JSON with this schema: [schema example]"
@@ -198,7 +196,6 @@ Configuration: Include structured output tools for consistent results
 
 **LLM Chain (@n8n/n8n-nodes-langchain.chainLlm)**
 Purpose: Document classification and data extraction
-Use with: Structured Output Parser for JSON consistency
 
 **Document Loader (@n8n/n8n-nodes-langchain.documentLoader)**
 Purpose: Load and process documents directly from binary data for AI processing
@@ -238,7 +235,7 @@ Modes: Use "Pass Through" to preserve binary from one branch
 **Edit Fields (Set) (n8n-nodes-base.set)**
 Purpose: Better choice for combining data from separate/independent branches
 Use for: Adding fields from different sources, preserving binary while adding processed data
-Configuration: Set common fields and use "Include Other Input Fields" OFF to preserve existing data including binary
+Configuration: Set common fields and use "Include Other Input Fields" ON to preserve existing data including binary
 
 **Execute Workflow Trigger (n8n-nodes-base.executeWorkflowTrigger)**
 Purpose: Start point for sub-workflows that are called by other workflows

package/dist/tools/best-practices/document-processing.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-processing.js","sourceRoot":"","sources":["../../../src/tools/best-practices/document-processing.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,+BAA+B;IAClC,SAAS,GAAG,kCAAiB,CAAC,mBAAmB,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DAiUyB,CAAC;IAE3D,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA1UD,0EA0UC"}
+{"version":3,"file":"document-processing.js","sourceRoot":"","sources":["../../../src/tools/best-practices/document-processing.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,+BAA+B;IAClC,SAAS,GAAG,kCAAiB,CAAC,mBAAmB,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DA8TyB,CAAC;IAE3D,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAvUD,0EAuUC"}

package/dist/tools/best-practices/index.js

@@ -5,23 +5,27 @@ const categorization_1 = require("../../types/categorization");
 const chatbot_1 = require("./chatbot");
 const content_generation_1 = require("./content-generation");
 const data_extraction_1 = require("./data-extraction");
+const data_persistence_1 = require("./data-persistence");
 const data_transformation_1 = require("./data-transformation");
 const document_processing_1 = require("./document-processing");
 const form_input_1 = require("./form-input");
+const notification_1 = require("./notification");
 const scraping_and_research_1 = require("./scraping-and-research");
+const triage_1 = require("./triage");
 exports.documentation = {
     [categorization_1.WorkflowTechnique.SCRAPING_AND_RESEARCH]: new scraping_and_research_1.ScrapingAndResearchBestPractices(),
     [categorization_1.WorkflowTechnique.CHATBOT]: new chatbot_1.ChatbotBestPractices(),
     [categorization_1.WorkflowTechnique.CONTENT_GENERATION]: new content_generation_1.ContentGenerationBestPractices(),
     [categorization_1.WorkflowTechnique.DATA_ANALYSIS]: undefined,
     [categorization_1.WorkflowTechnique.DATA_EXTRACTION]: new data_extraction_1.DataExtractionBestPractices(),
+    [categorization_1.WorkflowTechnique.DATA_PERSISTENCE]: new data_persistence_1.DataPersistenceBestPractices(),
     [categorization_1.WorkflowTechnique.DATA_TRANSFORMATION]: new data_transformation_1.DataTransformationBestPractices(),
     [categorization_1.WorkflowTechnique.DOCUMENT_PROCESSING]: new document_processing_1.DocumentProcessingBestPractices(),
     [categorization_1.WorkflowTechnique.ENRICHMENT]: undefined,
     [categorization_1.WorkflowTechnique.FORM_INPUT]: new form_input_1.FormInputBestPractices(),
     [categorization_1.WorkflowTechnique.KNOWLEDGE_BASE]: undefined,
-    [categorization_1.WorkflowTechnique.NOTIFICATION]: undefined,
-    [categorization_1.WorkflowTechnique.TRIAGE]: undefined,
+    [categorization_1.WorkflowTechnique.NOTIFICATION]: new notification_1.NotificationBestPractices(),
+    [categorization_1.WorkflowTechnique.TRIAGE]: new triage_1.TriageBestPractices(),
     [categorization_1.WorkflowTechnique.HUMAN_IN_THE_LOOP]: undefined,
     [categorization_1.WorkflowTechnique.MONITORING]: undefined,
     [categorization_1.WorkflowTechnique.SCHEDULING]: undefined,

package/dist/tools/best-practices/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/best-practices/index.ts"],"names":[],"mappings":";;;AACA,2DAAuF;AAEvF,uCAAiD;AACjD,6DAAsE;AAEtE,uDAAgE;AAChE,+DAAwE;AACxE,+DAAwE;AAExE,6CAAsD;AAKtD,mEAA2E;AAI9D,QAAA,aAAa,GAAqE;IAC9F,CAAC,kCAAiB,CAAC,qBAAqB,CAAC,EAAE,IAAI,wDAAgC,EAAE;IACjF,CAAC,kCAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,8BAAoB,EAAE;IACvD,CAAC,kCAAiB,CAAC,kBAAkB,CAAC,EAAE,IAAI,mDAA8B,EAAE;IAC5E,CAAC,kCAAiB,CAAC,aAAa,CAAC,EAAE,SAAS;IAC5C,CAAC,kCAAiB,CAAC,eAAe,CAAC,EAAE,IAAI,6CAA2B,EAAE;IACtE,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,IAAI,qDAA+B,EAAE;IAC9E,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,IAAI,qDAA+B,EAAE;IAC9E,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,IAAI,mCAAsB,EAAE;IAC5D,CAAC,kCAAiB,CAAC,cAAc,CAAC,EAAE,SAAS;IAC7C,CAAC,kCAAiB,CAAC,YAAY,CAAC,EAAE,SAAS;IAC3C,CAAC,kCAAiB,CAAC,MAAM,CAAC,EAAE,SAAS;IACrC,CAAC,kCAAiB,CAAC,iBAAiB,CAAC,EAAE,SAAS;IAChD,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;CACzC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/best-practices/index.ts"],"names":[],"mappings":";;;AACA,2DAAuF;AAEvF,uCAAiD;AACjD,6DAAsE;AAEtE,uDAAgE;AAChE,yDAAkE;AAClE,+DAAwE;AACxE,+DAAwE;AAExE,6CAAsD;AAItD,iDAA2D;AAC3D,mEAA2E;AAE3E,qCAA+C;AAElC,QAAA,aAAa,GAAqE;IAC9F,CAAC,kCAAiB,CAAC,qBAAqB,CAAC,EAAE,IAAI,wDAAgC,EAAE;IACjF,CAAC,kCAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,8BAAoB,EAAE;IACvD,CAAC,kCAAiB,CAAC,kBAAkB,CAAC,EAAE,IAAI,mDAA8B,EAAE;IAC5E,CAAC,kCAAiB,CAAC,aAAa,CAAC,EAAE,SAAS;IAC5C,CAAC,kCAAiB,CAAC,eAAe,CAAC,EAAE,IAAI,6CAA2B,EAAE;IACtE,CAAC,kCAAiB,CAAC,gBAAgB,CAAC,EAAE,IAAI,+CAA4B,EAAE;IACxE,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,IAAI,qDAA+B,EAAE;IAC9E,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,IAAI,qDAA+B,EAAE;IAC9E,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,IAAI,mCAAsB,EAAE;IAC5D,CAAC,kCAAiB,CAAC,cAAc,CAAC,EAAE,SAAS;IAC7C,CAAC,kCAAiB,CAAC,YAAY,CAAC,EAAE,IAAI,wCAAyB,EAAE;IACjE,CAAC,kCAAiB,CAAC,MAAM,CAAC,EAAE,IAAI,4BAAmB,EAAE;IACrD,CAAC,kCAAiB,CAAC,iBAAiB,CAAC,EAAE,SAAS;IAChD,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;CACzC,CAAC"}

package/dist/tools/best-practices/notification.js

@@ -9,45 +9,50 @@ class NotificationBestPractices {
 
 ## Workflow Design
 
-Structure notification workflows in a clear sequence: Trigger → Data Retrieval/Processing → Condition Check → Notification Action → Post-Notification (logging/tracking). Keep each part modular with nodes dedicated to specific purposes.
+Structure notification workflows in a clear sequence. Keep each part modular with nodes dedicated to specific purposes.
 
-Choose between event-based triggers (webhooks, form submissions, CRM events) for immediate notifications or scheduled triggers (Cron) for periodic condition monitoring. Test Cron triggers in manual mode first to avoid unintended executions.
+\`\`\`mermaid
+graph LR
+    A[Trigger] --> B[Data Retrieval/Processing]
+    B --> C[Condition Check]
+    C --> D[Notification Action]
+    D --> E[Post-Notification: logging/tracking]
+\`\`\`
+
+Choose between event-based triggers (webhooks, form submissions, CRM events) for immediate notifications or scheduled triggers (Cron) for periodic condition monitoring.
 
 CRITICAL: Multi-channel notifications should branch from a single condition check to multiple notification nodes in parallel, not duplicate the entire workflow. This enables easy extension and maintenance.
 
 Example pattern:
-- Webhook/Schedule Trigger → Fetch Data → IF (threshold exceeded) → [Email + Slack + SMS nodes in parallel]
-- Result: Single workflow handles all channels efficiently with consistent logic
+\`\`\`mermaid
+graph LR
+    A[Webhook/Schedule Trigger] --> B[Fetch Data]
+    B --> C[If: threshold exceeded]
+    C -->|true| D[Email]
+    C -->|true| E[Slack]
+    C -->|true| F[SMS]
+    C -->|false| G[End/Log]
+\`\`\`
+Result: Single workflow handles all channels efficiently with consistent logic
 
 ## Condition Logic & Filtering
 
-Use IF nodes for simple threshold checks without code. For complex conditions (multiple fields, array filtering), use Function nodes to script the logic and filter items that need alerts.
+Use IF nodes for simple checks without code. For complex conditions (multiple fields, array filtering), use Code nodes to script the logic and filter items that need alerts.
 
 Always include empty notification prevention - check that alert-worthy items exist (items.length > 0) before proceeding to notification nodes. Route the false branch to end the workflow or log "no alert needed".
 
-Store threshold values in environment variables or external sources (Google Sheets, database) rather than hardcoding. This enables adjustment without workflow modification.
-
 ## Message Construction
 
-Use expressions to inject dynamic data into messages. The expression \`{{ $json.fieldName }}\` pulls data from input items. For email subjects and bodies, include key details like metric names, values, and timestamps.
+Use expressions to inject dynamic data into messages. The expression \`{{ $json.fieldName }}\` pulls data from input items.
 
 Format messages appropriately for each channel:
 - Email: Support HTML or plain text, use clear subject lines
 - Slack: Use markdown-like formatting, \\n for newlines
 - SMS: Keep concise due to character limits, plain text only
 
-## Authentication & Permissions
-
-Configure proper credentials for each service:
-- Email: SMTP settings with correct host/port/auth (use App Passwords for Gmail)
-- Slack: Bot token with chat:write scope, bot must be invited to target channel
-- SMS (Twilio): Account SID, Auth Token, verified phone numbers
-
-Store sensitive information in n8n credentials system or environment variables, never hardcode in workflows.
-
 ## Alert Management
 
-Implement cooldown mechanisms to prevent notification floods. Record last alert time and check before sending duplicates. Consider alert aggregation - send one message listing multiple items rather than individual alerts.
+Consider alert aggregation - send one message listing multiple items rather than individual alerts.
 
 Add logging nodes to track sent notifications for audit trails and duplicate prevention. Consider using error handling paths with Continue on Fail settings for redundancy.
 
@@ -55,20 +60,25 @@ Add logging nodes to track sent notifications for audit trails and duplicate pre
 
 ### Trigger Nodes
 
+**Service-specific triggers** (e.g., n8n-nodes-base.googleSheetsTrigger, n8n-nodes-base.crmTrigger):
+- Purpose: Direct integration with specific services for event-based notifications
+- Use cases: New row in Google Sheets, CRM record updates
+- When to use: When specific trigger node is available
+
 **Webhook** (n8n-nodes-base.webhook):
 - Purpose: Event-based notifications triggered by external systems
 - Use cases: Form submissions, CRM events, API webhooks
-- Best practice: Validate incoming data before processing
+- When to use: When there is no dedicated trigger node and external service supports webhooks
 
 **Schedule Trigger** (n8n-nodes-base.scheduleTrigger):
 - Purpose: Periodic monitoring and batch notifications
 - Use cases: Daily reports, threshold monitoring, scheduled alerts
-- Best practice: Test in manual mode first to avoid unintended executions
+- When to use: For regular checks rather than immediate alerts, or as a polling mechanism when webhooks are not available
 
-**Email Trigger IMAP** (n8n-nodes-base.emailReadImap):
-- Purpose: Email-triggered alerts and auto-responses
-- Use cases: Support ticket creation, email monitoring
-- Best practice: Use filters to avoid processing every email
+**Form Trigger** (n8n-nodes-base.formTrigger):
+- Purpose: User-submitted data triggering notifications
+- Use cases: Contact forms, feedback submissions
+- When to use: For workflows initiated by user input via forms
 
 ### Notification Nodes
 
@@ -99,13 +109,12 @@ Add logging nodes to track sent notifications for audit trails and duplicate pre
 **HTTP Request** (n8n-nodes-base.httpRequest):
 - Purpose: Custom webhooks (Microsoft Teams, Discord, custom APIs)
 - Use cases: Integration with services without dedicated nodes
-- Best practice: Test webhook URLs before production
 
 ### Logic & Processing
 
 **IF** (n8n-nodes-base.if):
 - Purpose: Simple threshold checks and condition routing
-- Use cases: Check if metric exceeds threshold, validate data
+- Use cases: Check if notification criteria met
 - Best practice: Include empty notification prevention (items.length > 0)
 
 **Switch** (n8n-nodes-base.switch):
@@ -113,113 +122,10 @@ Add logging nodes to track sent notifications for audit trails and duplicate pre
 - Use cases: Different channels for different alert levels
 - Best practice: Always define Default case for unexpected values
 
-**Function** (n8n-nodes-base.function):
-- Purpose: Complex filtering and data transformation
-- Use cases: Array filtering, complex conditions, message formatting
-- Best practice: Keep logic focused and well-documented
-
-**Merge** (n8n-nodes-base.merge):
-- Purpose: Combine parallel notification branches
-- Use cases: Track all notification attempts, consolidate logs
-- Best practice: Use after parallel notification nodes
-
-### Data Sources
-
-**Database Nodes**:
-- Postgres (n8n-nodes-base.postgres)
-- MySQL (n8n-nodes-base.mySql)
-- MongoDB (n8n-nodes-base.mongoDb)
-
-Purpose: Fetch metrics, thresholds, and historical data
-Best practice: Use queries with proper indexing for performance
-
-**Google Sheets** (n8n-nodes-base.googleSheets):
-- Purpose: Configuration storage and logging
-- Use cases: Store thresholds, log notifications, track cooldowns
-- Best practice: Use for non-critical configurations that need easy updates
-
-**HTTP Request** (n8n-nodes-base.httpRequest):
-- Purpose: API data retrieval
-- Use cases: Fetch metrics from monitoring APIs, get user preferences
-- Best practice: Handle API errors gracefully
-
-### Utility Nodes
-
 **Set** (n8n-nodes-base.set):
 - Purpose: Prepare alert messages and structure data
 - Use cases: Format notification content, add metadata
 - Best practice: Use to centralize message construction logic
-
-**Wait** (n8n-nodes-base.wait):
-- Purpose: Delays between notifications
-- Use cases: Rate limiting, cooldown periods, retry logic
-- Best practice: Use for preventing notification floods
-
-**Split In Batches** (n8n-nodes-base.splitInBatches):
-- Purpose: Handle large datasets without overwhelming recipients
-- Use cases: Bulk notifications with rate limiting
-- Best practice: Combine with Wait node for controlled sending
-
-## Common Pitfalls to Avoid
-
-### Authentication Failures
-**Problem**: Invalid or expired credentials are the most common cause of failed notifications.
-
-**Solution**:
-- Regularly verify API keys, OAuth tokens, and SMTP passwords
-- Ensure bots have proper permissions (Slack bots need channel membership)
-- Use n8n credentials system, never hardcode sensitive data
-- Test authentication in isolation before deploying
-
-### Notification Floods
-**Problem**: Without proper controls, a threshold breach can trigger hundreds of identical alerts.
-
-**Solution**:
-- Implement cooldown periods using Wait node or tracking last alert time
-- Use alert aggregation - send one message listing multiple items
-- Use deduplication logic to prevent identical alerts
-- Consider exponential backoff for repeated alerts
-- Store last notification timestamp in database/sheets
-
-### Incorrect Channel Configuration
-**Problem**: Notifications fail due to misconfigured channels.
-
-**Solution**:
-- Slack requires channel IDs (starting with C) not names
-- Email requires verified sender addresses
-- SMS needs international format (+1234567890)
-- Test each channel with sample data before production
-- Validate configuration in node settings
-
-### Data Type Mismatches
-**Problem**: String-to-number comparisons fail silently ("5" > "10" is lexicographically true).
-
-**Solution**:
-- Always convert data types before comparisons
-- Use Number() or parseInt() for numeric comparisons
-- Escape special characters in messages to prevent formatting breaks
-- Validate data types early in the workflow
-
-### Missing Error Handling
-**Problem**: A single failed notification can stop the entire workflow.
-
-**Solution**:
-- Configure error workflows using Error Trigger node
-- Use "Continue on Fail" setting for redundancy
-- Implement fallback channels (if Slack fails, send email)
-- Log failed notification attempts for debugging
-- Add retry logic with exponential backoff
-
-### Rate Limit Violations
-**Problem**: External services have posting limits that can block notifications.
-
-**Solution**:
-- Add delays between bulk sends using Wait node
-- Monitor API quotas and adjust trigger frequency
-- Use BCC for bulk emails when appropriate
-- Implement batch processing with Split In Batches
-- Check service documentation for rate limits
-- Use webhook aggregation where possible
 `;
     getDocumentation() {
         return this.documentation;

package/dist/tools/best-practices/notification.js.map

@@ -1 +1 @@
-{"version":3,"file":"notification.js","sourceRoot":"","sources":["../../../src/tools/best-practices/notification.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,yBAAyB;IAC5B,SAAS,GAAG,kCAAiB,CAAC,YAAY,CAAC;IAC3C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuNjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAhOD,8DAgOC"}
+{"version":3,"file":"notification.js","sourceRoot":"","sources":["../../../src/tools/best-practices/notification.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,yBAAyB;IAC5B,SAAS,GAAG,kCAAiB,CAAC,YAAY,CAAC;IAC3C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAlID,8DAkIC"}

package/dist/tools/best-practices/scraping-and-research.js

@@ -34,10 +34,7 @@ Purpose: Fetches web pages or API data for scraping and research workflows
 Pitfalls:
 
 - Depending on the data which the user wishes to scrape/research, it maybe against the terms of service to attempt to
-fetch it from the site directly. Using scraping nodes is the best way to get around this.
-
-Pitfalls:
-
+fetch it from the site directly. Using scraping nodes is the best way to get around this
 - Double-check URL formatting, query parameters, and ensure all required fields are present to avoid bad request errors
 - Be aware of 429 rate limiting errors when the service receives too many requests - implement batching or use "Retry on
 Fail" feature

package/dist/tools/best-practices/scraping-and-research.js.map

@@ -1 +1 @@
-{"version":3,"file":"scraping-and-research.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scraping-and-research.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,gCAAgC;IACnC,SAAS,GAAG,kCAAiB,CAAC,qBAAqB,CAAC;IACpD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmJjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA5JD,4EA4JC"}
+{"version":3,"file":"scraping-and-research.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scraping-and-research.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,gCAAgC;IACnC,SAAS,GAAG,kCAAiB,CAAC,qBAAqB,CAAC;IACpD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgJjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAzJD,4EAyJC"}