> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Mapping Instances

A field mapping instance is automatically created once a [Connection](/docs/how-membrane-works/connections) 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:

```javascript theme={null}
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

<br />

See more: [Field Mapping UI](/reference/workspace-elements/field-mappings/field-mapping-instances)

## Creating & Configuring Instance via Membrane SDK

Here is how to use Field Mapping Instances via Membrane SDK

### Create

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').create()
```

<br />

### Get

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPINGS_KEY}').get()
```

<br />

### Update

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').patch('{INPUT}')
```

<br />

### 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.

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').setup()
```

<br />

### Reset

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

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').reset()
```

<br />

### Archive

```javascript theme={null}
await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').archive()
```

<br />

## 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`.

```javascript theme={null}
await membrane
  .connection('hubspot')
  .fieldMapping('{FIELD_MAPPINGS_KEY}', { instanceKey: '{INSTANCE_KEY}' })
  .get({ autoCreate: true })
```

<br />

When you apply `instanceKey` to a Field Mapping Instance, it is automatically applied to the legacy element configuration that still uses that Field Mapping.