ConnectorMapping

A ConnectorMapping row is the compiled JSONata expression that the connector sync pipeline uses to transform one MCP tool's response payload into one of twelve Well financial-graph entity types (company, invoice, transaction, account, etc.). One row is produced per unique (workspace_connector, target_model, tool_name) triple; the triple is enforced by a partial unique index on non-deleted rows. The record is entirely pipeline-owned: it is created, regenerated, and soft-deleted by SyncConfigService during each MCP sync cycle, and is never written by a user. It is associated upward to a WorkspaceConnector (the authenticated provider instance) and to a Workspace.

API operations

Data model

Attributes

Relationships

System-computed

• connector_mapping_id — generated via gen_random_uuid() at insert; unique constraint enforced at DB level
• created_at — set once by MikroORM onCreate lifecycle hook
• updated_at — set on every flush by MikroORM onUpdate lifecycle hook
• deleted_at — soft-delete; when set, the row is excluded from the partial unique index on (workspace_connector_pk, target_model, tool_name) WHERE deleted_at IS NULL, allowing a fresh row to be inserted under the same triple
• needs_regeneration — auto-flipped to true by SyncConfigService when schema drift ('drift' result from compareSchemaFingerprints) is detected or last_persist_count == 0 after a sync
• last_persist_count — stamped by SyncConfigService.recordPersistCount after each sync completes; zero value is the signal for automatic re-generation on the next sync cycle
• expression — produced by the structured slot-decision jury pipeline (3-panelist OpenAI strict json_schema → reconcileJuryDecisions → mergeSlotDecisions with YAML-pinned slots → compileSlotDecisionsToJsonata); regenerated when needs_regeneration is true; subject to three-tier graceful degradation (reuse prior working expression → legacy jury → hard fail)
• schema_fingerprint — computed from the provider tool schema sample at generation time; compareSchemaFingerprints returns identical | additive_only | drift; only 'drift' triggers regeneration
• schema_key_paths — extracted from the provider schema sample during jury generation; used for vocab-bound source_path validation by jury panelists
• audit_trail — written by JuryService after each jury run; null on rows predating the structured pipeline
• pagination_spec — discovered by the same schema-sample pass as the JSONata jury at generation time; null means single-page tool
• tool_args — captured once at AI tool-selection time (selected_at anchor); never mutated post-creation; bounded to 64 KB by a CHECK constraint (Migration20260420100000)
• Partial-unique index connector_mappings_wc_target_tool_unique on (workspace_connector_pk, target_model, tool_name) WHERE deleted_at IS NULL — enforces one active mapping per tool-per-target-per-connector; added in Migration20260420100000 replacing the legacy (workspace_connector_pk, target_model) unique index

Example

{
  "data": {
    "type": "connector_mapping",
    "id": "a3f8c1d2-7b4e-4f2a-9c01-3e5d8f2a6b19",
    "attributes": {
      "connector_mapping_id": "a3f8c1d2-7b4e-4f2a-9c01-3e5d8f2a6b19",
      "target_model": "invoice",
      "expression": "$map(result.invoices, function($v) { { 'reference_number': $v.invoice_number, 'grand_total': $number($v.total_amount), 'issue_date': $v.created_at } })",
      "user_instructions": "Map invoice totals from EUR cents to decimal euros.",
      "schema_fingerprint": "sha256:3a9c1e7f2b4d",
      "schema_key_paths": ["result.invoices[].invoice_number", "result.invoices[].total_amount", "result.invoices[].created_at"],
      "needs_regeneration": false,
      "tool_name": "pennylane_list_invoices",
      "tool_args": { "page": 1, "per_page": 100 },
      "selected_at": "2026-05-01T14:32:00.000Z",
      "audit_trail": {
        "jury_name": "slot-decision-v2",
        "panelists": ["gpt-5.4-0.4", "gpt-5.4-0.7", "gpt-5.4-1.0"],
        "disagreement_score": 0.12,
        "duration_ms": 4320,
        "synthesized": false
      },
      "pagination_spec": { "type": "page_number", "page_param": "page", "per_page_param": "per_page", "per_page": 100 },
      "last_persist_count": 87,
      "created_at": "2026-04-20T10:00:00.000Z",
      "updated_at": "2026-05-01T14:32:05.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "c7d4a2f1-1e3b-4a2c-8f01-9b2e7c3d5a11" }
      },
      "workspace": {
        "data": { "type": "workspace", "id": "9f3e2b1a-4c7d-4f8e-b3a1-2c5d9e7f3b08" }
      }
    }
  }
}