Salesforce Extension Customization Guide

Transcription

1 Salesforce Extension Customization Guide

2 Title Salesforce Extension Customization Guide Revision Contributors Purpose About incontact Copyright Disclaimer Namitha Nayak; Sean A. Bangerter This document provides a detailed explanation on the process for customizing the Salesforce Extension, including controlling screen pops, creating custom buttons, handling workitems, preventing changes to the agent state, and automatically logging out of incontact. incontact, Inc. (NASDAQ: SAAS) has helped over 750 contact centers around the globe create profitable customer experiences through its powerful portfolio of cloud-based contact center software solutions. The company s services and solutions enable contact centers to operate more efficiently, optimize the cost and quality of every customer interaction, create new pathways to profit, and ensure ongoing customer-centric business improvement and growth. The incontact Platform has grown from a powerful ACD with skills-based routing, CTI, and IVR with speech recognition to include an innovative online hiring solution, workforce management functionality, and a customer feedback and survey solution. Because the incontact Platform is delivered through a Software-as-a- Service (SaaS) model, incontact customers can realize significant cost savings and flexibility compared to premises-based alternatives. To learn more, visit incontact, Inc. InContact reserves the right to update or append this document, as needed incontact, Inc. - "incontact" is a registered trademark of incontact Inc., "intouch", "incontrol" and related logos are trademarks of incontact, Inc. All other registered and unregistered trademarks are the sole property of their respective owners. 4/12/2013

3 Contents Controlling Screen Pops... 1 Phase I: incontact receives a call... 1 Phase II: The call is delivered to an agent... 2 Phase III: The Salesforce Extension performs a query... 2 Salesforce.com Softphone Layout Settings... 3 Default Query... 4 Controlled Query... 4 Phase IV: The Extension pops (opens) a page... 6 Example 1: No Match... 7 Example 2: Single Match (a case is found)... 7 Example 3: Multiple Matches... 8 The Search Results Page... 8 Creating Custom Buttons... 9 WorkItem handling Prevent Agent State Change Auto Logout from incontact... 12

4 CONTROLLING SCREEN POPS When a call is delivered to an agent, the Salesforce Extension performs a query and attempts to pop a screen. The extension performs two types of queries: 1 A default query A controlled query In either case, once the query is complete, the extension may attempt to pop an appropriate screen (depending on configuration settings it may not attempt to pop any screen, if it s so configured). The Salesforce Extension controls both default and controlled queries through a combination of special incontact script variables known as query control variables and configuration settings in the Salesforce Softphone Layout. The results of the query control the actual screen pops, combined with configuration settings found in the Salesforce Softphone Layout and optionally the Extension Configuration Document (see the Installation and Configuration Guide for details). A screen pop has four phases: 1) The incontact IVR/ACD system receives a call. 2) The system delivers the call to an agent (possibly with optional query control variables). 3) The Salesforce Extension performs a query (either default or controlled, depending on variables). 4) The Salesforce Extension pops (opens) a page (unless configured to pop nothing). Each of these phases is described below: Phase I: incontact receives a call When a call routed to the incontact system, incontact will begin running an IVR script, which can be designed to acquire data about the call or the caller in many ways, including: Retrieve DTMF or ASR (Automatic Speech Recognition) input from the caller Query external systems such as Salesforce.com via Web Services Perform database lookups both in the incontact system and external database systems Perform calculations on data retrieved by any of the above methods Data acquired by the script using any of these methods can be assigned to variables in the script (see the ASSIGN action under the incontact Studio documentation found at for more details.) In addition to their name and their value, script variables have a variety of other properties that can be set. Among them is the ScreenPop property (a Boolean true/false property). Setting a variable s ScreenPop property to true causes the variable, with its name and value, to be delivered to the agent workstation along with other metadata about the call. NOTE: The Use Screen Pops property must be set to true on the skill (in the Central website) to which the call is queued. In addition, the REQAGENT script action which actually queues the call must have the ScreenPopSource property set to Default from Skill. If these settings are not configured properly, script variables will NOT be delivered to the agent workstation. Details about these

