CRM field mapping

How Agents map a connected CRM into the tenant DataPool model. CRM-native field names must not be written into DataPool rows.

Kind

Resource guardrails.

When to use

Any CRM read or write that feeds leads or opportunities. Do not use this skill to “summarize the CRM” without mapping. For RFP intake, CRM is the customer master — resolve accounts and contacts here before drafting offers (rfp-handling).

Depends on

tenant-data-model (install first).

Prerequisites

Import contract

Default map (generic B2B)

Trace must replace these CRM-side names with fields from describe_tenant_integration when they differ. Left column is CRM-native (source). Right column is DataPool (target).

Leads → {{leads_schema}}

Opportunities → {{opportunities_schema}}

Unmapped CRM fields stay in a DataPool column only if the operator adds it to tenant-data-model first.

Tenant SKILL.md (copy this body)

# CRM field mapping

Map CRM records into DataPool. Load `integrations` then `datapool`. Load tenant skill `tenant-data-model` when the bound schema names are needed.

## Bound values

- CRM integration id: `{{crm_integration_id}}`
- CRM lead object: `{{crm_lead_object}}`
- CRM opportunity object: `{{crm_opportunity_object}}`
- DataPool leads schema: `{{leads_schema}}`
- DataPool opportunities schema: `{{opportunities_schema}}`

## Sequence

1. `describe_tenant_integration` for `{{crm_integration_id}}`. Do not guess operations.
2. Read CRM only through `execute_tenant_integration` when `executable_by_ai_agents` is enabled; otherwise stop and report the flag.
3. `describe_datapool_table` for `{{leads_schema}}` and `{{opportunities_schema}}`.
4. Translate each CRM field through the map in this playbook (updated at import from describe output). Write DataPool columns only.
5. Normalize `status` / `stage` enumerations. If a CRM value has no mapping, stop; do not invent a stage.

## Stop

- Do not insert CRM-native keys as DataPool column names.
- Do not treat platform Entities as the CRM mirror.
- Do not execute the CRM integration merely to “try it”.

Optional skill.json

{
  "name": "crm-field-mapping",
  "version": "1.0.0",
  "description": "Map CRM fields into canonical DataPool leads and opportunities.",
  "capabilities": {
    "prompt": ["Describe the CRM integration and DataPool tables before mapping. Never copy CRM-native keys into rows."],
    "resources": [],
    "tools": [
      "describe_tenant_integration",
      "execute_tenant_integration",
      "describe_datapool_table",
      "query_datapool",
      "insert_datapool_rows",
      "update_datapool_rows",
      "request_human_input"
    ]
  }
}

See also

• Tenant data model
• RFP handling
• Marketing lead qualification