Object and field mapping

Ampersand supports object mapping and field mapping. This allows you to either pre-define a set of mappings, or prompt your users to define their own mappings via Ampersand’s UI components.

Predefined mapping

Object mapping

You can map an object from a provider API to a label of your choice. This can help you with any naming/semantic conventions that you need, or even help you build a unified API across different API providers.

For example, if you map the account object from Salesforce and the companies object from HubSpot to a unified label like company, your read action results will be delivered under the object name of company. The original object name will still be available in the response’s rawObjectName key.

If you wish to write data to company, you can inherit the mapping from the read action.

Here’s an example of a Salesforce integration that maps the account object to company:

  - name: salesforce-integration
    displayName: My Salesforce integration
    provider: salesforce
    read:
      objects:
        - objectName: account
          mapToName: company
          # Additional configuration
    write:
      objects:
        - objectName: account
          inheritMapping: true

Field mapping

You can map individual fields to labels of your choosing. This can help you enforce naming conventions, or standardize field names across API providers.

For example, you could map a mobilephone field to phone. Read results will deliver the field under the phone key, and when you make a call to the Write API, you can use phone to update the original mobilePhone field if the write action inherits the mapping.

  - name: hubspot-integration
    displayName: My HubSpot integration
    provider: hubspot
    module: crm
    read:
      objects:
        - objectName: contacts
          requiredFields:
            - fieldName: mobilephone
              mapToName: phone
    write:
      objects:
        - objectName: contacts
          inheritMapping: true

User-defined mapping

User-defined mappings allow your end users (or consumers, in Ampersand terminology) to define mappings. Currently, only user-defined field mappings are supported, not object mappings yet.

Field mapping

Your end users may have a custom field to add notes to an Account object. You can ask your consumers to define this mapping at the time of installation, and receive data across different consumers under a single unified field like notes.

Example:

• You define a notes field in your integration.
• User A stores notes in field_a, while User B uses field_b.
• The UI library will ask each user to identify which field to map, and Ampersand delivers them under notes, accommodating custom fields unique to each consumer.
• You can write back to each user’s specific fields by writing to the notes field, if you inherit the mapping.

Field mappings can either be inside requiredFields or optionalFields, you’ll specify:

• mapToName: when Ampersand delivers the data from this field to you, this is the name that will be used to identify the field.
• mapToDisplayName: the text to display to the user in the UI component when asking them to select a field.
• default (optional): the default field, you should only use standard fields as defaults.
• prompt (optional): additional context that you want to show your user in the UI Component about this field, in a tooltip.

  - name: salesforce-integration
    provider: salesforce
    read:
      objects:
        - objectName: account
          optionalFields:
            # There is no fieldName for user-mapped fields
            - mapToName: notes
              mapToDisplayName: Account notes
              prompt: Please select the field that contains notes for this account
          # Additional configuration
    write:
      objects:
        - objectName: account
          inheritMapping: true

If you have an optional field mapping, and the user chose not to map the field (because they do not have a field that corresponds to notes), you can still make Write API calls with notes populated, and Ampersand will automatically strip it from the request before writing to the provider API to prevent errors.

Dynamic field mappings

With regular field mappings, you can define a set of fields that all your users need to map. Sometimes, you may want different users to map different sets of fields.

For example: SampleApp is using Ampersand to integrate with their customer’s HubSpot. SampleApp needs to ask the customer to map their SampleApp fields to their HubSpot fields, and different customers can have different sets of fields in SampleApp.

To achieve this, you can pass in the mapping configuration in the fieldMapping property of the InstallIntegration component:

function MyComponent() {
  const mapping = {
    // You'd likely construct this dynamically based on your business logic
    // of determining which fields the user need to map.
    // The example is static for simplicity.
    contacts: [
      {
        mapToName: 'source',
        // Both mapToDisplayName and prompt are optional.
        mapToDisplayName: 'Source',
        prompt: 'Which field do you use to track the source of a contact?',
      },
      {
        mapToName: 'priority',
        mapToDisplayName: 'Priority',
        prompt: 'Which field do you use to track the priority of a contact?',
      }
    ],
    // Field mapping for the companies object
    companies: [
      {
        mapToName: 'AccountID',
        mapToDisplayName: 'Sales Territory',
        prompt: 'Which field do you use to track the sales territory of a company?',
      }
    ]
  }
  return (<InstallIntegration
    integration = "myHubSpotIntegration"
    consumerRef = {userId}
    consumerName = {userFullName}
    groupRef = {teamId}
    groupName = {teamName}
    fieldMapping = {mapping}
  />);
}

Dynamic mappings are considered optional for a user to set, i.e, your users can install the integration without explicitly mapping a field.

Note you can also use this configuration in tandem with static field mappings (the ones defined in amp.yaml):

