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
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.
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
...
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}
...
/>);
We only allow one-to-one mapping of values
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. 
