@awesomate/hosting-mcp/skill/awesomate-n8n/references/vendor/node-configuration/SKILL.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

<!--
  VENDORED from n8n-builder@d293559 (n8n-node-configuration/SKILL.md) — DO NOT EDIT HERE.
  Edit the source in ~/Projects/n8n-builder, then re-run:
    node mcp/scripts/sync-n8n-references.mjs --write

  Awesomate platform overrides — where this file conflicts with
  ../platform-notes.md, platform-notes wins:
    - $env is BLOCKED fleet-wide → use {{ $vars.key || 'fallback' }}
    - Task runners are ON → no $helpers in Code nodes; use HTTP Request nodes
    - Webhook payloads live at $json.body
    - saveExecutionProgress must stay false
-->

# 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:
- Start from the operation patterns in this skill ([OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)) — they cover the most-used nodes
- Consult n8n's official docs (docs.n8n.io) for nodes or operations not covered here
- Always produce complete node JSON with `resource` and `operation` set together

**Key insight**: Most configurations need only the required fields for the chosen operation, not every possible option!

---

## 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 — always set them together!

### 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. Finding Requirements Without Tools

In the claude.ai app there is no live n8n schema access. Determine requirements by:

1. **Operation patterns in this skill** - [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md) covers the top 20 nodes with minimal valid configs
2. **Official docs** - docs.n8n.io documents every node's operations and fields
3. **The n8n editor itself** - the user opens the node in their editor; missing or invalid required fields show warnings in the parameter panel

---

## Configuration Workflow

### Standard Process

```
1. Identify node type and operation
   ↓
2. Check OPERATION_PATTERNS.md / docs.n8n.io for requirements
   ↓
3. Write complete node JSON (resource + operation + required fields)
   ↓
4. User applies it in the n8n editor
   (paste via Workflow → Import from Clipboard, or configure the parameter panel)
   ↓
5. User opens the node — warnings flag missing/invalid required fields
   ↓
6. Add optional fields as needed
   ↓
7. User re-checks in the editor, then executes the node to verify
```

### Example: Configuring HTTP Request

**Step 1**: Identify what you need
```javascript
// Goal: POST JSON to API
```

**Step 2**: Check the pattern
The POST-with-JSON pattern (see [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)) requires: method, url, sendBody, body.

**Step 3**: Write the complete configuration
```javascript
{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true,                       // Required for POST with body
  "body": {                               // Required when sendBody=true
    "contentType": "json",
    "content": {
      "name": "={{$json.name}}",
      "email": "={{$json.email}}"
    }
  }
}
```

**Step 4**: Verify in the editor
The user pastes the node into their n8n editor and opens it — a missing `sendBody` or `body` would show a warning in the parameter panel. Execute the node with test data to confirm.

---

## 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
}
```

### Finding Property Dependencies

**Use the n8n editor**: add the node, toggle the controlling field (e.g. `sendBody`, `operation`), and watch which fields appear or disappear in the parameter panel — that IS the displayOptions rule in action.

**Or check docs.n8n.io**: each node's docs list fields per operation.

**Use this when**: the editor warns about a missing field you don't see, or a field seems to vanish after changing another value.

---

## 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. Check the operation's requirements (this skill's patterns or docs.n8n.io)
4. Configure required fields — always include `resource` and `operation` together in the JSON

### 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",
  "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
```javascript
{
  "method": "POST",
  "url": "https://api.example.com/users",
  "authentication": "none",
  "sendBody": true,                     // Required for POST
  "body": {                             // Required when sendBody=true
    "contentType": "json",
    "content": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}
```

### IF Node Examples

#### String Comparison (Binary)
```javascript
{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.status}}",
        "operation": "equals",
        "value2": "active"              // Binary: needs value2
      }
    ]
  }
}
```

#### Empty Check (Unary)
```javascript
{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.email}}",
        "operation": "isEmpty",
        // No value2 - unary operator
        "singleValue": true             // Required for unary operators
      }
    ]
  }
}
```

---

## Handling Conditional Requirements

### Example: HTTP Request Body

**Scenario**: body field required, but only sometimes

**Rule**:
```
body is required when:
  - sendBody = true AND
  - method IN (POST, PUT, PATCH, DELETE)
