Overview

Salesforce is a Customer Relationship Management (CRM) platform that is designed to help you sell, service, analyze, and connect with your customers.

Integrating Lytics with Salesforce allows you to import leads and opportunities to merge your CRM data with rich behavioral data in Lytics to gain a more complete view of your customers. Engage your users with messages on any channel based on their status in your sales cycle. You can also export any Lytics user fields such as Behavioral Scores and content affinities to qualify and sort your leads in Salesforce.

Authorization

If you haven't already done so, you will need to set up a Salesforce account before you begin the process described below. Lytics supports two methods for connecting to Salesforce: OAuth2 and JWT Bearer Token.

The user connecting to Salesforce must have the API Enabled and Offline User permissions within Salesforce. You can read more on Salesforce permissions.

If you are new to creating authorizations in Lytics, see the Authorizations documentation for more information.

OAuth2

OAuth2 allows you to simply enter your username and password to connect Lytics with Salesforce.

🚧

Before creating an OAuth2 authorization, you must install the Lytics Salesforce app in your Salesforce org:

• Production: Install the Salesforce app
• Sandbox: Install the Salesforce app in sandbox

1. Select Salesforce from the list of providers.
2. Select the OAuth2 (or OAuth2 Sandbox) method for authorization.
3. Input your Salesforce username and password into the login screen.
4. Enter a Label to identify your authorization.
5. (Optional) Enter a Description for further context on your authorization.
6. Click Save Authorization.

JWT Bearer Token

JWT Bearer Token authentication allows you to connect Lytics to Salesforce without a browser-based login. This is useful for service accounts and automated environments. Instead of a username/password login, you provide a Consumer Key, Salesforce Username, and RSA Private Key from a Salesforce External Client App.

Prerequisites

Before creating a JWT authorization in Lytics, you must set up an External Client App in Salesforce:

1. Generate an RSA key pair:

   Bash

   # Generate a private key
   openssl genpkey -algorithm RSA -out sf_private_key.pem -pkeyopt rsa_keygen_bits:2048
   
   # Create a self-signed X.509 certificate
   openssl req -new -x509 -key sf_private_key.pem -out sf_cert.pem -days 365 -subj "/CN=Lytics Salesforce JWT"

