@n8n/instance-ai 1.0.0

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

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocumentation = getDocumentation;
+function getDocumentation() {
+    return `# Best Practices: Data Transformation
+
+## Workflow Design
+
+### Core Principles
+- **Structure**: Always follow Input -> Transform -> Output pattern
+- **Optimization**: Filter and reduce data early to improve performance
+
+### Design Best Practices
+- Plan transformation requirements in plain language before building
+- Use Modular Design: Create reusable sub-workflows for common tasks like "Data Cleaning" or "Error Handler"
+- Batch datasets over 100 items using Split In Batches node to prevent timeouts
+
+## Recommended Nodes
+
+### Essential Transformation Nodes
+
+#### Edit Fields (Set) (n8n-nodes-base.set)
+
+**Purpose**: Create, modify, rename fields; change data types
+
+**Key Setting**: "Keep Only Set" - drops all fields not explicitly defined (default: disabled)
+
+**Use Cases**:
+- Extract specific columns
+- Add calculated fields
+- Convert data types (string to number)
+- Format dates using expressions
+
+**Pitfalls**:
+- Not understanding "Keep Only Set" behavior can lead to data loss
+- Enabled: Drops all fields not explicitly defined (data loss risk)
+- Disabled: Carries forward all fields (potential bloat)
+- Always verify output structure after configuration
+
+**Testing tip**: When transforming data from a workflow trigger, you can set values with a fallback default e.g. set name to {{$json.name || 'Jane Doe'}} to help test the workflow.
+
+#### IF/Filter Nodes
+
+**IF Node** (n8n-nodes-base.if):
+- **Purpose**: Conditional processing and routing
+- **Best Practice**: Use early to validate inputs and remove bad data
+- **Example**: Check if required fields exist before processing
+
+**Filter Node** (n8n-nodes-base.filter):
+- **Purpose**: Filter items based on conditions
+- **Best Practice**: Use early in workflow to reduce data volume
+
+#### Merge Node (n8n-nodes-base.merge)
+
+**Purpose**: Combine two data streams
+
+**Modes**:
+- Merge by Key (like database join)
+- Merge by Index
+- Append
+
+**Pitfalls**:
+- **Missing Keys**: Trying to merge on non-existent fields
+- **Field Name Mismatch**: Different field names in sources
+- **Solution**: Use Edit Fields node to normalize field names before merging
+
+#### Code Node (n8n-nodes-base.code)
+
+**Execution Modes**:
+- "Run Once per Item": Process each item independently
+- "Run Once for All Items": Access entire dataset (for aggregation)
+
+**Return Format**: Must return array of objects with json property
+\`\`\`javascript
+return items; // or return [{ json: {...} }];
+\`\`\`
+
+**Pitfalls**:
+- Wrong return format: Not returning array of objects with json property
+- Overly complex: Stuffing entire workflow logic in one Code node
+- Keep code nodes focused on single transformation aspect
+
+#### Summarize Node (n8n-nodes-base.summarize)
+
+**Purpose**: Pivot table-style aggregations (count, sum, average, min/max)
+
+**Configuration**:
+- Fields to Summarize: Choose aggregation function
+- Fields to Split By: Grouping keys
+
+**Output**: Single item with summary or multiple items per group
+
+### Data Restructuring Nodes
+
+- **Split Out** (n8n-nodes-base.splitOut): Convert single item with array into multiple items
+- **Aggregate** (n8n-nodes-base.aggregate): Combine multiple items into one
+- **Remove Duplicates** (n8n-nodes-base.removeDuplicates): Delete duplicate items based on field criteria
+- **Sort** (n8n-nodes-base.sort): Order items alphabetically/numerically
+- **Limit** (n8n-nodes-base.limit): Trim to maximum number of items
+
+### Batch Processing
+
+**Split In Batches** (n8n-nodes-base.splitInBatches):
+- **Purpose**: Process large datasets in chunks
+- **Use When**: Handling 100+ items with expensive operations (API calls, AI)
+
+## Input Data Validation
+- Validate external data before processing: check for nulls, empty values, and edge cases (special chars, empty arrays)
+
+## Common Pitfalls to Avoid
+
+### Critical Mistakes
+
+#### Edit Fields Node Issues
+- **Mistake**: Not understanding "Keep Only Set" behavior
+  - Enabled: Drops all fields not explicitly defined (data loss risk)
+  - Disabled: Carries forward all fields (potential bloat)
+- **Solution**: Always verify output structure after configuration
+
+#### Code Node Errors
+- **Wrong Return Format**: Not returning array of objects with json property
+- **Fix**: Always return \`items\` or \`[{ json: {...} }]\`
+- **Overly Complex**: Stuffing entire workflow logic in one Code node
+- **Fix**: Keep code nodes focused on single transformation aspect
+
+#### Merge Node Problems
+- **Field Name Mismatch**: Different field names in sources
+- **Fix**: Normalize field names with Edit Fields before merging
+
+### Performance Pitfalls
+- Processing large datasets without batching -> timeouts
+- Not filtering early -> unnecessary processing overhead
+- Excessive node chaining -> visual clutter and slow execution
+
+### Data Validation Pitfalls
+- Assuming input data is always perfect -> runtime errors
+`;
+}
+//# sourceMappingURL=data-transformation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-transformation.js","sourceRoot":"","sources":["../../../../src/tools/best-practices/guides/data-transformation.ts"],"names":[],"mappings":";;AAAA,4CAsIC;AAtID,SAAgB,gBAAgB;IAC/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIP,CAAC;AACF,CAAC"}

