Salesforce

Overview

To define the ipSCAPE Call Centre in Salesforce, follow these steps:

1. Create a Call Centre

A ‘Call Centre’ in Salesforce corresponds to a single instance of a CTI system at your organisation. To create a ‘Call Centre’ for the ipSCAPE CTI adaptor:

• Download the relevant XML file for Salesforce Classic or Lightning

Classic.xml

Lightning.xml

• In Salesforce, from Setup, enter Call Centres in the Quick Find box, then select Call Centres

• If the Introducing Salesforce CRM Call Center splash page appears, click Continue

• Click Import

• Next to the Call Center Definition File field, click Browse to navigate to the ipSCAPE Call Centre definition file that you downloaded in Step 1. Click Open to enter the path in the Call Center Definition File field

• Click Import

• Click Edit next to the name of the new call centre to make any additional changes
  

2. Configure

Several parameters should be added to the CTI Adaptor URL field to point the CTI Adaptor to your Cloud Contact Centre tenant and enable the Salesforce Integration features:

Example CTI Adapter URL with all parameters:

Classic:

https://ctiadaptor.ipscape.com.au/?api=yourorg.ipscape.com.au&apiKey=6T8D%v#k9S7c&integrationType=sf

Lightning:

https://ctiadaptor.ipscape.com.au/?api=yourorg.ipscape.com.au&apiKey=6T8D%v#k9S7c&integrationType=sf&integrationVersion=lightning

ipSCAPE Settings

You can configure the behaviour of the CTI Adaptor to suit your Salesforce environment and usage by changing the value of the fields in the ipSCAPE Settings section of the Salesforce Call Centre.

3. Assigning users

Salesforce users must be assigned to a call centre before they can use a Softphone.

To assign users to a call centre:

• From Setup, enter Call Centres in the Quick Find box, then select Call Centres

• Click the name of the call centre to which you want to assign users

• In the Call Center Users related list, click Manage Call Center Users

• Click Add More Users

• Specify criteria to find the users who should be assigned to the call centre

• Click Find. All users who already belong to a call centre are excluded from search results because a user can only be assigned to one call centre at a time

• Select the checkbox next to each user who should be assigned to the call centre and click Add to Call Centre

To change a user’s call centre: first, remove from their current call centre assignment and then add to the new call centre.
You can view a user’s call centre assignment on the User detail page

4. Customising Softphone Layouts

Similar to page layouts, you can design custom Softphone layouts and assign them to call centre users based on their user profile.

To define a custom Softphone layout:

• From Setup, enter Softphone Layouts in the Quick Find box, then select Softphone Layouts.

• Click New.

• In the Name field, enter a label that uniquely identifies your layout.

• In the Select Call Type pick list, choose the type of call for which the currently displayed Softphone layout should be used. A single Softphone layout definition allows you to specify different layouts for inbound, outbound, and internal calls.

• In the Display these call-related fields section, click Edit to add, remove, or change the order of fields that are directly related to a phone call, such as the number of the caller or the number that was dialed.

• In the Display these Salesforce objects section, click Add/Remove Objects to add, remove, or change the order of links to call-related objects.

• Below the list of selected objects, click Edit next to each If single <Object> found, display row to specify the fields that should be displayed if a single record of that type is the only record that is found.

• In the Screen Pop Settings section (for inbound call types), click Edit next to each type of record-matching row to specify which screens should display when the details of an inbound call match or don't match existing records in Salesforce. The following table describes each record-matching row and its screen pop options:

Existing browser window 

New browser window or tab 

Don't pop any screen 

Pop to new

Pop to Visualforce page 

Don't pop any screen 

Pop detail page 

Pop to Visualforce page 

Don't pop any screen 

Pop to search page 

Pop to Visualforce page 

• Configure layouts for any remaining call types in the Select Call Type list

• Click Save

• To assign a custom Softphone layout to a user profile:

