Salesforce Integration

Salesforce Integration

Overview

To create a Salesforce integration within Client Sense the following items need to be prepared in Salesforce. You will need to be an Admin within Salesforce to complete the setup for these items.
  1. Integration specific Connected App
    1. Connected Apps provide API credentials
  2. Relaxed IP restrictions for the Connected App
  3. A user account with a Username, Password and Security Token
    1. When connecting to the Salesforce API, Salesforce requires API credentials and a user account. Any updates or changes made through the API will be associated with the user account
    2. It is recommended that you create a new user account for the purpose of the integration but an existing account can also be used
  4. Upper Sigma integration only - Shared activities
    1. This item is only required when using the Upper Sigma integration and is not relevant for standard Salesforce integrations
When the above information has been prepared the integration can be added into Client Sense.

The integration will save successfully if the Salesforce details have been prepared correctly and the integration will be created in Client Sense. At the time of creation it will check to see what updates are needed within the Saleforce instance including flexipage and custom field changes.

Integration changes in Salesforce

The changes in this section will be completed automatically by Client Sense once the integration has been successfully added to Client Sense and an initial sync has been run. This information has been detailed so that you're aware of the changes that Client Sense will make to Salesforce.

Permission Sets

Two permission sets will be added "Client Sense Permission Set", and "CS Internal Permission Set". Only "Client Sense Permission Set" should be used. This permission set will need to be assigned to Users who wish to view the Client Sense fields.

Lightning Page changes

A tab will be added to display the Client Sense custom field data against contact records via a new Quick Action "Client Sense".

Custom field changes

The following custom fields will be added against Contacts by default

Field
Description
CS Created
Flagged as True when the contact is pushed into the CRM from Client Sense
CS Title
The title as captured in Client Sense
CS Street
The street of the primary address as captured in Client Sense
CS City
The city of the primary address as capture in Client Sense
CS State
The state of the primary address as captured in Client Sense
CS Postcode
The postcode of the primary address as captured in Client Sense
CS Country
The country of the primary address as captured in Client Sense
CS Top Employees
The top employees of the contact for the configured period from Client Sense
CS Top Groups
The top groups of the contact for the configured period from Client Sense
CS Relationship Managers
The relationship managers configured against the contact in Client Sense

Additional fields could be added at a later time

Data mapping

Client Sense maps by Email and Domain. Individuals within Client Sense will be mapped by email to Contacts within Salesforce. Organisations within Client Sense will be mapped by domain to Accounts within Salesforce.

Client Sense does not map any data for Contacts or Accounts that don't exist within Client Sense.

Contacts
When Client Sense finds a contact that exists in both Client Sense and Salesforce, the custom fields above will be populated with the data that is found in Client Sense. A flag will be set in Client Sense against the individual to represent its presence within the CRM.

If the contact is missing an account, Client Sense will search for an account that matches the domain of the Individual within Client Sense. If a matching account is found then it will be associated with the Contact in Salesforce. If no matching Account is found, Client Sense will create one matching the domain and associate it with the Contact in Salesforce.

Accounts
Client Sense will create accounts where necessary to ensure that all Contacts synced with Client Sense have an associated account.

Salesforce Configuration

This setup step should take approximately 5 minutes.
Please ensure you are logged in as Admin for these steps.

Setting up a Connected App


  1. Navigate to the Salesforce Setup


  2. Navigate to Apps > App Manager.


  3. Click New Connected App.


  4. Configure New Connected App
    1. Set App Name to "Client Sense Integration".
    2. Set Email to "support@clientsense.com".
    3. Tick "Enable OAuth Settings".
    4. Set Callback URL to "https://salesforce.com".
    5. Add "Full access (full)" in Selected OAuth Scopes.



  5. Click Save
  6. Click Manage Consumer Details

Write these down.
Take note of the Consumer Key. This is your Client Id.
Take note of the Consumer Secret. This is your Client Secret.

Modify Connected App IP restrictions

  1. Navigate to Apps > Connected Apps > Manage Connected Apps.


  2. Click edit for the Client Sense Integration.

  3. Set IP Relaxation to "Relax IP restriction"


  5. Click save.

