Field mapping: why customer setups never finish

A customer starts setting up your CRM integration on Tuesday. The mapping screen lists 22 standard fields. Their team qualifies leads on a custom field called “Region Tier”, and it isn’t there. They file a ticket. Support asks engineering whether it can be added. Two weeks later the answer is yes, for that customer, as a custom build. By then the customer has moved on, and the integration is set up but never turned on.

Once a customer has connected their account, they have to tell your embedded integration which of their fields match yours. It’s the step where every customer’s account turns out to be different.

What is customer field mapping?

Customer field mapping lets each customer match the fields in your product to the fields in their own account during setup. It reads the customer’s fields live from their account, custom fields included, and fills in sensible default matches. It shows a preview of real records before anything is written, and runs the first sync in small batches so it stays within the customer’s API limits.

Why customer setups never finish

1. The field list is fixed. It was built from a demo account, so no customer’s custom fields are in it.
2. Every match starts blank. Customers face thirty dropdowns, and many give up partway.
3. Nothing shows what will happen. The customer saves a mapping without seeing a single record, and learns it was wrong from the records it wrote.
4. The first sync tries to do everything. A three-year backfill hits the customer’s API limit in the first hour and fails.
5. Changing the mapping means starting again. The customer’s fields change, and the only way to update the mapping is a new setup.
6. Custom fields become custom builds. Each customer who needs one gets a variant, and every variant is maintained separately.

What it costs

A setup that isn’t finished is an integration that doesn’t run. It still counts as shipped on the roadmap while doing nothing for the customer.

When professional services finishes the setup by hand, the cost moves to your team. The custom variant stays on your books for as long as the customer does.

What to fix first

1. Read the fields from the customer’s account. Read them each time setup opens, so a field added yesterday is in the list today.
2. Default every match you can. Match by name and type, mark required fields, and let most customers accept the mapping as it is.
3. Show a preview of real records. A handful of records shown as they’d land catches a wrong match in seconds.
4. Pace the first sync. Run it in batches, newest records first, within the customer’s API limit, and show progress.
5. Let customers edit the mapping later. Changing a field shouldn’t mean setting up again.

The guide to building customer field mapping has the prompts for each step.

What it looks like at Cue

Cue’s customers wanted more than contact syncing. They needed pipeline, opportunities, deals and case records moved and transformed to fit their own business. On Tray.ai, Cue cut the time to build a customer’s integration from about a month to a couple of days.

Where it fits

Mapping reads from the customer’s connected account, so a missing permission shows up here as fields the customer can’t see. Once the integration is live, a mapping that stops matching, such as a deleted field, is a failure the customer can fix, and error alerts should tell them so.

For the full life of an embedded integration, from choosing what to build to tracking who uses it, see the beginner’s guide to embedded integrations.