package/dist/tools/best-practices/guides/document-processing.d.ts

@@ -0,0 +1 @@
+export declare function getDocumentation(): string;

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

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocumentation = getDocumentation;
+function getDocumentation() {
+    return `# Best Practices: Document Processing Workflows
+
+## Workflow Design
+
+Document processing workflows extract and act on content from files like PDFs, images, Word documents, and spreadsheets. Design your workflow following these core patterns:
+
+### Core Architecture Pattern
+Trigger -> Capture Binary -> Extract Text -> Parse/Transform -> Route to Destination -> Notify
+
+### Common Flow Patterns
+
+**Simple Document Processing:**
+- Gmail Trigger -> Check file type -> Extract from File -> DataTable -> Slack notification
+- Best for: Basic text-based PDFs with straightforward data extraction
+
+**Complex Document Processing with AI:**
+- Webhook -> File Type Check -> OCR (if image) -> AI Extract -> Validate -> CRM Update -> Multiple notifications
+- Best for: Varied document formats requiring intelligent parsing
+
+**Batch Document Processing:**
+- Main workflow: Schedule Trigger -> Fetch Files -> Split In Batches -> Sub-workflow -> Merge Results -> Bulk Update
+- Sub-workflow When Executed by Another Workflow -> Process result
+- Best for: High-volume processing with API rate limits
+
+**Multi-Source Document Aggregation:**
+- Multiple Triggers (Email + Drive + Webhook) -> Set common fields -> Standardize -> Process -> Store
+- Best for: Documents from various channels needing unified processing
+
+### Branching Strategy
+
+Always branch early based on document characteristics:
+- **File Type Branching**: Use IF/Switch nodes immediately after ingestion to route PDFs vs images vs spreadsheets
+- **Provider Branching**: Route documents to provider-specific processing (e.g., different invoice formats)
+- **Quality Branching**: Separate high-confidence extractions from those needing manual review
+
+## Binary Data Management
+Documents in n8n are handled as binary data that must be carefully preserved throughout the workflow.
+
+### Referencing Binary Data from Other Nodes
+When you need to reference binary data from a previous node, use this syntax:
+- Expression: '{{ $('Node Name').item.binary.property_name }}' or {{ $binary.property_name }} if previous item
+- Example for Gmail attachments: '{{ $('Gmail Trigger').item.binary.attachment_0 }}' or {{ $binary.attachment_0 }} if previous item
+- Example for webhook data: '{{ $('Webhook').item.binary.data }}' or {{ $binary.data }} if previous item
+- Important: The property name depends on how the previous node names the binary data
+
+### Preserving Binary Data
+- Many nodes (Code, Edit Fields, AI nodes) output JSON and drop binary data by default
+- Use parallel branches: one for processing, one to preserve the original file
+- Rejoin branches with Merge node in pass-through mode
+- Alternative: Configure nodes to keep binary (e.g., Edit field node's "Include Other Input Fields" option ON)
+
+### Memory Optimization
+For high-volume processing:
+- Process files sequentially or in small batches
+- Drop unnecessary binary data after extraction to free memory
+
+### File Metadata
+Documents uploaded via a form trigger will have various bits of metadata available - filename, mimetype and size.
+These are accessible using an expression like {{ $json.documents[0].mimetype }} to access each of the document's details.
+Multiple files can be uploaded to a form which is the reason for the documents array.
+
+## Text Extraction Strategy
+
+Choose extraction method based on document type and content:
+
+### Critical: File Type Detection
+**ALWAYS check the file type before using Extract from File node** (unless the file type is already known):
+- Use IF node to check file extension or MIME type first
+- The Extract from File node has multiple operations, each for a specific file type:
+  - "Extract from PDF" for PDF files
+  - "Extract from MS Excel" for Excel files (.xlsx, .xls)
+  - "Extract from MS Word" for Word documents (.docx, .doc)
+  - "Extract from CSV" for CSV files
+  - "Extract from HTML" for HTML files
+  - "Extract from RTF" for Rich Text Format files
+  - "Extract from Text File" for plain text files
+- Using the wrong operation will result in errors or empty output
+
+### Decision Tree for Extraction
+1. **Check file type** -> Route to appropriate extraction method
+2. **Scanned image/PDF?** -> Use OCR service (OCR.space, AWS Textract, Google Vision)
+3. **Structured invoice/receipt?** -> Use specialized parser (Mindee) or AI extraction
+4. **Text-based document?** -> Use Extract from File with the correct operation for that file type
+
+### Fallback Strategy
+Always implement fallback for extraction failures:
+- Check if text extraction returns empty
+- If empty, automatically route to OCR
+- If OCR fails, send to manual review queue
+
+## Data Parsing & Classification
+
+### AI-Powered Extraction Pattern
+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. 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. 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]"
+
+### Document Classification Flow
+Classify before processing for better accuracy:
+1. Initial AI classification (Invoice vs Receipt vs Contract)
+2. Route to specialized sub-workflow based on type
+3. Use type-specific prompts and validation rules
+4. This reduces errors and improves extraction quality
+
+## Error Handling Strategy
+
+Build resilience at every step:
+
+### Validation Checkpoints
+- After extraction: Verify text not empty
+- After AI parsing: Validate JSON schema
+- Before database insert: Check required fields
+- After API calls: Verify success response
+
+## Performance Optimization
+
+### Batch Processing Strategy
+- Use Split In Batches node: process 5-10 files at a time
+- Implement delays between batches for rate-limited APIs
+- Monitor memory usage and adjust batch size accordingly
+
+## Recommended Nodes
+
+### Triggers & Input
+
+**Gmail Trigger (n8n-nodes-base.gmailTrigger)**
+Purpose: Monitor Gmail for emails with attachments (Recommended over IMAP)
+Advantages: Real-time processing, simpler authentication, better integration with Google Workspace
+Critical Configuration for Attachments:
+- **MUST set "Simplify" to FALSE** - otherwise attachments won't be available
+- **MUST set "Download Attachments" to TRUE** to retrieve files
+- Set appropriate label filters
+- Set "Property Prefix Name" (e.g., "attachment_") - attachments will be named with this prefix plus index
+- Important: When referencing its binary data, it will be referenced "attachment_0", "attachment_1", etc., NOT "data"
+
+**Email Read (IMAP) (n8n-nodes-base.emailReadImap)**
+Purpose: Alternative email fetching if there's no specialized node for email provider
+Configuration:
+- Enable "Download Attachments" to retrieve files
+- Set "Property Prefix Name" (e.g., "attachment_") - attachments will be named with this prefix plus index
+- Important: When referencing binary data, it will be referenced "attachment_0", "attachment_1", etc., NOT "data"
+
+**HTTP Webhook (n8n-nodes-base.webhook)**
+Purpose: Receive file uploads from web forms
+Configuration: Enable "Raw Body" for binary data
+
+**Google Drive Trigger (n8n-nodes-base.googleDriveTrigger)**
+Purpose: Monitor folders for new documents
+Configuration: Set appropriate folder and file type filters
+
+### Text Extraction
+
+**Extract from File (n8n-nodes-base.extractFromFile)**
+Purpose: Extract text from various file formats using format-specific operations
+Critical: ALWAYS check file type first with an IF or Switch before and select the correct operation (Extract from PDF, Extract from MS Excel, etc.)
+Critical: If the user requests handling of multiple file types (PDF, CSV, JSON, etc) then a Switch (n8n-nodes-base.switch) node should be used
+to check the file type before text extraction. Multiple text extraction nodes should be used to handle each of the different file types. For example,
+if the workflow contains a form trigger node which receives a file, then a Switch node MUST be used to split the different options out to different extraction nodes.
+Output: Extracted text is returned under the "text" key in JSON (e.g., access with {{ $json.text }})
+Pitfalls:
+- Returns empty for scanned documents - always check and fallback to OCR; Using wrong operation causes errors
+- If connecting to a document upload form (n8n-nodes-base.formTrigger) use a File field type and then connect it to the extract from file node using the field name.
+For example if creating a form trigger with field "Upload Document" then set the extract from file input binary field to "Upload_Document"
+
+**AWS Textract (n8n-nodes-base.awsTextract)**
+Purpose: Advanced OCR with table and form detection
+Best for: Structured documents like invoices and forms
+
+**Mindee (n8n-nodes-base.mindee)**
+Purpose: Specialized invoice and receipt parsing
+Returns: Structured JSON with line items, totals, dates
+
+### Data Processing
+
+**AI Agent (@n8n/n8n-nodes-langchain.agent)**
+Purpose: Intelligent document parsing and decision making
+Configuration: Include structured output tools for consistent results
+
+**LLM Chain (@n8n/n8n-nodes-langchain.chainLlm)**
+Purpose: Document classification and data extraction
+
+**Document Loader (@n8n/n8n-nodes-langchain.documentLoader)**
+Purpose: Load and process documents directly from binary data for AI processing
+Critical: Use the "Binary" data source option to handle binary files directly - no need to convert to JSON first
+Configuration: Select "Binary" as Data Source, specify the binary property name (by default data unless renamed in a previous node)
+Best for: Direct document processing in AI workflows without intermediate extraction steps
+
+**Structured Output Parser (@n8n/n8n-nodes-langchain.outputParserStructured)**
+Purpose: Ensure AI outputs match expected JSON schema
+Critical for: Database inserts and API calls
+
+### Vector Storage (for RAG/Semantic Search)
+**Simple Vector Store (@n8n/n8n-nodes-langchain.vectorStore) - RECOMMENDED**
+Purpose: Easy-to-setup vector storage for document embeddings
+Advantages:
+- No external dependencies or API keys required
+- Works out of the box with local storage
+- Perfect for prototyping and small to medium datasets
+Configuration: Just connect and use - no complex setup needed
+Best for: Most document processing workflows that need semantic search
+
+### Flow Control
+
+**Split In Batches (n8n-nodes-base.splitInBatches)**
+Purpose: Process multiple documents in controlled batches
+Configuration: Set batch size based on API limits and memory
+Outputs (in order):
+- Output 0 "done": Executes after all batches are processed - use for final aggregation or notifications
+- Output 1 "loop": Connect processing nodes here - executes for each batch
+Important: Connect processing logic to the second output (loop), completion logic to the first output (done)
+
+**Merge (n8n-nodes-base.merge)**
+Purpose: Combine data from multiple branches that need to execute together
+Critical: Merge node waits for ALL input branches to complete - do NOT use for independent/optional branches
+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" 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
+Configuration: Automatically receives data from the calling workflow including binary data
+Best practice: Use for modular workflow design, heavy processing tasks, or reusable workflow components
+Pairing: Must be used with Execute Workflow node in the parent workflow
+
+**Execute Workflow (n8n-nodes-base.executeWorkflow)**
+Purpose: Call and execute another workflow from within the current workflow
+Critical configurations:
+- Workflow ID: Use expression "{{ $workflow.id }}" to reference sub-workflows in the same workflow
+- Choose execution mode: "Run Once for All Items" or "Run Once for Each Item"
+- Binary data is automatically passed to the sub-workflow
+Best practice: Use for delegating heavy processing, creating reusable modules, or managing memory in large batch operations
+
+### Data Destinations
+
+**DataTable (n8n-nodes-base.dataTable)**
+Purpose: Store extracted data in n8n's built-in data tables
+Operations: Insert, Update, Select rows without external dependencies
+Best for: Self-contained workflows that don't require external storage
+
+**Google Sheets (n8n-nodes-base.googleSheets)**
+Purpose: Log extracted data in external spreadsheet
+Operations: Use "Append" for new rows, "Update" with key column for existing
+Best for: Collaborative review and manual data validation
+
+**Database Nodes**
+- Postgres (n8n-nodes-base.postgres)
+- MySQL (n8n-nodes-base.mySql)
+- MongoDB (n8n-nodes-base.mongoDb)
+Purpose: Store structured extraction results in production databases
+Best Practice: Validate data schema before insert
+
+### Utilities
+
+**IF/Switch (n8n-nodes-base.if, n8n-nodes-base.switch)**
+Purpose: Route based on file type, extraction quality, or classification
+
+**Function/Code (n8n-nodes-base.function, n8n-nodes-base.code)**
+Purpose: Custom validation, data transformation, or regex extraction
+
+**HTTP Request (n8n-nodes-base.httpRequest)**
+Purpose: Call external OCR APIs (OCR.space, Google Vision, Mistral OCR)
+Configuration: Set "Response Format: File" for downloads
+Critical: NEVER set API keys directly in the request - user can set credentials from the UI for secure API key management
+
+## Common Pitfalls to Avoid
+
+### Binary Data Loss
+
+**Problem**: Binary file "disappears" after processing nodes
+**Solution**:
+- Use Merge node to reattach binary after processing
+- Or configure nodes to explicitly keep binary data
+- In Code nodes: copy items[0].binary to output
+
+### Incorrect OCR Fallback
+
+**Problem**: Not detecting when text extraction fails
+**Solution**:
+- Always check if extraction result is empty
+- Implement automatic OCR fallback for scanned documents
+- Don't assume all PDFs have extractable text
+
+### API Format Mismatches
+
+**Problem**: Sending files in wrong format to APIs
+**Solution**:
+- Check if API needs multipart/form-data vs Base64
+- Use "Extract from File" and "Convert to File" format conversion
+
+### Memory Overload
+
+**Problem**: Workflow crashes with large or multiple files
+**Solution**:
+- Process files sequentially or in small batches
+- Enable filesystem mode for binary data storage
+- Drop unnecessary data after extraction
+- Create a sub-workflow in the same workflow using "When Executed by Another Workflow" and "Execute Workflow". Delegate the heavy part of the workflow to the sub-workflow.
+
+### Duplicate Processing
+
+**Problem**: Same documents processed repeatedly
+**Solution**:
+- Configure email triggers to mark as read
+- Use "unseen" filters for email fetching
+- Implement deduplication logic based on file hash or name
+`;
+}
+//# sourceMappingURL=document-processing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-processing.js","sourceRoot":"","sources":["../../../../src/tools/best-practices/guides/document-processing.ts"],"names":[],"mappings":";;AAAA,4CAiUC;AAjUD,SAAgB,gBAAgB;IAC/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+TP,CAAC;AACF,CAAC"}

