Search documentation...

K

Salesforce

Push enriched data from your warehouse into Salesforce CRM for your teams to act upon it

Overview

With the Salesforce destination, Hightouch can both create and update standard or custom objects, update custom picklist field values on those objects, and also create platform events to drive more automation in Salesforce.

OAuth with Salesforce Authenticator

When connecting your Salesforce destination and you have Salesforce Authenticator setup as your 2FA, you may have to accept the request from your device (mobile phone). After you have accepted the request on your device, return to the destination setup page and click 'finish'.

Access Level Recommendations

We recommend that you authenticate with a user that has the correct access to update all fields, records and objects that you need to interact with. We highly recommend that you OAuth with a System Administrator or Integration User account as a result.

Syncing

The Salesforce destination supports the following sync types:
  • Object
  • Metadata (Custom Picklists)

Sync Modes

There are three different possible sync modes for Salesforce objects:
  • Insert — Insert mode pushes new objects to Salesforce, and does not update the objects as they change in your warehouse.
  • Upsert — Upsert mode pushes new objects to Salesforce and updates fields that change in your warehouse.
  • Update — Update mode updates particular fields on existing objects in Salesforce.

Insert

Insert is the simplest of modes for pushing to Salesforce. In this mode new objects will be inserted into Salesforce, but future changes to columns of those objects will not be reflected in Salesforce.
This mode is good for the following scenarios:
  • You want to push objects into Salesforce, but don't care if the data within each row remains up to date
  • Static data where each row is never updated, such as events
Insert has two configuration parameters:
NameDescription
Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be pushed into Salesforce
Hightouch to Salesforce Field MappingsA list of columns that will be pushed to new objects in Salesforce

Upsert

In this mode, new objects will be inserted into Salesforce and all designated columns will be kept up-to-date within Salesforce.
This mode is good for the following scenarios:
  • You want to push objects into Salesforce and want to keep the data up-to-date
Upsert has three configuration parameters:
NameDescription
Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be updated in Salesforce
Hightouch to Salesforce External Unique Identifier Column MappingThe name of the column on the Hightouch query, and the name of an external ID for the object in Salesforce. Note that this column in Salesforce must be marked as an external ID and unique for this to work.
Hightouch to Salesforce Field MappingsA list of columns that will be pushed to new objects in Salesforce. Each time a sync occurs in Hightouch these columns will be updated.

Update

In this mode, selected columns will be updated for an object within Salesforce. For example, you could add an LTV column to an account or contact. This mode does not create new rows for an object within Salesforce. Instead, it updates columns on existing objects.
Update mode requires you to have access to the IDs of the objects you want to update within your warehouse.
This mode is good for the following scenarios:
  • You have objects in Salesforce that you want to add additional information / columns to
  • You want to continuously sync data from your warehouse and add this data to existing objects within Salesforce
  • You already have access to Salesforce object IDs within your warehouse
Update has three configuration parameters:
NameDescription
Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be updated in Salesforce
Hightouch ID ColumnThe name of the column of the Hightouch query that contains a Salesforce object ID.
Hightouch to Salesforce Field MappingsA list of columns that will be updated for objects in Salesforce. Each time a sync occurs in Hightouch these columns will be updated.

Object ID Lookup

If you are attempting to associate two objects with a foreign key (e.g. associate a contact with an account via the AccountId field in the contact), Hightouch can lookup the ID of an object based on another unique column and use the object ID as the value of the column.
In this example, the object has a reference field founder_lead__c which should contain the Salesforce ID of the Lead object of the founder. However, you may only have the external ID of the founder in your source in column founder.
With object ID lookup, you can look up the Lead object where the value in column founder equals the unique external ID field db_user_id__c and return the ID of the lead object as the value, syncing it to founder_lead__c.

Salesforce Person Account Setup

