@n8n/ai-workflow-builder 0.31.2 → 0.32.0

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

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonitoringBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class MonitoringBestPractices {
+    technique = categorization_1.WorkflowTechnique.MONITORING;
+    version = '1.0.0';
+    documentation = `# Best Practices: Monitoring Workflows
+
+## Workflow Design
+
+Structure monitoring workflows with a Schedule Trigger for periodic checks, HTTP Request or appropriate check nodes for service status, and IF/Switch nodes for conditional alerting. Always enable error handling to prevent workflow crashes when services are down.
+
+CRITICAL: Enable "Continue On Fail" or "Never Error" mode on check nodes - otherwise the workflow stops exactly when you need alerts. This is the most common monitoring mistake.
+
+Example pattern for website monitoring:
+- Schedule Trigger (every 5 minutes) → HTTP Request (check status) → IF (status != 200?) → Send alert
+- Always test both success and failure paths during development
+
+For monitoring multiple services, store URLs/endpoints in Google Sheets or databases and loop through them rather than duplicating workflows.
+
+## Scheduling & Activation
+
+Always activate the workflow after configuration - forgetting this means no monitoring occurs. Test schedules with manual execution before relying on them in production.
+
+Configure appropriate check intervals based on criticality:
+- Critical services: 1-5 minutes
+- Important services: 10-15 minutes
+- Non-critical: 30-60 minutes
+
+Set correct time zones in Workflow Settings for daily/weekly schedules. Use crontab.guru to verify complex Cron expressions.
+
+## Service Status Checking
+
+Configure HTTP Request nodes with:
+- Timeout: Set to a few seconds to prevent hanging
+- Include Headers & Status: Access response codes for condition evaluation
+- Retry on Fail: 2-3 retries with 1s delay to filter transient failures
+- Authentication: Use credential system, never hardcode secrets
+
+For non-HTTP monitoring:
+- Databases: Use Query nodes (MySQL, Postgres) for health checks
+- Systems: Execute Command node for ping or custom scripts
+- APIs: Check specific endpoints, not just base URLs
+
+## Alert Configuration
+
+Implement multi-channel alerting for critical services to ensure visibility. Configure notifications with useful context.
+
+Message content should include:
+- Service name/URL
+- Failure time: {{$now}}
+- Error details: {{$json["statusCode"]}}
+- Example: "⚠️ Website XYZ DOWN (status 500) at {{new Date().toISOString()}}"
+
+Avoid alert storms by:
+- Tracking state changes (only alert when status changes)
+- Throttling repeated alerts (e.g., re-alert after 30 minutes)
+- Storing last known status in Google Sheets or database
+
+## Error Handling & Failsafes
+
+Implement multiple layers of error handling:
+
+1. Node-level: Enable "Continue On Fail" on check nodes
+2. Workflow-level: Create Error Trigger workflow to catch monitoring failures
+3. Heartbeat: Ping external service (healthchecks.io) to verify monitoring is running
+
+Configure Error Workflow in settings to alert when monitoring itself fails - otherwise you have blind spots.
+
+## Logging & State Management
+
+Log check results for trend analysis and uptime calculation. Store in Google Sheets (append row) or database with:
+- Timestamp
+- Service identifier
+- Status (up/down)
+- Response time
+- Error details if applicable
+
+Maintain current status dashboard by updating a status table/sheet that shows at-a-glance health of all monitored services.
+
+## Recommended Nodes
+
+### Schedule Trigger (n8n-nodes-base.scheduleTrigger)
+
+Purpose: Periodic workflow execution at fixed intervals or Cron schedules
+
+Configuration:
+- Set appropriate intervals based on service criticality
+- Always activate the workflow after configuration
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Check website/API availability and response codes
+
+Critical settings:
+- Enable "Continue On Fail" to handle errors gracefully
+- Set timeout to prevent hanging (2-5 seconds typical)
+- Configure retries for transient failure filtering
+
+### IF (n8n-nodes-base.if)
+
+Purpose: Evaluate service health and route to appropriate action
+
+Common conditions:
+- {{$json["statusCode"]}} equals 200 (service up)
+- {{$json["statusCode"]}} not equals 200 (service down)
+
+### Send Email (n8n-nodes-base.emailSend)
+
+Purpose: Email alerts for service issues
+
+Configure with SMTP credentials and clear subject lines for quick issue identification.
+
+### Messaging Integration Nodes
+
+- Slack (n8n-nodes-base.slack)
+- Microsoft Teams (n8n-nodes-base.microsoftTeams)
+- Telegram (n8n-nodes-base.telegram)
+- Discord (n8n-nodes-base.discord)
+
+Purpose: Real-time alerts to team communication channels
+
+### Twilio (n8n-nodes-base.twilio)
+
+Purpose: SMS/phone alerts for critical system failures requiring immediate attention
+
+### Database & Storage Nodes
+
+- Google Sheets (n8n-nodes-base.googleSheets)
+- MySQL (n8n-nodes-base.mySql)
+- PostgreSQL (n8n-nodes-base.postgres)
+
+Purpose: Store monitoring configuration, log results, track state changes
+
+### Execute Workflow (n8n-nodes-base.executeWorkflow)
+
+Purpose: Modular monitoring design with sub-workflows for different service types
+
+## Common Pitfalls to Avoid
+
+### Forgetting to Activate Workflow
+
+The #1 monitoring failure - creating the perfect monitoring workflow but forgetting to activate it. Always verify the workflow is active (toggle in top-right of editor).
+
+### No Error Handling on Check Nodes
+
+Without "Continue On Fail", the workflow crashes when services are down - exactly when you need alerts. This makes monitoring useless at the critical moment.
+
+### Alert Storms
+
+Sending alerts every check interval creates fatigue. Implement state tracking to alert only on status changes, not every failed check.
+
+### Incorrect Schedule Configuration
+
+Cron expression mistakes can cause workflows to run at wrong times or not at all. A Cron like "* * * * *" runs every minute (not every hour!). Always test schedules.
+
+### Hardcoded Credentials
+
+Never hardcode API keys, passwords, or sensitive URLs directly in nodes. Use n8n's credential manager for security and maintainability.
+
+### Missing Recovery Notifications
+
+Not sending "service recovered" messages leaves teams uncertain about incident resolution. Track state changes bidirectionally.
+
+### Resource Exhaustion
+
+Monitoring too many services in one workflow or setting intervals too frequent can overload n8n. Split large monitoring lists across multiple workflows.
+
+### No Monitoring of Monitoring
+
+If the monitoring workflow fails, you're blind to service issues. Implement Error Trigger workflows and external heartbeat monitoring for the monitoring system itself.`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.MonitoringBestPractices = MonitoringBestPractices;
+//# sourceMappingURL=monitoring.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"monitoring.js","sourceRoot":"","sources":["../../../src/tools/best-practices/monitoring.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,uBAAuB;IAC1B,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wKAoKsI,CAAC;IAExK,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7KD,0DA6KC"}

package/dist/tools/best-practices/notification.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../../types/best-practices';
+export declare class NotificationBestPractices implements BestPracticesDocument {
+    readonly technique: "notification";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}

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

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class NotificationBestPractices {
+    technique = categorization_1.WorkflowTechnique.NOTIFICATION;
+    version = '1.0.0';
+    documentation = `# Best Practices: Notification Workflows
+
+## 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.
+
+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.
+
+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
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+## Recommended Nodes
+
+### Trigger Nodes
+
+**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
+
+**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
+
+**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
+
+### Notification Nodes
+
+**Send Email** (n8n-nodes-base.emailSend):
+- Purpose: Detailed alerts with attachments and HTML formatting
+- Use cases: Reports, detailed notifications, formal communications
+- Configuration: SMTP settings, use App Passwords for Gmail
+- Best practice: Use clear subject lines with key information
+
+**Slack** (n8n-nodes-base.slack):
+- Purpose: Team notifications in channels or direct messages
+- Use cases: Team alerts, status updates, incident notifications
+- Configuration: Bot token with chat:write scope, bot must be invited to channel
+- Best practice: Use markdown formatting, channel IDs (starting with C) not names
+
+**Telegram** (n8n-nodes-base.telegram):
+- Purpose: Instant messaging alerts to individuals or groups
+- Use cases: Personal notifications, bot interactions
+- Configuration: Bot token from BotFather
+- Best practice: Use chat ID for direct messages
+
+**Twilio** (n8n-nodes-base.twilio):
+- Purpose: SMS/WhatsApp critical alerts
+- Use cases: High-priority alerts, two-factor authentication, critical incidents
+- Configuration: Account SID, Auth Token, verified phone numbers
+- Best practice: Keep messages concise, use international format (+1234567890)
+
+**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
+- Best practice: Include empty notification prevention (items.length > 0)
+
+**Switch** (n8n-nodes-base.switch):
+- Purpose: Route notifications based on severity/type
+- 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;
+    }
+}
+exports.NotificationBestPractices = NotificationBestPractices;
+//# sourceMappingURL=notification.js.map

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

@@ -0,0 +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"}

package/dist/tools/best-practices/scheduling.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../../types/best-practices';
+export declare class SchedulingBestPractices implements BestPracticesDocument {
+    readonly technique: "scheduling";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}