Search documentation...

K
ChangelogBook a demoSign up

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 create platform events to drive more automation in Salesforce.

Use the Salesforce destination to sync to:

  • Salesforce Sales Cloud (CRM)
  • Salesforce Financial Cloud
  • Salesforce Health Cloud
  • Salesforce Service Cloud

Supported syncing

Sync TypeDescriptionSupported Sync ModesAPI Reference
Standard and custom objectsSync records to Salesforce objects such as accounts, contacts or custom objectsInsert, Update, Upsert, ArchiveSalesforce object reference
Metadata for picklist fieldsSync metadata to your Salesforce Picklist fields.AllMetadata field types
Platform eventsPublish event messages that can be received by Salesforce flows, processes, Apex triggers, and more.InsertPlatform events developer guide
  • Insert: Insert mode pushes new objects or events to Salesforce and doesn't update them as they change in your data source. Insert is the only available mode for platform events.
  • Update: Update mode updates fields on existing objects in Salesforce.
  • Upsert: Upsert mode pushes new objects to Salesforce and updates fields that change in your data source.
  • Archive: Archive mode deletes all records that appear in your model's query results.
  • All: All mode is the only available mode for metadata for picklists. Each time you sync metadata values for a particular picklist, it overwrites all existing values.

For more information about sync modes, refer to the sync modes docs.

Understand your Salesforce setup

Before you begin your Hightouch to Salesforce sync configuration, clarifying your business goals and understanding your Salesforce setup is crucial. Walk through the following considerations to ensure your team is aligned and your sync plans are clear. If you prefer, you can download this resource as a PDF to share with your team.

Business goals

First, you need to plan what data you want to sync to Salesforce, how you want to update it, and how frequently you want to update it. Consider your business needs and consult with your team to align on the answers to these questions.

The following table shows how the responses affect your sync configuration.

Consideration
Effect on sync configuration
What standard and custom objects do you want to sync to Salesforce? Contacts, Leads, etc.?The response affects your sync types—in other words, which objects you select to sync to. You need to set up a separate sync configuration for each object you want to sync to.
What standard and custom data fields do these objects have that you want to sync to?The response affects the field mapping on each of your syncs.
Do you have new data to add, old data that needs updating, or a combination of both?The response affects your sync modes—for example, insert mode for new data, update mode for old, and upsert mode for both.
How frequently do you need to update the data?The response affects your sync schedule. This is the last step of your sync configuration.

To learn what objects and fields you are using in your Salesforce instance, you can inspect your Object Manager.

Required data specifications

Once you've confirmed the objects and fields you want to sync, you need to check that they have the correct data types and that you have permission to edit them. You can find the answers to these questions by using the Object Manager in Salesforce.

Consideration
Effect on sync configuration
Is the field that you would like to use for record matching an external ID and unique?The response affects your record matching; only fields that meet this criteria appear in the dropdown for record matching.
What are the expected data types of the fields you want to sync to?The response affects your field mapping; if the expected type is different than your model column type, you need to type cast your data in your model configuration.
Are the fields you want to sync to editable?Hightouch only displays editable fields during field mapping.
Does the user you are authenticating to Hightouch have edit access?The sync will error if the user doesn't have the correct permissions.
Are any of the data fields lookup fields to another Salesforce objectYou can set up Lookup fields while field mapping.
Are any of the data fields formula fields?Formula fields are non-editable and read-only, so the sync will throw an error; change the field type if you want to sync data to it.

Other considerations

These last considerations examine the wider context of your Salesforce instance to ensure that your sync won't conflict with other Salesforce automations or overuse your API call quota.

You can inspect an objects' triggers and flows using the Object Manager. You can inspect your API usage and quota by going to Setup > Environments > System Overview, or by checking Salesforce's quick reference.

Salesforce API usage

Refer to your Salesforce contract in case of any custom limits.

