How to integrate Salesforce with Sapho version 3.9 or greater

Last update:

Important Notes

Sapho requires regular API access to your Salesforce instance. In order to accomplish this, we recommend creating a dedicated user account (for example, sapho@company.com) in Salesforce and then using that account to configure the Salesforce integration in Sapho. This account should:

  • be given full data access privileges
  • be API-enabled
  • not allow two-factor authentication.

Using a dedicated account will be particularly useful for audit logs as it will help distinguish activities done through Sapho. This page contains tutorials for both Salesforce Classic and Salesforce Lightning Experience. Both tutorials assume that you are a System Administrator in Salesforce.

Note that Salesforce "Contact" and "Group" Editions do not support any API and that the "Professional" Edition does not include it automatically (but can be activated upon request).

Please also be aware of the fact, that the number of API requests are limited in Salesforce. In case you plan to frequently synchronize extensive amount of data, please refer here.

Tutorial for Salesforce Classic

Step 1: Sign in

Log in to www.salesforce.com

Step 2: Add a new profile

Go to Setup (1)> Administer > Manage Users > Profiles (2)> New Profile (3).

Set "Existing Profile" to "System Administrator" (this will ensure that the user we will create next for this profile will have full data access privileges). Enter "Sapho" in "Profile Name". Then click the Save button.

Step 3: Enable API access for the created profile

Click the "Edit" button on the newly created profile and scroll down to "Administrative Permissions".

Set "API Enabled" to ON by checking the checkbox for this option.

Step 4: Disable password expiration for the created profile (optional)

Additionally, still under "Administrative Permissions", you can set "Password Never Expires" to ON by checking the checkbox for this option.

Please note that setting "Password Never Expires" to ON is optional because it is a potential security vulnerability. It’s comfortable to not have to change passwords regularly; however, it’s up to your consideration whether you want to enable it or not.

Click the "Save" button at the bottom of the page.

Step 5: Restrict Login IP Ranges (optional)

If your organization sets IP ranges for User Profiles, then restrict login IP ranges for this dedicated profile as explained here at steps 3-5. The IP of the Sapho Server should be in the whitelisted range.

Step 6: Add a new user

Go to Setup > Administer > Manage Users > Users > New User.

Fill in the required fields indicated in red. Set User License to Salesforce and Profile to Sapho. Click the Save button.

This will be the dedicated user account that will be used to connect Sapho to Salesforce.

Step 7: Log in Salesforce with the new user

Open the message sent by Salesforce to the email account of the new user. Click the indicated link to log in, set a password and a password question.

Step 8: Generate a security token

If you did restrict login IP ranges for the dedicated user profile during step 5 of this tutorial, you can skip this step. The security token is not required for accounts connecting to the Salesforce API from a whitelisted IP block.

Otherwise, proceed as indicated below:

After logging in, you’ll be redirected to the "Home" page of the Salesforce instance. Click on the account name in the top right corner. Then go to My Settings (1)> Personal (2)> Reset My Security Token (3)> Reset Security Token (4).

The new security token will be sent to the email address indicated in the personal settings for this Salesforce account.

Please note that a new security token will be emailed as well when the password for this account will be reset.

Step 9: Paste the credentials in Sapho

Enter the Username and Password of the dedicated user account in the input fields of Salesforce service definition in Sapho.

If you did step 5 of this tutorial (i.e. whitelisted the IP of the Sapho Server), you don’t need to enter a Security Token.

Otherwise, paste the Security Token that was sent to the email box of the dedicated account.

Step 10: Finish the creation of the Salesforce integration

Tutorial for Salesforce Lightning Experience

Step 1: Sign in

Log in to www.salesforce.com

Step 2: Add a new profile

Go to Setup (1)> Administration > Users (2)> Profiles (3)> Profiles > New (4).

Set Existing Profile to System Administrator (this will ensure that the user we will create for this profile will have full data access privileges). Enter Sapho for Profile Name. Then click the Save button.

Step 3: Enable API access for the created profile

Click the Edit button on the newly created profile and scroll down to Administrative Permissions.

Set API Enabled to ON by checking the checkbox for this option.

Step 4: Disable password expiration for the created profile (optional)

Also under Administrative Permissions, set Password Never Expires to ON by checking the checkbox for this option.

Please note that setting Password Never Expires to ON is optional because it is a potential security vulnerability. It’s comfortable to not have to change passwords regularly; however, it’s up to your consideration whether you want to enable it or not.

Click the Save button at the bottom of the page.

Step 5: Restrict Login IP Ranges (optional)

If your organization sets IP ranges for User Profiles, then restrict login IP ranges for this dedicated profile as explained here at steps 3-5. The IP of the Sapho Server should be in the whitelisted range.

Step 6: Add a new user

Go to Setup > Administration > Users (1)> Users (2)> New User (3).

Fill in the mandatory fields (indicated in red). Set "User License" to "Salesforce" and Profile to "Sapho". Click the Save button.

This will be the dedicated user account that will be used to connect Sapho to Salesforce.

Step 7: Log in Salesforce with the new user

