DocumentationExperience PlatformDestinations Guide

Salesforce CRM connection

Last update: Mon Jan 22 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • User
  • Admin
  • Leader

Overview overview

Salesforce CRM is a popular Customer Relationship Management (CRM) platform and supports the types of profiles described below:

  • Leads - A lead is the name of a person or company who may (or may not) be interested in the products or services you sell.
  • Contacts - A contact is an individual with whom one of your representatives has established a relationship and has been qualified as a potential customer.

This Adobe Experience Platform destination leverages the Salesforce composite API, which supports both types of profiles described above.

When activating segments, you can select between either leads or contacts and update attributes and audience data into Salesforce CRM.

Salesforce CRM uses OAuth 2 with Password Grant as an authentication mechanism to communicate with the Salesforce REST API. Instructions to authenticate to your Salesforce CRM instance are further below, in the Authenticate to destination section.

Use cases use-cases

As a marketer, you can deliver personalized experiences to your users, based on attributes from their Adobe Experience Platform profiles. You can build audiences from your offline data and send these audiences to Salesforce CRM, to update CRM membership as soon as audiences and profiles are updated in Adobe Experience Platform.

Prerequisites prerequisites

Prerequisites in Experience Platform prerequisites-in-experience-platform

Before activating data to the Salesforce CRM destination, you must have a schema, a dataset, and segments created in Experience Platform.

Prerequisites in Salesforce CRM prerequisites-destination

Note the following prerequisites in Salesforce CRM, in order to export data from Platform to your Salesforce account:

You need to have a Salesforce account prerequisites-account

Go to the Salesforce trial page to register and create a Salesforce account, if you do not have one already.

Configure a connected app within Salesforce prerequisites-connected-app

First, you need to configure a Salesforce connected app within your Salesforce account, if you do not have one already. Salesforce CRM will leverage the connected app to connect to Salesforce.

Next, enable OAuth Settings for API Integration for the Salesforce connected app. Refer to the Salesforce documentation for guidance.

Also, ensure that the scopes mentioned below are selected for the Salesforce connected app.

  • chatter_api
  • lightning
  • visualforce
  • content
  • openid
  • full
  • api
  • web
  • refresh_token
  • offline_access

Finally, ensure that the password grant is enabled within your Salesforce account. Refer to the Salesforce OAuth 2.0 Username-Password Flow for Special Scenarios documentation if you need guidance.

IMPORTANT
If your Salesforce account administrator has restricted access to trusted IP ranges, you need to contact them to get Experience Platform IP’s allowlisted. Refer to the Salesforce Restrict Access to Trusted IP Ranges for a Connected App documentation if you need additional guidance.

Create custom fields within Salesforce prerequisites-custom-field

When activating audiences to the Salesforce CRM destination, you must input a value in the Mapping ID field for each activated audience, in the Audience schedule step.

Salesforce CRM requires this value to correctly read and interpret audiences coming in from Experience Platform and to update their audience status within Salesforce. Refer to the Experience Platform documentation for Audience Membership Details schema field group if you need guidance on audience statuses.

For each audience that you activate from Platform to Salesforce CRM, you need to create a custom field of the type Text Area (Long) within Salesforce. You can define the field character length of any size between 256 - 131,072 characters according to your business requirement. See the Salesforce Custom Field Types documentation page for additional information on custom field types. Also refer the Salesforce documentation to create custom fields if you need assistance on field creation.

IMPORTANT
Do not include whitespace characters in the field name. Instead, use the underscore (_) character as a separator.
Within Salesforce you must create custom fields with a Field Name that exactly matches the value specified within Mapping ID for each activated Platform segment. For example, the screenshot below shows a custom field named crm_2_seg. When activating an audience to this destination, add crm_2_seg as Mapping ID to populate audience audiences from Experience Platform into this custom field.

An example of custom field creation in Salesforce, Step 1 - Select the data type, is shown below:
Salesforce UI screenshot showing custom field creation, Step 1 - Select the data type.

An example of custom field creation in Salesforce, Step 2 - Enter the details for the custom field, is shown below:
Salesforce UI screenshot showing custom field creation, Step 2 - Enter the details for the custom field.

TIP
  • To distinguish between custom fields used for Platform audiences and other custom fields within Salesforce you could include a recognizable prefix or suffix when creating the custom field. For example, instead of test_segment, use Adobe_test_segment or test_segment_Adobe
  • If you already have other custom fields created in Salesforce, you can use the same name as the Platform segment, to easily identify the audience in Salesforce.
NOTE
  • Objects in Salesforce are restricted to 25 External fields, see Custom Field Attributes.
  • This restriction implies that you can only have a maximum of 25 Experience Platform audience memberships active at any time.
  • If you have reached this limit within Salesforce, you must remove the custom attributes from Salesforce that were used to store the audience status against older audiences within Experience Platform before a new Mapping ID can be used.

Gather Salesforce CRM credentials gather-credentials

Note down the items below before you authenticate to the Salesforce CRM destination:

