n8n-nodes-symao

Official n8n community node for sending metadata-only workflow outcomes and operational signals to Symao Portal.

Installation

Install @joshuanode/n8n-nodes-symao through Settings > Community Nodes in n8n. Symao Portal is available only to Symao Automation Partner customers.

Credentials

Create an ingestion credential for the customer environment in Symao Portal, copy the token once, and save it in an n8n Symao Portal API credential. Each token is bound to one customer workspace and is write-only; it cannot read portal data.

Use a separate credential for each customer environment. The node sends telemetry only to https://portal.symaosystems.com; the destination cannot be changed from a workflow credential.

Operations

• Completed Work records a positive quantity of completed business outcomes. Configure its business-friendly outcome name, time saved per unit, and job role in the node. The Portal snapshots that definition for every event and applies Portal-managed labor rates and FTE assumptions. Existing nodes with those fields blank continue using legacy Portal-managed models.
• Expected Exception records expected paths that prevent straight-through automation.
• Manual Work Needed records work that still required a person.
• Business Failure records customer-safe business/domain errors. General n8n execution failures are collected separately through the n8n API to avoid double counting.
• Advanced Metric records a registered counter, gauge, or duration value.
• Process Milestone records process progress for cycle-time and SLA reporting.

The node batches up to 25 events per request while still emitting one API receipt for every input item and preserving n8n item pairing. Each receipt identifies whether the event was accepted or duplicated, matched to a collected workflow, covered by a measurement model, and included in reporting or retained as test data. Enable n8n's Continue On Fail setting when a telemetry delivery failure should not stop the business workflow.

For self-service reporting, choose Eligible Request Completion. Provide a stable internal request ID, request type, and fulfillment mode. The node hashes the request ID locally, emits one deduplicated eligible-request fact, and never sends the raw ID. Staffing, endpoint inventory, service-quality, and Symao delivery-time inputs belong in Portal administration or dedicated connectors rather than customer workflows.

Data safety

This node is deliberately metadata-only. Never place workflow input/output bodies, provider responses, authorization headers, secrets, stack traces, names, email addresses, or customer record content into a summary or metadata field.

The node automatically sends only source identifiers required for correlation: n8n instance, workflow, execution, execution mode, node, operation, timestamp, and idempotency key. Manual and evaluation executions are retained as test telemetry and excluded from customer reporting. Custom metadata is flat, string-only, length-bounded, limited to six entries, and selected from Portal's supported metadata keys. The workflow designer supplies the operational time estimate and job-role name; hourly wages, subscription costs, FTE assumptions, and dollar calculations are never sent from n8n.

Idempotency

By default, the node derives a deterministic key from the n8n instance, workflow, execution, node run, input item, and operation. This suppresses normal retries and keeps repeated loop runs within one execution distinct.

For deduplication across entirely separate workflow executions, set Business Record ID to a stable internal ticket, alert, request, asset, or provider record identifier. The node hashes that value locally together with the workflow, node, operation, and outcome key; the raw value is never transmitted. Do not use names, email addresses, or other personal identifiers. Existing workflows using Legacy Idempotency Key remain supported, but new workflows should prefer Business Record ID.

Development

npm install
npm run build
npm run lint
npm test
npm pack --dry-run

Only dist is included in the published package.