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

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

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.

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.

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

Inspect objects, relationships, and fields

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

   

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

   

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

   

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.

   

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.

   

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.

   

   • 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.)

   

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

   

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

   

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

   

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

   

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.

   

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

   

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

  

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

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.

Record matching

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.

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.

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.

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.

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.

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]

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.

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:

In Upsert mode, you can select from all three. In Update mode, you can only select between Do nothing and Clear fields. 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.

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.

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

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:

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.

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.

   

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.

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:

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.

Field mapping

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

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.

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 reach out. We're here to help.

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.

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.

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.

Sync alerts

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