5 configuration settings are found below and in the Salesforce Extension Installation and Configuration Guide. Query control variables are identified by their name. There are two variable names that identify a variable as a query variable : sfdc# (where # is a digit from 0-9) sfdcquery# (where # is a digit from 0-9) NOTE: Refer to Phase III: The Salesforce Extension Performs a Query in this document for information on how to use these query variables. Also, you do not have to create and send query variables in order for the Salesforce Extension to perform a query. If no query control variables have been published, the Salesforce Extension will perform a default query (as described in the Phase III section below. Phase II: The call is delivered to an agent When the incontact ACD system selects an agent to whom the call will be routed, the voice path for the call is delivered to the agent s telephone, and information about the call is delivered to the agent s workstation. A certain number of default values about the call are always delivered to the workstation. In addition to these values, any script variables with a ScreenPop property set to True are sent to the workstation (assuming the skill in Central and the REQAGENT action are both configured properly.) When the call is delivered to the agent, the Salesforce Extension will do two things with the script variables (if any are published): Certain variables will be used to control the screen pop query (i.e. what to search for). All variables will be stored in a custom field on the User object, where they can be accessed and used by custom JavaScript or custom Apex/VisualForce pages from within Salesforce.com. After the call and its metadata and variables are delivered to the agent, the Salesforce Extension will perform a query (either a default query, or if query control variables are published, a controlled query.) Phase III: The Salesforce Extension performs a query When the Salesforce Extension receives the call, it performs a query for objects in Salesforce. The two types of queries that the extension may perform are: A default query A controlled query If the IVR script publishes any query control variables, then a controlled query is performed. Otherwise, a default query is performed. Both of these types of queries depend on the Softphone Layout settings in Salesforce.com. 2

6 Salesforce.com Softphone Layout Settings The Softphone Layout settings in Salesforce.com specify information that is available to CTI Toolkit applications like the incontact Salesforce Plugin Agent Extension. Some of the settings apply to the default softphone that is displayed by default by CTI Toolkit integrations (hence the name). Use the Softphone Layout settings to configure the following items: Objects to search for on an inbound call Actions to take once the query is complete, based on whether 0, 1, or <1 matches were found Fields to display in the softphone that is provided by default CTI Toolkit integrations when a single match is found The Salesforce Extension uses the first and second settings. Because the Salesforce Extension doesn t use the default CTI Toolkit softphone, the third set of settings do not apply to the incontact Salesforce Extension. Objects to Search The Softphone Layout settings allow you to specify what types of objects are searched in a default query (see below). In addition, you can specify what actions to take once the query is complete. These settings are more fully described below under Phase IV: The Salesforce Extension pops (opens) a page. When the query is complete, one of three things will have happened: No matches were found A single match was found Multiple matches were found The Softphone Layout settings allow you to configure what action to take in each scenario: No matches were found o Do nothing o Pop a new [object] page ( [object] can be configured) o Pop a custom VisualForce page A single match was found o Do nothing o Pop the details page of the single found object o Pop a custom VisualForce page Multiple matches were found o Do nothing o Pop the search results page (which may contain results of various types) o Pop a custom VisualForce page The behavior of the page pop in each of these scenarios is described below in the section labeled Phase IV: The Salesforce Extension pops (opens) a page. 3

7 Default Query If no query variables are sent to the extension with the call, then the extension will perform a default query. The default query is a SOSL search (Salesforce Object Search Language SOSL is a simplified query language for Salesforce.) In a default query, the extension will search for the caller s ANI (caller ID phone number) in any phone fields in objects identified in the Softphone Layout settings. NOTE: Phone fields refers to any field that is of type Phone. If the Softphone Layout settings specify that contacts and accounts should be searched, then in a default query, all phone fields for all contacts and accounts will be searched for the caller s ANI. The results will be shown according to the Softphone Layout settings (see Phase IV in this document.) Controlled Query If any query variables (see above) are sent to the extension with the call, then they will control how the extension performs the query. There are two types of query variables that can be used by the extension: 4 sfdc# variables (where # is a digit from 0-9) sfdcquery# variables (where # is a digit from 0-9) sfdc# variables The sfdc# variables are used to identify portions of the query. They must be named sfdc0-sfdc9, and there can be a maximum of 10 of them (per their names). Sfdc# variables have a specific syntax: object.field>value This syntax specifies that the object, field, and value should be part of the query. If there are multiple sfdc# variables, they are combined into a single query. Example 1: Suppose the following variables are sent from the IVR script: sfdc0=case.priority>high sfdc1=case.isclosed>false sfdc2=case.contactid> bbl3 The extension will then perform the following SOQL query: SELECT id FROM case WHERE priority=high AND isclosed=false AND contactid= bbl3 This would query for all open, high priority cases belonging to a specific contact in Salesforce. Example 2: Suppose the following variables are sent from the IVR script: sfdc0=case.priority>high sfdc1=case.isclosed>false sfdc2=case.contactid> bbl3 sfdc3=activity.whoid> bbl3 The extension will then perform the following two SOQL queries:

