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.

Document information

Field	Value
Canonical URL	`/docs/07_ai-agents-and-mcp/model_skills/00_shared/crm-field-mapping`
Version (published date)	`2026-08-26`
Tags	`ai`, `skills`, `datapool`, `integrations`, `playbooks`

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.

Depends on

tenant-data-model (install first).

Prerequisites

id	question	search	if_missing_or_ambiguous	default_to_propose	binds_to
`crm_integration_id`	Which tenant integration is the CRM?	Load `integrations`. `list_integrations` / `entity_search` for CRM, Espo, Salesforce, HubSpot, or the name the operator used.	`request_human_input` `kind: choice` with matches, or `text` if none	None — must be a real integration	Tenant `SKILL.md`
`crm_lead_object`	What is the CRM object/collection for leads?	`describe_tenant_integration` operations / schema	Ask	Propose `Lead` if the connector schema uses that label	Tenant `SKILL.md`
`crm_opportunity_object`	What is the CRM object for deals/opportunities?	Same	Ask	Propose `Opportunity` / `Deal` from describe	Tenant `SKILL.md`
`leads_schema`	DataPool leads table	From installed `tenant-data-model`	Import `tenant-data-model` first	Bound name from that skill	Tenant `SKILL.md`
`opportunities_schema`	DataPool opportunities table	From `tenant-data-model`	Same	Bound name	Tenant `SKILL.md`

Import contract

Field	Value
`suggested_skill_id`	`crm-field-mapping`
`version`	`1.0.0`
`capabilities.tools`	`describe_tenant_integration`, `execute_tenant_integration`, `describe_datapool_table`, `query_datapool`, `insert_datapool_rows`, `update_datapool_rows`, `request_human_input`

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}}

CRM field (example)	DataPool column
id / LeadId	`lead_id`
company / AccountName	`company_name`
name / FullName	`contact_name`
email	`contact_email`
source / LeadSource	`source`
status	`status` (normalize to `new` \| `qualifying` \| `sales_ready` \| `disqualified`)
score	`score`

Opportunities → {{opportunities_schema}}

CRM field (example)	DataPool column
id	`opportunity_id`
lead id / LeadId	`lead_id`
name / Account	`company_name`
stage / Status	`stage` (normalize to `discovery` \| `proposal` \| `negotiation` \| `won` \| `lost`)
amount	`amount`
currency	`currency`
close date	`close_date`

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"
    ]
  }
}