Configuring Salesforce integration

You can access the Salesforce integration configuration in the Settings application under the Integration → Salesforce.com category. These settings allow you to authorize access to your Salesforce organization and modify how the system maps the attributes of Xperience contacts to leads in Salesforce.

Prerequisites

To configure the Salesforce authorization and use the synchronization, your Xperience administration application must have HTTPS set up.

If you wish to use synchronization of data from Salesforce leads back into Xperience contacts, your Xperience administration must also run on a publicly accessible domain.

Additionally, your server (IIS) must support the TLS 1.1 protocol or newer. For more information, see the IIS documentation.

Authorizing access to Salesforce

You need to authorize access of Xperience to your organization on behalf of a specific Salesforce user. This process requires you to generate a Consumer key and Consumer secret in Salesforce itself.

The following instructions apply to Salesforce Classic. The steps may be different if using Salesforce Lightning Experience.

  1. Log in to Salesforce.com.
  2. Navigate to App Setup → Create → Apps.
  3. Under Connected Apps, click New.
  4. Enter the following values for the remote access application:
    • Basic Information
      • Connected App Name: Type a name for the application. This name allows you to identify your application as the source of the request when authorizing access to your organization.
      • API Name: The application's name is filled in automatically.
      • Contact Email: Enter an email address where you want to be contacted.

    • API (Enable OAuth Settings)
      • Enable OAuth Settings: Select the checkbox.
      • Callback URL: Add the full URL of the AuthorizationSetup.aspx endpoint of your Xperience administration application. For example:
        https://administration.example.com/CMSModules/ContactManagement/Pages/Tools/SalesForce/AuthorizationSetup.aspx
      • Use digital signatures: Do not select the checkbox. The Salesforce integration does not use digital signatures for logging in.
      • Select OAuth Scopes
        • Full access (full)
        • Perform requests at any time (refresh_token, offline_access)
  5. Click Save, and copy the Consumer Key and Consumer Secret provided by Salesforce for your remote access application.
  6. Open the Settings application in the Xperience administration.
  7. Navigate to the Integration → Salesforce.com category.
  8. Click Authorize next to the Organization access setting.
  9. Paste your consumer values into the corresponding fields in the authorization dialog and click Authorize.
    • A Salesforce login screen opens in the current window.
  10. Log in and click Allow to grant permission to your Xperience application.

    Security

    The system uses the OAuth 2.0 protocol to authorize access to Salesforce. Your Salesforce login and password are never disclosed to Xperience. Access tokens are stored in encrypted format and the communication itself is encrypted over HTTPS.

  11. Save the settings to finish the authorization process.

The Organization access section now shows the user and company name that the application uses to authorize access to Salesforce.

On this page

Enterprise license required

Features described on this page require the Kentico Xperience Enterprise license.

Configuring the replication of contacts

Once the authorization is complete, you need to configure how the system replicates contacts into Salesforce leads. Access the settings in the Xperience Settings application under the Integration → Salesforce.com category.

Replication of contacts into Salesforce leads

Enabled

Enables or disables synchronization between Xperience contacts and Salesforce leads:

Keep Salesforce leads updated

If enabled, the replication process includes contacts that have already been replicated before. This ensures that the system updates the corresponding Salesforce leads based on the current contact data.

If disabled, contacts are only replicated once.

Mapping of contacts to Salesforce leads

Allows you to map contact fields to the fields of Salesforce leads. The synchronization process transfers data between contacts and leads according to the mappings.

See the Mapping contact fields to Salesforce lead fields section below for details.

Batch size

Applications can only make a limited number of API calls to Salesforce within a 24 hour window. To minimize the number of calls, the replication process handles contacts in batches. Each batch only requires one API call.

This setting specifies the maximum number of contacts that the system replicates in a single batch.

Score

Allows you to select the score that determines which contacts are replicated. The system only replicates contacts that reach a certain value in the given score (specified via the Minimum number of points for replication setting).

If you do not choose a score (None), the system replicates all contacts.

To learn more about scoring, refer to Scoring contacts.

Minimum number of points for replication

Specifies the amount of points that contacts must reach in the score selected through the Score setting. Once a contact reaches this value, the system marks it for replication as a Salesforce lead.

Lead description

Defines a custom description for replicated contacts. To map the description to a specific field of Salesforce leads, select the Generated lead description source in the field mappings.

You can insert the values of contact fields into the description using macro expressions.

The default description adds the Last name of the contact that is being replicated:

{% Contact.ContactLastName %}

For example, to use the Business phone value instead of the last name, enter the following expression:

 {% Contact.ContactBusinessPhone %}

Default company name

All Salesforce leads require a company name value.

This setting allows you to specify a default company name, which the replication process uses for contacts who are not associated with any company.

The system attempts to retrieve the company name value from sources in Xperience in the following order:

  1. The value of the contact's Company name field
  2. The name of the account in which the contact is listed as a primary contact
  3. The account that lists the contact as a secondary contact
  4. The first account that contains the contact as a regular contact
  5. The value of the Default company name setting (if none of the above steps are successful)

