To create truly personalized experience, marketers need rich and up-to-date data. Using Sitecore Connect for Salesforce CRM, data will be synchronzed between Salesforce CRM and Sitecore Experience Platform. This article is a step by step guide how to set up the connector.
Step one: Install the necessary packages
You’ll need to install a collection of packages to be able to sync between Sitecore and Salesforce.
In this example, we used Sitecore 9.0.2 to install the following packages in the same order:
- Data Exchange Framework 2.0.1
- Sitecore Provider for Data Exchange Framework 2.0.1
- xConnect Provider for Data Exchange Framework 2.0.1
- Salesforce Provider for Data Exchange Framework 2.0.1
- Sitecore Connect for Salesforce CRM 2.0.1
Serialize and deploy to xConnect Collection model:
Once you finish installing the above-mentioned packages, Sitecore will create new custom facets. These facets will be used to associate information from Salesforce with Sitecore contacts and interactions.
These facets are not defined yet to xConnect. So, we’ll need to deploy the collection model of these facets to make them defined for xConnect.
- Go to Sitecore instance.
- Open the Content Editor and navigate into “sitecore/system/Settings/Data Exchange/Providers/xConnect/ Collection Models/Connect for Salesforce/Connect for Salesforce Collection Model”.
- Click the “Convert Model to JSON” from the ribbon.
- The Salesforce Connect Collection Model contains the following facets: SalesforceContact, SalesforceCampaignMembership and SalesforceInteraction.
- To deploy the new collection model, copy the JSON file into the following paths on the
- xConnect server
- [PATH TO XCONNECT]\App_Data\Models\
- xConnect Search Indexer. By default, this one is located on the same path to the xConnect server and under:
- [PATH TO XCONNECT]\App_Data\jobs\continuous\IndexWorker\App_Data \Models\
- xConnect server
Now, we’ll need to do some configuration on Salesforce side. If you don’t have a Salesforce account and would like to test the connection, Salesforce offers you a developer account (free account) (https://developer.salesforce.com/signup).
When you log into your Salesforce account for the first time, the default interface of the CRM is called “Lighting Experience” which is more modern and faster. As I noticed, the Sitecore documentation for Salesforce connector is based on the classic Salesforce interface.
To switch from the “Lighting Experience” into Salesforce Classic:
- Click on the profile image icon on the top left corner and then click on Switch to Salesforce Classic
- The Salesforce classic interface looks like this
To be able to connect Salesforce with Sitecore, you’ll need to create a custom app on Salesforce:
- Click on “Setup” from the top menu
- Click on “Apps” from the left side menu
- You’ll be redirected to the “Apps” page. There is a section for “Connected Apps”, click “New” to create a new connected app.
- Fill in the necessary/Required information to complete creating the new app as mentioned below
- We’ll start by filling in the basic information
- Enable the OAuth Setting
- Click on Save
- You’ll be redirected a new page with a message telling you that the app was successfully created. Click on Continue
- Notice now that the new app is added under the section “Connected Apps”
Add custom fields in Salesforce
If you would like to write contact data from Sitecore to Salesforce, you will need to create a custom field in Salesforce and associate this field with the corresponding on Sitecore.
- Create the custom Salesforce Contact field
- From the left side menu, navigate into Build > Customize > Contacts > Fields
- You’ll be redirected into the Contact fields page
- Go to “Contact Custom fields & Relationships” section and click on “New”
- Follow these steps:
- Choose the field type: TEXT, then click on “Next”
- Enter field details, then click on “Next”
- The two last steps are about specifying the security level of the field and on which page layouts it can be displayed in Salesforce.
- Finally click on “Save”
- The new field is created. (Salesforce adds “__c” at the end of a custom field name to show that the field is a custom field)
- Choose the field type: TEXT, then click on “Next”
- Create the custom Salesforce Activity field
- From the left side menu, navigate into Build > Customize > Activities > Activity Custom Fields
- Click on “New”
- Follow the same steps mentioned to create a custom field on contact object with the same entered values.
- When you finish, you will get the new field under Activity Custom Fields page
Configure the connection string
We have installed the necessary packages needed on our Sitecore instance to connect to Salesforce and on Salesforce we created the custom app that will be used to synchronize data between both systems. We still need to configure the connection string in our Sitecore project and specify the endpoints.
The connection string will look like this:
<add name="[name of the connection]" connectionString="user id=[user id];password=[password];client id=[client id];secret key=[secret key];security token=[security token]" />
- [name of the connection]: you can replace this with any name you want.
- [user id]: is the ID of Salesforce user that Sitecore uses to connect to the Salesforce API
- [password]: the password of this Salesforce user
- [client id]: the customer secret value in Salesforce connected app
- [security key]: the consumer key value in Salesforce connected app
NOTE: it is important to define from the beginning the Salesforce account that will be used to establish the connection between both systems. The level of user permissions/rights depends of the purpose of this connection.
For example, of you only need to read contact data from Salesforce and create the corresponding data in Sitecore, it is enough to have read-access on both contacts and campaigns. But if you want to push the contact data from Sitecore into Salesforce, then you will need to have write-access on contacts in Salesforce.
Get the Client ID and the Secret Key
- Navigate into Build > Create > Apps > Sitecore Data Exchange App (the connected app we just created)
- Click on the Sitecore Data Exchange App
- You will get a detail page about the app
- Copy the “Consumer Key“ value to replace the “Client ID” in the connection string and the “Consumer Secret” value to replace the “Secret Key” value in the same connection string.
Get the Security Token
- From the top menu, click on your username. A drop menu will get displayed, click on “My Settings"
- On the left menu of the page, navigate into My Settings > Personal > Reset My Security Token
- Click on the “Reset Security Token” button.
- A notification will be displayed telling you that the new security token is sent to your email.
- Open your email inbox and get the access token.
- Add it to the connection string.
Finally, a connection string for Salesforce will look like this example:
<add name="mysf" connectionString="user firstname.lastname@example.org;password=b;client id=GEH9zlTNB8o8BA45pAeDtC8W.DIqrAzuky2uffEEOwtHxIEhLzkmPwjz8KF_vzWY8dNIfurWHpfb ZPGdtc3b;secret key=5468568999798354123;security token=g3ygFuNzGgm33YTfsM3WKG3AA" />
Now, you can go to Sitecore Connection string in your project root > App_Config > ConnectionStrings.config to add the Salesforce connection string after collecting the necessary data from Salesforce.
Time to Sync Data between both systems 😊
Create a tenant
- Navigate in Sitecore into System > Data Exchange
- Click on “Connect for Salesforce Tenant” to create the tenant. This tenant will contain our configuration and endpoints to connect both systems and sync data.
- Give a meaningful name to the tenant
- It is possible to create multiple tenants on the same solution to connect to different Salesforce instances or under the same tenant. In this example, we’ll establish one connection to one instance.
- Click on “OK”, the script of creating the tenant will get executed. This could take some time to create the tenant and its componets.
- Once the tenant is successfully created, navigate into Endpoints > Providers > Salesforce > Salesforce Client Endpoint
- Add the name of the connection string we have added to the ConnectionStrings.config (mysf) to “Connection String Name”. Sitecore will get the connection string parameters from the config file to connect to the Salesforce API.
- Test the connection to Salesforce by clicking on “Run Troubleshooter” on the ribbon
- If you see the above pop-up window, then the connection was tested successfully.
- Now we need to do the same for the xConnect endpoint. Navigate into Endpoints > xConnect > xConnect Client Endpoint, and make sure to add the same values in the image below. (you can find these connection string names on your ConnectionStrings.config) (these names are the default names to connect to xConnect, if you changed the names make sure to update the Endpoint as well).
- Test the connection to xConnect.
- By default, the tenant is not enabled to execute the process of synchronization between Sitecore and third-party systems. In a later stage, we’ll enable the tenant and execute the process.
Update a Salesforce custom field
- Let’s check if in the default configuration, the custom field we added on Salesforce matches the one mentioned in the tenant
- Navigate into Data Access > Value Access Sets > Providers > Salesforce
- Open the “Salesforce Contact Fields” and click on “Sitecore Id on Salesforce Contact”
- The default value of the field does not match, here, the one we added on Salesforce contact.
- Update the value with “Sitecore_Id__c” (the API Name of the Salesforce field), then save your changes.
Push contact data from Sitecore to Salesforce
- We have created a testing contact on the List manager to test pushing data into Salesforce. Notice the email address of the testing contact (this contact does not exist or created in Salesforce)
- Sitecore DEF has the idea of Pipelines and Pipeline batches. Pipelines items contains a set of Pipeline Steps and Pipeline batches can include one or more pipelines to execute.
- Before you execute the batch, you’ll need to make sure that the tenant is enabled.
- Ok, our testing contact is created in XDB
- To push the contact into Slaesforce, we’ll need to run a batch. Navigate into Pipeline Batches > xConnect Contacts to Salesforce Sync, click on “Run Pipeline Batch”
- Go to Sitecore, find the Contacts List (normally, in the classic interface, you can click on the “+” button and select “Contacts”, then Go to All Contacts)
- As you notice the Sitecore contact is added to Salesforce Contacts List with the same email address
Write Contact data from Salesforce into Sitecore xConnect
- As you noticed, the XDB only contains the contact we have created. Now, we’ll add the Salesforce contacts into Sitecore XDB via xConnect.
- If you have a look on the Salesforce Contacts List in Salesforce, you’ll see that Salesforce creates about 20 testing contact for you (Developer Account).
- To add these contacts into Sitecore, navigate into Pipeline Batches > Salesforce Contacts to xConnect Sync. Running this batch will make Sitecore reading the Contacts from Salesforce and add them to Sitecore XDB.
- If you go now to the database of ContactFacets, you’ll find that these contacts were added there!
We hope this blog was useful for you and answers on your questions about the synchronization between Sitecore and Salesforce.
For more information, our certified and experienced Sitecore team will be happy to help. Just contact us here and we’ll respond asap!