---
name: connectwise-n8n-automation
description: Use when automating ConnectWise PSA tasks via n8n workflows.
---

# ConnectWise n8n Automation

Use when automating ConnectWise PSA tasks (fetching tickets, updating owners, summarizing notes) using n8n workflows via MCP.

## Workflow
1. **Identify Workflow**: Search for existing workflows using `mcp__n8n__search_workflows`.
2. **Inspect Schema**: Use `mcp__n8n__get_workflow_details` to understand required input parameters (e.g., `username`, `ticketId`).
3. **Execute**: Use `mcp__n8n__execute_workflow`.
4. **Retrieve Results**: 
    - Use `mcp__n8n__get_execution` with `includeData: true`.
    - If the result is large and truncated to a file (e.g., `/tmp/hermes-results/...`), use `read_file` and `execute_code`.
5. **Verification**: If a workflow is supposed to update data, verify the change by re-fetching the record.

## Pitfalls & Lessons

### 1. Parsing Truncated Tool Outputs
When `mcp__n8n__get_execution` returns a result too large for the context, Hermes saves it to a file. These files are **not** raw JSON; they are line-numbered (e.g., `1|{"result": ...}`).
- **Wrong**: `json.loads(file_content)`
- **Right**: `json_str = line.split('|', 1)[1].strip()` before parsing.

### 2. User Filtering Ambiguity
ConnectWise nodes in n8n may use different fields for "username". 
- If filtering by `SBrown` (identifier) returns 0 results but you know tickets exist, try `Scott Brown` (full name).
- The workflow's internal query often uses `owner/name like ...`, which may require the human-readable name.

### 3. API Auth (n8n vs. Direct)
Direct API calls via `execute_code` (using `requests`) often fail with `401 Unauthorized` even with correct Public/Private keys because they lack the required `clientId` (UUID).
- **Guidance**: Always prefer existing n8n workflows for ConnectWise actions. If no workflow exists, create one using `mcp__n8n__create_workflow_from_code` to leverage n8n's managed credentials.

### 4. Long-Running LLM Workflows
Workflows utilizing AI (e.g., Ollama for summarization) take significantly longer than standard API la calls.
- **Action**: Poll `mcp__n8n__get_execution` multiple times or implement a wait loop in `execute_code` before attempting to read the final results.

### 5. MCP Server Access: Two Servers, Two Tokens, SSE Result Framing
- TWO n8n MCP servers exist: tallerhawk (token in ~/.hermes/.env as N8N_API_KEY) and n8n.vistanetinc.com (token ONLY in config.yaml under mcp_servers). The .env token returns `Unauthorized` against vistanetinc — pull the config.yaml one instead.
- Raw HTTP MCP works: POST to /mcp-server/http with Accept: 'application/json, text/event-stream'; responses are SSE frames. The RESULT frame is the first `data:` frame containing a `result` key (it often has NO `id` key — don't wait for id==1).
- search_workflow_executions: server retains only ~30 recent executions server-wide; `status` filter param is not accepted; filter by workflowId param works but also just filter client-side by scanning. `nextCursor` pagination exists but the retained window is tiny anyway.
- Direct API Auth & Headers: same as below
Direct API calls via `execute_code` (using `requests`) fail with `401 Unauthorized` if the `clientId` and `companyId` are missing from the headers, even if Basic Auth is correct.
- **Required Headers**: 
  - `clientId`: UUID of the client application.
  - `companyId`: The company identifier (e.g., `VNI`).
- **Auth String Format**: The username must be constructed as `companyid+publickey`. If the public key already starts with a `+`, do not add an additional `+` between the company ID and the key (to avoid the "double-plus bug").
- **Correct Base64 Pattern**: `base64(companyid+publickey:privatekey)`.
- **Correction**: Ensure both headers are present alongside Basic Auth. If standard `auth=(user, pass)` parameters fail, manually construct the `Authorization: Basic <base64>` header.

### 7. Trigger-Specific Data Mapping (MCP vs Webhook)
When triggering a workflow via the `execute_workflow` MCP tool, input data is injected at the root level, whereas real HTTP requests put data under the `body` object.
- **Pitfall**: An n8n workflow starting with a Webhook trigger will see an empty `$json.body` when executed via MCP, causing downstream nodes to fail or receive `undefined`.
- **Fix**: Add a **Set (Edit Fields)** node immediately after the trigger to normalize the data using nullish coalescing:
  - `ticketId` $\rightarrow$ `{{ $json.body?.ticketId ?? $json.ticketId }}`
  - `memberId` $\rightarrow$ `{{ $json.body?.memberId ?? $json.memberId }}`
- **Result**: Downstream nodes can now safely use `{{ $json.ticketId }}` regardless of how the workflow was triggered.

### 8. PSA Release Notes Are Not Programmatically Reachable
docs.connectwise.com's PSA release-notes tree is SSO-gated and blocks anonymous datacenter IPs at the CDN edge (every fetch returns a login interstitial; Wayback/archive.today hold zero captures). When asked what a release contains: verify CVE/security-bulletin facts from public bulletins first — those ARE fetchable — then route functional release-note questions to the user (ConnectWise Home release-notes widget on their logged-in console) instead of cycling anonymous recovery ladders. For a full pull, ask the user to save partner-portal credentials to the vault so the docs site can be logged into.