How to build customer field mapping

What matters here

• Read the customer's fields from their account. A fixed list never has their custom fields.
• Default every match you can. Most customers should be able to accept the mapping as it is.
• Show a preview of real records before anything is written. It catches wrong matches in seconds.
• Run the first sync in batches, newest records first. A three-year backfill in one go hits the customer's API limit.
• Let customers change the mapping later without starting again. Their fields change too.

Who this is for

You build the integration experience inside a software product. Customers need to match your product's fields to their own, and mapping questions are your biggest source of setup tickets.

How it works in practice

From a customer opening setup to their first records syncing.

1. 1

   The customer's fields are read from their account

   Standard and custom, with their labels and types, straight after they connect.

2. 2

   Default matches are filled in

   By name and type, so email maps to email and the customer reviews rather than builds.

3. 3

   The customer adjusts and adds

   Picking from their own fields, with a type check so a date can't be mapped to a yes or no field.

4. 4

   A preview shows real records

   Five records from your product, as they would appear in the customer's app, before anything is written.

5. 5

   The instance is turned on

   After your own checks, since a new instance starts switched off.

6. 6

   The first sync runs in batches

   Newest records first, paced to the customer's API limit, with progress shown in your product.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Read the customer's fields from their account

   A fixed list never has their custom fields.

   Headless skills build-workflow

   Copy

   Use build-workflow. The integration writes contacts and companies from
   our product to HubSpot, or whichever app we are integrating with.
   
   Build a small workflow that, given a customer's connection, lists the
   fields on each object we write to: name, label, type, whether it is
   required, and for pick lists, the allowed values.
   
   In Tray Embedded, use this list for the data mapping slot in the
   config wizard, so the customer picks from their own fields. If a
   customer will map more fields than fit on one screen, tell me, and
   we will use our own form with the same list instead.

2. 2

   Fill in the defaults and check the types

   Most customers should accept the mapping as it is.

   Copy

   For each of our fields, suggest a match from the customer's fields by
   name and type. Mark which of our fields must be mapped.
   
   Refuse a match whose types can't hold the value: a date into a yes or
   no field, free text into a pick list without a value rule. Say why in
   plain words next to the field.
   
   Store the mapping on the customer's instance, so they can change it
   later without setting the integration up again.

3. 3

   Preview before anything is written

   A wrong match is seen in seconds, not in their records.

   Headless skills build-workflow tray-gotchas

   Copy

   Use build-workflow and tray-gotchas. Before the customer finishes
   setup, take five recent records from our product, apply their mapping,
   and show the result as it would appear in their app, field by field.
   
   Write nothing to the customer's account during the preview. Flag any
   required field that would be empty, and any value that their app
   would refuse.

4. 4

   Turn it on, then sync the history in batches

   A three-year backfill in one go hits their API limit.

   Copy

   A new instance starts switched off. When setup finishes, run our own
   checks (connection works, required fields mapped), then turn it on.
   
   Run the first sync in batches, newest records first, paced to the
   customer's API limit for their plan. Match on email or the customer's
   own id so a record that already exists is updated, never duplicated.
   
   Show progress in our product and tell the customer when the history
   has finished. After that, only changes sync.

   Newest first means the records the customer cares about are there in minutes, even when the full history takes hours.

What it connects to

The fields are the customer's. The mapping belongs to their instance.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Related guides