Mapping contact fields to Salesforce lead fields

The synchronization process transfers data between Xperience contacts and Salesforce leads based on field mapping settings.

Note: You need to authorize Organization access before you can adjust the field mappings.

Preparing the Salesforce mapping identifier field

Xperience stores the bindings between Salesforce leads and contacts in a custom Salesforce field. You need to create a dedicated field for your Salesforce leads for this purpose.

The following instructions apply to Salesforce Classic. The steps may be different if using Salesforce Lightning Experience.

  1. Log in to Salesforce.com.
  2. Navigate to App Setup → Customize → Leads → Fields.
  3. Click New in the Lead Custom Fields & Relationships section.
  4. Choose Text as the field type and click Next.
  5. In the Enter the details step, fill in the following values:
    • Field Label: type any label for the field, for example: Xperience ID
    • Length: 32
    • Field Name: type any name for the field, for example: Xperience_ID
    • Unique: select the checkbox
      • Select Treat "ABC" and "abc" as duplicate values (case insensitive).
    • External ID: select the checkbox
  6. Fill in the rest of the information as required and finish the New Custom Field wizard.
  7. In Xperience, go to Settings → Integration → Salesforce.com and click Edit below the Mapping of contacts to Salesforce leads section.
  8. Select your new Salesforce lead field as the External identifier field.
  9. Click Save & Close.
  10. Save the settings.

You can now configure the mappings between the fields of Xperience contacts and Salesforce leads.

Setting up the field mappings

To access the field mapping dialog, go to Settings → Integration → Salesforce.com in the Xperience administration and click Edit below the Mapping of contacts to Salesforce leads section.

The mapping dialog offers a list of all standard and custom fields defined for your Salesforce leads. You can select the following items as the source for the fields:

  • Fields – the fields of Xperience contacts. Only fields containing relevant data are available (internal system fields of contacts are hidden).
  • Custom – related values that cannot be loaded directly from contact fields, including the following:
    • Company name – ensures that each contact has a company name value. See the description of the Default company name setting for details about the process.
    • Generated lead description – loads the value of the Lead description setting.
    • Country name – provides the name of the contact's country as a text value.
    • State name – provides the name of the contact's state as a text value.
  • Picklist entry – allows you to select from the values predefined in Salesforce for picklist type fields.
  • (macro) – a dynamic data source based on a macro expression. Allows you to get values that are related to the contact, but not directly available in a contact field. For example, the following macro gets the names of all contact groups to which the contact belongs:

    {% Contact.ContactGroups.DisplayNames %}

    If you have the Keep Salesforce leads updated setting enabled, changes are only propagated after the contacts themselves are updated. Keep this in mind when using (macro) data sources for lead fields. Changes of other objects used in the macro (such as contact groups) do not trigger the replication until the contact itself is updated.

You can only select contact fields that fit the data type of the target Salesforce field. The following table shows which types of Xperience fields are supported by the available Salesforce data types:

Salesforce Data type

Supported Xperience field data types

Checkbox

Boolean (Yes/No)

Currency

Replication does not support the Currency data type at this time.

Date

Date and time

Date/Time

Date and time

Email

Text, Long text

Geolocation

Floating point number (requires two separate fields for latitude and longitude)

Number

Decimal number, Floating point number, Integer number, Long integer number

Percent

Decimal number, Floating point number, Integer number, Long integer number

Phone

Text, Long text

Picklist

Text, Long text

Picklist (Multi-Select)

Text, Long text

Text

Text, Long text

Text Area (Long, Rich, Encrypted)

Text, Long text

Time

Date and time

URL

Text, Long text

The system may modify values during the replication process according to the parameters of the target fields in Salesforce.

  • Text values – the replication process may shorten long text values (strings) to fit the maximum length of the target field.
  • Decimal numbers – the fractional part of decimal numbers may be truncated based on the data type settings of the target field. For example, the number 2.45397 could be shortened to 2.45. The same also applies to Floating point numbers.
  • Large numbers – replication of large numbers may result in an error if the target field has an insufficient length. Such errors block the related contact from replication until the contact's values are updated, or the field mapping settings change.

Once you configure all field mappings as required, you can start Replicating contacts to Salesforce.

Implementing custom data sources for fields

If the options available when setting up the Salesforce lead field mappings are not sufficient for your scenario, developers can implement custom sources for fields.

  1. Open your Xperience solution in Visual Studio.
  2. Add a custom assembly (Class Library project) with class discovery enabled to the solution (or reuse an existing custom assembly).
  3. Reference the custom project from the Xperience administration project (CMSApp).
  4. Create a new class within the custom project.
  5. Set the class to inherit from the LeadReplicationHelper class.
  6. Override the following methods:
    • GetCustomizedFieldsInternal – return an IEnumerable collection of strings with the names of the Salesforce lead fields for which you want to implement a custom data source.
    • PrepareLeadForReplicationInternal – call the method's base implementation, and then set values for the fields declared in GetCustomizedFieldsInternal. You can also perform any required modifications of the Entity object representing the lead, before the system runs the replication to Salesforce.
  7. Add the RegisterCustomHelper assembly attribute above the class declaration to register the provider.
  8. Save the changes and rebuild your solution.