If you need to send data to a Salesforce Person Account, here are the following steps:
  1. Contact Salesforce to enable Person Accounts
  2. Select Account in the Hightouch Sync configuration as your object (Person Account is not an API object, it's a copy of Account).
  3. You must sync LastName at a minimum instead of FullName to push to the object correctly (Otherwise, it will fail.)

Trouble merging data into Salesforce fields?

We only allow you to merge data from your source columns into Salesforce fields that are:
  • Set as External ID
  • Set as Unique
  • Not native Salesforce fields. Fields such as Salesforce's default 'email' field are native and cannot be set as external identifiers. Thus you won't be able to merge on them. You'll need to create a new custom field with the same name.
Before trying to find fields in the Hightouch dropdown menu, you need to ensure the above is true for the fields you wish to merge on. Here's how:
  1. In Salesforce, find the "Sales" module and go to it:
  2. Go to Setup in the upper right:
  3. From within setup, find the Object Manager:
    Search for object manager
  4. Select the object you want to merge data into, for example, the contact object:
  5. At this point, you may either create a new custom field and set it to Unique and an External ID, or check an existing field to ensure it is unique and set to an external ID. Lets create a new one:
    Click on the "New" button in your chosen object
    Choose the field type you want to use
  6. Create a new custom field (we chose an e-mail field type in this example):
    Select the 2 required options as shown
    These 2 options must be selected in order for Hightouch to detect the fields in our configuration form dropdown. After ensuring these are checked, proceed by clicking the "Next" buttons in Salesforce to finish updating your object with the new custom field.
    Then come back to Hightouch. From the Salesforce destination configuration form, click the 'refresh' icon if needed to see the field available for selection. You should now be able to merge on it.
    You should now be able to find your field in the destination 'Field' dropdown menu

Multi Object Syncs

Hightouch supports syncing to multiple target objects, such as Contact or Lead and Account or Lead. When syncing to multiple objects, Hightouch checks to see if your external ID mapping maps to either object -- if so, it updates the appropriate object.
To use multi object syncs, make sure that your Lead's external ID field is mapped to the matching field on your Contact or Account:
  1. Find Lead in the Salesforce Object Manager.
  2. Go to Fields & Relationships.
  3. Go to Map Lead Field.
  4. Map your Lead's external ID to the matching field on the Contact or Account.
You may also map other fields that you want to carry over from Leads when they're converted.

Syncing Custom Picklist Values

Sync Modes

This integration only supports the All sync mode. In this mode, all active picklist values are replaced with each sync.

Sync Configuration

Picklists are first filtered by the object they're associated with. Hightouch then allows you to specify the picklist whose values you wish to update:

Record Matching

Custom picklist values contain two main fields "label" and "API Name" (also referred to as valueName). Both values must be unique amongst active values, though API Names must be unique across both inactive and active values within a picklist.
Records can be matched from your source to your Salesforce workspace by the API Name mapping of your choice:

Field Mappings

You may also sync custom labels from your source to your custom picklist values in Salesforce:

Limitations

Custom picklists may only contain a total of 1000 values (active and inactive) per picklist.

Syncing Platform Events

Sync Modes

This integration only supports the Insert sync mode. Platform Events are considered Immutable, so any detected row changes or row removals will be ignored by Hightouch. If you would like support for Platform Event changes being sent, please let us know. In the meantime, it is a best practice for any changes to Platform Events to result in a new row returning from your model.

Sync Configuration

Platform Events first need to be created in your Salesforce instance. All created events will then be surfaced within the sync configuration in a dropdown for you to select.

Field Mappings

Any column available from your model's results can be mapped to a platform event. It's important to note that Hightouch does not support creating Platform Event fields, so when creating your event in Salesforce, ensure you're including all the relevant fields.

Troubleshooting

Common Error Messages

Error MessageExplanation
UNABLE_TO_LOCK_ROWThis error is caused by conflicting APEX or workflow processes. Salesforce cannot work on a row while another process is touching it. Delete or pause the process or rerun sync when processes are finished.
CANNOT_UPDATE_CONVERTED_LEADWhen you convert a lead to a contact, account, or opportunity, it cannot be updated as it does not exist anymore. The minute a lead is converted it is "soft" deleted from the leads object. You are no longer able to update this record.
INVALID_CROSS_REFERENCE_KEYThis error generally occurs when someone tries to sync ids from a different object or a different production or sandbox environment. It's a mismatch that Salesforce identifies for the user.
INVALID_FIELD_FOR_INSERT_UPDATEThis error often occurs when you try to update a read-only field. Visit your Salesforce object manager to confirm or change field types.
DUPLICATE_EXTERNAL_IDThis error occurs if you have records with the same IDs coming from an external system. Unique fields are unique to a record and cannot be duplicated. This can happen when a lead or contact was imported with the wrong External CRM ID. This error can also appear when you have null values in your primary key.
INVALID_OR_NULL_FOR_RESTRICTED_PICKLISTThis error occurs when you attempt to sync invalid data into a picklist field, e.g. the length is too long or the data type incorrect. Review the field's settings in Salesforce.
See Salesforce's comprehensive list of error messages and error codes for more.

High CPU Limit

Customers may experience issues with pushing data into Salesforce because of the amount or complexity of their APEX triggers. The way to determine if your APEX is causing this High CPU Limit error message is to go into setup and search for "Bulk Data Load Jobs".
From here you will be able to see all of the bulk jobs that are hitting the API for your instance of Salesforce. To see the impact of this job run, select one of the most recent jobs, by clicking on the job id.
Here we can see that there is no APEX impact on the far right side of the page with 0 time processing APEX. If your job has a high processing time, this will impact performance or cause High CPU limit errors.
The best course of action to solve the High CPU limit error is to drop your batch size in half. By default, Hightouch does batch sizes of 1,000. You can have a maximum of 10,000 records per batch. If you have dropped your batch size in half and are no longer encountering the error, you can continue to tune this by raising the batch size limit slowly. The other option is to simplify any APEX triggers or Process Flows that you have by consolidating superflous code or limiting your SOQL queries to a more manageable size.

Missing Fields in Sync Configuration

  1. Please check to make sure fields you want to match against are set as external identifiers.
  2. If you authenticated with your personal user id, make sure you have permission to view and update the fields you want.

Limitations on Sandboxes

If you are building Hightouch syncs to Salesforce sandbox environments and encounter processing delays or errors, check the version of your Salesforce sandbox and upgrade to a higher version if necessary. You can find more information here: Salesforce Sandbox Licenses and Storage Limits by Type

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    or

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

OverviewOAuth with Salesforce AuthenticatorAccess Level RecommendationsSyncingSync ModesObject ID LookupSalesforce Person Account SetupTrouble merging data into Salesforce fields?Multi Object SyncsSyncing Custom Picklist ValuesSync ModesSync ConfigurationRecord MatchingField MappingsLimitationsSyncing Platform EventsSync ModesSync ConfigurationField MappingsTroubleshootingCommon Error MessagesHigh CPU LimitMissing Fields in Sync ConfigurationLimitations on Sandboxes

Was this page helpful?