Custom Field Mapping UI

Create a Field Mapping

Before building a field mapping UI, you need to create a Field Mapping.
Select what you want to map your fields from and to, and the mapping direction. Then continue.

Get a Field Mapping Instance

To apply field mapping to a specific Connection, you need to get a Field Mapping Instance:

await integrationApp
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPINGS_KEY}')
  .get()

Field Mapping Instance has the following properties:

externalSchema – Data Schema on the external app side.
appSchema – Data Schema on your app's side.
importValue – mapping from external app to your app.
exportValue – mapping from your app to external app.
direction – mapping direction. Can be import, export, or both.

Using DataForm

This API is experimental and is likely to change significantly in the future.
Expect needing to migrate this code when new versions of our SDK are released.

To simplify working with schemas and values, we provide a DataForm class. It works like this:

import { DataForm } from '@integration-app/sdk'

const fieldMappingInstance = await integrationApp
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .get({ autoCreate: true })

const importDataForm = new DataForm({
  schema: fieldMappingInstance.appSchema,
  value: fieldMappingInstance.importValue,
  variablesSchema: fieldMappingInstance.externalSchema,
})

const fields = importDataForm.getFields()
const fieldOptions = importDataForm.getFieldValueOptions(fields[0])
const newImportValue = importDataForm.setFieldValue(fields[0], fieldOptions[0])

// fieldMappingInstance.patch({ importValue: newImportValue })

To put it all together, here is an example of a simple field mapping editing UI:

import { useFieldMappingInstance, DataForm } from '@integration-app/react'

export function FieldMappingUI() {
  const { fieldMappingInstance, patch, loading, error } =
    useFieldMappingInstance({
      integrationKey: '{INTEGRATION_KEY}',
      fieldMappingKey: '{FIELD_MAPPING_KEY}',
      autoCreate: true
    })

  if (!fieldMappingInstance) {
    return (
      <div>
        {loading && <div>Loading...</div>}
        {error && <div>Error: {error.message}</div>}
      </div>
    )
  }

  const importForm = new DataForm({
    schema: fieldMappingInstance.appSchema,
    value: fieldMappingInstance.importValue,
    variablesSchema: fieldMappingInstance.externalSchema
  })

  function handleOptionSelected(field, idx) {
    const option = importForm.getFieldValueOptions(field)[idx]
    const newImportValue = importForm.setFieldValue(
      field,
      option ? option.value : undefined,
    )

    return patch({ importValue: newImportValue })
  }

  return (
    <table>
      <tr>
        <th>Field</th>
        <th>Value</th>
      </tr>
      {importForm.getFields().map((field) => (
        <tr key={field.locator}>
          <td>{field.name}</td>
          <td>
            <select
              onChange={(e) => handleOptionSelected(field, e.target.value)}
            >
              <option></option>
              {importForm.getFieldValueOptions(field).map((option, idx) => (
                <option key={idx} value={idx} selected={option.selected}>
                  {option.name}
                </option>
              ))}
            </select>
          </td>
        </tr>
      ))}
    </table>
  )
}

Advanced Functionality

This example does not handle complex fields (like arrays or objects) and does not support formulas.

Here are articles you should check out to build a more advanced field mapping UI:

Field Mappings

Mapping fields between your app and external apps.

Data Schemas

Representing data structures used in integrations.

Formulas

Dynamically generate values when building flows.