• From Setup, enter Softphone Layouts in the Quick Find box, then select Softphone Layouts

• Click Layout Assignment

• For each user profile that appears on the page, select the Softphone layout that the profile should use.

• Click Save

Profiles are only listed on this page if they include users that are currently assigned to a call centre, or if they have already been assigned a custom Softphone layout. The number in parentheses shows the number of call centre users who are assigned to that profile

5. Configure Salesforce Lightning App

Once you have configured your Salesforce Call Centre, you will need to make sure that you have a Lightning App configured with a CTI Softphone.

To configure Salesforce Lightning Apps with a CTI Softphone:

• From Setup, enter App Manager in the Quick Find search box.

• Select the Lightning App from the list displayed in the App Manager and click Edit from the dropdown

• Navigate to Utility Items (Desktop Only)

• Click Add New Utility Item and select Open CTI Softphone from the list
  

  

• Edit the label and properties if required and click Save
  

  

• To check the phone was configured correctly, navigate to the Salesforce Lightning page that was configured and the CTI should be visible
  

  

•  For instances where CTI is required for multiple Salesforce Apps (E.g. Sales, Service, Marketing), repeat steps 2-6

6. Add ipSCAPE fields to Salesforce manually

ipSCAPE fields can be mapped to two different types of Salesforce field:

1. Standard - these fields already exist in your standard Salesforce. The fields in the table below are already mapped, select the ones you need in The 'Task Page Layout' to use them

2. Custom - these fields need to be manually created in Salesforce and mapped using details in the second table below

To make your fields visible to the end-user you need to add them to the Task Page Layout'. To do that follow these steps:

• For Salesforce Classic:

  • Go to the Administration Setup Page in Salesforce

  • On the left-hand side of the Salesforce window, in the Build section, expand Customize and then Activities (Salesforce Classic)

  • In the expanded list of items, click Task Page Layout
    

• For Salesforce Lightning:

  • You will find your Salesforce data labels in Object Manager.

  • Select Task from the list of Objects.

  • In the left panel, navigate to Page Layouts and click Task Layout
    

• From the top panel drag and drop the fields you require into the Task Page Layout

If the standard fields are not mapped to the fields you want them to be or you want to use more ipSCAPE fields than those listed below you can use a custom settings file.

Standard Field Mapping 

 Custom Field Mapping

• For Salesforce Classic:

  • Go to the Administration Setup Page in Salesforce

  • On the left-hand side of the Salesforce window, in the Build section, expand Customize and then Activities

  • In the expanded list of items, click Activity Custom Fields. Activity Fields appears
    

• For Salesforce Lightning:

  • You will find your Salesforce data labels in Object Manager

  • Select Activity from the list of Objects

  • In the left panel, navigate to Fields & Relationships.
    

• Click New. The New Custom Field dialog box opens
  

