n8n Connector for Workflow Automation

Overview

The connector pulls data from the n8n public API (X-N8N-API-KEY auth, cursor pagination) into dedicated Odoo models. It is import-first and pull-based: every remote call is a read, and nothing is ever pushed back to n8n.

Direction of sync: Odoo ← n8n (read-only monitoring; one-way import).

It covers two entities:

• Workflows — imported into n8n Connector ▸ Imported Data ▸ Workflows (model n8n.workflow). Each record mirrors the n8n workflow shape: name, the Active in n8n flag, node count, trigger count, comma-joined tag names, and the created/updated timestamps from n8n.

• Executions — imported into n8n Connector ▸ Imported Data ▸ Executions (model n8n.execution). Each record mirrors an n8n run: status (Success, Error, Running, Waiting, Unknown), mode (manual / trigger / webhook / …), the Finished flag, started/stopped timestamps, and a best-effort link to the parent workflow once that workflow has also been imported.

Every remote call goes through a queue: nothing is written to Odoo until a job runs, jobs retry with back-off on transient failures, and a circuit breaker pauses an instance that keeps failing.

Requirements

• Odoo: 18.0, Community or Enterprise.

• n8n: any n8n server that exposes the public REST API at /api/v1 with workflows and executions endpoints (self-hosted or n8n Cloud). The server must be reachable from the Odoo server.

• Python: no extra libraries beyond a standard Odoo 18 install.

• Odoo access: any internal user can use the connector screens. The n8n API key and webhook secret are stored in system-only fields, so only the Settings / Administration user can read or change them.

• Network: outbound HTTPS from Odoo to your n8n server. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see Safety features).

Installation

1. Copy bambooforge_n8n_connector into your Odoo addons path.

2. Restart the Odoo service.

3. Open Apps, click Update Apps List, search for n8n, and press Activate / Install. Dependencies (base, mail) install automatically.

No n8n server is required to evaluate the connector: a mock n8n API ships inside the module, so you can install, explore and run the full import flow against sample workflows and executions before pointing it at a real n8n instance.

Step 1 — Create an n8n API key

The connector authenticates with a single n8n API key, sent on every request as the X-N8N-API-KEY header. There is no OAuth and no token exchange.

In your n8n instance:

1. Open Settings ▸ n8n API.

2. Click Create an API key.

3. Give the key a label (e.g. Odoo) and create it.

4. Copy the key shown — it is displayed once. This is the value you paste into Odoo in Step 2.

A read scope is sufficient: the connector only ever issues GET requests to /api/v1/workflows and /api/v1/executions. It never creates, updates or deletes anything in n8n.

Step 2 — Create the connection in Odoo

Open n8n Connector ▸ Configuration ▸ Instances and create a record.

Key fields:

Then click Test Connection. It performs a lightweight GET /api/v1/workflows?limit=1 to validate the key and reachability. A green Connected state means the API key and URL are correct. If it fails, the exact error is recorded on the form (last connection error) and in Logs (see Troubleshooting).

Tip: use Quick Setup (button on the instance) to seed starter flows, default field mappings and a safety profile in one step.

Step 3 — First import (dry-run, then live)

New instances start with Dry-run ON. In dry-run, import jobs simulate writes: instead of creating records they produce Validation Results you can review under n8n Connector ▸ Operations ▸ Validation Results. This lets you confirm what would be imported before anything is written.

To run a first import:

1. On the instance, click Import Workflows (and/or Import Executions). This enqueues jobs; it does not block the UI.

2. Jobs are processed by the N8n Queue Processor scheduled action (every minute), or immediately if you run it manually from Operations ▸ Queue Jobs.

3. Review Validation Results while still in dry-run.

4. When satisfied, open the instance, turn Dry-run OFF, and run the imports again to write the records for real.

Imported records land in n8n Connector ▸ Imported Data ▸ Workflows and ▸ Executions. Each carries its n8n id, so re-imports update the same record instead of duplicating it.

Defaults: a workflow import pulls up to 100 workflows per run and an execution import up to 200 (the Workflows import limit / Executions import limit fields on the instance). The connector follows n8n's cursor pagination across pages automatically.

Field mapping & customization

The two n8n entities have no native Odoo counterpart, so the connector ships dedicated models (n8n.workflow / n8n.execution) and a built-in mapping that already populates the core fields (name, ids, active flag, node/trigger counts, tags, status, mode, finished, timestamps). You do not need to configure anything for a standard import.

To customize:

• Field Mappings (Configuration) let you map additional n8n payload fields to Odoo fields per entity (workflow / execution), with optional transforms and defaults. They are applied on top of the built-in mapping. Use Generate suggested mappings on the instance to seed the common ones, then adjust.

