Legacy Salesforce: Configuring user and organization syncing in Salesforce

Important: On 30 January, 2020 the legacy Salesforce Integration (managed package) will be deprecated and replaced by a new Salesforce Integration - built on Zendesk. Read the announcement about the removal of the legacy Salesforce Integration and timelines here.

The legacy Salesforce Integration is no longer available to install. If you need to upgrade the legacy integration to version 5.9, please contact Zendesk Support.

We are excited to be offering a new Salesforce Integration - built on Zendesk which is now generally available. You need to have a Salesforce Edition with API rights to use this. Get started with setting up the new integration here.

If you do not have a Salesforce Edition with API rights, you can:
Try the Workato Salesforce to Support Integration
Try Zendesk Sell with its native integration to Zendesk Support

Updated: February 13, 2018 (for package 5.6.1)

You can configure a one-way, ongoing sync from Salesforce to Zendesk. You can sync Contacts/Leads to users, and Accounts and to organizations. You can also filter the Contacts/Leads and Accounts that are synced into Zendesk.

Note: You must have installed the Zendesk for Salesforce app before you configure user and organization syncing.

Important: This is an advanced feature. New Salesforce installations and smaller Salesforce organizations with clean data can go ahead and give it a try. However, for more complex Salesforce organizations, contact your Zendesk account manager to determine whether this feature is right for you and to get implementation assistance.

This article covers the following topics:

• Understanding limitations of sync
• Preparing for the sync process (Group and Professional editions only)
• (Optional) Setting a logging level
• Configuring ongoing syncing to Zendesk organizations and users
• Creating a sync filter condition

Related articles:

• Choosing Zendesk for Salesforce features
• Salesforce: Using the Zendesk Support bulk sync feature
• Using multi-organization membership in the Salesforce integration
• Salesforce integration resources

For links to all of our Salesforce documentation, see Salesforce integration resources.

Understanding limitations of sync

The sync functionality for users and organizations is very powerful. But there are limitations to this feature that you should understand before you decide if sync is right for you.

• Neither the organization sync or the user sync will move Person Accounts. The organization sync treats Parent Accounts as normal organizations in Zendesk. It does not give any special consideration to the Parent relationship.
• The user sync does not support Converted Leads.
• Currently, ongoing sync will not run if triggered by more than one record (such as a bulk upload of records through Salesforce data loader, or bulk update of records using Salesforce batch job). We do not support bulk sync triggers, as we cannot control the record processing rate, and multiple sync requests can excessively consume system resources in both Salesforce and Zendesk, which can impact performance. If you need to sync a large number of records, we recommend using our bulk sync feature, which can sync up to 250,000 records.
• If an account has previously synced from SFDC to Zendesk, the related organization ID is stored in a hidden Account field called Zendesk Support Organization ID. If organizations are failing to sync, please add this field to a layout to see whether this value is set, and to which organization it corresponds.
  Warning: A value present within this field will take precedence over other sync matching logic. If you have previously synced with a different instance of Zendesk, the difference in organization ids may cause issues when syncing with the new instance. Removing this value and re-syncing would force a sync based on matching logic which should resolve the issue.

Preparing for the sync process (Professional edition only)

If you are using the Professional edition, you need to complete this procedure before you can start the synchronization process.

Important: You must add all of the following package fields for the sync process to work. Do not omit any of the items in the steps below.

To prepare for the sync

1. Add all of the following Zendesk package fields to the page layouts for admins on Account:
   • createdUpdatedFlag
   • Domain_Mapping
   • Last Sync Date
   • Last Sync Status
   • Notes
   • Tags
   • Zendesk_oldTags
   • Zendesk_OutofSync
   • Zendesk_Organization
   • Zendesk_Organization_Id
   • Zendesk_Result
2. Add all of the following Zendesk package fields to the page layouts for admins on Contact:
   • isCreatedUpdatedFlag
   • Notes
   • Tags
   • Zendesk_oldTags
   • Zendesk_OutofSync
   • Zendesk_Result
   • Zendesk_User_Id
3. Add all of the following Zendesk package fields to the page layouts for admins on Lead:
   • isCreatedUpdatedFlag
   • Notes
   • Organization
   • Tags
   • Zendesk_oldTags
   • Zendesk_OutofSync
   • Zendesk_Result
   • Zendesk_User_Id

If you do not add these fields to the layout before you set up the sync, you'll see a section called Objects and field permissions in the settings page listing all the missing field permissions. You'll need to add the fields to your layout to resolve the missing permissions.

(Optional) Setting a logging level

You can determine if and when you'd like to collect a log. Logs are saved in a custom object included in the package called Integration Logs.