```

**How to discover**:
- The editor's parameter panel warns when body is enabled but empty
- docs.n8n.io HTTP Request page documents the body options per method
- Start from the minimal patterns in this skill and add only what the operation needs

### Example: IF Node singleValue

**Scenario**: singleValue property applies to unary operators

**Rule**:
```
singleValue should be true when:
  - operation IN (isEmpty, isNotEmpty, true, false)
```

Include `"singleValue": true` in the JSON for unary operators, and omit `value2`. (The n8n editor normalizes this structure when the node is configured through the UI.)

---

## Configuration Anti-Patterns

### ❌ Don't: Over-configure Upfront

**Bad**:
```javascript
// Adding every possible field
{
  "method": "GET",
  "url": "...",
  "sendQuery": false,
  "sendHeaders": false,
  "sendBody": false,
  "timeout": 10000,
  "ignoreResponseCode": false,
  // ... 20 more optional fields
}
```

**Good**:
```javascript
// Start minimal
{
  "method": "GET",
  "url": "...",
  "authentication": "none"
}
// Add fields only when needed
```

### ❌ Don't: Skip Editor Verification

**Bad**: Hand over node JSON and call it done.

**Good**: Tell the user to open the node in their n8n editor — missing or invalid required fields show warnings in the parameter panel — and execute it with test data before relying on it.

### ❌ Don't: Ignore Operation Context

**Bad**:
```javascript
// Same config for all Slack operations
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",
  "text": "..."
}

// Then switching operation without updating config
{
  "resource": "message",
  "operation": "update",  // Changed
  "channel": "#general",  // Wrong field for update!
  "text": "..."
}
```

**Good**: When the operation changes, re-check that operation's requirements (update needs `messageId`, not `channel`) and rewrite the config for the new context.

---

## Best Practices

### ✅ Do

1. **Start from known patterns**
   - [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md) has minimal valid configs for the top 20 nodes
   - docs.n8n.io covers the rest

2. **Always set resource + operation together**
   - They jointly determine every other requirement
   - Never emit one without the other

3. **Verify in the n8n editor**
   - Open the node — warnings flag missing/invalid required fields
   - Execute with test data before relying on the configuration

4. **Respect operation context**
   - Different operations = different requirements
   - Re-check requirements whenever the operation changes
   - Don't assume configs are transferable

5. **Iterate**
   - Configure minimal → verify in editor → add what's flagged → repeat
   - 2-3 iterations is normal

### ❌ Don't

1. **Configure blindly**
   - Understand why fields are required
   - Watch the parameter panel to learn what controls conditional fields

2. **Copy configs without understanding**
   - Different operations need different fields
   - Adjust for the new context and re-verify in the editor

3. **Guess field names for unfamiliar nodes**
   - Check docs.n8n.io or have the user read the field names off their editor's parameter panel

---

## Detailed References

For comprehensive guides on specific topics:

- **[DEPENDENCIES.md](DEPENDENCIES.md)** - Deep dive into property dependencies and displayOptions
- **[OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)** - Common configuration patterns by node type

---

## Summary

**Configuration Strategy**:
1. Identify node type and operation
2. Look up requirements (this skill's patterns, then docs.n8n.io)
3. Write complete node JSON with resource + operation + required fields
4. User applies it in their n8n editor and checks for warnings
5. Iterate until the node executes cleanly

**Key Principles**:
- **Operation-aware**: Different operations = different requirements
- **Progressive disclosure**: Start minimal, add as needed
- **Dependency-aware**: Understand field visibility rules
- **Editor-verified**: The n8n parameter panel is the ground truth

**Related Skills**:
- **n8n Validation Expert** - Interpret editor/execution errors
- **n8n Expression Syntax** - Configure expression fields
- **n8n Workflow Patterns** - Apply patterns with proper configuration