8 SELECT id FROM case WHERE priority=high AND isclosed=false AND contactid= bbl3 SELECT id FROM activity WHERE whoid= bbl3 This would query for any open, high priority cases belonging to a specific contact, AND for any activity history records belonging to that same contact. NOTE: sfdc# variables are grouped based on the object identified in the variable, and that sfdc# variables applying to the same object type are strictly combined as AND queries (i.e. all conditions must be true for a match to be found.) For more complex queries, you can use the sfdcquery# variable. sfdcquery# variables Up to 10 sfdcquery# variables can also be passed from the IVR script. sfdcquery# variables are much simpler than the sfdc# variables. Each sfdcquery# variable is a simple string that specifies a full SOQL query. Each sfdcquery# query is completely independent. If the Softphone Layout configuration is set to display a search results page when there are multiple matches, and each sfdcquery# variable specifies a different query that returns one or more matches, then all of the matches will be combined into a single results page. In addition, if both sfdcquery# and sfdc# variables are sent from the script at the same time, then both will be used to perform queries. Example 1: Suppose the following variable is published from the IVR script: sfdcquery0= SELECT id FROM opportunity WHERE accountid= vkcu9 This would result in the following query: SELECT id FROM opportunity WHERE accountid= vkcu9 This would query for any opportunity records assigned to the identified account. Example 2: Suppose the following variables are published from the IVR script: sfdcquery0= SELECT id FROM opportunity WHERE accountid= vkcu9 sfdcquery2= SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false The following queries would be executed: SELECT id FROM opportunity WHERE accountid= vkcu9 SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false This would query for any opportunites assigned to the account, AND for any OpenActivity objects that are not closed, and that are assigned to the account. The results from both queries would be displayed. 5

9 6 Example 3: Suppose the following variables are published from the IVR script: sfdc0= case.priority>high sfdc1= case.isclosed>false sfdc2= case.contactid> bbl3 sfdc3= activity.whoid> bbl3 sfdcquery0= SELECT id FROM opportunity WHERE accountid= vkcu9 sfdcquery2= SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false Then the following queries would be performed: SELECT id FROM case WHERE priority=high AND isclosed=false AND contactid= bbl3 SELECT id FROM activity WHERE whoid= bbl3 SELECT id FROM opportunity WHERE accountid= vkcu9 SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false This would query for any high priority and open cases for the identified contact, as well as any activity records assigned to the contact, and all opportunity records assigned to the identified account, as well as all openactivity records that are not closed, that are assigned to the identified account. Any results would be displayed based on the Softephone Layout settings. Phase IV: The Extension pops (opens) a page After the extension performs a query, it will determine what page to open (if any) based on two things: The results of the query (queries if there are multiple) The settings in the Softphone Layout settings in Salesforce.com Refer to Salesforce.com Softphone Layout Settings in this document for more details on the Softphone Layout settings. Whether a controlled query was performed, or the default query, one of three things will have occurred: No matches were found A single match was found Multiple matches were found The Softphone Layout Settings specifies what kind of pop should occur in each scenario: No Matches o Do nothing o Pop a create [object] page ( [object] can be customized) o Pop a custom VisualForce page Single Match o Do nothing o Pop the details page of the found object

10 o Pop a custom VisualForce page Multiple Matches o Do nothing o Pop the search results page containing the matches o Pop a custom VisualForce page Regardless of the type or number of queries performed, the Salesforce Extension will pop a page based on the corresponding Softphone Layout setting. Suppose the following variables are published from the IVR script: sfdc0= case.priority>high sfdc1= case.isclosed>false sfdc2= case.contactid> bbl3 sfdc3= activity.whoid> bbl3 sfdcquery0= SELECT id FROM opportunity WHERE accountid= vkcu9 sfdcquery2= SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false Then the following queries would be performed: SELECT id FROM case WHERE priority=high AND isclosed=false AND contactid= bbl3 SELECT id FROM activity WHERE whoid= bbl3 SELECT id FROM opportunity WHERE accountid= vkcu9 SELECT id FROM openactivity WHERE accountid= vkcu9 AND isclosed=false Suppose that the following settings are set in the Softphone Layout: No Match: Open a new contact page Single Match: Open the details page Multiple Match: Open the search results page Example 1: No Match If all four queries return no matches, the Salesforce Extension will open a new contact page, because in the Salesforce Softphone Layout Settings, the No Match scenario is configured to create a new object. NOTE: Because the Salesforce API doesn t allow the Salesforce Extension to read the name of the object type you want to create in a No Match scenario, you must add a configuration setting in the Extension Configuration Document to indicate what type of object to create (in this case, Contact ). For example: <profile id= _default > <SoftphoneLayoutSettings> <NoMatch>Contact</NoMatch> </SoftphoneLayoutSettings> </profile> Example 2: Single Match (a case is found) If the first query returns a single result, and the other three queries return no results, then the Single Match scenario will be handled. In this case, a single case is found. The single case will be opened to 7