• Schema Fields lists the discovered n8n fields per entity alongside the Odoo target fields. Run Schema Introspection on the instance to refresh it; it samples one live n8n record (falling back to the bundled mock when the API is unreachable) and flattens its shape so you can see the available paths.

• Execution Status Mappings (Configuration) hold per-instance rules seeded on first successful connect. n8n execution statuses are normalized to Success / Error / Running / Waiting / Unknown; any status the mapping does not recognize is stored as Unknown so an unexpected value never breaks an import.

Automation (scheduled actions)

The module ships these scheduled actions (Settings ▸ Technical ▸ Scheduled Actions):

Turn on Auto import / Auto reconcile per entity on the instance (Auto import workflows, Auto import executions, Auto reconcile workflows, Auto reconcile executions) to let the scheduled actions keep the imported data current hands-free.

Webhooks: n8n does not push workflow/execution change notifications to third parties, so this connector is scheduled-pull only. A route exists at /n8n/webhook but it is intentionally inert — it always returns 501 Not Implemented so nothing breaks on install. Keeping data current relies on the reconciliation schedule above, not on inbound webhooks.

Safety features

• Dry-run mode — simulate imports and review Validation Results before going live (field Dry-run mode, ON by default).

• Business validation profiles — Minimal / Standard / Strict gate risky writes (field Business validation profile, default Standard).

• Safety profiles — Conservative / Balanced / Aggressive presets set dry-run, validation, rollback, delete strategy and batch size in one click (field Safety profile, default Balanced).

• Resilient queue — every import is a job with retry and backoff (fixed or exponential, base 1 min, cap 120 min by default) and a dead-letter state.

• Circuit breaker — after repeated failures an instance auto-pauses (Tripped, default threshold 5 consecutive failures); the Auto Recover action reopens it after a 30-minute cooldown once no blocking issues remain.

• Rollback snapshots — when enabled, imports capture a snapshot so you can undo a batch from Operations ▸ Rollback Snapshots (field Rollback enabled, ON by default).

• SSRF guard — the connector refuses internal/loopback/private/link-local/ reserved hosts (including cloud metadata addresses) unless Allow internal host is explicitly enabled.

Troubleshooting

For anything else, Operations ▸ Logs records every API call, payload and error with a timestamp.

Frequently asked questions

Which versions are supported? Odoo 18.0 on the Odoo side. On the n8n side, any server exposing the public REST API at /api/v1 with workflows and executions endpoints (self-hosted or Cloud). Validate your build with the bundled mock first.

Do I need an n8n server to evaluate it? No. A mock n8n API ships inside, so you can install, explore and demo the full import flow before connecting a real server.

How does authentication work? Create one n8n API key under Settings ▸ n8n API and paste it into the instance. The connector sends it as the X-N8N-API-KEY header on every request. No OAuth, no token exchange.

Does it change anything in n8n? No. The connector is read-only: it only issues GET requests to list and fetch workflows and executions. Export to n8n is not supported.

Does it use webhooks for real-time updates? No. n8n does not push workflow/execution change notifications to third parties, so the connector keeps data current on a schedule (the Reconciliation cron). The /n8n/webhook route exists but is inert and returns 501.

Is it safe to run against production data? It only reads from n8n, and on the Odoo side dry-run is ON by default with validation and rollback snapshots. You decide when to write for real.

What support and refund policy do I get? Every request is answered within 24 hours, setup help included. If you report a bug within 2 months of purchase and it is not resolved within 15 days, you are entitled to a full money-back refund.

Data, privacy & limits

• The connector reads workflows and executions from your n8n server and writes the corresponding Odoo n8n.workflow / n8n.execution records. It never writes to n8n. The API key and webhook secret are stored in admin-only fields.

• In scope today: read-only import of workflows and executions, scheduled reconciliation, field mapping, schema introspection, dry-run, validation, rollback snapshots and a multi-step flow engine.

• Out of scope: any write-back to n8n (creating/activating/running workflows), inbound change webhooks, and timestamp-based incremental list filtering on the n8n API (v1 lists by cursor pagination; reconciliation re-lists and queues the delta).

Support & updates

• Support: support@bambooforge.dev — answered within 24 hours, setup help included.

• Refund: report a bug within 2 months of purchase; if unresolved within 15 days, full refund.

• Full source is included. Updates track the supported Odoo 18 / n8n public REST API v1 line.

Upgrading & version compatibility

This build targets Odoo 18.0. Each Odoo major series (17.0, 18.0, 19.0) has its own dedicated build of this module — always install the build that matches your Odoo version. Mixing a build with a different Odoo series is not supported.

Uninstallation

You can remove this module at any time from Apps → (this module) → Uninstall, or from the command line. Uninstalling is clean and reversible by reinstalling — but note what is and is not deleted.

Changelog