Overview

In this article we describe what is needed to create an integration between XCALLY and Salesforce through RESTful API methods.  Once a connection is established between these two systems then Triggers may be created to exchange information like creating tasks or cases once an interaction is received.

Requisites for a successful integration between XCALLY and Salesforce

It is important to understand what elements are required to fully establish a connection between these two systems.  Please consider:

• A working Salesforce environment.  It could be a staging, sandbox or production environment.  If you are under a trial please consult if your instance offers API access; some trial environments may not offer access to API calls.
• A Salesforce account with administration privileges.  For the integration to work, it is mandatory to have access to Salesforce login with administrative privileges. Make sure you have contacted your Salesforce server team or your instance administrator if you need privileges.
• A XCALLY administration login.   The same way administration rights are needed on Salesforce, privileged access to Salesforce accounts are required.  If you are using a User (supervisor) login please consult your administrator to make sure you have the required access.

Understanding important concepts about Salesforce and XCALLY integration

For XCALLY to achieve a proper connection with Salesforce it's going to need specific objects that need to exist first.  These objects are: 

• A Connected App.   A connected app is used to be the bridge between XCALLY and Salesforce. This app works as an API tooling to exchange authenticated messages that will allow XCALLY to send and receive Salesforce data.  In the next lines we will show you how to create one.
• A Consumer Key.   Once the app is created it's going to be identified by a key pretty similar to an username.
• A Consumer Secret. This is going to be the password to the Consumer Key or the username associated to the app.
• A Salesforce valid URL.  This is the web address associated to your instance or environment; something like https://mycompany.salesforce.com/.
• A Salesforce valid login and password.  The actual credentials with administration privileges that are used to login to Salesforce.
• A Salesforce Account's Security Token.  A special security key associated with your login credentials.

Step to Step procedure to create a Salesforce integration with XCALLY

Set up base Salesforce API connectivity 

1. Login to your Salesforce instance with your credentials.  Identify what type of interface you are using.  Salesforce offers two types of UI experiences: Classic and Lightning.  For this procedure we are going to use Salesforce's Lightning experience.
2. Switch to Lightning Experience. To switch to Lightning Experience identify the icon next to your Login name at the top bar and click there:

3. Enter Setup mode. Once you are in Lightning now you have to switch to the Setup mode.  Click on the wrench icon   () and then click on Setup:

4. Now let's look for the App Manager application.  To search for that specific application please type App Manager on the Quick Find search bar located at the top left of the screen:

Please click on App Manager.

5. Create a new Connected App. Once the Lightning Experience App Manager has been shown please identify the button New Connected App at the right side of the top bar:

Please click on New Connected App.

6. Add basic app information.   You may give it a name like XCALLY API Bridge. Please establish a valid contact email address.

Required fields are marked with a red stripe.

7.  Setup API connection.  Now let's configure the API settings required for a correct authentication method using special permission scopes so XCALLY and Salesforce can communicate between each other.  Consider this screen:

7.1. Enable OAuth Settings.  Click on Enable OAuth Settings and consider all the available options:

7.2. Now specify the Callback URL. Please copy and paste the following URL string into the Callback URL field:

https://login.salesforce.com/services/oauth2/callback

7.3. Set the required scopes.  Now it's important to select the proper OAuth Scopes that allow for information exchange.   From the list of available scopes on the left please select the following:

• Access Connect REST API resources (chatter_api)
• Manage user data via APIs (api)
• Access custom permissions (custom_permissions)
• Access the identity URL service (id, profile, email, address, phone)
• Allow access to your unique identifier (openid)
• Full access (full)
• Perform requests at any time (refresh_token, offline_access)
• Access Visualforce applications (visualforce)
• Manage user data via Web browsers (web)

Consider this is how your Selected OAuth Scopes will look:

NOTE: Consider the names of the OAuth Scopes may change from time to time and from Salesforce version.  Use the name in parenthesis as a guide.

7.4. Disable non desired Flows.  By default some flows like Refresh Token Flow or Client Credetian Flow options may be on.   To grant access to this app from XCALLY the ONLY flow that is needed is the Web Server Flow:

7.5. Save.  Once you are sure your changes have been applied correctly please click on Save button.

Make sure your API settings should look like this:

Obtaining required Connected App credentials

8. Obtain Consumer Details.   After saving please identify the button Manage Consumer Detail located in the API (Enable OAuth Settings) section:

8.1.  Click on Manage Consumer Details.  Obtain your consumer details by clicking the button.  You may need to verify your identity to go through this step with a code that is sent to the email associated with your Salesforce login:

8.2. Obtain credentials.   Please copy your Consumer Key and Consumer Secret using the copy buttons:

Please keep these credentials handy as they will be needed for the XCALLY side configuration.

Obtaining required Salesforce account credentials

9. Obtain Salesforce account Security Token.   Now is time to obtain the last required credential. 

9.1. Switch to Classic interface.  The best way to do this is by switching to Classic interface.  Please click on the Salesforce icon ( ) at the top right and then identify the Switch to Salesforce Classic option:

9.2. Look for Account Personal Settings.  To do this identify your Login name at the top bar:

Now click on your Login name and then on My Settings:

As a result you will see a screen similar to this:

9.2. Reset Security Token. Click on Personal menu to obtain a series of new options including Reset My Security Token:

NOTE: If you don't see the option Reset My Security Token then most likely the Salesforce Administrator has enabled a Whitelist or Trusted IP list and you are connecting from one of the trusted IP addresses in that list;  Salesforce won't show you this option as you are connecting from a trusted network.

In order to access Reset My Security Token feature the simplest way is to access the URL directly.  For that simply add the following string to your current Salesforce URL:

/_ui/system/security/ResetApiTokenEdit

For example:

https://mycompany.salesforce.com/_ui/system/security/ResetApiTokenEdit

This will result in the following web page:

Click on Reset Security Token and follow the instructions. You will receive an email with the actual security token:

Conclusions

By following these guidelines you'll have achieved what's needed to configure your XCALLY Salesforce integration account:

• The connected app's Client ID
• The connected app's Client Secret
• The Salesforce account's Security Token

Next you can follow the additional steps in the XCALLY Salesforce integration to add the Call Center Adaptor, the XCALLY Salesforce Integration configurations and the Trigger.