n8n-node-configuration

# n8n Node Configuration Expert guidance for operation-aware node configuration with property dependencies. --- ## Configuration Philosophy **Progressive disclosure**: Start minimal, add complexity as needed Configuration best practices: - get_node_essentials is the most used discovery pattern - 56 seconds average between configuration edits - 91.7% success rate with essentials-based configuration **Key insight**: Most configurations need only essentials, not full schema! --- ## Core Concepts ### 1. Operation-Aware Configuration **Not all fields are always required** - it depends on operation! **Example**: Slack node ```javascript // For operation='post' { "resource": "message", "operation": "post", "channel": "#general", // Required for post "text": "Hello!" // Required for post } // For operation='update' { "resource": "message", "operation": "update", "messageId": "123", // Required for update (different!) "text": "Updated!" // Required for update // channel NOT required for update } ``` **Key**: Resource + operation determine which fields are required! ### 2. Property Dependencies **Fields appear/disappear based on other field values** **Example**: HTTP Request node ```javascript // When method='GET' { "method": "GET", "url": "https://api.example.com" // sendBody not shown (GET doesn't have body) } // When method='POST' { "method": "POST", "url": "https://api.example.com", "sendBody": true, // Now visible! "body": { // Required when sendBody=true "contentType": "json", "content": {...} } } ``` **Mechanism**: displayOptions control field visibility ### 3. Progressive Discovery **Use the right tool for the right job**: 1. **get_node_essentials** (91.7% success rate) - Quick overview - Required fields - Common options - **Use first** - covers 90% of needs 2. **get_property_dependencies** (for complex nodes) - Shows what fields depend on others - Reveals conditional requirements - Use when essentials isn't enough 3. **get_node_info** (full schema) - Complete documentation - All possible fields - Use when essentials + dependencies insufficient --- ## Configuration Workflow ### Standard Process ``` 1. Identify node type and operation ↓ 2. Use get_node_essentials ↓ 3. Configure required fields ↓ 4. Validate configuration ↓ 5. If dependencies unclear → get_property_dependencies ↓ 6. Add optional fields as needed ↓ 7. Validate again ↓ 8. Deploy ``` ### Example: Configuring HTTP Request **Step 1**: Identify what you need ```javascript // Goal: POST JSON to API ``` **Step 2**: Get essentials ```javascript const info = get_node_essentials({ nodeType: "nodes-base.httpRequest" }); // Returns: method, url, sendBody, body, authentication required/optional ``` **Step 3**: Minimal config ```javascript { "method": "POST", "url": "https://api.example.com/create", "authentication": "none" } ``` **Step 4**: Validate ```javascript validate_node_operation({ nodeType: "nodes-base.httpRequest", config, profile: "runtime" }); // → Error: "sendBody required for POST" ``` **Step 5**: Add required field ```javascript { "method": "POST", "url": "https://api.example.com/create", "authentication": "none", "sendBody": true } ``` **Step 6**: Validate again ```javascript validate_node_operation({...}); // → Error: "body required when sendBody=true" ``` **Step 7**: Complete configuration ```javascript { "method": "POST", "url": "https://api.example.com/create", "authentication": "none", "sendBody": true, "body": { "contentType": "json", "content": { "name": "={{$json.name}}", "email": "={{$json.email}}" } } } ``` **Step 8**: Final validation ```javascript validate_node_operation({...}); // → Valid! ✅ ``` --- ## get_node_essentials vs get_node_info ### Use get_node_essentials When: **✅ Starting configuration** (91.7% success rate) ```javascript get_node_essentials({ nodeType: "nodes-base.slack" }); ``` **Returns**: - Required fields - Common options - Basic examples - Operation list **Fast**: ~18 seconds average (from search → essentials) ### Use get_node_info When: **✅ Essentials insufficient** ```javascript get_node_info({ nodeType: "nodes-base.slack" }); ``` **Returns**: - Full schema - All properties - Complete documentation - Advanced options **Slower**: More data to process ### Decision Tree ``` ┌─────────────────────────────────┐ │ Starting new node config? │ ├─────────────────────────────────┤ │ YES → get_node_essentials │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Essentials has what you need? │ ├─────────────────────────────────┤ │ YES → Configure with essentials │ │ NO → Continue │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Need dependency info? │ ├─────────────────────────────────┤ │ YES → get_property_dependencies │ │ NO → Continue │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Still need more details? │ ├─────────────────────────────────┤ │ YES → get_node_info │ └─────────────────────────────────┘ ``` --- ## Property Dependencies Deep Dive ### displayOptions Mechanism **Fields have visibility rules**: ```javascript { "name": "body", "displayOptions": { "show": { "sendBody": [true], "method": ["POST", "PUT", "PATCH"] } } } ``` **Translation**: "body" field shows when: - sendBody = true AND - method = POST, PUT, or PATCH ### Common Dependency Patterns #### Pattern 1: Boolean Toggle **Example**: HTTP Request sendBody ```javascript // sendBody controls body visibility { "sendBody": true // → body field appears } ``` #### Pattern 2: Operation Switch **Example**: Slack resource/operation ```javascript // Different operations → different fields { "resource": "message", "operation": "post" // → Shows: channel, text, attachments, etc. } { "resource": "message", "operation": "update" // → Shows: messageId, text (different fields!) } ``` #### Pattern 3: Type Selection **Example**: IF node conditions ```javascript { "type": "string", "operation": "contains" // → Shows: value1, value2 } { "type": "boolean", "operation": "equals" // → Shows: value1, value2, different operators } ``` ### Using get_property_dependencies **Example**: ```javascript const deps = get_property_dependencies({ nodeType: "nodes-base.httpRequest" }); // Returns dependency tree { "dependencies": { "body": { "shows_when": { "sendBody": [true], "method": ["POST", "PUT", "PATCH", "DELETE"] } }, "queryParameters": { "shows_when": { "sendQuery": [true] } } } } ``` **Use this when**: Validation fails and you don't understand why field is missing/required --- ## Common Node Patterns ### Pattern 1: Resource/Operation Nodes **Examples**: Slack, Google Sheets, Airtable **Structure**: ```javascript { "resource": "<entity>", // What type of thing "operation": "<action>", // What to do with it // ... operation-specific fields } ``` **How to configure**: 1. Choose resource 2. Choose operation 3. Use get_node_essentials to see operation-specific requirements 4. Configure required fields ### Pattern 2: HTTP-Based Nodes **Examples**: HTTP Request, Webhook **Structure**: ```javascript { "method": "<HTTP_METHOD>", "url": "<endpoint>", "authentication": "<type>", // ... method-specific fields } ``` **Dependencies**: - POST/PUT/PATCH → sendBody available - sendBody=true → body required - authentication != "none" → credentials required ### Pattern 3: Database Nodes **Examples**: Postgres, MySQL, MongoDB **Structure**: ```javascript { "operation": "<query|insert|update|delete>", // ... operation-specific fields } ``` **Dependencies**: - operation="executeQuery" → query required - operation="insert" → table + values required - operation="update" → table + values + where required ### Pattern 4: Conditional Logic Nodes **Examples**: IF, Switch, Merge **Structure**: ```javascript { "conditions": { "<type>": [ { "operation": "<operator>", "value1": "...", "value2": "..." // Only for binary operators } ] } } ``` **Dependencies**: - Binary operators (equals, contains, etc.) → value1 + value2 - Unary operators (isEmpty, isNotEmpty) → value1 only + singleValue: true --- ## Operation-Specific Configuration ### Slack Node Examples #### Post Message ```javascript { "resource": "message", "operation": "post", "channel": "#general", // Required "text": "Hello!", // Required "attachments": [], // Optional "blocks": [] // Optional } ``` #### Update Message ```javascript { "resource": "message", "operation": "update", "messageId": "1234567890", // Required (different from post!) "text": "Updated!", // Required "channel": "#general" // Optional (can be inferred) } ``` #### Create Channel ```javascript { "resource": "channel", "operation": "create", "name": "new-channel", // Required "isPrivate": false // Optional // Note: text NOT required for this operation } ``` ### HTTP Request Node Examples #### GET Request ```javascript { "method": "GET",