Sitecore + Salesforce – Setting up Sitecore Connect for SalesForce CRM

Dear Sitecore Family,

Recently, my friend and colleague Alok Kadudeshmukh and I, we presented at SUGCON India 2019 – on Sitecore + SalesForce – Let’s Improve a User Journey. Our focus was mainly to introduce the audience to the Sitecore Connect Modules – for Sales Cloud and Marketing Cloud and show how easy it is to set it up and get started.

Alok has already blogged about Things to keep in mind while integrating Sitecore and SalesForce

Why this post?

Well, after our session was over, Alok and I were at the HI Booth for sometime and we got some questions from the Sitecore community members coming over to the booth, that how do we get started and get all setup. Now, in our session, we had mainly focused on the Demo piece and we kind of ran through the slides for setup, so they wanted to know things in detail along with its importance. So be it! Here it comes my dear friends.

Lets have a brief look at the steps to setup SalesForce Connect:

So we tried dividing it into 5 simple steps:

System Pre-requisites
Installing the required Sitecore Packages
Deploying xDB Models
Ceating a SalesForce Connected App
Creating a Tenant and Running Pipeline Batches.

So lets get started one after the other:

Step 1: System Pre-requisites

Now, as we know we are talking about two systems here, Sitecore and SalesForce, we have to understand, that we have pre-requisites for both these systems.

Sitecore Pre-requisites
- Obviously, we need a running Sitecore XP instance.
- We need xDB Enabled on the Sitecore instance.
- The Sitecore license needs to support use of the Salesforce Connect module. This is not supported out of the box and its good to check with Sitecore Representative team if your license supports it.

So there we have a Sitecore 9.1 Instance running!

And the xDB is enabled – we can know that from the following config entry:

SalesForce Pre-requisites
- We need to have a user login to SalesForce – best is, Signup as a Developer for SalesForce and get started with the SalesForce Cloud from this link https://developer.salesforce.com/signup
- With this user account, we will use the API level access for the application we will create later.

Step 2: Installing Sitecore Packages

I would say, this is the only task which is a little uninteresting, as you need to wait looking at the screen for all the packages to be installed. There are 5 Sitecore packages that you need to install to get started.

Sitecore Data Exchange Framework 2.1
- The foundation of data Synchronization between Sitecore and Salesforce is Data Exchange Framework.
- We know DEF is Robust, Modular and customizable
- Data Exchange Framework models synchronization processes in a pipeline. A pipeline is made up of pipeline steps.
Sitecore Provider for Data Exchange Framework 2.1
xConnect Provider for Data Exchange Framework 2.1
Salesforce Provider for Data Exchange Framework 2.1
Sitecore Connect for SalesForce CRM 2.1
- This basically installs a pre-configured Synchronization process – and when we create a Tenant in Step 5 – all this comes into picture.
- The good thing is, we as devs don’t need to do anything custom, everything is all set for us nicely.

Sitecore Data Exchange Framework can be found here while the other four downloads can be found here on the Sitecore Developer Portal.

In every package, the details will show pre-requisites as well, so there is no chance we can make a mistake. 🙂

This is pretty standard, so I am not sharing any more screenshot of the package installation.

Let’s move to step 3 – the part from where the fun begins!

Step 3: Deploy xDB Models

The first question that might come to our mind, is why do we need this?

Well, Great Question!

We need a mapping between the two – a Sitecore Contact and a SalesForce Contact and that is what we do in this step. So basically, we need a Primary Key!

Say when our contact which is created in Sitecore goes to SalesForce, there should be a way of identifying it uniquely in SalesForce.

The good thing is, Sitecore Connect adds the new facet required to associate this information for us and when we installed the package, it comes to our Sitecore environment. But, our xConnect, doesn’t know about that field and hence, we create a JSON of the updated model and put it on to our xConnect Instance.

Lets look at the steps of how do we do it:

Login to Sitecore and open Content Editor.
Next, go to the item /sitecore/system/Settings/Data Exchange/Providers/xConnect/Collection Models/Connect for Salesforce/Connect for Salesforce Collection Model

Now, in the Data Exchange tab of the ribbon, we will be able to see a Button – Convert Model to JSON

Sitecore will convert the Model to JSON and give it as a download to us. Save it.
Now, we deploy this file at two places
- To the xConnect Server – location – [PATH-TO-XCONNECT-WEBSITE]\App_Data\Models
- To the xConnect Indexing Server – i.e. the Index Worker – location – [PATH-TO-XCONNECT-WEBSITE]\App_Data\jobs\continuous\IndexWorker\App_data\Models
Recycle the App pool of the xConnect Server
Restart the xConnect Indexing Windows Service.

Step 4: Create a SalesForce Connected App

So, to be honest, I wasn’t clear the first time I looked at this in the Sitecore documentation, so I googled it. And I found the following answer, which I would like to share:

Connected Apps allows external applications to connect to Salesforce over Identity and other DATA APIs. It utilizes the standard OAuth 2.0 protocol, can provide Single Sign-On and acquire access tokens for use by the various Salesforce supported APIs

Reference: What is Connected Apps and how can it provide better external and mobile app security

So, for our understanding from Sitecore’s perspective, to make Sitecore to communicate with SalesForce, we need to configure a SalesForce connected app.

This step will include 3 sub-steps:

