Your product syncs contacts into whatever CRM a customer connects. Your contact has firstName, jobTitle and a nested company.name.

Customer A wants those in Salesforce FirstName, Title and Company. Customer B keeps job titles in a custom field. Customer C wants Leads, not Contacts.

You can't hardcode that. Only the customer, looking at their own account, knows where your jobTitle belongs.

Building it yourself means a settings screen, field-listing endpoints per CRM, per-user storage and a hand-written transform. With ByteChef Embedded it's three pieces:

  1. A field_mapping input on the integration's workflow
  2. A Field Mapping step that applies the saved mapping
  3. A mapObjectFields config on the Connect dialog that loads options from the user's own account

This is part 14 of the ByteChef Embedded series. The full version, with every edge case and API call, is on the ByteChef blog. You need an @bytechef/embedded release newer than 0.4.0.

Two halves, one string

Design time: you declare a field_mapping input with "objectName": "Contacts" and add a Field Mapping step.

Runtime: the connected user opens the Connect dialog, picks an object type and pairs each of your fields with one of theirs.

The two halves meet on the object name. The workflow stores neither the option lists nor the mapping. Object types and fields come from the user's live connection through callbacks you write, and the Field Mapping step fetches the saved mapping by object name when it runs.

The running example

Your product emits a contact.created app event:

{ "contactId": "c_123", "firstName": "Ada", "lastName": "Lovelace", "email": "ada@example.com", "jobTitle": "CTO", "company": {"name": "Analytical Engines"} } 

You want a Salesforce workflow, Sync new contacts to Salesforce, where each customer decides Lead or Contact, and which Salesforce field each of yours lands in.

Step 1: Declare the input

