Technical Setup and Configurations
Now that you've nailed the discovery by following my previous post, We'll spend some time going through the technical setup. This post will include the installation steps up to creating a Sitecore tenant with commentary along the way. Refer to the official documentation for configuring the tenant itself as it's very black and white. This post is not intended to replace the Sitecore official installation guide but may be helpful as supplemental documentation for some gray areas in the initial setup.
Before you install Sitecore Connect for Salesforce, you must have:
- Proper Sitecore Licensing
- xDB is enabled (default:
) found in:\App_Config\Sitecore\Marketing.xDB\Sitecore.Xdb.config
- Sitecore Experience Platform 9.1 or greater
- Access to a Salesforce CRM instance and a user account on Salesforce - at a minimum, this account must have rights to read data from Salesforce. To write data to Salesforce, the account must also have rights to write data to Salesforce.
- Network connectivity - you must install on a Sitecore server that has network connectivity to your Salesforce instance. This can require configuration based on your network setup.
One additional recommendation is to make sure that contact tracking is functioning normally prior to installation. With any installation it is good practice to survey the log files to identify problems that already exist prior to the new features. If there are any pending issues with xDB or the experience profiles, I recommend fixing those prior to installing the connector.
Sitecore Connector Packages
Make sure to be well rested or highly caffeinated before beginning this installation. It's easy to get distracted and install these out of order, which will cause the functionality to fail. Also, make doubly sure you're using a version of Sitecore compatible with the module. At the time of this post Sitecore 9.2 was not compatible due to a dependency on an unreleased version of the data exchange framework.
The following instructions require access to dev.sitecore.net, where official documentation and packages can be obtained.
- Download and install Data Exchange Framework 2.1.
- Download and Install Sitecore Provider for Data Exchange Framework 2.1.
- Download and Install xConnect Provider for Data Exchange Framework 2.1.
- Download and Install Salesforce Provider for Data Exchange Framework 2.1
- Install Connect for Salesforce 2.1.
Generate and Distribute New xConnect Collection Models
xConnect collects and maps data based on system models located on the xConnect server. The connector installation adds new facets required to sync data with Salesforce and Sitecore.
- Once the packages have been installed you should be able to navigate to the following path in the content tree:
- sitecore/system/Settings/Data Exchange/Providers/xConnect/Collection Models/Connect for Salesforce/Connect for Salesforce Collection Model
- Use the Data Exchange tab to expose and click the “Convert Model to JSON” button. This action downloads your new model so it can be deployed in the next step.
- Copy that JSON model into your xConnect server in two location:
- \App_Data\jobs\continuous\IndexWorker\App_Data \Models\
For Sitecore to communicate with Salesforce, a connected app needs to be set up in Salesforce. This allows not only the connectivity, but also the ability for Salesforce Admins to set permissions and roles if additional security or user limitations are in place.
Sitecore's documentation shows the classic interface, but the clients I work with typically have lightning, so I will be using that as our reference.
If you don't have access to a Salesforce environment already, you can create a developer account by visiting https://developer.salesforce.com/signup. Also, it's helpful to have Salesforce seed data. There are lots of ways to get that data, but I went with the path of least resistance and found some data ready made for import at the end of this thread: https://success.salesforce.com/answers?id=9063A000000e6TzQAI
Once you have access to log into a Salesforce environment let's begin prepping our application.
- Log in to your Salesforce account (Lightning version)
- In the top right menu, click the gear and follow the link to Setup:
- In the setup area, find the left navigation and expand the “Apps” section of Platform tools and click on App Manager:
- Within the App manager, click “New Connected App”
- Enter the appropriate values
Field Name Value Notes Connected App Name Sitecore_Data_Exchange_App The specific value does not matter API Name Sitecore_Data_Exchange_App Salesforce generates this value based on the app name.
It is recommended that this value not be changed.
Contact Email [your email address] The specific value does not matter. Enable OAuth Settings Selected Callback URL http://localhost This value is not used, so the value you enter does not
Selected OAuth Scopes Access and manage your data (api) Require Secret for Web Server Flow Selected
- At the bottom of the screen, click Save.
- Salesforce informs you that a new connected app was created. Click Continue.
Custom Salesforce Field
Add a custom field to allow tighter synchronization between the systems. Sitecore says it's optional, but I recommend it since it allows Sitecore to write xDB contact IDs onto Salesforce contacts.
Adding a field to a contact object is done under the setup area of your Salesforce account. On the left navigation expand “Objects and Fields” and select the object manager. From there you can select the Contact object > Fields & Relationships > New
- Add a custom field on the contact object using the following values:
- Data Type - Text
- Field Label - Sitecore Id
- Length - 36
- Field Name – SitecoreId
- External ID – selected
Follow similar steps to add a field to the Activity object.
- Add a custom field on the activity object using the following values:
- Data Type – Text
- Field Label – SitecoreId
- Length – 36
- Field Name – SitecoreId
- External ID - selected
Configure the Salesforce Connection Strings
Just like connecting to Sitecore databases, the connector uses connection strings to connect to the Salesforce app. The data you'll need from Salesforce is:
- User ID
- Client ID and Secret Key
To get the values above, go to Apps > App Manager > Select the App you created > View
- Security Token
To get the user security token if you don't have it available, you'll have to reset it. This is done by clicking your profile icon on the top right and selecting “Settings”. Then in the left column, select “Reset My Security Token”
The example config entry will look as follows and is inserted at the end of the main Connection string file " \App_Config\ConnectionStrings.config":
Proceed to Setting up you tenant in Sitecore
At this point your external work is complete and the foundation is laid. You're ready to follow the steps in the Sitecore Connect for Salesforce 2.1 Installation Guide starting at section 3.3.
In the next blog post we'll cover rollout strategy and common challenges