Open the message sent by Salesforce to the email account of the new user. Click the indicated link to log in, set a password and a password question.

Step 8: Generate a security token

If you did restrict login IP ranges for the dedicated user profile during step 5 of this tutorial, you can skip this step. The security token is not required for accounts connecting to the Salesforce API from a whitelisted IP block.

Otherwise, proceed as indicated below:

After logging in, you’ll be redirected to the "Home" page of the Salesforce instance. Click on the account name in the top right corner. Then go to Settings (1) > Reset My Security Token (2) > Reset Security Token (3).

The new security token will be sent to the email address indicated in the personal settings for this Salesforce user account. Please note that a new security token will be emailed as well when the password for this account will be reset.

Step 9: Paste the credentials in Sapho

Enter the Username and Password of the dedicated user account in the input fields of Salesforce service definition in Sapho.

If you did step 5 of this tutorial (i.e. whitelisted the IP of the Sapho Server), you don’t need to enter a Security Token.

Otherwise, paste the Security Token that was sent to the email box of the dedicated account.

Step 10: Finish the creation of the Salesforce integration

Audit Trail

Once you have created a separate profile and user in Salesforce and set up the integration in Sapho using that user account, you will be able to ensure transparency in your audit logs. Any write-backs from Sapho to Salesforce will be indicated in All Updates section for the respective record.

For example, a Lead converted through a Sapho micro app will indicate on the detail page of the newly created Account in Salesforce that it was converted by the dedicated user account (e.g. sapho@company.com). See example below.

sfdc20.png

Filter Queries

Most of Salesforce entities support filtering. You can choose between predefined queries or write your own custom queries using Salesforce SOQL language. For more information consult Salesforce Object Query Language documentation.

Troubleshooting

This section will describe a number of possible connectivity blockers. Follow the suggested solutions or contact support@sapho.com.

1) Sapho on-premises cannot connect to the Salesforce cloud

If Sapho Server runs on premises behind a firewall, it might not be able to connect to the Salesforce cloud.

Solution:

In your firewall settings, you will need to allow access to hostname www.salesforce.com with port 443.

2) Require secure connections HTTPS

There is a new change to Session Settings, including a new Permission titled "Require secure connections (HTTPS) for all 3rd-party domains". The permission is supposed to be OFF by default for existing organization, and only ON by default for new Summer '17 organizations. However, it is auto activating for existing customers and hence can cause some issues with 3rd party connections on http.

Solution:

Salesforce System Admins are able to disable the permission themselves without having to contact Salesforce Support. To make it work customer needs to turn off the perm under setup->Security Controls->Session settings - "Require secure connections (HTTPS) for all 3rd-party domains"

3) Dashboards/data hidden in Private folders

Administrators are NOT allowed to access private folders, so if the admin wants to access "My Personal Custom Reports" default folder (and share it in Sapho for example) they need to use the “allPrivate” query scope, otherwise they won't be able to do so.

For example, the below query returns reports saved inside users’ private folders that haven’t been run in more than one year:

SELECT Id FROM Report USING SCOPE allPrivate WHERE LastRunDate < LAST_N_DAYS:365

You can also query reports saved inside a specific user’s private folder.

SELECT Id FROM Report USING SCOPE allPrivate WHERE OwnerId='005A0000000Bc2deFG'

More about this issue here.

4) Too many requests waiting for connection

If you are getting any of the below error messages, it is probably because you have too many jobs connected to a Salesforce instance and the reason is that the server ( on the cloud ) doesn’t have enough resources to accept new connections.

  • com.salesforce.soap.partner.UnexpectedErrorFault: SERVER_UNAVAILABLE: Too many requests waiting for connections
  • Exception in component tSalesforceConnection_1
  • com.salesforce.soap.partner.UnexpectedErrorFault: SERVER_UNAVAILABLE: Too many requests waiting for connections

More about the issue here.

5) Login to sandbox via API after refresh not possible

After refreshing sandbox, API login works on production but fail in sandbox with below error:

  • Fatal error: Uncaught SoapFault exception: [INVALID_LOGIN] INVALID_LOGIN: Invalid username, password, security token; or user locked out. in /Applications/XAMPP/xamppfiles/htdocs/trunk/plugins/system/salesforce/soapclient/SforceBaseClient.php:168

Solution:

It's probably due to the fact that the login via test.salesforce.com has cached the old sandbox user, so any attempt via test instead of the specific cs hits the old one.  This really needs to be fixed, because some tools don't let you specify your own URL (like real force explorer).  There is a workaround:

  • Change your username
  • Specify your domain in the login URL (ex: cs3.salesforce.com)

6) Query Timeout at sync

If you are getting the below error message when synchronizing your Salesforce data, it is most probably because the data set for the entity is too big:

  • *Error: *
    UnexpectedErrorFault [ApiFault exceptionCode='QUERY_TIMEOUT' exceptionMessage='Your query request was running for too long.']

Solution:

Narrow down the downloaded data set using entity filters (see filters for other entities). Possible filters could be:
CreatedDate >= LAST_N_MONTHS:1
or
SystemModStamp >= LAST_N_MONTHS:1