To set the logging level

1. In Salesforce, click the Zendesk tab in the Zendesk for Salesforce app.
2. Locate the Logging level section.

   

3. Select a Logging level from the drop-down:
   • None does not create a log
   • Error creates a log when errors occur only
   • Debug always creates a log
4. Select an option for Weeks to retain logs.
5. Click Save Logging Level.

Note: You should not use the option to export debug data to a CSV file unless you are working with Zendesk Support.

Configuring ongoing syncing to Zendesk organizations and users

You can configure an ongoing sync that automatically creates and updates Zendesk organizations immediately after accounts are created or updated in Salesforce. Likewise, you can configure an ongoing sync that automatically creates and updates Zendesk users immediately after contacts or leads are created or updated in Salesforce.

This is a one-way sync of data; changes applied in Zendesk are not reflected in Salesforce. The sync is triggered when a mapped

field is updated (in an existing record), or created (in a new record). Updates to unmapped fields do not trigger the ongoing sync.

If you set up the ongoing sync, we suggest performing an initial bulk sync (see Using the Zendesk Support bulk sync feature). The bulk sync option is also an advanced feature.

Enabling and configuring the sync requires updating a number of settings on the User and Organization Sync Settings page.

Begin by opening the User and Organization Sync Settings page and verifying the general settings.

When a record in Salesforce is created or changed, part of the syncing process is an attempt to establish whether a new record in Support should be created, or if an existing record should be updated. This is done by comparing field values based on user-configurable criteria.

If more than one matching result is found, the sync is unable to determine which record in needs to updated; and, since this is a background process, there is no way to ask the user to clarify which record is the correct match (which is what bulk sync does). In this case ongoing sync won't update any of the records, and instead will log an unsuccessful sync event.

The automatic matching criteria are shared with bulk sync and are explained here.

As in a bulk sync, once a successful match of existing records has been made, or a new record has been created in Support, the Salesforce record and the Support record are linked by placing an external ID on each one.

This means that subsequent updates to the record in Salesforce won't need to use matching criteria but rather update the linked record on the Support side.

This also allows Support users to configure the Salesforce sidebar app to look up Salesforce data based on the external ID stored in Support.

Important: Populating the External Id field in Zendesk Support could interfere with other integrations that rely on this field.

Zendesk Searchable Fields

Not all fields in Zendesk are available for searching (standard fields like domain_names, details, etc are not available to be used in a matching criteria).

Available Zendesk fields that can be used are listed below:

Organization Searchable Fields

• name
• custom fields

User Searchable Fields

• name
• email
• custom fields

To enable ongoing sync for Accounts and Organizations

1. In Salesforce, click the Zendesk tab in the Zendesk for Salesforce app.
2. In the User and Organization Sync Settings section, click Go to Mappings. The Sync Settings page opens.
3. Use the Sync Pairing drop-down menu to select Accounts - Organizations, if it is not already selected.
4. In the General Options section, use the Enable Updates drop-down menu to select Yes, if it is not already selected.

To complete the sync setup, you need to configure the following:

• Updating the sync filters
• Mapping Zendesk and Salesforce fields
• Configuring custom mappings and assigning picklist values
• Configuring syncs for Contacts to users, or for Leads to users

Updating the sync filters

First, you should consider setting the sync filters to choose what information is synced to Zendesk. You can tightly control the elements used in the sync by building conditional statements to filter the results.

To update the sync filters

1. On the Sync Settings page, locate the Filters section:

   

2. To create a sync filter condition, specify the Field, the Operator, and the Value (value field is left empty for "is blank" and "is not blank" operators) in the condition builder sections:
   • Meet ALL of these conditions: All of the Conditions added to this section must be satisfied to include the Salesforce record in the sync.
   • Meet ANY of these conditions: One or more of the conditions in this section must be satisfied to include the Salesforce record in the sync.

     For more detailed instructions on building filtering conditions, see Creating a sync filter condition.

3. (Optional) Click the Test Query button to see if the record count, sample records queried, and SOQL query match your expected outcome. The information is displayed in the Test your filters section:

   

   Important: Testing your filters does not mean the filters are already taking effect as your sync filter settings. Until you click the save button, the last saved filter configuration will still be the one used on currently running syncs. That also means, it is safe to tweak and test every filter combination on this page until you get your desired filtering as long as you don’t save it.

   If no filters were set up, all the supported records are in scope for syncing.

4. Click Save.

Mapping Zendesk and Salesforce fields

Now you need to map the Zendesk fields to the Salesforce fields you want to populate them.

To setup which account field to map to organization:

