NocoDB Connector

Overview

The connector reads from the NocoDB REST/Meta API (api/v2) and mirrors the metadata into dedicated Odoo models. It covers:

• Bases — every NocoDB base (database/project) from GET /api/v2/meta/bases, imported into NocoDB Base records (the base id and its title).

• Tables — the tables inside each base from GET /api/v2/meta/bases/<baseId>/tables, imported into NocoDB Table records. Each table links back to its base (resolved from the table's baseId).

• Row counts — a live record count per table, read from GET /api/v2/tables/<tableId>/records?limit=1 -> pageInfo.totalRows and stored on the table at import time.

Direction of sync: Odoo <- NocoDB (import only). This connector never writes to NocoDB — no create, update or delete is ever sent to your workspace. Bases are imported before tables so each table can link back to its base.

Importing the actual table records (the row data itself) is a roadmap item; v1 imports the base/table inventory and row counts only.

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.

• NocoDB: any NocoDB exposing the v2 Meta/REST API (/api/v2/meta/bases, /api/v2/meta/bases/<id>/tables, /api/v2/tables/<id>/records) with xc-token header auth. NocoDB 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 NocoDB API token is stored in a system-only field, so only the Settings / Administration user can read or change it.

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

Installation

1. Copy bambooforge_nocodb_connector into your Odoo addons path.

2. Restart the Odoo service.

3. Open Apps, click Update Apps List, search for NocoDB, and press Activate / Install. The only dependencies are base and mail.

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

Step 1 — Create an API token in NocoDB

NocoDB authenticates with a single API token, sent as the xc-token header on every request. To create one:

1. In NocoDB, open Account Settings (your avatar, top of the sidebar).

2. Go to the Tokens section.

3. Click Create / Add new token, give it a description such as Odoo, and create it.

4. Copy the generated token. You will paste it into Odoo in Step 2.

Because the connector is read-only, the token only ever needs read access to your bases, tables and records.

Step 2 — Create the connection in Odoo

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

Key fields:

Then click Test Connection. The connector lists your bases as a lightweight auth + connectivity check. A green Connected state means the token and URL are correct. If it fails, the exact error is shown on the form and recorded in Logs (see Troubleshooting).

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

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

To run a first import:

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

2. Jobs are processed by the Nocodb 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 NocoDB Connector ▸ Imported Data ▸ Bases and ▸ Tables. Each carries its NocoDB id, so re-imports update the same record instead of duplicating it. Bases are imported before tables so each table links back to its base.

Field mapping & customization

• Field Mappings (Configuration) map NocoDB fields to Odoo fields per entity. Use Generate suggested mappings on the instance to seed the core ones, then adjust.

• Schema Fields lists the discovered fields per entity. Run Schema Introspection on the instance to refresh it: it records the Odoo target fields and samples one live NocoDB record (falling back to the bundled mock when the API is unreachable) so you can see both sides.

• Import limits on the instance cap how much is pulled per run: Bases import limit (default 100) and Tables import limit (default 200), with matching reconcile limits. Raise them if your workspace is larger.

Because the connector is read-only, there are no stock/image/tax/order toggles — it imports the base and table inventory and row counts, nothing more.

Automation (scheduled actions & webhooks)

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

Turn on Auto import / Auto reconcile per entity on the instance (Auto import bases, Auto import tables, Auto reconcile bases, Auto reconcile tables) to let the scheduled actions keep the inventory current hands-free.

Webhooks: this connector is a pull-only importer. The route /nocodb/webhook exists only as a neutralized stub that always answers a clear "not supported" response (HTTP 501) — there is no webhook intake. A genuine push path (NocoDB does support per-table webhooks) is a roadmap item, not part of this read-only v1. The scheduled reconciliation keeps your inventory current without it.

Safety features

• Read-only by design — the connector only ever issues authenticated GET calls to NocoDB. There is no write path, so it cannot create, change or delete anything in your workspace.

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

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

• Resilient queue — every import is a job with retry and exponential back-off (Retry limit, Backoff policy, Backoff base/cap minutes).

• Circuit breaker — after repeated failures (or an auth/configuration error) an instance auto-pauses (Tripped); the Auto Recover action reopens it once NocoDB responds again (Auto-pause threshold, default 5).

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

• SSRF guard — the connector refuses internal/loopback/private/link-local/ reserved hosts unless Allow internal host is explicitly enabled.

Troubleshooting

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

Frequently asked questions

Which versions are supported? Odoo 18.0 on the Odoo side. On the NocoDB side, any server exposing the v2 Meta/REST API with xc-token auth. Validate your exact build with the bundled mock first.

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

How does authentication work? Create an API token in NocoDB under Account Settings ▸ Tokens and paste it into the API Token field. The connector sends it as the xc-token header on every request.

Does the connector write anything to NocoDB? No. It is read-only: every call is an authenticated GET. It cannot create, update or delete bases, tables or records in your workspace.

Does it import the actual rows in my tables? Not in v1. It imports the base/table inventory and a live row count per table. Importing the row data itself is on the roadmap.

How does it keep the inventory current? The scheduled actions (Queue Processor + Reconciliation) re-import on a schedule when you enable Auto import / Auto reconcile. There is no webhook intake.

Is it safe to run against production data? Yes. It only reads from NocoDB, and on the Odoo side dry-run is ON by default, validation gates risky writes, and rollback snapshots let you undo. You decide when to go live.

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 bases, tables and per-table row counts from your NocoDB and writes the corresponding NocoDB Base / NocoDB Table records in Odoo. It never writes back to NocoDB.

• The API token is stored in an administrator-only field.

• In scope today: base import, table import, live row counts, scheduled re-import/reconciliation, dry-run, validation, rollback snapshots, SSRF guard.

• Out of scope / roadmap: importing the actual table records (row data); webhook/push intake from NocoDB; writing any data back to NocoDB.

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 / NocoDB v2 API 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