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.

Salesforce Sandbox organizations

Note: Sandbox support is an experimental feature, and may not work in all possible Salesforce integration scenarios.

If you wish to set up and test the Salesforce integration without affecting your production organization, you can use a Sandbox organization. To connect to a Sandbox org, you need to add the CMSSalesForceUseSandbox key to the web.config file of your Xperience administration project.

<add key="CMSSalesForceUseSandbox" value="true" /> 

The key ensures that the system connects to Salesforce using the https://test.salesforce.com domain.

Once you are ready to connect to your production organization, remove the key or set its value to false, and re-authorize access to Salesforce.

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.

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. Modify the OAuth policies for your application:

   1. Under Connected Apps, click Manage next to your application.
   2. In the Connected App Detail section, click Edit Policies.
   3. Under OAuth Policies, set Permitted Users to: All users may self-authorize
   4. Click Save.

7. Open the Settings application in the Xperience administration.

8. Navigate to the Integration → Salesforce.com category.

9. Click Authorize next to the Organization access setting.

10. Paste your consumer values into the corresponding fields in the authorization dialog and click Authorize.

    • A Salesforce login screen opens in the current window.

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

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

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.

{% Contact.ContactLastName %}

 {% Contact.ContactBusinessPhone %}

Mapping contact fields to Salesforce lead fields

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

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.

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:

  Copy

  
  
  
    {% 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:

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

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.

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)

     • Add the following condition:
       • Field: your mapping identifier field
       • Operator: Is Null
       • Value: False

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