Consideration
Effect on sync configuration
What Salesforce workflows or APEX triggers are you running? What objects do they touch, when do they run?The response affects your sync schedule; syncs will error if there are conflicting processes.
What Salesforce plan do you have and what are your API limits?The response affects your sync schedule; syncs will error if you use up your API call quota.

Inspect objects, relationships, and fields

  1. Login to your Salesforce instance and make sure you are in the Sales module.

    Screenshot of Salesforce Sales module homepage

  2. Click on the gear icon in the top right and open the Setup page.

    Screenshot of Salesforce Sales module homepage

  3. Search for Object Manager in the left search input and open it.

    Search for Object Manager

  4. Search for the object you are interested in syncing to the Quick find input, for example Contact. Click on the label name to inspect the object.

    Search for objects in the Object Manager

  5. From the left sidebar, click Fields & Relationships. Inspect the field names and data types to confirm which you plan to sync via Hightouch. Any fields you want to use for record matching must have the External ID and Unique types.

    Inspect fields and relationships in the Object Manager

  6. If necessary, create a new custom field and set it's type to Unique and an External ID.

    • Click New in your chosen object's Fields & Relationships.

    Click on the "New" button in your chosen object

    • Choose the field type, for example Email or Text, then click Next. (You'll set the Unique and an External ID types in the next step.)

    Choose the field type you want to use

    • Give your new field a Field Label and description. Enable the Unique and External ID checkboxes. Click Next.

    Select the 2 required options as shown

    • Select the profiles to which you want to grant edit access to this field via field-level security. The field will be hidden from all profiles if you don't add it to field-level security. Click Next.

    • Add the field to the page layouts you like and click Save.

Inspect APEX triggers and flows

  1. Login to your Salesforce instance and make sure you are in the Sales module.

    Screenshot of Salesforce Sales module homepage

  2. Click on the gear icon in the top right and open the Setup page.

    Screenshot of Salesforce Sales module homepage

  3. Search for Object Manager in the left search input and open it.

    Search for Object Manager

  4. Select the object you want to inspect the APEX triggers and workflows for, for example Contact. Click on the object to open its detail page.

    Search for objects in the Object Manager

  5. From the left sidebar, click Triggers or Flow Triggers, depending on which one you want to inspect first.

    Object Triggers

  • The Triggers page displays a list of all the APEX triggers that are associated with the object. To inspect a specific trigger, click its name.

  • The Flow Triggers page displays list of all the workflows that are associated with the object. To inspect a specific flow, click its name.

    Object Triggers

  1. Once you've opened a specific workflow or trigger, you can inspect its properties, such as its name, status, and other details. You can also edit or delete the workflow or trigger from this page, as well as view the history of changes made to it, if you have the correct permissions.

If you have any triggers or flows on objects you plan on syncing to, make sure to schedule your Hightouch syncs so as to not conflict with them.

Connect to Salesforce

Go to the Destinations overview page and click the Add destination button. Select Salesforce and click Continue. You can then authenticate Hightouch to Salesforce via OAuth.

We recommend that you authenticate with a user that has access to update all fields, records, and objects that you need to interact with. The easiest way to do this is to authenticate with a system administrator or integration account user.

Click Log in to Salesforce, log in with a Salesforce account with the correct access level, and click Allow. You should then see a success notification in the Hightouch UI.

Success notification in the Hightouch UI

If you have Salesforce Authenticator setup as your 2FA, you may have to accept the request from your device.

After you've authorized access to Salesforce click Continue. Give your destination a descriptive name, for example, "Salesforce Production," and click Finish.

Sync configuration

Once you've set up your Salesforce destination, have a model to pull data from, and have a clear idea of the data you want to sync, you can set up your sync. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Salesforce destination you want to sync to.

Syncing objects

When syncing objects, you can choose to insert, update, upsert, or delete (archive) them. Consult the following table to understand which is best for your use case.

Sync modeUse case
InsertYou want to push objects into Salesforce, but don't care if the data within each object remains up to date.
UpdateYou have objects in Salesforce that you want to add information to, but you don't want to create any new objects.
UpsertYou want to push objects into Salesforce and want to keep the data up-to-date.
ArchiveYou have objects in Salesforce you would like to delete and your model contains those records and only those records.

Record matching

Because inserts are non-idempotent when using Salesforce ID as an identifier, Hightouch doesn't support matching on Salesforce ID when upserting. If you'd like to sync records based on Salesforce ID, use update mode.

To match rows from your model to record in Salesforce, you need to select the model column and corresponding Salesforce field. Hightouch requires you use an external ID type field as the field to match on. It should be an explicit external ID type in Salesforce, not just an external ID field by practice.

Using an external ID field for matching lets Hightouch use Salesforce's native upsert API, meaning Hightouch doesn't need to perform a search to determine if a record should be updated or inserted. As a result, sync performance improves and avoids inadvertent duplicates.

You can create a custom field and set it to the external ID type by following the steps outlined above. To learn more, check out the Salesforce article on externalID field creation. The information regarding audit fields in the Salesforce article doesn't apply.

Once you've created the custom field, click the refresh icon to access the newly created field. An explicit external ID field will have (recommended) written next to its name.

Refreshing fields in the Hightouch UI

Field mapping

You can map data from any of your model columns to native and custom fields in your Salesforce objects. Ensure the data type of your model column matches the data type of the field you want to sync to in Salesforce. For example, a string-type Salesforce field like FirstName expects a string-type model column.

Field mapping in the Hightouch UI

Certain Salesforce fields can be set upon record creation but can't be edited on existing records. Since Salesforce rejects updates to fields that can't be edited:

  • in Update mode, the field mapping section only lists editable Salesforce fields;
  • in Upsert mode, you can also map to non-editable Salesforce fields, but Hightouch omits those mappings when updating existing records, to make sure that your sync is successful.

To see if a field is editable, check its updateable field property via the Salesforce API. You can check this property by generating an initial access token and calling the sObject Describe API endpoint. The updateable value is included in Salesforce's API response, as shown in this example.

When syncing to a multi-select picklist type field, make sure to sync string-type values containing semicolon-delimited lists, as explained in Salesforce's documentation.

Relationships (object ID lookup)

In Salesforce, you can set up different types of relationships to associate records on a main object with records on a linked object. Using Hightouch, you can relate your Salesforce data through lookup relationships, which associate records by using a foreign key. This relationship type requires you to copy the Salesforce ID of the associated record (on the linked object) and insert it in a specific reference field in the record you're syncing (on the main object).

This reference field needs to be an associated field data type, which corresponds to Salesforce's lookup type. You can confirm the field is a lookup data type in Salesforce by using the Object Manager.

Lookup data type in the Salesforce UI

For example, you may want to associate contacts you're updating with their respective Salesforce accounts. In this case, the Contact object is the main object and the Account object is the linked object.

Records on the Contact object have an AccountId field which expects the Salesforce ID of the related records on the Account object. However, your data model might not contain the required Salesforce ID values. As a workaround, Hightouch allows you to perform an Object ID lookup by:

  1. looking up the Account object based on another unique Salesforce field,
  2. retrieving the Salesforce ID of the associated record on the Account object,
  3. syncing that value to the AccountId field on the Contact object.

Make sure to use a unique Salesforce field for the lookup. If you already created a separate sync to the linked object, you can select the Salesforce field used for record matching in that sync.

If your source data already contains the required Salesforce ID values, you can skip the lookup by selecting the Salesforce ID field in the relationship mapping. This will also increase your sync performance.

Make sure that the sync to the linked object always runs before the one to the main object. After creating your syncs, you can set up a sequence to schedule them in the correct order.

In your sync configuration, start by selecting the Salesforce reference field you want to sync to. The left side of the mapper displays the text and inputs:

  • find [linked object]
  • where [Salesforce field to use for lookup]
  • equals [model column to match on]

Object ID lookup in the Hightouch UI

You then need to select the Salesforce field and model column to match on. In this example, Hightouch looks up the corresponding record on the Account object by matching the value in the unique_key model column to the values in the Unique_Key__c Salesforce field. The lookup returns the associated Salesforce ID, which Hightouch syncs to the AccountId field on the Contact object.

Object ID lookup in the Hightouch UI

You can set up a lookup relationship between records on the same object, such as relating two records on the Account object by mapping the ParentId lookup field.

Delete behavior

The delete behavior you select dictates what to do when a row no longer appears in your model's query results. Depending on the sync mode you're using, you can select from some or all of these options:

BehaviorDescription
Do nothingKeep the record in Salesforce
Clear fieldsKeep the record, but clear the mapped fields
Delete recordDelete the record in Salesforce

In Upsert mode, you can select from all three. In Update mode, you can only select between Clear fields and Delete record. Insert mode doesn't support delete behavior.

Batching and parallelization

By default, Hightouch sends batches of 1,000 records to Salesforce and sends ten batches in parallel.

Batch and parallelization settings in the Hightouch UI

You can increase the batch size up to 10,000 records per batch and parallelization up to 50 batches. Higher batch sizes and batch parallelization can increase the speed of your sync, but may eventually cause errors due to the amount of processing power they require from Salesforce.

If you run into APEX errors such as TOO_MANY_APEX_REQUESTS it can be helpful to lower and tune these numbers. For example, you can decrease your batch size by half and if you no longer encounter errors, you can raise the batch size limit slowly.

Bulk API version

Hightouch supports both legacy Bulk API and Bulk API 2.0. Hightouch uses the original Bulk API by default. You can opt in to use V2.0 in the sync configuration.

The API versions have different batch and parallelization limits. Specifically, the original Bulk API counts the number of calls and Bulk API 2.0 counts the number of records. You can learn more about different limits and allocations between the two versions in Salesforce's docs. You should select the version that best suits your Salesforce agreement.

Insert mode doesn't support Bulk API 2.0.

Split retries

Salesforce return a 200 successful response even when part of a batch of updates failed. In some cases, you may want to retry the failed records, like for the UNABLE_TO_LOCK_ROW error. You can enable split retries to filter out the records that received the relevant errors and retry them again.

Merging objects

You can only merge Account, Contact, Individual, and Lead objects. Only upsert and insert modes support merging, and you must set parallelization to 1.

If your model contains child records that should be merged into a parent record, Hightouch handles merging the records into their respective parents based on two fields:

  • shared_id
  • merge_id or is_child

Hightouch treats records with the same shared_id as the same record and merges them together. All child records in a group with the same shared_id must have a merge_id or is_child field populated.

For example, suppose you have the following records in your model's query result:

AccountShared IDIs child
Account A1true
Account B1true
Account C1false
Account D2false
Account E3false
Account F3true

Hightouch would merge Account A, Account B, and Account C together with Account C as the parent. Accounts E and F will be merged together with Account E as the parent.

Select the appropriate model columns and corresponding Salesforce fields for this logic.

Merge settings in the Hightouch UI

Multi-object syncs

Hightouch supports syncing to multiple 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. You can check by following these steps.

  1. Find the Lead in the Salesforce Object Manager. Refer to the above documentation for information on how to use and access the Object Manager.

  2. Go to Fields & Relationships.

  3. Click Map Lead Field.

    Mapping Lead Fields in the Salesforce UI

  4. Map your Lead's external ID to the matching field on the Contact or Account.

    Mapping Lead Fields in the Salesforce UI

You may also map other fields that you want to carry over from Leads when they're converted.

Salesforce person accounts syncs

If you need to send data to a Salesforce person account, follow these steps:

  1. Contact Salesforce to enable person accounts if they aren't already.
  2. In your Hightouch sync configuration, select Account as the object to sync data to. A person account is a copy of the account object.
  3. Select your desired sync mode.
  4. Ensure you map at least a LastName field instead of FullName. Without this level of specificity, the sync fails.
  5. Complete your configuration as usual.

Syncing custom picklist values

Hightouch lets you update picklist values on any object. You need to create a separate sync configuration for each picklist you want to update, even if the picklists exist on the same object.

When syncing custom picklist values, all active picklist values are replaced with each sync. For example, if your model returns four records, all four records become values for your picklist. Hightouch doesn't check which values are already there or append the new values. Each sync completes overwrites existing picklist values.

First, select the object whose picklist you want to update, then specify the picklist whose values you wish to update:

Picklist configuration in the Hightouch UI

Record matching

Hightouch matches rows from your model to picklist values on the values' API name, also referred to as valueName. Select the model column that includes the appropriate API names for matching. API names must be unique across both inactive and active values within a picklist.

Picklist configuration in the Hightouch UI

Field mapping

You can optionally select a model column that custom labels. Label values must be unique amongst active values in a picklist.

Picklist configuration in the Hightouch UI

Limitations

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

Syncing platform events

Salesforce platform events are immutable, which means that you cannot update or delete them after they have been published. As a result, platform event syncs always use insert mode. This means that Hightouch ignores row changes and removals in your model's query results, and publishes a new platform event whenever a new row appears in your model results.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Before events appear in your Hightouch sync configuration, you first need to create platform events in your Salesforce instance. Hightouch then surfaces them within the sync configuration in a dropdown.

Record matching

Since platform events are Insert only, you don't need to match them to existing records.

Field mapping

You can map any column in your source to a platform event. Hightouch doesn't support creating platform event fields. When creating your event in Salesforce, ensure you're including all the relevant fields so that Hightouch can sync to them.

Tips and troubleshooting

Sync volume and performance

Hightouch can process millions of rows to Salesforce in a single sync, given you have the available Salesforce API calls. In other words, sync volume limitations are a factor of your Salesforce API request limits and allocations, rather than Hightouch. If you're syncing large volumes of data, you may want to finetune your batching and parallelization configuration for optimal performance.

Upsert mode calls Salesforce's upsert endpoint, which can improve sync performance and lower API datapoint consumption since it only requires one single API request per batch of rows. However, there are still some additional API calls for rejected row retries and miscellaneous data that needs to be sent to Salesforce. This efficient Upsert mode only works when the Salesforce field used for record matching is an explicit external ID field.

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

Error MessageExplanation
CANNOT_UPDATE_
CONVERTED_LEAD
When you convert a lead to a contact, account, or opportunity, it can't be updated as it doesn't exist anymore. The minute a lead is converted it's "soft" deleted from the leads object. You are no longer able to update this record.
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 can't be duplicated.

This can happen:
  • when a lead or contact was imported with the wrong External CRM ID
  • when you have null values in your primary key
  • when the Salesforce field used for record matching contains duplicates
DUPLICATES_DETECTEDVerify that your batch of data doesn't include duplicates within the batch. Unique fields are unique to a record and can't be duplicated.

This can happen:
  • when you have null values in your primary key
  • when the Salesforce field used for record matching contains duplicates
INVALID_CROSS_
REFERENCE_KEY
This 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_UPDATE
This error often occurs when you try to update a read-only field. Visit your Salesforce Object Manager to confirm or change field types. It can also happen if you're using record types and you don't set a default record type.
INVALID_OR_NULL_
FOR_RESTRICTED_PICKLIST
This error occurs when you attempt to sync invalid data into a picklist field, for example, the length is too long or the data type incorrect. Review the field's settings in Salesforce.
INSUFFICIENT_ACCESS_ON_
CROSS_REFERENCE_ENTITY
Check that your Salesforce credentials have access to the Salesforce object you are cross-referencing in your sync.
INSUFFICIENT_ACCESS_
OR_READONLY
Check that your Salesforce credentials have access and/or write access to the Salesforce object you are referencing in your sync.
INVALID_TYPE_ON_
FIELD_IN_RECORD
See below.
OAUTH_APP_BLOCKEDSee below.
UNABLE_TO_LOCK_ROWSee below.
ValidationError:
Reference not found
See below.

See Salesforce's comprehensive list of error messages and error codes for more.

UNABLE_TO_LOCK_ROW

This error occurs when one or more users or processes—including Hightouch syncs—are trying to modify the same record at the same time. Salesforce can't work on a row while another process is touching it. To mitigate this error, you can try the following solutions:

  • Remove conflicting processes: If there is an APEX trigger or workflow that conflicts with your sync, delete or pause the process or rerun sync when the process finishes. Usually, this error is a temporary issue that can be resolved by retrying the operation after a few minutes.
  • Reduce the number of parallel processes: lowering your parallelization to five or less minimizes the chances of two requests trying to modify the same record at the same time.
  • Check for long-running processes: Identify any long-running processes in your Salesforce environment that could be holding locks on records for an extended period. Try to optimize these processes or break them up into smaller batches to reduce the time they take to complete.
  • Remove duplicated records: This error can also be caused by duplicates in your model's query results. Ensure your model doesn't return any duplicated rows and try the sync again.

You can find more information from Salesforce's Help Center.

INVALID_TYPE_ON_FIELD_IN_RECORD

This error occurs when sending a null value to a Boolean field in Salesforce or when a before-save update flow tries to set a value that conflicts with the value sent from Hightouch. To mitigate this error, you can try disabling or modifying the flow.

OAUTH_APP_BLOCKED

This error occurs when Hightouch is installed in Salesforce. Ensure that it's unblocked on the Connected Apps OAuth Usage page. The user verifying OAuth permissions must be an admin in Salesforce. Additionally, Hightouch should be granted read and write access to all the objects and fields that you intend to sync.

Keep in mind that Salesforce requires the "View Setup and Configuration" permission for the user account. Ensure that this permission is enabled in the Profile assigned to the user, under the "Administrative Permissions" section of their profile.

ValidationError: Reference not found

This error indicates that a relationship lookup mapping in the sync configuration isn't able to successfully perform the lookup. The error message contains the Salesforce field name used for the lookup and the value that is causing the failure. Ensure that the model column used for the lookup mapping only contains values that already exist in Salesforce.

Missing fields in sync configuration

If you are missing an expected field when configuring syncs, try these tips:

  • Ensure fields you want to match against are set as external identifiers.
  • If you authenticated with your personal user ID, make sure you have permission to view and update the fields you want.
  • If you're missing the Salesforce ID field for matching on, make sure you're in the correct sync mode. Matching on Salesforce ID isn't supported for upserting—use update mode instead.
  • If you set your sync to Update mode, the field mapping section only lists updateable Salesforce fields.

When syncing to multi-objects, for example, Contact or Lead or Account or Lead, ensure both object types include a shared unique field marked as a Unique ID or a unique external ID. Without meeting this requirement, you won't see any fields populate for record matching.

Record matching on multi-objects in the Hightouch UI

Duplicate records in Salesforce

Make sure that the Salesforce field used for record matching is an explicit external ID field. You can learn more about this in the record matching section.

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

Enhanced domains

If you are enabling enhanced domains for your Salesforce instance, you need to reauthorize your Salesforce destination to avoid sync disruptions.

To do so, go to your Salesforce destination configuration page, and click Log in to Salesforce under Reauthorize connection.

Reauthorizing the Salesforce connection in the Hightouch UI

To learn more about enhanced domains, check out Salesforce's enhanced domain FAQ.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

The debugger isn't available for All and Insert sync modes.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Jan 25, 2024

On this page

OverviewSupported syncingUnderstand your Salesforce setupBusiness goalsRequired data specificationsOther considerationsInspect objects, relationships, and fieldsInspect APEX triggers and flowsConnect to SalesforceSync configurationSyncing objectsSyncing custom picklist valuesSyncing platform eventsTips and troubleshootingSync volume and performanceCommon errorsMissing fields in sync configurationDuplicate records in SalesforceLimitations on sandboxesEnhanced domainsLive debuggerSync alerts

Was this page helpful?