• Choose a field type:

  • Date

    • Enter a Field Label,  e.g. "Due date".

    • Enter a Field Name, e.g. "Due_Date"

    • Enter a Description for the field, e.g. "This field displays the date when the call was answered."

    • Enter Help Text, e.g. "Set to the date of the call in the Agent's local time.."

    • Ignore the Required setting.

    • Ignore the Default Value setting.

    • Click Next
      .

  • Formula

    • Lightning Only:

      • Enter a Field Label,  e.g. "Link Call Recording".

      • Enter a Field Name, e.g. " Link Call Recording"

      • Select a Formula Return Type, click Next

    • Click the Advanced Formula tab.

    • Copy and paste the following code into the Call Recording Link (text) = field:
      

      IF(
      CallObject = " ", " ", HYPERLINK
      ("https://<tenant_URL>/workspace/home?view=voice_recording&sub=search&agntintrcn_id=" & CallObject, "Open Call Recording")
      )

      CODE

    • Enter a Description of the field, for future reference, e.g. "Displays a link to the call recording link in ContactWorld".

    • Enter the Help Text that appears alongside the field, e.g. "Click to access the call recording".

    • Click Next.
      

  • Number

    • Enter a Field Label,  e.g. "Time in Queue".

    • Set the Field Length to '18'.

    • Set the decimal places to '0'.

    • Enter a Field Name, e.g. "ipSCAPE_Time_in_Queue"

    • Enter a Description for the field, e.g. "This field displays the time the caller waited before the call was answered."

    • Enter Help Text, e.g. "The time in the queue."

    • Ignore the Required setting.

    • Ignore the Unique setting.

    • Ignore the External ID setting.

    • Ignore the Default Value setting.

    • Click Next.
      

  • Phone

    • Enter a Field Label,  e.g. "Customer Phone Number".

    • Enter a Field Name, e.g. "ipSCAPE_Customer_Phone_Number"

    • Enter a Description, e.g. "This is the phone number for the contact".

    • Enter Help Text, e.g. "Customer Phone Number".

    • Click Required. This is now a mandatory field. 

    • Enter a Default Value, e.g. "Customer Number".

    • Click Next.
      

  • Text

    • Enter a Field Label,  e.g. "Campaign Description".

    • Set the Field Length to '255'.

    • Enter a Field Name, e.g. "ipSCAPE_Campaign"  (the "_c" suffix is added by Salesforce)

    • Enter a Description for the field, e.g. "This records the campaign description, entered in the ipSCAPE Workspace campaign details, in the Salesforce record."

    • Enter Help Text, e.g. "Campaign Description"

    • Ignore the Required setting.

    • Ignore the Unique setting.

    • Ignore the External ID setting.

    • Ignore the Default Value setting.

    • Click Next.
      

• Establish field-level security

• Add to Task Page Layouts
  
  The SF Field Name is required to connect the CTI Adaptor to the Salesforce record. The "_c" is added by Salesforce.

If you are not adding custom mapping via a JSON file it is required to set up these ipSCAPE custom fields.
If the fields you require are not listed above you can in either the Standard or Custom fields you can add them using a Settings file in JSON format.

7. Add ipSCAPE fields using a JSON custom settings file

If data mapping is set using the JSON file, the Custom Field Mapping described in the previous section is not applicable  

The JSON file must be hosted on a publicly available host with CORS (Cross-origin-resource-sharing) enabled.

A custom settings file can be used to:

1. Map ipSCAPE fields to Salesforce Task Custom Fields beyond the standard mapping.

2. Assign a default ipSCAPE wrap code to all calls made and received using the CTI Adapter which is useful if you are using Salesforce wrap/outcome codes rather than those in ipSCAPE

3. Alter the display settings for the CTI adaptor so that agents only view what is relevant to the task at hand.

4. Have additional control over which records are popped in Salesforce when managing calls

Here is an example of the settings file format. You need to modify this to include the mappings and settings you require. Take note of the ipSCAPE fields you would like to map to Salesforce custom fields from the list below: 

Sample JSON File

