S4S List Builder (Optional) (Pre-Sitecore 9)

Introduction

S4S List Builder is an application that lets operators create Sitecore Contact Lists in xDB from Salesforce Reports and Campaigns. Once a Sitecore Contact List has been created it can be associated with a Sitecore EXM email campaign.


IMPORTANT: S4S List Builder is built as a Sitecore Launch Pad application.

IMPORTANT: If you have downloaded S4SLB version earlier than 1.6.1, please update it to version 1.6.1. Version 1.6.1 supports multiple Salesforce orgs and have more features.

Prerequisites

To use S4S List Builder you require the following:

  • S4S List Builder Version 1.6.1
  • S4S versions after changeset cs29282 or later e.g. S4S Release 1.81.17031.1 or 1.82.16343, will show reports and campaigns
  • Sitecore version greater or equal to Sitecore 8.1. (For Sitecore 9 and upwards we have released a new S4SLB package. Please refer this)

Usage

Using S4S List builder requires several steps:

1. Create Salesforce Reports and Campaigns

  • Campaigns: One or more active Salesforce campaigns, each comprising leads or contacts (or both), can be the data source for S4SLB
  • Reports: Only one report can be used at a time. It needs to have the following columns in the report:
    • Lead ID or Contact ID or Lead/Contact ID
    • First Name
    • Last Name (Optional)
    • Email address

2. Open S4SLB from the Sitecore Launch Pad

3. Select the Data Sources

Select one report or several campaigns with an Active status. Note the campaign list from Salesforce shows the number of contacts, leads and converted leads.

4. View the Summary Data

After selecting at least one item, users can click the next button and come to step 2. This allows users to edit the name of the Sitecore Contact List they are about to create and add a description. The "Total Size" field shows the count of members expected to be created in Sitecore if each Salesforce entity has the prerequisite data.

5. Import the List

Depending on the list size, the import processing time will vary. Once the import is completed, Sitecore will only release the list after it has been indexed, which may take some time if the list is large. After creating the new Sitecore contact list in xDB, users have the option to use the Sitecore List Manager to remove duplicates, filter members and create segmentations.

IMPORTANT: The Salesforce Lead Id and Contact Id do not appear against the Sitecore Contact when viewed in Sitecore. They are only available programmatically.

Operational Nuances

Campaigns

  • Some Salesforce campaigns that are restricted or have locked access may appear in S4SLB in Sitecore pending the permissions of the API user (which can be changed in Salesforce). 
  • Additional spaces in Salesforce Campaign names are not visible in Salesforce. They are, however, visible through the API and therefore S4SLB in Sitecore.
  • No changes to the Salesforce Campaign status is made during the import process.  

Reports

  • Only those Salesforce reports that have been recently created or saved will appear in S4SLB in the Sitecore.
  • Some reports may appear that do not have the required fields (see section 1 above). If a required field is missing, an error message will appear after the import has been attempted.

Installation

S4S List builder comes as standard Sitecore Package. Users can install it from

Sitecore Desktop » Start menu » Development Tools » Installation Wizard.

If you are installing S4SLB 1.5 or later, please follow the post installation step below.

  • S4SLB version 1.5 and later supports multiple Salesforce orgs. After installing the package, add connections string names (which are configured in ConnectionStrings.config) as settings to App_Config/include/S4S.config. If there are multiple Salesforce connection strings configured, you have to add multiple setting nodes.

         <settings>

            <setting name="S4SConnString" value="Default Org"/>      

         </settings>

         ‘name’ attribute needs to match with the connection string name in the ConnectionStrings.config file.

         ‘value’ attribute of these settings will be the display text of the connection string selection dropdown in the S4SLB UI.


If you are installing S4SLB 1.6 or later and if you need to includes more Salesforce Contact/Lead fields as Sitecore contact facets please follow the following steps.

(All the below config settings can be found in App_Config/Include/S4SLB.config file.)

  • Set “S4SLB.AddDictionaryFacets” config setting value to “true”.
  • Fill “S4SLB.SalesforceContactFieldNames” config setting value with the names of Salesforce Contact fields you need to add as Sitecore Facets. Make sure those field names are separated by “|”.

          Example

          <setting name="S4SLB.SalesforceContactFieldNames" value="FirstName|LastName|Email|Birthdate|MobilePhone|CreatedDate|Languages__c"/>

  • Fill “S4SLB.SalesforceLeadFieldNames” config setting value with the names of Salesforce Lead fields you need to add as Sitecore Facets. Make sure those field names are separated by “|”. 

          Example

          <setting name="S4SLB.SalesforceLeadFieldNames" value="FirstName|LastName|MobilePhone|NumberOfEmployees|Rating "/>

Constraints

S4SLB does not push Sitecore Email Experience analytics back to Salesforce so full "round trip" reporting is not possible. Our S4S EXM module is required for this.

Technical

S4SLB creates new Contact Lists in Sitecore. These are not real lists, but list name references in each Contact record that the contact belongs to. Each Sitecore Contact record imported using S4SLB has an Id field that is the Salesforce OrgId and the Salesforce Lead or Contact Id concatenated into an Id. For example, 00D3b0000000fxk_0036000001rWLdH is the Salesforce OrgId followed by the Contact Id. Developers could use this information to map the data in Sitecore xDB analytics back to Salesforce via S4S.


 

IMPORTANT:

S4SLB uses the Sitecore SSC Framework for communication between client and server, which is configured within the App_Config\Include\Sitecore.Services.Client.config file.

If you use S4SLB and you are connected externally from your Sitecore CM Server, you may need to change Sitecore.Services.Client.config file "SITECORE SERVICES SECURITY POLICY" for external access.

 In other words if your Sitecore instance hosted in a remote location from where you try to connect as a client, you have to change the “Sitecore.Services.SecurityPolicy” config setting value in App_Config\Include\Sitecore.Services.Client.config file to “Sitecore.Services.Infrastructure.Web.Http.Security.ServicesOnPolicy, Sitecore.Services.Infrastructure”.  

OR

Add following configuration section to S4SLB.config in App_Config/Include (Or any other config file) Or add it as a separate patch file. This will allow access to the controller which S4SLB is using in Sitecore SSC framework.

<sitecore>
    <api>
      <services>
        <configuration type="Sitecore.Services.Infrastructure.Configuration.ServicesConfiguration, Sitecore.Services.Infrastructure">
          <allowedControllers hint="list:AddController">
            <allowedController desc="FuseIT S4SLB">FuseIT.S4S.SitecoreSalesforceListBuilder.Controllers.SalesforceCampaignsController, FuseIT.S4S.SitecoreSalesforceListBuilder</allowedController>
          </allowedControllers>
        </configuration>
      </services>
    </api>
  </sitecore>

Next Step

Congratulations, you have finished installing this option.