11 the details page because the Salesforce Softphone Layout Settings is configured to open the details page of a single match. Example 3: Multiple Matches If any one of the queries returns more than one result, or if any two or more of the queries return one or more results, then the Multiple Matches scenario will be handled. In this case, the Softphone Layout is configured to open the search results page. For a default query, a built-in Advanced Query Results page will be opened by Salesforce. For a controlled query (as in this example), a custom search results page will be opened. This is a custom VisualForce page provided by incontact, which will show all of the items that were found in the query (or queries). See the Installation and Configuration guide for information about how to import and create this custom VisualForce page. The Search Results Page The Search Results Page that is included with the Salesforce Extension setup works differently from the traditional v3.x CTI Toolkit-based adapter. With the old adapter, if multiple matches were found, the adapter would pop an advanced search results page that is identical to the default search results the results are objects with phone fields that match the ANI (regardless of what queries were performed, or what actual matches were returned.) The old adapter will display the list of matching objects in the softphone. NOTE: The size of this list is limited, and a More link is provided if there are more items than are displayed. Clicking the More link will open the Advanced Search Results page with default search results matching the ANI to phone fields (rather than showing the full list of items that were actually found in the query that was performed.) The incontact Salesforce Extension behaves differently. If you select Show search page as the Multiple Matches action, and if the queries find multiple matches, a custom VisualForce page that is provided by incontact with the Salesforce Extension Admin package will be displayed. 8

12 CREATING CUSTOM BUTTONS With previous versions of the Salesforce Adapter, it was necessary to publish variables from the IVR script to display custom buttons to agents. These custom buttons could only be configured to display a specific URL, and were displayed in the Softphone canvas (removed from the layout page where the agent does their work.) With the new Salesforce Extension, we take a different approach. The approach is to make all of the call metadata and IVR script variables available to the Salesforce environment, so you can use Salesforce s built-in capabilities for creating custom buttons and other controls, and have them be driven and informed by data from the incontact system. Consider the following use case: Suppose you want a custom button that will create a new Case object, with certain fields pre-populated with data from the IVR script. With the old Salesforce Adapter, you would create a series of IVR script variables that describe the button, including its size, color, label, and the URL to pop when it is clicked. In addition, the button would show up far to the left (or at the bottom, if using the Service Cloud Console), removed from the Page Layout where the agent does their work. With the new extension, you would do the following: 1) Create a custom button and add it to your page layout (on the Contact object and page layout, for example). The button could be configured to Execute JavaScript : 2) Create code that is able to access incontact variables from the User.Custom_Screenpop c field. When a call is delivered to the agent, any variables that are published from the IVR script are stored as a pipe-delimited list in the User.Custom_Screenpop c field. The following code shows how to access the data in this field, and parse it into a collection of variable names and values for use in your JavaScript: {!REQUIRESCRIPT("/soap/ajax/20.0/connection.js")} // get the contents of the field var userval = "{!User.Custom_Screenpop c}"; // create an array that splits on the symbol var splitvals = userval.split(" "); // each element of the splitvals array will be in the // format of varname=value, where varname is the variable // name published from incontact. 3) Publish variables from the IVR script that you want to use in the JavaScript code. The following code shows how to take variables from the IVR script, and create a button that will create a new Case object, and pre-populate it with values from the script. {!REQUIRESCRIPT("/soap/ajax/20.0/connection.js")} var userval = "{!User.Custom_Screenpop c}"; var splitvals = userval.split(" "); 9 // this is the main URL that we will pop

