salesforce-field-mapping-skill

Pure-generation T0 skill that maps CSV/spreadsheet column headers to Salesforce field API names with type mismatch detection. The daily-driver for admins migrating from HubSpot, Pipedrive, Excel exports, and legacy CRMs. Outputs a complete mapping table, type mismatch report, missing-field list, and a Data Loader–ready column header row.

When This Skill Owns the Task

Use salesforce-field-mapping-skill when the work is to design or validate a field mapping for a data import:

• "I'm migrating from HubSpot — map these column headers to Salesforce Contact fields"
• "Here's my Excel export. What are the Salesforce API names?"
• "I need a Data Loader field mapping CSV for importing Opportunities from Pipedrive"
• "Flag any type mismatches in my column list before I import"
• "Which of my CSV columns don't have matching Salesforce fields?"

Delegate elsewhere when:

Required Context to Gather First

Before generating a mapping, confirm:

1. Target Salesforce object — standard (Contact, Lead, Account, Opportunity, Case) or custom (Custom_Object__c).
2. Source system — HubSpot, Pipedrive, Salesforce Classic, Excel/CSV export, Marketo, or other. Source system determines default field label conventions.
3. Column header list — the complete list of CSV/spreadsheet column headers, either as a comma-separated list or pasted table.
4. Custom fields in scope — list any known custom fields on the target object that may receive data (e.g., HubSpot_Contact_ID__c).
5. Operation type — insert, update, or upsert. Affects whether Id or an external ID field is required in the mapping.
6. External ID field — for upsert: which field is the external ID key? (e.g., HubSpot_Contact_ID__c, Email)
7. Multi-value fields — any source columns that contain comma-separated multi-values intended for multi-select picklists.

If the column header list is not provided, ask before proceeding.

Recommended Workflow

Step 1 — Normalize source column headers

Apply label normalization to make headers comparable:

• Strip leading/trailing whitespace
• Collapse multiple spaces to single space
• Remove non-alphanumeric prefix/suffix characters
• Flag headers containing special characters that may corrupt Data Loader (e.g., #, $, %, (, ), /)

Step 2 — Derive candidate API names from labels

For each normalized column header, apply the API name derivation rules (see references/api-name-normalization.md):

1. Replace spaces with underscores
2. Remove characters not in [A-Za-z0-9_]
3. Strip leading digits (Salesforce API names must start with a letter)
4. Collapse consecutive underscores to single underscore
5. Truncate to 40 characters (API name limit)
6. Append __c for custom fields
7. Check against reserved words list

Step 3 — Match against known standard field API names

Apply fuzzy matching against the standard object's well-known fields:

For Contact: FirstName, LastName, Email, Phone, MobilePhone, Title, Department, AccountId, MailingStreet, MailingCity, MailingState, MailingPostalCode, MailingCountry, LeadSource, Salutation, Birthdate, Description, DoNotCall, HasOptedOutOfEmail, OwnerId, ReportsToId

For Lead: FirstName, LastName, Company, Email, Phone, MobilePhone, Status, LeadSource, Title, Industry, AnnualRevenue, NumberOfEmployees, Rating, Street, City, State, PostalCode, Country, Description, HasOptedOutOfEmail, DoNotCall

For Account: Name, Type, Industry, AnnualRevenue, NumberOfEmployees, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, Phone, Website, Description, OwnerId, ParentId

For Opportunity: Name, StageName, CloseDate, Amount, Probability, AccountId, OwnerId, Type, LeadSource, Description, ForecastCategory, ForecastCategoryName, CampaignId, NextStep

Step 4 — Detect type mismatches

For each mapped pair, compare source data type to Salesforce field type. Flag mismatches (see references/type-mismatch-detection.md):

Step 5 — Flag missing and unmappable fields

Produce two lists:

1. Unmapped source columns — columns with no clear Salesforce target
2. Required fields missing from source — Salesforce required fields (e.g., LastName on Contact, LastName + Company on Lead, Name + StageName + CloseDate on Opportunity, Name on Account) not present in the source column list

Step 6 — Normalize picklist values

For any column mapping to a standard picklist field, list the expected Salesforce API values and flag mismatches:

• LeadSource: Cold Call, Web, Phone Inquiry, Partner Referral, Purchased List, Other, Word of mouth, Employee, Internal, Partner
• StageName: Prospecting, Qualification, Needs Analysis, Value Proposition, Id. Decision Makers, Perception Analysis, Proposal/Price Quote, Negotiation/Review, Closed Won, Closed Lost
• Industry: Agriculture, Apparel, Banking, Biotechnology, Chemicals, Communications, Construction, Consulting, Education, Electronics, Energy, Engineering, Entertainment, Environmental, Finance, Food & Beverage, Government, Healthcare, Hospitality, Insurance, Machinery, Manufacturing, Media, Not For Profit, Recreation, Retail, Shipping, Technology, Telecommunications, Transportation, Utilities, Other

Step 7 — Detect special character and collision risks

• Flag API names that would collide (two source columns normalizing to the same API name)
• Flag reserved words: Id, Name, OwnerId, CreatedDate, LastModifiedDate, SystemModstamp, IsDeleted — these cannot be used as custom field API names
• Flag API names exceeding 40 characters after normalization

Step 8 — Emit structured output

Produce the full output block per the Output Format section below, including a Data Loader–ready header row.

Quality Scoring Rubric (100-point)

Score every output before emitting. Threshold: 85+ ship, 70–84 ship with caveat, below 70 reject and revise.