Allow OAuth Username-Passwords Flows

This option may already be enabled for your environment however instances of Salesforce created since June 2023 will have this configuration option disabled by default.
  1. Navigate to Setup
  2. Under the Settings heading in the left menu expand Identity and select OAuth and OpenID Connect Settings


  3. Turn the Allow OAuth Username-Password Flows switch to On


Upper Sigma only - enable Shared Activities

The step below is only applicable for the Upper Sigma Integration. If you are using just Salesforce, then you are done.


Getting ready to configure the integration in Client Sense

The changes in the preceeding steps may take up to 15 minutes to propagate. If the integration can not successfully authenticate ensure sufficient time has passed.
Once the integration has been created, the user should not be changed.
Create a new user (suggested) or assign a preexisting one for use with the integration (username and password below).
Please ensure that the user is a full user rather than an integration user

You should now have all the information to set up an integration. Six pieces are required in total.

To locate the security token for the integration user, follow the instructions here  https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm&language=en_US
API Key = Integration user Security Token (Obtained in the link above)
Please ensure that the format of the API URL matches the format of "my.salesforce.com". For example, if your URL is of the form "example.sandbox.lightning.force.com" change it to "example.sandbox.my.salesforce.com".
Client Id = Consumer Id (noted down earlier)
Client Secret = Consumer Secret (noted down earlier)
Ensure that you are using the username for the Integration account and not the email. While the two may be identical, it would be prudent to check under Settings > Users > Users and locating the Integration account.
Username = Integration user Username
Password = Integration user Password

Adding the integration into Client Sense

Please ensure that you're a full Client Sense user to perform this step
  1. Launch Client Sense
  2. From the top right dropdown menu, select Integrations
  3. Click New Integration
  4. Select Salesforce (If using Upper Sigma, please choose Upper Sigma)
  5. Populate the fields
    1. API Key = Integration user Security Token
    3. Client Id = Consumer Id
    4. Client Secret = Consumer Secret
    5. Username = Integration user Username
    6. Password = Integration user Password
  6. Click Save
  7. Click the gear icon to modify the integration
  8. Turn the service switch On
  9. Click Save
It's a good idea to run an initial sync after adding the integration, you can do this now
  1. Click the gear icon to modify the integration
  2. Click Run Now
  3. The initial sync will take some time - the gear icon on the integration will be replaced with a spinner while the sync is running

Upper Sigma Enhancements

This functionality only applies to Upper Sigma
Additional functionality for Relationship Creation and Activity Syncing can be enabled and controlled through the Customisation tab of the integration configuration screen.

Automatic Relationship Creation

Client Sense can use the connections that are known between employees and individuals to automatically create these connections as relationships in Upper Sigma. You can specify the type of relationship to be created by choosing an existing type or creating a new type for the purpose of Client Sense based connections. For relationships to be automatically created both the employee and external individual must exist in the CRM. Relationship creation will be performed during a nightly sync and new connections will be created as new contacts and employees enter the CRM and where Client Sense holds a connection.

  1. Click the gear icon to modify the integration
  2. Select the Customisation tab
  3. Check the Sync Relationships option
  4. Choose the Relationship Type from the dropdown
  5. Click Save
  6. Relationships will be created on the next full sync (overnight, otherwise you can initiate it manually)


Automatic Activity Sync

Client Sense can create activities that it holds against contacts as activities in Upper Sigma. You can choose which types of activity you wish to sync into Upper Sigma. Some future activities may be added to the CRM although if these change Client Sense will try to maintain these by updating or removing where necessary. Activities created by Client Sense will  include text in the description "Created by Client Sense - [MeetingId:xxx]" - this text must remain in the description to ensure it can be tracked and maintained by Client Sense although additional text can be added to the description above this text.

  1. Click the gear icon to modify the integration
  2. Select the Customisation tab
  3. Check the Sync Activities option
  4. Check the boxes for the types of Activity you wish to sync
  5. Click Save
  6. Activities will be created on the next full sync (overnight, otherwise you can initiate it manually)