{
  "map": {
    "transfer": {
      "ipSCAPE_queueTime__c": "timeInQueue",
      "ipSCAPE_campaign__c": "campaignTitle"
    },
    "outbound": {
      "ipSCAPE_campaign__c": "campaignTitle"
    },
    "inbound": {
      "ipSCAPE_bookingId__c": "bookingId",
      "ipSCAPE_queueTime__c": "timeInQueue",
      "ipSCAPE_campaign__c": "campaignTitle"
    },
    "default": {
      "ipSCAPE_callEnd__c": "callEndedDate",
      "ipSCAPE_callStart__c": "callStartedDate",
      "phone__c": "customerPhoneNumber",
      "activity__c": "activityId",
      "activityOrigin__c": "'ipSCAPE'",
      "CallCenter__c": "platformPhoneNumber",
      "agent__c": "agentFullName"
    }
  },
  "settings": {
    "disablePaymentsBtn": "true",
    "defaultWrapCode": null,
    "displayWrapCodes": "true"
  },
  "tabs": {
    "call": {
      "display": true,
      "index": 1,
      "title": "Call",
      "campaignInfo": true,
      "relatedObjects": false,
      "notes": true
    },
    "info": {
      "display": true,
      "index": 0,
      "title": "Data",
      "objects": {
        "customData": true,
        "voiceRecordingId": true,
        "platformPhoneNumber": true,
        "customerPhoneNumber": true,
        "campaignTitle": true,
        "interactionId": true,
        "callType": true,
        "ivrData": {
          "display": true,
          "data": [
            {
              "param": "product",
              "label": "Product",
              "asTag": false,
              "outcomes": [],
              "class": ""
            },
            {
              "param": "priority",
              "label": "Priority",
              "asTag": true,
              "outcomes": [
                {
                  "text": "low",
                  "class": "label-success"
                },
                {
                  "text": "normal",
                  "class": "label-info"
                },
                {
                  "text": "high",
                  "class": "label-warning"
                },
                {
                  "text": "urgent",
                  "class": "label-danger"
                }
              ],
              "class": "label-default"
            }
          ]
        }
      }
    }
  },
  "screenPopConfig": {
      "default": {
        "ref": "nationalPhoneNumber"
      },
      "rules": [
        {
          "campaignId": 64,
          "search": false,
          "ref": "SFAccountId"
        },
        {
          "campaignId": 676,
          "search": false,
          "ref": "SFAccountId"
        },
        {
          "campaignId": 10,
          "search": false,
          "ref": "customerKey"
        },
        {
          "callType": "outbound",
          "search": false,
          "ref": ["customerKey", "SFLeadId"],
        },
        {
          "callType": "transfer",
          "ref": "internationalPhoneNumber"
        }
      ]
    }
  }
}

Data Mapping

This section explains the sample JSON file above.

The "map" object is used for data mapping. This literally maps data from the ipSCAPE call data to a Salesforce API named parameter that can then be recorded in a Salesforce activity/task.

The map object contains four sections containing a selection of key/value pairs.

• transfer - Only applies to transfer calls

• outbound - Only applies to outbound calls

• inbound - Only applies to inbound calls

• default - Affects all calls

The key/value pairs are the map. The key is a Salesforce API name and the value is a parameter name from the call data.

    "phone__c": "customerPhoneNumber"

In this example, the call data parameter "customerPhoneNumber" will be sent to Salesforce to be recorded in an activity/task field with the API Name "phone__c". 

The "__c" is added automatically by Salesforce when creating your data field.

The most common errors when debugging this data mapping usually relates to API names incorrectly recorded.

ipSCAPE Call Data includes the following:

campaignId

agentInteractionId

voiceRecordingId

customerPhoneNumber

nationalCustomerPhoneNumber

internationalCustomerPhoneNumber

platformPhoneNumber

campaignTitle

campaignTimezone

Australia/Sydney

callType

timeInQueue

recording

callStartedDate

callEndedDate

IVR Data

Data entered into the IVR by the caller for example entering a booking ID. This will be available in the call data and available for data mapping. In the call data it will be available as:

         { "bookingId": "987654321" }

Settings

The "settings" object contains three basic switches: 

ipSCAPE Field Name	Field Type	Description
disablePaymentsBtn CODE	boolean	Allow agents to use the "Make a Payment" button on the "Services” tab?
defaultWrapCode CODE	number	The default wrap code ID that should be preselected for all calls.
displayWrapCodes CODE	boolean	Display the "Choose a wrap code" select box? When this is hidden, a defaultWrapCode must be included for the campaign or the agent will be unable to close/wrap the call.

Tabs (Display Settings)

The "tabs" object is used for customising the CTI Adaptor display. This is split into two main sections:

