Metabase BI Connector

Overview

The connector reads three Metabase asset types over the Metabase REST API and keeps a local mirror of them inside Odoo. It is import-only: nothing is ever written back to Metabase. It covers:

• Databases — every data source registered in Metabase, with its name and engine. Imported from GET /api/database into metabase.database.

• Questions (cards) — saved questions with their chart type (the Metabase display value) and a link to the parent Metabase database. Imported from GET /api/card into metabase.question.

• Dashboards — dashboards with their collection. Imported from GET /api/dashboard into metabase.dashboard.

Direction of sync: Odoo ← Metabase (read-only catalog). The connector never creates, updates or deletes anything in Metabase; it only catalogs metadata about your BI assets inside Odoo.

Databases are imported before questions, so each question can resolve its parent database. 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. Depends only on base and mail, which are always present.

• Metabase: a reachable Metabase server that supports API-key authentication (the x-api-key header) on its REST API. The connector reads /api/database, /api/card and /api/dashboard.

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

• Odoo access: any internal user can use the connector screens. The Metabase 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 the Odoo server to your Metabase server. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see Safety features).

Installation

1. Copy bambooforge_metabase_connector into your Odoo addons path.

2. Restart the Odoo service.

3. Open Apps, click Update Apps List, search for Metabase, and press Activate / Install.

No Metabase server is required to evaluate the connector: a mock Metabase REST 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 server.

Step 1 — Create an API key in Metabase

The connector authenticates with a single Metabase API key, sent on every request as the x-api-key HTTP header. Create one in Metabase:

1. Sign in to Metabase as an administrator.

2. Open the gear menu and go to Admin settings ▸ Authentication ▸ API keys (on some builds: Admin settings ▸ Settings ▸ API keys).

3. Click Create API key.

4. Give it a name such as Odoo and assign it to a group that can read your databases, questions and dashboards. Read access is enough — the connector never writes.

5. Click Create and copy the generated key. It is shown once.

You will paste this key into Odoo in Step 2.

Step 2 — Create the connection in Odoo

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

Key fields:

Then click Test Connection. The connector lists your Metabase databases as a lightweight auth + connectivity check; 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 default flows, field mappings and a recommended schedule 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 changing data they produce Validation Results you can review under Metabase Connector ▸ Operations ▸ Validation Results. This lets you confirm what would happen before anything is written.

To run a first import:

1. On the instance, open the Import tab and click Queue Database Import (and/or Queue Question Import, Queue Dashboard Import). This enqueues jobs; it does not block the UI. Queueing questions imports databases first so each question resolves its parent database.

2. Jobs are processed by the Metabase 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 catalog records for real.

Imported records land in Metabase Connector ▸ Catalog: Databases, Questions and Dashboards. Each carries its Metabase external ID, so re-imports update the same record instead of duplicating it. A question shows its chart type and is linked to its database.

Field mapping & customization

• Field Mappings (Configuration) map Metabase fields to the Odoo catalog fields per entity. Use Suggest Mappings on the instance to seed the core ones, then adjust.

• Schema Fields lists the discovered Metabase fields per entity. Run Schema Introspection on the instance to refresh it: it samples one live Metabase record per entity (falling back to the bundled mock when the API is unreachable) and flattens its shape next to the Odoo target fields.

• Import limits are per-entity dials on the instance — Databases import limit (default 100), Questions import limit (default 200), Dashboards import limit (default 200) — capping how many remote IDs each import enqueues.

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 (Import tab) to let the scheduled actions keep the catalog current hands-free.

Webhooks: this connector is a pull-only importer, so there is no webhook intake. A route exists at /metabase/webhook only so anything still pointed at it gets a clear not supported reply (HTTP 501) instead of a 404; a genuine push path is a roadmap item, not part of this read-only version. Keep the catalog current with the scheduled actions above.

Safety features

• Dry-run mode — simulate writes and review Validation Results before going live. Controlled by Dry-run on the instance (ON by default).

• Pre-flight validation — Minimal / Standard / Strict business-validation profiles gate risky writes. Controlled by Validation and Business validation profile.

• Resilient queue — every import action is a job with retry and exponential back-off (Retry limit, Backoff policy, Backoff base/cap minutes). HTTP calls additionally retry transient failures (API retry limit, default 2).

• Circuit breaker — after repeated failures (Auto pause threshold, default 5) an instance auto-pauses (Tripped); the Auto Recover action reopens it once the server responds again. Auth/configuration errors trip it immediately.

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

• SSRF guard — the connector refuses internal/loopback/private hosts (and cloud-metadata addresses such as 169.254.169.254) 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 Metabase side, any server whose REST API supports API-key authentication via the x-api-key header and the /api/database, /api/card and /api/dashboard endpoints. Validate your exact build with the bundled mock first.

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

How does authentication work? Create a Metabase API key under Admin settings ▸ Authentication ▸ API keys and paste it into the instance. The connector sends it as the x-api-key header on every request. There is no username/password and no token exchange.

Does this write anything back to Metabase? No. The connector is read-only by design: it only lists and reads your databases, questions and dashboards. It never creates, updates or deletes anything in Metabase.

Is there real-time / webhook sync? No. This is a pull-only importer; the /metabase/webhook route is a stub that answers not supported. Use the scheduled Reconciliation and Auto import to keep the catalog current. A push path is a roadmap item.

Is it safe to run against production data? Yes. The connector never touches your Metabase data. 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 metadata only — database names and engines, question names/chart types and their database link, and dashboard names/collections — and writes the corresponding Odoo catalog records. It does not read or copy the rows inside your databases, nor the result data of any question. The Metabase API key and webhook secret are stored in admin-only fields.

• In scope today: read-only import of Metabase databases, questions (cards) and dashboards into Odoo; scheduled reconciliation; dry-run, validation and rollback safety; schema introspection; field-mapping suggestions; a bundled mock for evaluation.

• Out of scope / roadmap: any write-back to Metabase; webhook/push intake (the route is a neutralized stub); incremental list filtering by timestamp (v1 lists by cursor pagination); importing question result data or query definitions.

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 / Metabase REST 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