1. Navigate to Zendesk > User and Organization Sync Settings > Go to Mappings and set Sync Pairing dropdown to Accounts - Organizations.
2. In the Field Mappings section, configure the following:
   • Zendesk Support Organization Name: By default, this option is set to Account Name (Name). This controls which field in the Salesforce account record is synced as its related organization’s name.
   • Zendesk Domain Names (Optional): Use the drop-down menu to select the Salesforce fields you want to map to the Domain Names field, then use the Notes drop-down menu to select the Notes field on a Zendesk organization profile. If the domain value in Salesforce includes a protocol prefix (i.e. https://www.abc.com -> abc.com) it will be stripped when syncing to Zendesk.
   • Zendesk Tags: Use the picklist to select the available Salesforce fields to use as tags in your Zendesk, by clicking the field(s) in the left pane and using the arrows to move it to the right pane.The selected Salesforce field values are added as tags in your Zendesk.

     Mapping a field to domain names enables user mapping for organizations in Zendesk. User mapping automatically adds users to an organization based on their email domain when they are created in your Zendesk. If you want to enable user mapping, you must first set up a field on Account with the organization email domain(s) (separated by a space).

3. Click Save

Configuring custom mappings and assigning picklist values

Finally, configure any custom field mappings and assign picklist values, if needed.

To configure custom mappings and assign picklist values

1. On the Sync Settings page, locate the Field Mapping section:

   

2. Use the Salesforce Field drop-down menu to select a Salesforce field, and to display a new drop-down list of available Zendesk fields.
3. Use the Zendesk Fields drop-down to select a Zendesk custom organization field, then click Add.

   Mapping these fields means that they update during the ongoing sync and the bulk sync. The options in the Zendesk Field drop-down vary according to the type of field you select in the Salesforce Field drop-down; only fields of the same type will be available (see Allowed field types for Zendesk field mapping).

4. If you mapped a Salesforce picklist field to a Zendesk drop-down field, click Map beside each one, then select a drop-down value for each picklist value and click Add.

Configuring syncs for Contacts to users, or for Leads to users

You can also configure an ongoing sync for Contacts to users, and for Leads to users.

To configure a sync for Contacts to users, or for Leads to users

1. At the top of the User and Organization Sync Settings page, use the Sync Pairing drop-down menu to select Contacts - Users, or Leads - Users.
2. In the General Options section, use the Enable Updates drop-down menu to select Yes, if it is not already selected.
3. Update the Filters, Tag Mapping, and Field Mapping sections as described above.

Allowed field types for Zendesk field mapping

The following table shows the supported Salesforce field types and the corresponding allowed Zendesk field types.

Supported Salesforce field type	Drop-down	Text	Multi-line text	Numeric	Decimal	Checkbox	Date
Auto Number		X	X
Checkbox						X
Currency					X
Date							X
Date/Time		X	X				X
Email		X
Geolocation				X	X
Number				X (if no decimal is present)	X
Percent					X
Phone		X	X
Picklist	X
Text		X	X
Text Area		X	X
Text Area (Long)		X	X
Text Area (Rich)		X	X
Text Area (Encrypted)		X	X
URL		X	X

Creating a sync filter condition

To create a sync filter condition, specify the field, the operator, and the value (value field is left empty for ‘is blank’ and ‘is not blank’ operators).

If you wish to remove a condition from the table, click the Clear link on its row.

Related-record field filtering

Related-record fields have a double angle bracket (>>) at the right side of the label:

If you click the bracket, the fields for that related record are displayed. Click Back to return to the main field list.

Operators for each field type

Operator options will vary depending on the type of field you have selected.

Date field operators:

• = (exactly the same date)
• != (not the same date)
• > (later than)
• >= (later than or same)
• < (earlier than)
• <= (earlier than or same)
• is blank
• is not blank

Datetime field operators:

• = (exactly the same datetime)
• != (not the same datetime)
• > (later than)
• >= (later than or same)
• < (earlier than)
• <= (earlier than or same)
• is blank
• is not blank

Id field operators:

• =
• !=

Text field operators:

• =
• !=
• contains
• does not contain
• is blank
• is not blank

Picklist field operators:

• in
• not in
• is blank
• is not blank

Number field operators:

• =
• !=
• >
• >=
• <
• <=
• is blank
• is not blank

Checkbox field operators:

• =

Formula field operators:

Operators will depend on the output type of this formula. Except for the Picklist operators, it could be any of those field type mentioned above.

Important: Notice that you can choose multiple values for ‘in’ and ‘not in’ operators. That is particularly made for picklist fields and record . Also note that the first value selected in a filter using the ‘in’ operator will be used as the default value for that field on newly created Salesforce records in Bulk Sync.