A field mapping instance is automatically created once a Connection is established with an external app.

By default, a Field Mapping instance carries the default mapping that was specified on the Field Mapping. Like the Field Mapping itself, the instance may have a two-way mapping:

importValue – mapping from external app schema to your app schema
exportValue – mapping from your app schema to external app schema

A tenant can configure both the import and export sides of the field mapping instance.

Why configure field mapping instance

You'd want to have your user configure their field mapping instance if you want to have them control how properties in the external application map to field used by your app.

Configuring Instance via Membrane UI

The simplest way to configure a Field Mapping is to use the configuration UI:

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .openConfiguration()

This will open up a the field mapping instance and let the user configure both sides of the field mapping

See more: Field Mapping UI

Creating & Configuring Instance via Membrane SDK

Here is how to use Field Mapping Instances via Membrane SDK

Create

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .create()

Get

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

Update

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .patch('{INPUT}')

Set up / Refresh

Updates to the base field mapping are automatically applied. If they aren't, you can use .setup() to manually pull merged updates from the base field mapping.

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .setup()

Reset

This method resets the field mapping instance to its default state, erasing all the tenant configuration.

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .reset()

Archive

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPING_KEY}')
  .archive()

Multiple Field Mapping Instances per Connection

By default, every pair of Field Mapping and Connection will use the same Field Mapping Instance, which means that mapping values will be shared between them.

If you want to use multiple different mapping values for the same pair of Field Mapping + Connection, you should use instanceKey.

await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPINGS_KEY}', { instanceKey: '{INSTANCE_KEY}' })
  .get({ autoCreate: true })

When you apply instanceKey to a Field Mapping Instance, it will be automatically applied to the elements Field Mapping works with: Data Source, App Data Collection, etc.