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

// 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

// 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

// Goal: POST JSON to API

Step 2: Get essentials

const info = get_node_essentials({
  nodeType: "nodes-base.httpRequest"
});

// Returns: method, url, sendBody, body, authentication required/optional

Step 3: Minimal config

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none"
}

Step 4: Validate

validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config,
  profile: "runtime"
});
// → Error: "sendBody required for POST"

Step 5: Add required field

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true
}

Step 6: Validate again

validate_node_operation({...});
// → Error: "body required when sendBody=true"

Step 7: Complete configuration

{
  "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

validate_node_operation({...});
// → Valid! ✅

---

get_node_essentials vs get_node_info

Use get_node_essentials When:

✅ Starting configuration (91.7% success rate)

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

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:

{
  "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

// sendBody controls body visibility
{
  "sendBody": true   // → body field appears
}

Pattern 2: Operation Switch

Example: Slack resource/operation

// 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

{
  "type": "string",
  "operation": "contains"
  // → Shows: value1, value2
}

{
  "type": "boolean",
  "operation": "equals"
  // → Shows: value1, value2, different operators
}

Using get_property_dependencies

Example:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "resource": "message",
  "operation": "post",
  "channel": "#general",      // Required
  "text": "Hello!",           // Required
  "attachments": [],          // Optional
  "blocks": []                // Optional
}

Update Message

{
  "resource": "message",
  "operation": "update",
  "messageId": "1234567890",  // Required (different from post!)
  "text": "Updated!",         // Required
  "channel": "#general"       // Optional (can be inferred)
}

Create Channel

{
  "resource": "channel",
  "operation": "create",
  "name": "new-channel",      // Required
  "isPrivate": false          // Optional
  // Note: text NOT required for this operation
}

HTTP Request Node Examples

GET Request

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "authentication": "predefinedCredentialType",
  "nodeCredentialType": "httpHeaderAuth",
  "sendQuery": true,                    // Optional
  "queryParameters": {                  // Shows when sendQuery=true
    "parameters": [
      {
        "name": "limit",
        "value": "100"
      }
    ]
  }
}

POST with JSON

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "authentication": "none",
  "sendBody": true,  

---

*Content truncated.*