ipSCAPE Field Name	Field Type	Description
display CODE	boolean	Display or hide the "Info" tab
index CODE	number	Sets the initial display order. Use "0" if you want this to open as the default tab.
title CODE	string	Sets the tab title.  The maximum screen width in some Salesforce views in only 250px. It is advised to configure this below the maximum screen width of your instance.
campaignInfo CODE	boolean	Display/hide the campaign title for agents to see.
relatedObjects CODE	boolean	Display/hide the related objects select boxes.
notes CODE	boolean	Display/hide the notes field.

ipSCAPE Field Name	Field Type	Description
display CODE	boolean	Display or hide the "info" tab
index CODE	number	Sets the initial display order. Use "0" if you want this to open as the default tab.
title CODE	string	Sets the tab title.  The maximum screen width in some Salesforce views in only 250px. It is advised to configure this below the maximum screen width of your instance.
Objects
customData CODE	boolean	Display/hide the custom data parameter value.
voiceRecordingId CODE	boolean	Display/hide the voice recording ID.
platformPhoneNumber CODE	boolean	Display/hide the number the caller dialled in.
customerPhoneNumber CODE	boolean	Display/hide the customer phone number.
campaignTitle CODE	boolean	Display/hide the campaign title.
interactionId CODE	boolean	Display/hide the unique ID for the agent leg of the call.
callType CODE	boolean	Display/hide the call type [Inbound, Outbound, Transfer]
ivrData CODE		Contains formatting to display data entered into the IVR by the caller.

IVR Data can be displayed as a tag as illustrated in the red box drawn on the screenshot above, or displayed in a tabular format.

To display as a tag you would need to add the format to the JSON inside the "ivrData" block. This would look like the example JSON. In this example, we are displaying a parameter "priority" that has four possible values (low, normal, high, urgent). These values will be displayed as a tag and will be colour-coded by adding a class to the tag.

• "label-success" is displayed with a green background

• "label-info" is displayed with a blue background

• "label-warning" is displayed with a yellow background

• "label-danger" is displayed with a red background

Add Link to Salesforce Settings

• Open and log in to Salesforce.

• Click Setup to go to the Administration Setup Page.

• In the left-hand side of the Salesforce window, in the search box, enter "Call Centers". Call Centers will appear below the search box.

• Click Call Centers. The All Call Centers page opens. 
  

• Click EDIT the ipSCAPE call center 

• Enter the link to the JSON file you created in the Settings URL field

Modifying the Task Page Layout to include your Custom Fields

To make your fields visible to the end-user you may need to add them to the 'Task Page Layout'. To do that follow these steps:

• Go to the Administration Setup Page in Salesforce

• On the left-hand side of the Salesforce window, in the Build section, expand Customize and then Activities

• In the expanded list of items, click Task Page Layout

• From the top panel drag and drop the fields you require into the Task Page Layout

 Screen Pop Config

The screen pop configuration is designed to allow more control over the searchAndPop feature in Salesforce. Using this feature, admins have control over the behaviour in Salesforce when a call is allocated to an agent it can either: Directly pop a page using a Salesforce Id Perform a search in Salesforce Fall back to a default search based on the customer CLI The config is designed so that when a call is allocated, the CTI adaptor will read through the rules and attempt to find a match. Matches are possible on either a campaignId or a callType. The CTI will always follow the first matching rule, which is why the more generic "callType" rules should be included after any "campaignId" rules. If no matching rule is found, the CTI will fall-back to the default.

{ "callType": "outbound", "search": false, "ref": ["customerKey", "SFLeadId"], }, CODE A rule must contain either a callType or campaignId parameter. The search (boolean) parameter: True: The CTI will search Salesforce for the data (ref) False: The CTI will pop the page using the data (ref) The default is search equals true. ref: This is pointing to the parameter from the ipSCAPE call data that you wish to use. The ref can be either a single string parameter or an array of strings. In the case where it is an array, the default behaviour is to return the first matching data.