Create a SalesForce Connected App
Get the Client ID and Secret Key
1. The Client ID and Secret Key belongs to a SalesForce Connected App – which means they will be unique for each app we create.
2. This is eventually identified when we create the SalesForce connected app itself. (https://developer.salesforce.com/forums/?id=9060G000000I8HJQA0)
Get the security token
1. A Security Token is that of a User – which means it will remain same for every new SalesForce Connected App we create.

Let’s take care of the First Sub Step – Create a SalesForce Connected App.

Login to your SalesForce Account.
Next, in the top right corner, click on the Gear icon and selected Setup

Now, we have moved to the Setup Home. Here, in the right hand navigation pane, we’ll find a number of links. The one which interests us is Apps. Now as we talked about Connected Apps, the first path that we might go is Click on Apps -> Connected Apps -> Manage Connected Apps, but that is not the correct one – its a little misleading. I had gone that same route as well, and then found a StackExchange conversation that helped me, when I was setting it up (https://salesforce.stackexchange.com/questions/101817/new-button-missing-from-connected-apps) When we want to create a new Connected App, we need to go to the App Manager.

Click on the New Connected App. Let’s call it Sitecore App and then fill in the required fields.

In the second section, API (Enable OAuth Settings) Click on Enable OAuth Settings Checkbox, Add localhost to the Callback URL and select access and manage your data (api) in the selected OAuth Scopes. Also, make sure that Require Secret for Web Server Flow is checked.

Click Save. It takes 2-10 minutes for the changes to take effect and you will notice a Continue button on the next screen.
Once you click on Continue, you will notice that the Consumer Key is visible and We need to click to reveal the Consumer Secret. Note that this is the only time, when we can see the Consumer Key and Consumer Secret.

So what if we forget to note down the Consumer Key and Consumer Secret?

Well, a simple solution is edit the App, Uncheck the Enable OAuth Settings, Save it and click Continue.

Next, again edit it, enable the OAuth Settings, and select what we selected above, click save and click continue – Bingo! You are on the Screen where the Consumer Key and Consumer Secret is visible!

We can now move to the third sub-step – Get the security token

When you click on the right hand top corner which basically says our Username, we will see a link called Settings, click on it.

Now, in the left hand pane, we will notice a link Reset My Security Token. Click on it.

Click on the button Reset Security Token. It will notify that the Security Token has been sent to the email address with which we had registered.

Now, when we open our Email account, we will notice an email from SalesForce, with the Username and Security Token

Step 5: Create Tenant and Run Pipeline Batches

Well, the last piece, is creating the tenant and getting started! Believe me, this is the most interesting step of all!

So what is a Tenant?

According to the Sitecore Documentation, Tenant is the basic unit of configuration in Sitecore Connect for SalesForce. All the Synchronization settings reside here.

So how do we do it?

Right-click and Insert – Connect for Salesforce Tenant – Name it Salesforce Tenant.

It takes sometime to create it for us.

Once done, it appears right below the Data Exchange item.

Next, we will configure the end points, for which we will first go to the SalesForce Client Endpoint – it is at the following location: /sitecore/system/Data Exchange/Salesforce Tenant/Endpoints/Providers/Salesforce/Salesforce Client Endpoint

Now, remember all the efforts we took in the previous step of Creating a Connected App – for getting the security token and consumer secret and all? Well, it all comes to use now.

Go to the ConnectionStrings.config and create a new entry the following way:

<add name=”mysf” connectionString=”user id=[user id];password=[password];client id=[client id];secret key=[secret key];security token= [security token]” />

And now, save the ConnectionStrings.config – this will recycle the app pool so please open the login page of your Sitecore App in a different browser tab.
Next, we enter the key of the connectionstring we entered – mysf in this endpoint and save it.

Now, we should definitely verify if the connection to SalesForce has succeeded or not. To check that, click on Run Troubleshooter. If we get a success message, we are done!

In case we don’t get the above message, its good to check the connectionstring entry we did for SalesForce, as well as the name of the key we entered a couple of steps back.
[Update 1st June 2019] In case there is something wrong and you are unable to get Connection established successfully, check this post for further troubleshooting [/Update 1st June 2019]

[Update 1st June 2019]

Bummer, we missed a few steps!

The same way we configured our SalesForce Endpoint, by giving the connectionstring key, we need to do simiar steps for xConnect Endpoint as well, so that our Tenant is connected to the xConnect Server. So lets do it now.

Go to the xConnect Client Endpoint item: /sitecore/system/Data Exchange/Salesforce Tenant/Endpoints/Providers/xConnect/xConnect Client Endpoint

Now, add the Collection Service Connection String Name as “xconnect.collection” while the Collection Service Certificate Connection String Name as “xconnect.collection.certificate”. Generally, in our local or POC environments, we put our Self Signed Certificates for xConnect, so lets also check Allow Invalid Certificates checkbox. Save it.

Now, Run the Troubleshooter. It should succeed in first go.

In case there is something wrong and you are unable to get Connection established successfully, check this post for further troubleshooting.

[/Update 1st June 2019]

Lastly, we need to enable this Tenant so that in future whenever the Synchronization happens, the configurations in this Tenant are used. for doing that, we go back to the Tenant Item that we created in this step : /sitecore/system/Data Exchange/Salesforce Tenant and Click on the checkbox Enabled and save it.

A great thing to note about the Tenants is that because of this architecture which Sitecore has designed, we can have one-many connections available – which means, one Sitecore solution can connect to many SalesForce Connected Apps – even though that might not be required in real life but we have that facility. How? Well, simply create multiple tenants!

References:

Credits:

Hope that, even though this was a very long post, you liked reading it.

Happy Sitecore Connecting! 🙂