Credential
Description
Example
Username
Your Salesforce account username.
Password
Your Salesforce account password.
Security Token
Your Salesforce security token which you will later append to the end of your Salesforce Password to create a concatenated string to be used as the Password when authenticating to the destination.
Refer to the Salesforce documentation to reset your security token to learn how to regenerate it from the Salesforce interface if you do not have the Security Token.
Custom Domain
Your Salesforce domain prefix.
See the Salesforce documentation to learn how to obtain this value from the Salesforce interface.
If your Salesforce domain is
d5i000000isb4eak-dev-ed.my.salesforce.com,
you will need d5i000000isb4eak-dev-ed as the value.
Client ID
Your Salesforce Consumer Key.
Refer to the Salesforce documentation to learn how to obtain this value from the Salesforce interface.
Client Secret
Your Salesforce Consumer Secret.
Refer to the Salesforce documentation to learn how to obtain this value from the Salesforce interface.

Guardrails guardrails

Salesforce balances transaction loads by imposing request, rate and timeout limits. Refer to the API Request Limits and Allocations for details.

If your Salesforce account administrator has enforced IP restrictions, you will need to add Experience Platform IP addresses to your Salesforce accounts’ trusted IP ranges. Refer to the Salesforce Restrict Access to Trusted IP Ranges for a Connected App documentation if you need additional guidance.

IMPORTANT
When activating segments you must select between either Contact or Lead types. You need to ensure that your audiences have the appropriate data mapping according to the type selected.

Supported identities supported-identities

Salesforce CRM supports update of identities described in the table below. Learn more about identities.

Target Identity
Description
Considerations
SalesforceId
The Salesforce CRM identifier for the contact or lead identities that you export or update through your segment.
Mandatory

Export type and frequency export-type-frequency

Refer to the table below for information about the destination export type and frequency.

Item
Type
Notes
Export type
Profile-based
  • You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), according to your field mapping.
  • Each audience status in Salesforce CRM gets updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling step.
Export frequency
Streaming
  • Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations.

Connect to the destination connect

IMPORTANT
To connect to the destination, you need the View Destinations and Manage Destinations access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.

To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.

Within Destinations > Catalog search for Salesforce CRM. Alternatively you can locate it under the CRM category.

Authenticate to destination authenticate

To authenticate to the destination, fill in the required fields below and select Connect to destination. Refer to the Gather Salesforce CRM credentials section for any guidance.

Credential
Description
Username
Your Salesforce account username.
Password
A concatenated string composed of your Salesforce account password appended with your Salesforce Security Token.
The concatenated value takes the form of {PASSWORD}{TOKEN}.
Note, do not use any braces or spaces.
For example if your Salesforce Password is MyPa$$w0rd123 and Salesforce Security Token is TOKEN12345....0000, the concatenated value you will use in the Password field is MyPa$$w0rd123TOKEN12345....0000.
Custom Domain
Your Salesforce domain prefix.
For example if your domain is d5i000000isb4eak-dev-ed.my.salesforce.com, you need to provide d5i000000isb4eak-dev-ed as the value.
Client ID
Your Salesforce connected app Consumer Key.
Client Secret
Your Salesforce connected app Consumer Secret.

Platform UI screenshot showing how to authenticate.

If the details provided are valid, the UI displays a Connected status with a green check mark, you can then proceed to the next step.

Fill in destination details destination-details

To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.

  • Name: A name by which you will recognize this destination in the future.

  • Description: A description that will help you identify this destination in the future.

  • Salesforce ID Type:

    • Select Contact if the identities you are looking to export or update are of type Contact.
    • Select Lead if the identities you are looking to export or update are of type Lead.

Platform UI screenshot showing the destination details.

Enable alerts enable-alerts

You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.

When you are finished providing details for your destination connection, select Next.

Activate audiences to this destination activate

IMPORTANT

Read Activate profiles and audiences to streaming audience export destinations for instructions on activating audiences to this destination.

Mapping considerations and example mapping-considerations-example

To correctly send your audience data from Adobe Experience Platform to the Salesforce CRM destination, you need to go through the field mapping step. Mapping consists of creating a link between your Experience Data Model (XDM) schema fields in your Platform account and their corresponding equivalents from the target destination.

Attributes specified in the Target field should be named exactly as described in the attribute mappings table as these attributes will form the request body.

Attributes specified in the Source field do not follow any such restriction. You can map it based on your need, however ensure the format of the input data is valid according to the Salesforce documentation. If the input data is not valid, the update call to Salesforce will fail and your contacts / leads would not get updated.