{ "leadId":96, "agentInteractionId":592, "campaignId":2, "phoneNumber1":"+61283213004", "phoneNumber2":null, "phoneNumber3":null, "autoPreviewTime":0, "leadTimezone":"Australia/Sydney", "campaignTimezone":"Australia/Sydney", "customerKey":"0010I00001yF2zq", "customData":{ "SFLeadId":"", "Address":"99 Test St", "City":"Sydney", "Name":"Test Client2", }, } CODE

Using the example configuration and data above, the CTI adaptor will, when it receives an allocated call where the callType = outbound, search through the allocated data for a parameter that matches the ref. As the ref is an array with two options, firstly it will look for the the customerKey, then the SFLeadID.  In this example it will find the match on the customerKey and as the search parameter is false, it will call Salesforce with a request to pop a page with the corresponding value.

Screen Pop using Lead Information

Currently, when using the CTI Adaptor with Salesforce, the system displays the customer details in Salesforce based on a CLI search in Salesforce. 

This section will describe how you can use Lead information to display the customer details. This is especially useful when multiple accounts exist in Salesforce for the same Customer. At present, when using the CTI Adaptor, if the CLI exists on multiple accounts, the agent is presented with a Salesforce search screen. listing multiple accounts. The Agent then identifies which account they should be working on.

This feature will enable you to specify the field to be used to search and present the Agent with the correct account.

To configure this option in Salesforce requires a change to the JSON file. A sample of the JSON file can be found below:

"screenPopConfig": {
    "default": {
      "ref": "nationalCustomerPhoneNumber"
    },
    "rules": [{
        "campaignId": 64,
        "ref": "accountName__c"
      },
      {
        "campaignId": 676,
        "ref": "accountId"
      },
      {
        "campaignId": 10,
        "search": false,
        "ref": "customerKey"
      },
      {
        "callType": "Outbound",
        "search": false,
        "ref": "customerKey"
      },
      {
        "callType": "Transfer",
        "ref": "taskId"
      }
    ]
  }

The default object is used in the event that the conditions do not match any of the given rules. As such, the ref should be global (i.e. present in all call types.)

The rule parameters are as follows:

• "callType" can be one of (Inbound, Outbound, Transfer)

• "search" by default this is true. When set as false, the CTI will attempt a 'screen pop' without searching. 

• "ref" is the key used for matching the data in the call or lead.

• "campaignId" is used when the rule only applies to a specific campaign.

When adding campaign rules, you should make sure that these are included before the "callType" rules as screen pop will be done on the first matching rule.

All values are case-sensitive. 

8. Salesforce Views and Permissions

There are different ways of viewing Salesforce, such as Sales or Console views. For this section, Sample Console will be used as an example.

To view in Salesforce Classic- In the top right-hand corner of Salesforce, from the App Menu, select Sample Console.

To view in Salesforce Lightning- In the top left-hand corner of Salesforce, from the App Menu icon, click to search for and select Sample Console.

If you do not see the view in the App Menu, it is because it has not been made visible to your user Profile.

Each user in Salesforce is given a Profile that defines what they see and can do as they navigate through the system. To make the Sample Console visible you need to go to the profile that has been applied to your User and edit the settings following these steps:

• Open Salesforce with an account that has admin rights

• Go to Setup in the top right-hand corner

• In the Quick Search bar to the left of the screen type in Profiles and select Administer>Manage Users>Profiles

• Select and open the relevant Profile and click Edit

• In the Custom App Settings check the column called Visible for Sample Console (standard__ServiceConsole) and click Save

• Log out and log back in again and you will be able to see the Sample Console option in the App Menu using the steps above.
  

ipSCAPE is aware of instances where customers have experienced issues with data fields that are caused by incorrect field permission configurations. Agents need to be granted access to the data fields that are modified when updating tasks.
If you are experiencing any issues, please review the data field permissions prior to contacting ipSCAPE Support.