2. Create an External Client App in Salesforce:

   • Go to Setup > App Manager > New Connected App (or External Client App depending on your Salesforce edition).
   • Fill in the basic info (name, contact email).
   • Check Enable OAuth Settings.
   • Set the callback URL to any valid URL (e.g. https://login.salesforce.com/services/oauth2/callback). This value is not used by JWT Bearer Token authentication but is required by Salesforce.
   • Select OAuth scopes: Full access (full) or at minimum API (api). You must also include Perform requests at any time (refresh_token, offline_access).
   • Check Use digital signatures and upload the sf_cert.pem certificate file you created above.
   • Click Save.

3. Pre-authorize users for the app:

   • Go to Setup > App Manager > find your app > Manage.
   • Click Edit Policies.
   • Under Permitted Users, select Admin approved users are pre-authorized.
   • Click Save.
   • Scroll down to the Profiles section and click Manage Profiles.
   • Select the profile(s) that include the Salesforce user you want to authorize (e.g. System Administrator).
   • Click Save.

4. Copy the Consumer Key:

   • In the app detail page, copy the Consumer Key value.

Create the Authorization in Lytics

1. Select Salesforce from the list of providers.
2. Select the JWT Bearer Token (or JWT Bearer Token (Sandbox) for sandbox orgs) method for authorization.
3. Enter the Consumer Key from your Salesforce External Client App.
4. Enter the Salesforce Username of the pre-authorized user.
5. Paste the contents of your Private Key file (sf_private_key.pem).
6. Enter a Label to identify your authorization.
7. (Optional) Enter a Description for further context on your authorization.
8. Click Save Authorization.

Import Audiences & Activity Data

Importing Leads and Opportunities from Salesforce allows you to enrich Lytics profiles with sales and CRM data to improve targeting for your marketing efforts.

Integration Details

• Implementation Type: <<glossary:Server-side Integration>>.
• Implementation Technique: REST <<glossary:API Integration>>.
• Frequency: One time <<glossary:Batch Integration>>, with the option to update hourly.
• Resulting data: <<glossary:User Profile>>s containing Lead or Opportunity data from Salesforce.

This integration utilizes Salesforce APIs to import user data. Once the import is started the job will:

1. Request Salesforce objects to import.
2. Ingest the data from the JSON files into the respective stream until there are no additional pages to import.

Account, Contact, Lead, and Opportunity data will be mapped to the following streams respectively: salesforce_accounts, salesforce_contacts, salesforce_leads, and salesforce_opportunities streams.

Fields

The following fields are included in the default mapping of the salesforce_accounts stream:

📘

Note on billing and shipping country/state fields:

Salesforce provides two variants for country and state on billing and shipping addresses:

• Free-text fields (e.g. BillingCountry, BillingState): Plain text values entered by users, mapped to salesforce_account_billing_country, salesforce_account_billing_state, etc.
• ISO-code fields (e.g. BillingCountryCode, BillingStateCode): Standardized ISO code values (e.g. US, CA), mapped to the _code variants such as salesforce_account_billing_country_code.

Both variants are now imported by Lytics. The ISO-code (_code) fields are only populated if the State and Country Picklists feature is enabled in your Salesforce org.

The following fields are included in the default mapping of the salesforce_contacts stream:

The following fields are included in the default mapping of the salesforce_leads stream:

The following fields are included in the default mapping of the salesforce_opportunities stream:

📘

Note on additional fields:

In addition to the standard fields listed above, you can select additional fields (including both Salesforce standard and custom fields) to import using the Additional Fields inputs during job configuration. Custom mappings are required to use additional fields.

Configuration

Follow these steps to set up and configure an import of Salesforce Leads & Opportunities in the Lytics platform.

1. Select Salesforce from the list of providers.
2. Select the Import Audiences & Activity Data job type from the list.
3. Select the Authorization you would like to use or create a new one.
4. Enter a Label to identify this job you are creating in Lytics.
5. (Optional) Enter a Description for further context on your job.
6. From the Maximum Daily API Calls numeric field, select the maximum number of API calls the Lytics import can make on your behalf per day. See API Limitations for tips on finding and estimating this.
7. From the Additional Lead Fields input, select additional Lead fields to import beyond the standard fields listed above.
8. From the Additional Contact Fields input, select additional Contact fields to import beyond the standard fields listed above.
9. From the Additional Account Fields input, select additional Account fields to import beyond the standard fields listed above.
10. From the Additional Opportunity Fields input, select additional Opportunity fields to import beyond the standard fields listed above.
11. From the Import Leads checkbox, choose if you would like to include leads in the import.
12. From the Keep Updated checkbox, continuously run this import.
13. From the Import Frequency input, select how frequently the import should be run.
14. (Optional) In the Time of Day text input, enter in a time for the weekly and daily continuous imports to run.
15. (Optional) From the Time Zone input, select the time zone for the time of day entered above.
16. (Optional) From the Lead Timestamp Field input, select a field on the Leads object to identify when the object was last modified. Lytics will use this field to search for newly created and updated objects when running continuously. If not selected, the Last Modified field will be used.
17. (Optional) From the Contact Timestamp Field input, select a field on the Leads object to identify when the object was last modified. Lytics will use this field to search for newly created and updated objects when running continuously. If not selected, the Last Modified field will be used.
18. (Optional) From the Account Timestamp Field input, select a field on the Leads object to identify when the object was last modified. Lytics will use this field to search for newly created and updated objects when running continuously. If not selected, the Last Modified field will be used.
19. (Optional) From the Opportunity Timestamp Field input, select a field on the Leads object to identify when the object was last modified. Lytics will use this field to search for newly created and updated objects when running continuously. If not selected, the Last Modified field will be used.
20. (Optional) From the Leads Since text input, add a date and time of the oldest Lead to import.
21. (Optional) From the Contacts Since text input, add a date and time of the oldest Contact to import.
22. (Optional) From the Accounts Since text input, add a date and time of the oldest Account to import.
23. (Optional) From the Opportunities Since text input, add a date and time of the oldest Opportunity to import.
24. Click Start Import.

Import Custom Object

Importing custom objects from Salesforce allows you to enrich Lytics profiles with sales and CRM data from your Salesforce account. This will aid in targeting for your marketing efforts.

Integration Details

• Implementation Type: <<glossary:Server-side Integration>>.
• Implementation Technique: REST <<glossary:API Integration>>.
• Frequency: One time <<glossary:Batch Integration>> or daily continuous updates.
• Resulting data: Raw <<glossary:Event>> Data which may be mapped as custom <<glossary:User Field>>.

This integration utilizes Salesforce APIs to import user data. Once the import is started the job will:

1. Request a set of information from the configured Salesforce object.
2. Ingest data from the Salesforce object to the data stream stream defined during configuration.

The job will run again in 24 hours if configured to run continuously.

Fields

Lytics will import any fields that are selected during the job configuration. Because the imported fields are custom you will need to map the custom fields.

Configuration

Follow these steps to set up and configure an import of Salesforce in the Lytics platform.

1. Select Salesforce from the list of providers.
2. Select the Import Custom Object job type from the list.
3. Select the Authorization you would like to use or create a new one.
4. Enter a Label to identify this job you are creating in Lytics.
5. (Optional) Enter a Description for further context on your job.
6. Using the Stream text input, select an existing stream to write to, or enter a new stream name.
7. From the Maximum Daily API Calls numeric field, select the maximum number of API calls the Lytics job can make on your behalf per day.
8. From the Salesforce Object input, select the Salesforce object you want to import.
9. From the Salesforce Fields input, select fields to import.
10. Toggle the Keep Updated checkbox to continuously run this export.
11. (Optional) From the Timestamp Field input, select a field on the Salesforce object to identify when the object was last modified. Lytics will use this field to search for newly created and updated objects when running continuously. If not selected, the Last Modified field will be used.
12. (Optional) From the Objects Since text input, add a date and time of the oldest object to import.
13. (Optional) In the Time of Day text input, enter in a time for the daily continuous import to run.
14. (Optional) From the Time Zone input, select the time zone for the time of day entered above.
15. Click Start Import.

You should see the custom Salesforce object data populated in the stream selected shortly after starting the job.

Export Audiences

Exporting users to Salesforce will allow you to create new Leads or Opportunities from promising groups of users you've encountered through other channels such as the web, email, or mobile. This export supports any kind of Salesforce object. Exporting Lytics user fields to existing Leads can help qualify and sort your Leads.

Integration Details

• Implementation Type: <<glossary:Server-side Integration>>.
• Implementation Technique: REST <<glossary:API Integration>> - <<glossary:Audience Trigger Integration>>.
• Frequency: <<glossary:Real-time Integration>> with a one-time <<glossary:Backfill>> of the audience after setup.
• Resulting data: New or existing Salesforce objects populated with Lytics user field and audience membership.

This integration utilizes the Salesforce APIs to send user data. Once the export is started the job will begin backfilling users who already exist in the selected audiences. For each user to export, regardless if the user is being added as part of the backfill, or they're entering/exiting the audience in realtime, it will:

1. If a match field was provided during configuration, the job will update an existing Salesforce object based on values of the match field. Otherwise it will create a new Salesforce object.
2. Keep your Lytics audience in sync with Salesforce by updating users in Salesforce as users are updated in Lytics.

Fields

All fields that are provided in the mapping during configuration will be sent to Salesforce.

Configuration

Follow these steps to set up and configure an export of Salesforce in the Lytics platform.

1. Select Salesforce from the list of providers.
2. Select the Export Audiences job type from the list.
3. Select the Authorization you would like to use or create a new one.
4. Enter a Label to identify this job you are creating in Lytics.
5. (Optional) Enter a Description for further context on your job.
6. From the Audiences field, input the Lytics audience(s) you'd like to send to Salesforce. Then click Next Step.
7. In the Maximum Daily API Calls numeric field, enter the maximum number of API calls the Lytics workflow can make on your behalf per day.
8. From the Salesforce Object field, select the Salesforce object type you would like to export to.
9. From the Match Field field, input the field in Salesforce to match records to avoid duplicates. The field you select must be mapped in the fields below (either in the Required Fields or the Extra Fields).
10. From the Send Audiences To field, select a field on your Salesforce object which will contain a list of Lytics audiences for the user.
11. From the Required Fields section, map all the required fields from Lytics to Salesforce by selecting the Lytics field on the left, and its Salesforce destination field on the right. All fields in the Salesforce dropdown must be mapped.
12. From the Extra Fields section, map all the extra fields from Lytics to Salesforce by selecting the Lytics field on the left, and its Salesforce destination on the right.
13. From the Fields to Trigger section, select up to 75 user fields to trigger on. For any user currently in the exported audience, if any of the selected field values change, then the user will be sent to Salesforce.
14. Click Start Export.
    You should see Lytics user data populated in your Salesforce object shortly after starting the workflow.

Salesforce Administrator Setup

You'll need to involve a Salesforce administrator when setting up the export. The administrator will need to perform the following setup:

1. Set up a Duplicate Rule in Salesforce for leads (configuration pictured below).
2. Set up the following Custom Fields on the Salesforce "Lead" object:

• For "Send Audiences To"
  • Field Type: Text Area (Long)
  • Field Label: Lytics Audiences
  • Field Length: 32,768 characters (32 KB)
  • Field Visible Lines: 3
  • Field Name: Lytics_Audiences
  • Field Description: This user is a member of these Lytics Audiences
  • Visibility: Checked for all users
  • Read-Only: Not checked for any users
  • Layouts: Add to all available
• Optional: For "Send Content Affinity To"
  • Field Type: Text Area (Long)
  • Field Label: Lytics Content Affinity
  • Field Length: 32,768 characters (32 KB)
  • Field Visible Lines: 3
  • Field Name: Lytics_Content_Affinity
  • Field Description: The top three kinds of content this user prefers
  • Visibility: Checked for all users
  • Read-Only: Not checked for any users
  • Layouts: Add to all available
• Optional: For "Send Scores To" (optional)
  • Field Type: Text Area (Long)
  • Field Label: Lytics Scores
  • Field Length: 32,768 characters (32 KB)
  • Field Visible Lines: 3
  • Field Name: Lytics_Scores
  • Field Description
  • Visibility: Checked for all users
  • Read-Only: Not checked for any users
  • Layouts: Add to all available

API Limitations

Salesforce has limitations for the maximum number of daily API Calls. An API call is a connection made to a Salesforce server on your account's behalf. Lytics provides some guidelines below for working with these limits for your integration connection.

• Different accounts have different limits on the number of API calls allowed per 24 hours. You can find more information about these limits in the Salesforce documentation.
• In addition to your Lytics integration, your Sales team may have additional integrations using the Salesforce API. For example, they may use a tool to capture LinkedIn information and send it into Salesforce, which would also use their API.

To estimate an appropriate number of API calls to enter for the Salesforce import, Lytics recommends you use the following formula:

(Total Daily API Calls Allowed - Daily API Calls For Other Integrations) / 2

Dividing by two allows you to allot the same number of API calls to the upcoming Salesforce Export.

To roughly estimate how long your initial import will take, use the following formula:

(Total Leads + Total Contacts + Total Opportunities + Total Accounts) / Total Daily API Calls Allowed for Lytics Import

This will yield the approximate number of days that will be required.

Note: this estimate will be slightly low because each time the import encounters an API limit, it sleeps for 24 hours rather than restarting at the same time the following day.