To correctly map your XDM fields to the (API) Salesforce CRM destination fields, follow these steps:

  1. In the Mapping step, select Add new mapping, you will see a new mapping row on the screen.
    Platform UI screenshot example for Add new mapping.

  2. In the Select source field window, choose the Select attributes category and select the XDM attribute or choose the Select identity namespace and select an identity.

  3. In the Select target field window, choose the Select identity namespace and select an identity or choose Select custom attributes category and select an attribute or define one using the Attribute name field as needed. Refer to the Salesforce CRM documentation for guidance on supported attributes.

    • Repeat these steps to add the following mappings between your XDM profile schema and (API) Salesforce CRM:

    Working with Contacts

    • If you are working with Contacts within your segment, refer to the Object Reference in Salesforce for Contact to define mappings for the fields to be updated.

    • You can identify mandatory fields by searching for the word Required, which is mentioned in field descriptions in the link above.

    • Depending on the fields you want to export or update, add mappings between your XDM profile schema and (API) Salesforce CRM:

      table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
      Source Field Target Field Notes
      IdentityMap: crmID Identity: SalesforceId Mandatory
      xdm: person.name.lastName Attribute: LastName Mandatory. Last name of the contact up to 80 characters.
      xdm: person.name.firstName Attribute: FirstName The contact’s first name up to 40 characters.
      xdm: personalEmail.address Attribute: Email The contact’s email address.

    • An example using these mappings is shown below:
      Platform UI screenshot example showing Target mappings.

    Working with Leads

    • If you are working with Leads within your segment, refer to the Object Reference in Salesforce for Lead to define mappings for the fields to be updated.

    • You can identify mandatory fields by searching for the word Required, which is mentioned in field descriptions in the link above.

    • Depending on the fields you want to export or update, add mappings between your XDM profile schema and (API) Salesforce CRM:

      table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
      Source Field Target Field Notes
      IdentityMap: crmID Identity: SalesforceId Mandatory
      xdm: person.name.lastName Attribute: LastName Mandatory. Last name of the lead up to 80 characters.
      xdm: b2b.companyName Attribute: Company Mandatory. The lead’s company.
      xdm: personalEmail.address Attribute: Email The lead’s email address.

    • An example using these mappings is shown below:
      Platform UI screenshot example showing Target mappings.

When you have finished providing the mappings for your destination connection, select Next.

Schedule audience export and example schedule-segment-export-example

When performing the Schedule audience export step you must manually map audiences activated from Platform to their corresponding custom field in Salesforce.

To do this, select each segment, then enter the custom field name from Salesforce in the Salesforce CRM Mapping ID field. Refer to the Create custom fields within Salesforce section for guidance and best practices on creating custom fields in Salesforce.

For example, if your Salesforce custom field is crm_2_seg, specify this value in the Salesforce CRM Mapping ID to populate audience audiences from Experience Platform into this custom field.

An example custom field from Salesforce is shown below:
Salesforce UI screenshot showing custom field.

An example indicating the location of the Salesforce CRM Mapping ID is shown below:
Platform UI screenshot example showing Schedule audience export.

As shown above the Salesforce Field Name exactly matches the value specified within Salesforce CRM Mapping ID.

Depending on your use case, all activated audiences can be mapped to the same Salesforce custom field or to different Field Name in Salesforce CRM. A typical example based on the image shown above could be.

Salesforce CRM segment name
Salesforce Field Name
Salesforce CRM Mapping ID
crm_1_seg
crm_1_seg
crm_1_seg
crm_2_seg
crm_2_seg
crm_2_seg

Repeat this section for each activated Platform segment.

Validate data export exported-data

To validate that you have correctly set up the destination, follow the steps below:

  1. Select Destinations > Browse to navigate to the list of destinations.
    Platform UI screenshot showing Browse Destinations.

  2. Select the destination and validate that the status is enabled.
    Platform UI screenshot showing Destinations Dataflow Run.

  3. Switch to the Activation data tab, then select an audience name.
    Platform UI screenshot example showing Destinations Activation Data.

  4. Monitor the audience summary and ensure that the count of profiles corresponds to the count created within the segment.
    Platform UI screenshot example showing Segment.

  5. Finally, log in to the Salesforce website and validate if the profiles from the audience have been added or updated.

    Working with Contacts

    • If you have selected Contacts within your Platform segment, navigate to the Apps > Contacts page.
      Salesforce CRM screenshot showing the Contacts page with the profiles from the segment.

    • Select a Contact and check if the fields are updated. You can see that each audience status in Salesforce CRM was updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling.
      Salesforce CRM screenshot showing the Contact Details page with updated audience statuses.

    Working with Leads

    • If you have selected Leads within your Platform segment, then navigate to the Apps > Leads page.
      Salesforce CRM screenshot showing the Leads page with the profiles from the segment.

    • Select a Lead and check if the fields are updated. You can see that each audience status in Salesforce CRM was updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling.
      Salesforce CRM screenshot showing the Lead Details page with updated audience statuses.

Data usage and governance data-usage-governance

All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.

Errors and troubleshooting errors-and-troubleshooting

Unknown errors encountered while pushing events to the destination unknown-errors

  • When checking a dataflow run, you might encounter the following error message: Unknown errors encountered while pushing events to the destination. Please contact the administrator and try again.
    Platform UI screenshot showing error.

    • To fix this error, verify that the Mapping ID that you provided in the activation workflow to the Salesforce CRM destination exactly matches the value of the custom field type you created in Salesforce. Refer to the Create custom fields within Salesforce section for guidance.

  • When activating a segment, you might obtain an error message: The client's IP address is unauthorized for this account. Allowlist the client's IP address...

Additional resources additional-resources

Additional useful information from the Salesforce developer portal is below:

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6