The Workflow Inputs panel only offers scalar types, so add this one in the Workflow Code Editor (the code icon in the integration workflow's right sidebar) and click Save:

{ "inputs": [ { "name": "contactMapping", "label": "Contact Mapping", "type": "field_mapping", "required": false, "objectName": "Contacts" } ] } 
  • type: field_mapping makes the Connect dialog render the mapping UI instead of a text box.
  • objectName joins the two halves. The match is exact: Contacts isn't contacts.
  • name is how you read the saved value: ${contactMapping}.
  • label is the heading above the mapping in the dialog.

The editor's validation list may say type must be a scalar type. Ignore it. Saving and publishing still work.

Step 2: Apply it with the Field Mapping component

Field Mapping lives under Helpers and has one action per direction:

Action Turns Into Use it
mapToIntegration your object (firstName, jobTitle) their shape (FirstName, Title) before writing into the user's app
mapToApplication their record (FirstName, Title) your shape (firstName, jobTitle) before handing a record back to yours

Both take objectName, inputType (OBJECT or ARRAY), data and includeUnmapped.

Notice what's missing: the mapping. You never wire the input into the action. At run time it finds the workflow's field_mapping input by object name and loads the connected user's saved value on its own.

Here's the complete workflow, ready to paste into the code editor:

{ "label": "Sync new contacts to Salesforce", "description": "Creates a Salesforce record for every contact.created event, using the connected user's field mapping.", "inputs": [ { "name": "contactMapping", "label": "Contact Mapping", "type": "field_mapping", "required": false, "objectName": "Contacts" } ], "triggers": [ { "label": "Contact Created", "name": "trigger_1", "type": "appEvent/v1/newEvent", "parameters": {"appEventId": 1} } ], "tasks": [ { "label": "Map to Salesforce fields", "name": "fieldMapping_1", "type": "fieldMapping/v1/mapToIntegration", "parameters": { "objectName": "Contacts", "inputType": "OBJECT", "data": "${trigger_1}", "includeUnmapped": false } }, { "label": "Create Salesforce record", "name": "salesforce_1", "type": "salesforce/v1/createRecord", "parameters": { "object": "${contactMapping.objectType}", "fields": "${fieldMapping_1}" } } ] } 

Replace 1 with your own app event's id. For a user who mapped your fields to Lead fields, the mapping step outputs:

{ "FirstName": "Ada", "LastName": "Lovelace", "Email": "ada@example.com", "Title": "CTO", "Company": "Analytical Engines" } 

The Salesforce object comes from the mapping too. ${contactMapping.objectType} is the object type the user picked. Rule of thumb: use the data pill when a step needs to read the mapping, and the Field Mapping actions when it needs to apply it.

The renaming rules decide what reaches the user's account, so know them:

  • Dotted paths work both ways. company.name is read out of a nested object, and mapping back builds it again.
  • Absent keys are skipped. A payload without jobTitle never blanks Title. A key present with null copies the null.
  • Unmapped keys are dropped by default. With includeUnmapped on they pass through under their original names, which a strict API like Salesforce rejects.
  • Arrays are mapped item by item, and every item must be an object.

Both actions work from a Script step too, through context.component:

function perform(input, context) { const contacts = context.component.fieldMapping.mapToApplication({ objectName: "Contacts", inputType: "ARRAY", data: input.records }); return contacts.filter((contact) => contact.email); } 

Step 3: Give the editor a test value

The editor's Test button runs without a connected user, so there's no saved mapping to read. Instead the actions look for a sampleMapping under the object name in the input's test value:

{ "objectType": "Lead", "Contacts": { "sampleMapping": { "mappings": [ {"applicationField": {"custom": false, "label": "First name", "value": "firstName"}, "integrationField": "FirstName"}, {"applicationField": {"custom": false, "label": "Last name", "value": "lastName"}, "integrationField": "LastName"}, {"applicationField": {"custom": false, "label": "Email", "value": "email"}, "integrationField": "Email"}, {"applicationField": {"custom": false, "label": "Job title", "value": "jobTitle"}, "integrationField": "Title"}, {"applicationField": {"custom": false, "label": "Company", "value": "company.name"}, "integrationField": "Company"} ], "objectType": "Lead" } } } 

Open Workflow Inputs, click the edit icon on contactMapping, paste it into Test Value and save. Leave the Type list alone.

sampleMapping has exactly the shape the Connect dialog saves, so you can paste a real one in later. The top-level objectType makes ${contactMapping.objectType} resolve to Lead in test runs, so the Create Salesforce record step runs from the editor too. Without a sample, the step fails with a message that tells you to add one.

Step 4: Publish and enable

  1. Publish the integration.
  2. Make sure its configuration is enabled, on the new version, with this workflow enabled in it.
  3. The user connects Salesforce in the Connect dialog and enables the workflow. The mapping shows up among that workflow's inputs.

Step 5: Wire the Connect dialog

Pass mapObjectFields to useConnectDialog, keyed by the same object name:

import {useConnectDialog, type MapObjectFieldsType, type OptionType} from '@bytechef/embedded'; interface SoqlResponseI { records?: Array<{Label: string; QualifiedApiName: string}>; } const SALESFORCE_OBJECT_TYPES: OptionType[] = [ {label: 'Lead', value: 'Lead'}, {label: 'Contact', value: 'Contact'}, ]; const mapObjectFields: MapObjectFieldsType = { Contacts: { objectTypes: { get: async () => SALESFORCE_OBJECT_TYPES, }, integrationFields: { get: async ({executeAction, objectType}) => { const response = (await executeAction('salesforce', 1, 'soqlQuery', { q: `SELECT QualifiedApiName, Label FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = '${objectType}'`, })) as unknown as SoqlResponseI; return (response.records ?? []) .map((record): OptionType => ({label: record.Label, value: record.QualifiedApiName})) .sort((first, second) => first.label.localeCompare(second.label)); }, }, applicationFields: { fields: [ {label: 'First name', value: 'firstName'}, {label: 'Last name', value: 'lastName'}, {label: 'Email', value: 'email'}, {label: 'Job title', value: 'jobTitle'}, {label: 'Company', value: 'company.name'}, ], userCanCreateFields: true, userCanRemoveMappings: true, }, }, }; export function ConnectSalesforceButton({integrationId, jwtToken}: {integrationId: string; jwtToken: string}) { const {openDialog} = useConnectDialog({ baseUrl: 'https://bytechef.example.com', environment: 'DEVELOPMENT', integrationId, jwtToken, mapObjectFields, }); return <button onClick={openDialog}>Connect Salesforce</button>; } 

Each entry has three parts:

  • objectTypes.get fills the Object type select. It doesn't have to call the remote system. A fixed list guarantees the objectType the next callback receives is one you chose.
  • integrationFields.get runs each time the user picks an object type. Here it runs Salesforce's SOQL Query action on the user's own connection against FieldDefinition, so custom fields show up too.
  • applicationFields is your side of the table: fields (values can be dotted paths like company.name), optional defaultFields, plus userCanRemoveMappings and userCanCreateFields.

Using the Integration Marketplace instead of your own page? Pass the same object to its mapObjectFields prop.

What executeAction actually does

You never build it. The SDK creates it, bound to the current user and the integration instance being configured. Each call is one request to the same embedded actions endpoint the ComponentKit uses, with the user's JWT and an X-Instance-Id header. ByteChef checks that the JWT's user owns that instance and answers 403 if not, so a callback can't reach another user's account.

Two things that will bite you:

  • It resolves to whatever the action returns. It's typed as an array, but SOQL Query returns an object, hence the cast.
  • It never throws. A network error or error status is logged to the console as Failed to execute action and resolves to []. An unexpectedly empty select means: check the console.

What the user sees

The mapping sits with every other workflow input in the Connect dialog's managed view. Here's that view for a workflow with no inputs:

Connect dialog for a connected integration, with a Workflows tab, one enabled workflow and an INPUTS section that reads No inputs defined for this workflow

With the example workflow enabled, the INPUTS section holds a Contact Mapping heading, an Object type select, and one row per application field. Each row's select stays disabled until an object type is chosen, then lists what integrationFields.get returned.

There's no Save button. Every change saves on its own, 600 milliseconds after the user stops editing.

The mapping is stored as the input's value. Your app can read it back with GET /api/embedded/v1/integrations/{id} to show something like "Leads, 5 fields mapped" in your own UI. Your backend can pre-fill a sensible default with your environment's API secret key right after a user connects. Send all of the workflow's inputs when you do: whatever you leave out is removed.

Try it in the sample app

The embedded sample app ships a Field Mapping Playground at /field-mapping. It walks through preparing the workflow, describing your application's fields, mapping in the Connect dialog, reading the stored mapping back and previewing a sample record in both directions.

The Field Mapping Playground: the Describe Your Application Fields card with Object Name Contacts and rows for firstName, lastName, email, jobTitle and company.name, next to the Map in the Connect Dialog card

The Preview the Mapping card with the example mapping and a sample contact, next to the Result card showing mapToIntegration output and the round trip back through mapToApplication

One warning: the sample's Integrations pages call listObjects and listObjectFields on the salesforce component as placeholders. Those actions don't exist, so the selects stay empty. Swap in the SOQL Query callback above.

Gotchas

  • Text box instead of a mapping editor? You're on @bytechef/embedded 0.4.0. Upgrade before you debug your callbacks.
  • No mapObjectFields entry for the object name means the dialog renders nothing for that input. No error, no placeholder.
  • Two field_mapping inputs with the same object name make the Field Mapping actions fail rather than guess.
  • Switching Lead to Contact keeps existing pairings, which may name fields the new object lacks. Have users review every row.
  • Rows come from your config every time. A custom field added earlier stays in the saved value but gets no row back, and the next change saves without it. If custom fields matter, list the common ones in fields.
  • required isn't enforced in the dialog. The user can close it with nothing mapped. The example uses required: false so the failure shows up as a readable Field Mapping error in Workflow Executions.
  • The mapping can't know the target's rules. Salesforce won't create a Lead without LastName and Company.
  • Build queries from values you trust. The SOQL string is only safe because objectTypes.get returns a fixed list. Validate the value if object types come from the remote system.

Before you ship

  • Run an @bytechef/embedded release newer than 0.4.0 in every frontend that shows the Connect dialog.
  • Replace placeholder callbacks with actions your integration really has. Try them in the ComponentKit first.
  • Pass environment explicitly. It defaults to PRODUCTION, and executeAction uses it too.
  • Write a sampleMapping for every field-mapping input.
  • Pre-fill defaults from your backend and point users at the mapping right after they connect.
  • Test the full loop per integration: connect, map, trigger an event, check the run and the record in the user's app.

Who owns what

You own: the field-mapping input and its object name, the workflow and its test value, which of your fields are mappable, the callbacks that decide which remote objects and fields are offered, and any defaults your backend writes.

ByteChef owns: the mapping UI, running your callbacks' actions on the user's credentials with ownership checks, storing every user's mapping, null-safe nested renaming in both directions, and the run-time lookup by object name.

One input, one step, one config object with two callbacks. Every customer gets a mapping screen for their own account.

Next in the series: Shared Connections, for when the account is yours instead of the user's, like the Slack workspace your alerts go to or the API key you pay for.

ByteChef is an open-source workflow automation and AI agent platform (Apache 2.0). Star it on GitHub and read the full guide on the ByteChef blog.