specVersion: 1.0.0
integrations:
  - name: myHubSpotIntegration
    provider: hubspot
    module: crm
    read:
      objects:
        # contacts also has a static field mapping
        - objectName: contacts
          optionalFields:
            - mapToName: pronoun
              mapToDisplayName: Pronoun
              prompt: We will use this word when addressing this person in emails we send out.
          ...
        - objectName: companies
          ...

When the webhook message is delivered, both statically mapped fields (defined in amp.yaml) and dynamically mapped fields (defined in the UI component) will be present in result.mappedFields

{
 ...
 "objectName": "Contact",
 "result": [
  {
    "fields": {
      ... // non-mapped fields
    },
    "mappedFields": {
      "pronoun": "she", // statically mapping
      "source": "LinkedIn", // dynamically mapped
      "priority": "high", // dynamically mapped
    },
    "raw": {
      ...
    }
  }
 ]
}

Mapping values

Ampersand platform also offers the flexibility of mapping values of fields from your app to a provider like HubSpot.

These might be for fields that are mapped either in a user-defined fashion or have a pre-defined mapping defined.

Lets take an example:

• SampleApp is using Ampersand to integrate with their customer’s HubSpot.
• SampleApp needs to ask the customer to map their SampleApp fields to their HubSpot fields.
• For a certain field, such as Priority, SampleApp has the values Very High, High, Medium, Low while HubSpot has the values P1, P2, P3, and P4. SampleApp would like the user to map the correlation between the SampleApp values and HubSpot values.

To achieve this you can define the SampleApp side of the values that need to be mapped in InstallIntegration component like below:

const mapping = {
    deals: [
      {
        mapToName: 'priority',
        mapToDisplayName: 'Priority',
        prompt: 'Which field do you use to track the priority of a deal?',
        // Mapping values for a field that's mapped by a user
        mappedValues: [
          {
            mappedValue: 'veryhigh',
            mappedDisplayValue: 'Very High'
          },
          {
            mappedValue: 'high',
            mappedDisplayValue: 'High'
          },{
            mappedValue: 'medium',
            mappedDisplayValue: 'Medium'
          },{
            mappedValue: 'low',
            mappedDisplayValue: 'Low'
          },
        ]
      },
      {
        fieldName: 'stage',
        /**
        ** Here `stage` only needs the values to be mapped.
        ** The users will not need to map the field.
        **/
        mappedValues: [
          {
            mappedValue: 'open',
            mappedDisplayValue: 'Open'
          },{
            mappedValue: 'closedWon',
            mappedDisplayValue: 'Closed Won'
          },{
            mappedValue: 'closedLost',
            mappedDisplayValue: 'Closed Lost'
          },
        ],
      },
    ],
    companies: [
      {
        mapToName: 'territory', // No mapping of values on this field
        mapToDisplayName: 'Sales Territory',
        prompt: 'Which field do you use to track the sales territory of a company?',
      }
    ]
  }
...
return (<InstallIntegration
   integration="myHubSpotIntegration"
   fieldMapping={mapping}
   groupRef={groupRef}
   ...
/>);

This will ensure that your users see a mapping UI where they can select the values from the HubSpot side to be mapped to the app side values defined here.

We only allow one-to-one mapping of values

Nested field mapping

Some provider APIs may have nested structures. Ampersand supports mapping from and to nested fields using JSONPath’s bracket notation, allowing you to extract values from nested objects or write values into nested structures.

Nested field paths use the format $['parentField']['childField']. Bracket notation ensures that field names containing dots, spaces, or other special characters are correctly parsed. For example, $['parentField']['childField$With.Special"Characters"'] is valid.

Value mappings also support bracket notation.

When you call the Get Object Metadata API, some providers may return nested fields such as $['parentField']['childField']. These field names can be used directly in your amp.yaml configuration.

Reading nested data

When a provider API returns nested data, you can use field mappings to extract nested values into mapped fields. Here is an example:

Provider returns:

{
  "userInfo": {
    "email": "[e-mail]",
    "name": "John Doe"
  },
  "status": "active"
}

With this pre-defined field mapping in amp.yaml:

    read:
      objects:
        - objectName: contacts
          requiredFields:
            - mapToName: contactEmail
              fieldName: $['userInfo']['email']
            - mapToName: contactName
              fieldName: $['userInfo']['name']
            - mapToName: $['moreInfo']['currentStatus']
              fieldName: status

Your destination receives:

{
  "mappedFields": {
    "contactEmail": "[e-mail]",
    "contactName": "John Doe",
    "moreInfo": {
      "currentStatus": "active"
    }
  }
}

Writing nested data

The same mappings will be applied in reverse when writing to a provider using the Write API.

Your app sends:

{
  "contactEmail": "[e-mail]",
  "contactName": "John Doe",
  "moreInfo": {
    "currentStatus": "deleted"
  }
}

Provider receives:

{
  "userInfo": {
    "email": "[e-mail]",
    "name": "John Doe"
  },
  "status": "deleted"
}

Full example

To see a full example of how to define object and field mappings, check out the unified CRM example in our samples repository.