Field Mapping Configuration

Field mappings define how data from external connectors is translated into GTM Clarity's canonical schema. Each connector provides default mappings, but admins can customize them to match their specific data model.

How Field Mapping Works

When a connector syncs data, each record passes through the field mapping layer. The mapper reads the configured mappings for that connector and entity type, applies any transforms, and outputs a canonical record for storage.

Field Mapping Table

Mappings are stored in the field_mappings table:

Column	Type	Description
id	text (UUID)	Primary key
tenant_id	text	Tenant scope
connector_id	text	FK to connectors
entity_type	text	account, person, opportunity, or activity
mappings	jsonb	Array of FieldMappingEntry objects
is_default	boolean	Whether this is the system default mapping

A unique index on (tenant_id, connector_id, entity_type) ensures one mapping set per connector per entity type.

Mapping Entry Structure

Each entry in the mappings array follows this structure:

interface FieldMappingEntry {
  sourceField: string;      // Field name in the source system
  targetField: string;      // Field name in the canonical schema
  transform: "none" | "lowercase" | "uppercase" | "trim" | "custom";
  customTransform?: string; // Expression for custom transforms
  required?: boolean;       // Whether this field must be present
}

Example: Salesforce Account Mapping

[
  {
    "sourceField": "Name",
    "targetField": "name",
    "transform": "trim",
    "required": true
  },
  {
    "sourceField": "Website",
    "targetField": "domain",
    "transform": "lowercase"
  },
  {
    "sourceField": "Industry",
    "targetField": "industry",
    "transform": "none"
  },
  {
    "sourceField": "NumberOfEmployees",
    "targetField": "employeeCount",
    "transform": "none"
  },
  {
    "sourceField": "AnnualRevenue",
    "targetField": "annualRevenue",
    "transform": "none"
  }
]

Transform Options

Transform	Behavior	Use Case
none	Pass through unchanged	Numeric fields, IDs
lowercase	Convert to lowercase	Email addresses, domains
uppercase	Convert to uppercase	Country codes, state abbreviations
trim	Remove leading/trailing whitespace	Names, free-text fields
custom	Apply custom expression	Complex transformations

tip

Use the lowercase transform on email and domain fields to ensure consistent matching and deduplication across data sources.

Default Mappings Per Connector

Each connector ships with sensible defaults. These are created automatically when a connector is first added.

Salesforce Defaults

Source Field	Target Field	Entity
Name	name	Account
Website	domain	Account
Industry	industry	Account
NumberOfEmployees	employeeCount	Account
AnnualRevenue	annualRevenue	Account
Email	email	Person
FirstName	firstName	Person
LastName	lastName	Person
Title	title	Person
Phone	phone	Person
StageName	stage	Opportunity
Amount	amount	Opportunity
CloseDate	closeDate	Opportunity

Customer.io Defaults

Source Field	Target Field	Entity
email	email	Person
first_name	firstName	Person
last_name	lastName	Person
event_name	type	Activity
timestamp	occurredAt	Activity

Custom Field Mapping

To override default mappings:

1. Navigate to Settings > Connectors > [Connector Name] > Field Mappings
2. Select the entity type (Account, Person, Opportunity, Activity)
3. Modify existing mappings or add new ones
4. Click Save to apply changes

Custom mappings override the defaults entirely for that entity type. Any fields not included in your custom mapping will not be imported.

warning

If you remove a required field mapping (like name for accounts or email for people), sync operations may fail or produce incomplete records. Always verify your mappings after changes.

Writeback Field Maps

In addition to inbound mappings, GTM Clarity supports writeback -- pushing computed scores back to the source system. Writeback mappings define which canonical score fields map to which target fields in the CRM.

The writeback_configs table stores these mappings:

Column	Type	Description
id	text (UUID)	Primary key
tenant_id	text	Tenant scope
connector_id	text	FK to connectors
entity_type	text	account, person, or opportunity
field_map	jsonb	Array of WritebackFieldMap
enabled	boolean	Whether writeback is active
last_writeback_at	timestamptz	Last successful writeback
last_writeback_error	text	Error from last attempt

Writeback Field Map Structure

interface WritebackFieldMap {
  canonicalField: "fitScore" | "engagementScore" | "combinedScore" | "tier" | "scoredAt";
  targetField: string; // Field name in the CRM
}

Example: Salesforce Writeback

[
  { "canonicalField": "fitScore", "targetField": "GTM_Fit_Score__c" },
  { "canonicalField": "engagementScore", "targetField": "GTM_Engagement_Score__c" },
  { "canonicalField": "combinedScore", "targetField": "GTM_Combined_Score__c" },
  { "canonicalField": "tier", "targetField": "GTM_Tier__c" },
  { "canonicalField": "scoredAt", "targetField": "GTM_Scored_At__c" }
]

info

Writeback requires custom fields to exist in the target CRM. For Salesforce, create custom fields via Setup > Object Manager before enabling writeback. The Salesforce Metadata API can be used to discover available fields.

Related Pages

• Connector Management -- Adding and managing connectors
• Scoring Configuration -- Score fields available for writeback
• Database Schema -- Full schema for field_mappings and writeback_configs