13 // we will add a query string to it that auto-populates // values in the new case object. /500 means a case, // and /e means open in edit mode. These are // Salesforce conventions. var mainurl="/500/e?" // These are Salesforce field names that can be used on // the query string to prepopulate. cas4 // is the name of the accountname field on the // contact. cas3 is the contact name. The // other field names are for custom fields (such // as a product family lookup field, a field for // the incontact contact ID, the ANI, etc. // // Consult the Salesforce community for information about // the format of URL s that prepopulate field values on new // objects. var accountname="cas4=" var contactname="cas3=" var ani="00n ur4e=" var caseproductfamily="00n hmyh=" var contactid="00n wns6=" var type="cas11=phone" var finalurl="" function Begin() { // for each variable from the platform, // check to see if it s one of the variables // with a value we need to pre-populate. If // so, we should save its value and add it to // the appropriate variable, so we can build // the final URL. for (var i = 0; i < splitvals.length; i++) { var keyvalue = splitvals[i].split("="); } if (keyvalue[0].tolowercase()=="accountname") { accountname = accountname + keyvalue[1] } else if (keyvalue[0].tolowercase()=="contactname") { contactname = contactname + keyvalue[1] } else if (keyvalue[0].tolowercase()=="ani") { ani = ani + keyvalue[1] } else if (keyvalue[0].tolowercase()=="case_product_family") { caseproductfamily = caseproductfamily + keyvalue[1] } else if (keyvalue[0].tolowercase()=="contactid") { contactid = contactid + keyvalue[1] } // construct the final URL finalurl = mainurl + accountname + "&" + contactname finalurl = finalurl + "&" + ani + "&" + contactid finalurl = finalurl + "&" + caseproductfamily // this bit of code checks to see if we are running 10

14 } // in the Service Cloud Console if we are, we call // srcup() which opens the new case object in an SCC // tab. Otherwise, we just open the new case object. if (typeof(srcup) == 'function') { srcup(finalurl) } else { window.location=finalurl } Begin(); 11

15 WORKITEM HANDLING When a WorkItem is delivered and accepted by the agent, the Salesforce Extension will search for matching Case and attempt to pop open the case detail page. NOTE: The WorkItem type should be SFDC CASE (case insensitive) This search and pop can be controlled from the incontact script by using the query variables sfdc# and sfdcquery# as in the phone call controlled search. When the query variables are passed from incontact, then those variables control the screenpop, and the normal case popup does not happen. After the WorkItem is terminated, the Salesforce Extension will create the activity associated with the Case in the Related To field, and other fields as mapped in the Sfdc Config Utility tool. PREVENT AGENT STATE CHANGE If the agent is logged into incontact, and not logged into Salesforce,com, then the extension might prevent the agent from going available. This is controlled by the configuration setting labeled PreventAgentStateChange This setting can be turned on or off in the extension s configuration file (sfdcextension.dll.config), which can be found in the extension s installation directory. 12 <add key="preventagentstatechange" value="true"/> Similarly, when the user tries to log out of Salesforce.com. if the PreventAgentStateChange setting is set to True, the following will occur: a. If the Agent state is Available or ACW, then the state will be changed to Unavailable, and a message will be displayed - You have logged out of Salesforce.com. Your state has been changed to Unavailable. b. If the agent is on an active call, then the next state will be changed to Unavailable and a message will be displayed You have logged out of Salesforce.com while on an active call. Your after-call state has been changed to Unavailable. AUTO LOGOUT FROM INCONTACT If the agent logs out of Salesforce.com while logged into incontact platform, then the extension might require a log out, or have the state set to unavailable or logout based on the configuration setting labeled AutoLogoutCTI in the extension s configuration file. <add key="autologoutcti" value="false"/> When the user attempts to logout of Salesforce.com, if the AutoLogoutCTI is set the true, the following will occur: a. If the agent is in Available or Unavailable state, then the agent will be automatically logged out, and no message will be shown to user. b. If the agent is on an active call, then the next state will be changed to unavailable and a message will be displayed You have logged out of Salesforce.com while on an active call. Normally, logging out of Salesforce.com would also log you out of incontact.

16 13 Since you are on an active call, you will need to manually log out of incontact after your call ends. Your after-call state has been changed to Unavailable. c. If the agent is in after-contact-work, then the state will be changed to Unavailable and a message will be displayed You have logged out of Salesforce.com while in after contact work. Normally, logging out of Salesforce.com would also log you out of incontact. Since you are in after contact work, you will need to manually log out of incontact after your work ends. Your state has been changed to Unavailable.