using System.Collections.Generic;

using CMS;
using CMS.ContactManagement;
using CMS.SalesForce;

// Registers the custom helper
[assembly: RegisterCustomHelper(typeof(CustomLeadReplicationHelper))]

public class CustomLeadReplicationHelper : LeadReplicationHelper
{
    // Prepares a collection of Salesforce lead fields
    // The values of the fields are set within the code of the 'PrepareLeadForReplicationInternal' override
    protected override IEnumerable<string> GetCustomizedFieldsInternal()
    {
        return new string[] { "SFLeadField" };
    }

    // Modifies the Salesforce lead entity based on contact mappings and performs further customization
    protected override void PrepareLeadForReplicationInternal(Entity lead, ContactInfo contact)
    {
        // Calls the base implementation
        base.PrepareLeadForReplicationInternal(lead, contact);

        // Sets the value for the 'SFLeadField' field
        lead["SFLeadField"] = "Custom value";
    }    
}

When replicating contacts, the system uses the custom helper to fill the values of fields handled by your implementation (such as SFLeadField in the example above).

If you have the Keep Salesforce leads updated setting enabled, changes are only propagated after the contacts themselves are updated. Keep this in mind when using custom data sources for lead fields. Changes of custom source data do not trigger replication until the contact itself is updated.

Setting up synchronization of Salesforce leads to contacts

After you authorize access to Salesforce and configure replication of contacts, you can additionally set up synchronization of Salesforce lead data back into Xperience contacts. This ensures that your leads and contacts are up-to-date whenever you update the data in either system.

Only leads that were previously replicated from Xperience can be synchronized back to the corresponding contacts. Currently, the feature does not allow "export" of existing Salesforce lead data into new contacts.

Synchronization from Salesforce to Xperience works via Outbound Messaging.

The following instructions apply to Salesforce Classic. The steps may be different if using Salesforce Lightning Experience.

  1. Log in to Salesforce.com.
  2. Navigate to App Setup → Create → Workflow & Approvals → Outbound Messages.
  3. Click New outbound message.
  4. In the Object drop-down, select Lead and click Next.
  5. Fill in the following details:
    • Name: Type a name for the outbound message.
    • Unique name: The unique name is filled in automatically.
    • Endpoint URL: Add the full URL of the LeadOutboundMessageHandler.ashx endpoint of your Xperience administration application. For example:
      https://administration.example.com/CMSModules/ContactManagement/Pages/Tools/SalesForce/LeadOutboundMessageHandler.ashx
    • Send Session ID: Select the checkbox.
    • Lead fields to send: Add all fields that you want to update in Xperience contacts when a lead is modified in Salesforce.

      The synchronization uses the field mappings configured in Xperience. 

      Only Salesforce lead fields that are mapped directly from a contact field are supported. You cannot synchronize fields whose source in Xperience is a macro or custom code.

  6. Click Save.

Next, you need to create a Salesforce flow:

  1. In Salesforce, navigate to App Setup → Create → Workflow & Approvals → Flows.
  2. Click New flow.
  3. Under the Core tab, select Record-Triggered Flow and click Create.
  4. Select the following options:
    • Object: Lead
    • Trigger the Flow When: A record is updated

    • Condition Requirements: All conditions are met (AND)

    • When to Run the Flow for Updated Records: Every time a record is updated and meets the condition requirements
    • Optimize the Flow for: Actions and Related Records
  5. Click Done.
  6. In the Flow Builder, click the + button (Add element).
  7. Search for the name of your Outbound Message and select it.
  8. Enter a suitable Label for the flow element and click Done.
  9. Click Save in the top-right of the Flow Builder.
  10. In the Save the flow dialog, fill in the following details:
    1.  Flow Label: Type a name.
    2. Show advanced > API Version for Running the Flow: 54
  11. Click Save.

  12. Activate the flow once you are ready to start synchronizing leads to Xperience contacts.

When a lead is updated in your Salesforce organization, a message is sent to your Xperience administration application and the fields of the corresponding contact are updated.

Optimizing performance

By default, the Xperience on-line marketing features are optimized for the most common configurations (with Salesforce integration disabled). If you are using the Salesforce integration with a large number of contacts, we recommend that you optimize database operations by manually creating a database index with the following columns on the OM_Contact table:

  1. ContactSalesForceLeadID
  2. ContactSalesForceLeadReplicationDisabled
  3. ContactSalesForceLeadReplicationSuspensionDateTime

The index should be non-clustered and non-unique. See the Create Nonclustered Indexes article for more information.