package/dist/tools/best-practices/guides/form-input.d.ts

@@ -0,0 +1 @@
+export declare function getDocumentation(): string;

package/dist/tools/best-practices/guides/form-input.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocumentation = getDocumentation;
+function getDocumentation() {
+    return `# Best Practices: Form Input Workflows
+
+## Workflow Design
+
+### Critical: Always Store Raw Form Data
+
+ALWAYS store raw form responses to a persistent data storage destination even if the primary purpose of the workflow is
+to trigger another action (like sending to an API or triggering a notification). This allows users to monitor
+form responses as part of the administration of their workflow.
+
+Required storage destinations include:
+- Google Sheets node
+- Airtable node
+- n8n Data Tables
+- PostgreSQL/MySQL/MongoDB nodes
+- Any other database or spreadsheet service
+
+IMPORTANT: Simply using Set or Merge nodes is NOT sufficient. These nodes only transform data in memory - they do not
+persist data. You must use an actual storage node (like Google Sheets, Airtable, or Data Tables) to write the data.
+
+Storage Requirements:
+- Store the un-edited user input immediately after the form steps are complete
+- Do not store only a summary or edited version of the user's inputs - store the raw data
+- For single-step forms: store immediately after the form trigger
+- For multi-step forms: store immediately after aggregating all steps with Set/Merge nodes
+- The storage node should appear in the workflow right after data collection/aggregation
+
+## Message Attribution
+
+n8n forms attach the attribution "n8n workflow" to messages by default - you must disable this setting which will
+often be called "Append n8n Attribution" for the n8n form nodes, add this setting and set it to false.
+
+## Multi-Step Forms
+
+Build multi-step forms by chaining multiple Form nodes together. Each Form node represents a page or step in your form
+sequence. Use the n8n Form Trigger node to start the workflow and display the first form page to the user.
+
+## Data Collection & Aggregation
+
+Collect and merge all user responses from each form step before writing to your destination (e.g., Data Table). Use
+Set or Merge nodes to combine data as needed. Make sure your JSON keys match the column names in your destination for
+automatic mapping.
+
+## Conditional Logic & Branching
+
+Use IF or Switch nodes to direct users to different form pages based on their previous answers. This enables dynamic
+form flows where the path changes based on user input, creating personalized form experiences.
+
+## Dynamic Form Fields
+
+For forms that require dynamic options (e.g., dropdowns populated from an API or previous step), generate the form
+definition in a Code node and pass it to the Form node as JSON. You can define forms using JSON for dynamic or
+conditional fields, and even generate form fields dynamically using a Code node if needed.
+
+## Input Validation
+
+Validate user input between steps to ensure data quality. If input is invalid, loop back to the relevant form step with
+an error message to guide the user to correct their submission. This prevents bad data from entering your system.
+
+## Recommended Nodes
+
+### n8n Form Trigger (n8n-nodes-base.formTrigger)
+
+Purpose: Starts the workflow and displays the first form page to the user
+
+Pitfalls:
+
+- Use the Production URL for live forms; the Test URL is for development and debugging only
+- Ensure the form trigger is properly configured before sharing URLs with users
+
+### n8n Form (n8n-nodes-base.form)
+
+Purpose: Displays form pages in multi-step form sequences
+
+Pitfalls:
+
+- Each Form node represents one page/step in your form
+- You can define forms using JSON for dynamic or conditional fields
+- Generate form fields dynamically using a Code node if needed for complex scenarios
+
+### Storage Nodes
+
+Purpose: Persist raw form data to a storage destination, preference should be for built-in n8n tables
+but use the most applicable node depending on the user's request.
+
+Required nodes (use at least one):
+- Data table (n8n-nodes-base.dataTable): Built-in n8n storage for quick setup - preferred
+- Google Sheets (n8n-nodes-base.googleSheets): Best for simple spreadsheet storage
+- Airtable (n8n-nodes-base.airtable): Best for structured database with relationships
+- Postgres (n8n-nodes-base.postgres) / MySQL (n8n-nodes-base.mySql) / MongoDB (n8n-nodes-base.mongoDb): For production database storage
+
+Pitfalls:
+
+- Every form workflow MUST include a storage node that actually writes data to a destination
+- Set and Merge nodes alone are NOT sufficient - they only transform data in memory
+- The storage node should be placed immediately after the form trigger (single-step) or after data aggregation (multi-step)
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Processes form data, generates dynamic form definitions, or implements custom validation logic
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Aggregates and transforms form data between steps (NOT for storage - use a storage node)
+
+### Merge (n8n-nodes-base.merge)
+
+Purpose: Combines data from multiple form steps into a single dataset (NOT for storage - use a storage node)
+
+Pitfalls:
+
+- Ensure data from all form steps is properly merged before writing to destination
+- Use appropriate merge modes (append, merge by key, etc.) for your use case
+- Remember: Merge prepares data but does not store it - add a storage node after Merge
+
+### If (n8n-nodes-base.if)
+
+Purpose: Routes users to different form pages based on their previous answers
+
+### Switch (n8n-nodes-base.switch)
+
+Purpose: Implements multi-path conditional routing in complex forms
+
+Pitfalls:
+
+- Include a default case to handle unexpected input values
+- Keep routing logic clear and maintainable
+
+## Common Pitfalls to Avoid
+
+### Missing Raw Form Response Storage
+
+When building n8n forms it is recommended to always store the raw form response to some form of data storage (Googlesheets, Airtable, etc)
+for administration later. It is CRITICAL if you create a n8n form node that you store the raw output with a storage node.
+
+### Data Loss in Multi-Step Forms
+
+Aggregate all form step data using Set/Merge nodes before writing to your destination. Failing to merge data from multiple steps
+can result in incomplete form submissions being stored. After merging, ensure you write the complete dataset to a storage node.
+
+### Poor User Experience
+
+Use the Form Ending page type to show a completion message or redirect users after submission.
+Without a proper ending, users may be confused about whether their submission was successful.
+
+### Invalid Data
+
+Implement validation between form steps to catch errors early. Without validation, invalid data can
+propagate through your workflow and corrupt your destination data.
+
+### Complex Field Generation
+
+When generating dynamic form fields, ensure the JSON structure exactly matches what the Form
+node expects. Test thoroughly with the Test URL before going live.
+
+### Mapping Errors
+
+When writing to Google Sheets or other destinations, ensure field names match exactly. Mismatched names
+will cause data to be written to wrong columns or fail entirely.
+`;
+}
+//# sourceMappingURL=form-input.js.map

package/dist/tools/best-practices/guides/form-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-input.js","sourceRoot":"","sources":["../../../../src/tools/best-practices/guides/form-input.ts"],"names":[],"mappings":";;AAAA,4CAiKC;AAjKD,SAAgB,gBAAgB;IAC/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+JP,CAAC;AACF,CAAC"}

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

@@ -0,0 +1 @@
+export declare function getDocumentation(): string;