Skip to main content
Connectors bring external business records into Mandala and expose narrowly defined capabilities to agents. A connector is not considered ready merely because rows were imported once: Mandala tracks its installation, grants, schema version, health, sync state, and data freshness separately.

​
Connector layers

An agent compiles only when its required capability can be resolved through all of these layers.

​
Current connectors

The repository contains:
  • Synthetic commerce: credential-free Mandala Bean Co. data and mock procurement capabilities for repeatable tests.
  • ShipHero: catalog, inventory, sales, purchase-order, and vendor data sync.
  • Trello: supporting business and open-order records used by workspace questions and procurement coverage.
Connector credentials are server-only. They must never appear in terminal output, model prompts, work items, traces, or Context Engine documents.

​
Workspace data catalog

Imported records are profiled into a workspace data catalog. The catalog records dataset identity, shape, maintained counts, freshness, source coverage, and a schema fingerprint. Capability mapping versions connect a skill’s declared business fields to concrete catalog datasets. Activated agents bind to an immutable mapping version so a later connector change cannot silently reinterpret an existing workflow. Before a real-data Sandbox or manual agent run, Mandala checks that the mapping still matches the current catalog. Catalog drift triggers a refresh or blocks the run instead of guessing.

​
Sync lifecycle

The connector worker:
  1. claims an enabled installation;
  2. authenticates with the provider using server-side credentials;
  3. fetches a bounded page of records;
  4. normalizes records and source links;
  5. upserts snapshots with stable external ids;
  6. advances a signed pagination cursor;
  7. records success, error, and freshness state; and
  8. publishes changed-record events for downstream catalog and Context Engine work.
Periodic reconciliation is a backup. Provider changes should normally flow through connector sync and changed-record events.

​
Health and freshness

Mandala treats these as different questions:
  • Installed: does the workspace have a connector record?
  • Authenticated: can the server use the configured credentials?
  • Granted: may this workspace use a particular capability?
  • Healthy: is the provider reachable and schema-compatible?
  • Fresh: are the required records recent enough for this workflow?
  • Complete: did every required source participate successfully?
A stale inventory snapshot, incomplete open-order coverage, or rate-limited provider can block a procurement recommendation even when older imported rows exist.
Never describe an imported snapshot as a live connector unless authentication, continuous sync, worker health, and freshness have been verified.

​
Adding a connector

A production connector requires more than an API client:
  1. Define a stable connector and versioned capability catalog.
  2. Classify fields and explicitly approve model-visible paths.
  3. Normalize provider records into the external-record contract.
  4. Implement cursor-safe, retry-safe sync and health reporting.
  5. Add workspace installation, grant, and policy setup.
  6. Add catalog mapping and schema-drift tests.
  7. For writes, register a controlled executor with input/output validation, idempotency, timeout, retry, reconciliation, approval, and audit behavior.
  8. Prove tenant isolation and secret redaction before enabling the connector.