USER GUIDE

SHORETEL SALESFORCE.COM CALL CENTER ADAPTER VERSION 4.X

Introduction
This document describes the installation, configuration and basic usage of the ShoreTel Salesforce.com Call Center Adapter version 4.x. The Adapter is a Microsoft Windows tray application which supports a web browser based SoftPhone run on each users desktop. This SoftPhone, not to be confused with a ShoreTel Communicator based SoftPhone, shows up in the users web browser when they are viewing Salesforce pages. It displays properties of the users active calls and has buttons which supports call control operations like answer and hold. Depending on configuration, it automatically displays the Salesforce entities like contacts and accounts that are associated with calls based on the callers phone number. It can be configured to automatically create call activity logs in Salesforce and have these call logs associated with the related Salesforce entities. Note that while this product is called the Call Center adapter, in point of fact it is fully usable for non-call center agents. Most of the value of the adapter involves the rapid lookup of Salesforce information related to calls, which is independent of whether the user is an agent or not. The only call center specific feature it provides is a drop down setting which is part of the SoftPhone user interface. Thissetting allows ShoreTel Workgroup agents to change their status to available or unavailable for Workgroup calls or to take themselves in or out of wrap up. If the user isnt a ShoreTel Workgroup agent then they can hide this control. Note that while this application works well ShoreTels Enterprise Contact Center, the agent control only supports ShoreTel Workgroups so Contact Center users will likely want to hide the control.

Important Upgrade Notice!

If you are upgrading from any version prior to 4.x, note that in addition to shutting down and uninstalling the client on each users desktop and then installing the updated version, you MUST also perform the steps detailed below in the Installation section on creating the Call Center and associating it with the user(s) running the upgraded client. Specifically: Import the updated ShoreTelCTIAdapter.xml. This will create a new Call Center adapter definition named ShoreTel Adapter for SF Call Center Version 4.x. Change the users call center assignment from their current version to the new 4.x version. If users running the new 4.x version of the client software are still assigned to the previous version call center definition in Salesforce then they will see this error when they start their client: The CTI stylesheet x.x you are using is incompatible with call center 4.0.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 1 of 35

Table of Contents
Introduction .................................................................................................................................................. 1 Important Upgrade Notice! ...................................................................................................................... 1 Requirements................................................................................................................................................ 4 Browser Versions .......................................................................................................................................... 4 Installation .................................................................................................................................................... 4 1) 2) 3) 4) 5) Installing the ShoreTel Application Licensing Server ........................................................................ 5 Adding the ShoreTel Salesforce.com Call Center Adapter license to the Licensing Server .............. 5 Create the Call Center in Salesforce ................................................................................................. 5 Associating Users with the ShoreTel Call Center Adapter ................................................................ 6 Installing Clients ................................................................................................................................ 7

Usage........................................................................................................................................................... 10 Starting the Adapter................................................................................................................................ 11 Adapter Tray Icon Menu ......................................................................................................................... 13 Exploring the SoftPhone Layout.............................................................................................................. 14 ShoreTel Workgroup agent status ...................................................................................................... 15 Phone line header ............................................................................................................................... 16 Call information .................................................................................................................................. 16 Call button area................................................................................................................................... 16 Current Call Log ................................................................................................................................... 16 Last three calls display ........................................................................................................................ 16 My Calls Today report link .................................................................................................................. 16 ShoreTel logo ...................................................................................................................................... 17 Using the SoftPhone ............................................................................................................................... 17 Specifying Personal SoftPhone Settings .................................................................................................. 17 Automatically log in to your call center when logging into salesforce.com ....................................... 17 If only one record found on incoming call .......................................................................................... 17 Administrative Configuration...................................................................................................................... 18 Customizing SoftPhone Layouts .............................................................................................................. 18 Previewing SoftPhone Layouts............................................................................................................ 21 Assigning SoftPhone Layouts to Users .................................................................................................... 21 Adding Directory Numbers ..................................................................................................................... 21
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 2 of 35

Appendix A: Frequently Asked Questions................................................................................................... 23 What versions of Salesforce support the ShoreTel adapter? ................................................................. 23 What changes were made in Version 4.0? ............................................................................................. 23 Are there best practices for working with the adapter? ........................................................................ 23 Why do I get an error saying License Failed: when the client starts?.............................................. 23 Can I run the Softphone in different browsers at the same time (IE + FF + Chrome)?........................... 24 Why am I getting a big red error message saying "500 stream:1: XML file has no top-element. All wellformed XML files have a single top-level element."? ............................................................................. 24 I receive a "Do you want to view only the webpage content that was delivered securely" Security Warning in Internet Explorer as shown here: ......................................................................................... 25 Do I need HTTPS with the CTI Adapter?.................................................................................................. 25 Is there a way I can try the adapter if I dont have a Salesforce.com account? ..................................... 26 Why isn't my Softphone showing?.......................................................................................................... 26 Why isn't the agent area of the Softphone showing? ............................................................................ 26 Softphone shows "Line (xxx) not found"?............................................................................................... 26 Why does my Softphone show "Line xxx unconnected" or "Line xxx out of service"? .......................... 26 Softphone shows "ShoreTel COM object STMLControl.dll not registered or not found"? .................... 26 Why isnt the bowser going to the Salesforce entity associated with an offering call? ......................... 27 Browser isnt allowing me to navigate when a call is presenting? ......................................................... 27 Why does my browser cycle between two pages? ................................................................................. 27 Appendix B: Configuring HTTPS for a CTI Adapter ...................................................................................... 28 Adding HTTPS to a Call Center ................................................................................................................ 28 Adding HTTPS to CTI Adapters ................................................................................................................ 28 Creating and Installing a Security Certificate .......................................................................................... 29 Appendix C: Application Integration Features ............................................................................................ 31 Displaying Call Related Records .............................................................................................................. 31 Handling Attached Data .......................................................................................................................... 31 Passing Data from Enterprise Contact Center ........................................................................................ 32 Examples of Attached Data Search Queries............................................................................................ 32 An Example Using the COM SDK ............................................................................................................. 33 Using the COM SDK Browser to Pass Salesforce.com Properties ........................................................... 34

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 3 of 35

Requirements
The Adapter requires the following: PC running Microsoft Windows XP or later. Note that at this time Salesforce does not provide a CTI interface that works on Apple or other operating systems. Microsoft .NET 3.5 runtime. If not already installed, the installation program will direct the user to the Microsoft web site for installation. ShoreTel Communicator Client. The client needs to have been installed for the ShoreTel Adapter to function. It does not need to be running. We expect that this connector should work fine with earlier versions of ShoreTel's software. Specifically ShoreTel 7.0 should work without problems and earlier versions may do too. The ShoreTel Application Licensing Server must be installed and either a trial or permanent license key for the Salesforce.com Call Center Adapter must be added.

Browser Versions
Version 4.x is now browser agnostic for HTML5 compatible browsers as long as they support local storage and post messages. This includes: Internet Explorer version 8 and later. Firefox version 3.5 and later. Chrome version 10 and later.

While we do support IE8, and Firefox 3.5 performance is significantly improved in browsers like these which are recommended: Internet Explorer version 9 or later. Firefox 5 or later. Chrome 13 or later.

Note: If you are running Internet Explorer and receive warnings which say Do you want to view only the webpage content that was delivered securely when using the browser and want to avoid them then see the question in the Frequently Asked Questions Appendix.

Installation
To get the adapter working on a users desktop there are several procedures that need to be followed. Installing the client by running the client setup program is not, in and of itself, sufficient for the client to function. There are several steps required to getting the Adapter installed and working: 1) Install the ShoreTel Application Licensing server on the customers ShoreTel Headquarters server.
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 4 of 35

2) Add ShoreTel Salesforce.com Call Center Adapter license to the Licensing Server. 3) A Salesforce administrator imports the ShoreTel call center definition XML file into Salesforce. 4) For each user, a Salesforce administrator associates the user with the ShoreTel call center definition. 5) For each user, the ShoreTel Salesforce.com Call Center desktop client is installed on the users PC.

1)

Installing the ShoreTel Application Licensing Server

The ShoreTel application licensing server is installed only once on the customers ShoreTel Headquarters server. It is used by all ShoreTel Professional Services applications that require licenses. Dont confuse it was the standard ShoreTel licensing features. If the licensing server (service name "STPS Application License Service") has been previously installed on the customers ShoreTel Headquarters server then you can skip this step. Installing the licensing server consists of two steps: Installing the licensing server service which runs all the time. Installing the licensing server admin web site used to add, remove and configure licenses. You should have received separate information and instructions on installing and using the ShoreTel Application Licensing Server. Please consult that information for instructions.

2) Adding the ShoreTel Salesforce.com Call Center Adapter license to the Licensing Server
Using the license servers admin web interface, you will need to add a Salesforce client license with a sufficient count of licenses for all the clients who intend to use the ShoreTel Salesforce.com adapter. Licensing is per user and once a user requests and receives a license they will continue to use that license unless an Administrator administer frees up the license so it can be assigned to another user. When purchasing the software, you should receive a permanent license good for the number of clients purchased. This will usually be delivered via email and is a long string of text that is copied and pasted into the ShoreTel Application Licensing Servers Install Licenses page. If you are trialing the program you can use the 45 day trial license key below. This is good for up to five users. Note that you would copy from the start Salesforce.com through the two equal signs at the end:

Salesforce.com Call Center Adapter|5|Trial License| |0|3/19/2010 18:20:50|3/19/2010|5/18/2010| |0|1440|qtOCO6g1kRGVrrVDFqYDVg|1.0|qGQ/H48N3Z/bouxO /eookTjHI95Uq+v2mf3BBn4AW616jfxRasHr5g== 3) Create the Call Center in Salesforce
In order to be able to tell Salesforce to use a specific vendors CTI adapter the CTI adapter needs to be defined as a Call Center to Salesforce. This requires the one time importation of the

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 5 of 35

ShoreTelCTIAdapter.xml file by a ShoreTel administrator. A copy of the XML file is included in the client zip file. A copy is also installed in the clients installation folder when each client is installed. The Salesforce admin would follow this procedure to import the ShoreTel call center definition: 1. In Salesforce, click Your Name Setup Customize Call Center Call Centers. 2. If the Introducing Salesforce CRM Call Center splash page appears, click Continue. 3. Click Import. 4. Next to the Call Center Definition File field, click Browse to navigate to the location of the ShoreTelCTIAdatper.xml. Click Open to enter the path in the Call Center Definition File field. 5. Click Import. 6. Click Edit next to the name of the new call center, ShoreTel Adapter for SF Call Center Version 4.x, to make any additional changes. If you are using the adapter at multiple sites in your organization and those sites use different settings for trunk access code or location then follow this procedure to create additional call centers for a particular CTI adapter: 1. In the Call Centers list page, click the name of the ShoreTel call center. 2. Click Clone. 3. Specify a unique value for Internal Name. This name identifies the new call center record in Salesforce and is limited to 40 alphanumeric characters. It must start with an alphabetic character. 4. Make any additional changes to the new call center as necessary. For example, set a different trunk access code. 5. Click Save. As installed, the default settings are for a trunk access code of "9" and North American dialing plan. If you are using a different trunk access code or are outside of the North American dialing area, you will need to edit the "ShoreTel Adapter" call center and change the values as appropriate.

4)

Associating Users with the ShoreTel Call Center Adapter

This step can be performed before or after the client is installed (see the next step). Salesforce users must be assigned to a call center that matches their client software before they can run the client and use a SoftPhone. To assign users to a call center: 1. Click Your Name Setup Customize Call Center Call Centers. 2. Click the name of the call center to which you want to assign users. For this version, the default definition is named ShoreTel Adapter for SF Call Center Version 4.x. This shows it listed along

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 6 of 35

with the two older versions:

3. 4. 5. 6.

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 center. Click Find. All users who belong to a call center are excluded from search results because a user can only be assigned to one call center at a time. 7. Select the checkbox next to each user who should be assigned to the call center and click Add to Call Center. Note: To change a users call center, first remove him or her from their current call center and then add him or her to the new call center. You can view a users call center on the User detail page.

5)

Installing Clients

Once the call center has been created then the following steps must be performed for each user who will be using the ShoreTel Salesforce.com client: The Adapter setup must be run on the user's PC to install software. Note: If you are upgrading from an earlier version of the ShoreTel Adapter client, you should first shutdown the Adapter from the tray if it is currently running, then go to the Microsoft Windows Add/Remove Programs utility in the Control Panel and remove the current "ShoreTel Salesforce.com Call Center Adapter". To install the software, unzip the setup zip file into a folder and run the enclosed setup.exe. If the Microsoft .NET 3.5 runtime is not installed you will be prompted to install it first before continuing.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 7 of 35

After the initial screen, the installation program will prompt for the user's extension:

DO NOT SET THE EXTENSION UNLESS YOU ARE RUNNING ON A SERVER PLATFORM! Note that if you wish to change or clear the user extension after the Adapter has been installed you could change the registry value located at: HKCU\Software\ShoreTel\STSalesforceConnector\Extension. If you change the extension setting in the registry then make sure to exit and then restart the client. Alternatively, you could reinstall the application. Note that when the Adapter is run on a server platform, the agent features of the Adapter are not supported and will not be displayed.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 8 of 35

The next screen will prompt for two settings which control the Adapter:

Show agent area will show the part of the SoftPhone used to view and control the user's ShoreTel Workgroup status. If the user is not part of Workgroups then they may want to disable this. Note also that the agent controls are not supported when the Adapter is run on a server platform. Auto start at login causes the program to be added to the user's run Registry key so that whenever he or she logs into the Windows machine the Adapter will automatically run.

Note that both of these settings can be changed after the program is installed via the tray icon context menu of the installed ShoreTel Adapter. The next screen prompts for the installation directory and then, following confirmation, the installation takes place.

Note that unlike previous versions, Adapter version 4.x no longer needs to prompt for, and possibly install, Firefox specific support. The support is now embedded in the Java Script of the web pages served by Salesforce. This simplifies the installation and operation of the clients interaction with the browser and is part of the reason it is able to work in a more browser agnostic fashion.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 9 of 35

Following installation, a shortcut named "ShoreTel Salesforce.com Call Center Adapter" will be added to the user's desktop as well as to his or her Programs\ShoreTel folder:

Usage
When working correctly, the ShoreTel client causes the users web browser to show a SoftPhone on the left side of the screen with details of any active calls. For example, this shows a user logged into Salesforce using Internet Explorer:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 10 of 35

The Brought to you by splash screen is not part of the SoftPhone. It is associated with a test account we are using.

Starting the Adapter

To start the adapter and get the SoftPhone to show up in the users browser requires two steps: 1) Run the ShoreTel Salesforce.com Call Center Adapter client program. 2) Log into Salesforce.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 11 of 35

To run the ShoreTel client program, the user can double click the desktop shortcut or click the Programs | ShoreTel shortcut. The running ShoreTel client will show up in the user's Windows tray area with a red "S" icon:

Note: You may need to show the hidden icons in your Windows tray. In addition, you may find it desirable to customize your tray icons to always Show icons and notifications so you always know when the ShoreTel client is running. Once the Adapter has been installed, it can be run when needed or it can be configured to run automatically when the user logs into Windows. The user should run the client program first and then log into Salesforce, Salesforce will automatically connect to the SoftPhone. If the user logs into Salesforce without the ShoreTel client running then the SoftPhone will not connect and will instead display this button:

The user should run the Salesforce client program and then click on the button then the SoftPhone will connect after initialization as below for several seconds:

Then the softphone will connect and display in its initial form:

The Connect CTI Adapter button has no function before the adapter client program is running. If you click on it before you run the ShoreTel client then nothing will happen. If the user exits the ShoreTel client program from the icon tray while he or she is logged into Salesforce with the SoftPhone, the user will see this error:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 12 of 35

Adapter Tray Icon Menu

The ShoreTel Adapter's tray icon menu, displayed by right-clicking the icon, provides several settings that control how the SoftPhone works. In addition, this is where users go to exit the adapter as well as display version information and configure logging. Right clicking the menu displays the following items. Note, the top 5 choices (everything except Logging, About, and Exit) will only show once the user has connected via their browser to the SoftPhone. Show agent area This controls whether the ShoreTel Workgroup agent control is shown as part of the user's SoftPhone. This would normally be disabled unless the user will be handling ShoreTel Workgroup calls. Automatically create call activities for inbound calls Automatically create call activities for outbound calls These two settings control the automatic creation of Salesforce.com call activity record in response to inbound and outbound calls. If checked then call logs for the appropriate option will be created. If unchecked then call logs will not be created. Keep the call log open on call disconnect Normally, for an external call, if a call activity is created it will automatically be saved and the call log pane closed when the call disconnects or, in the case of ShoreTel Workgroup calls, when the agent completes wrap up. Enabling this option will cause the call log to stay open when a call disconnects. The current call's call log will actually be moved to the recent calls area of the users SoftPhone (see the description of the SoftPhone below) and displayed until the user manually saves or cancels. When used in this enabled mode, the user decides when and if the call log will be saved. If the user cancels from the recent calls pane then no call activity will be written to the Salesforce.com database. Auto start at login This option is the same as the corresponding installation program option. A user can decide whether to have the Adapter start automatically when he logs into his Windows machine or whether he prefers to manually start the application. Logging Display a dialog which provides control of the logging feature of the Adapter. Depending on the settings, the Adapter will write fairly extensive logs to the Logs directory within the Adapter's installation directory. In general, this feature should not be used unless a problem is being tracked and the user is working with ShoreTel Professional Services or Salesforce.com. About Displays the about box for the ShoreTel Adapter showing the version of the Salesforce.com code portions as well as the ShoreTel specific code. The latter is shown under the CTI Connector area
Page 13 of 35

ShoreTel Salesforce.com Adapter Version 4.x User Guide

and can be used to determine the specific version of the Adapter being used.

Exit Shuts down the ShoreTel Salesforce.com Call Center Adapter client program.

Exploring the SoftPhone Layout

The SoftPhone has a number of sections which provide information and controls to allow a user to interact with ShoreTel calls and Salesforce and the relation between the two. This example shows the typical layout for a SoftPhone but administrators can modify SoftPhone definitions and create additional definitions and assign different users to use different SoftPhone layouts. This shows the ShoreTel Salesforce SoftPhone with the various sections pointed out:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 14 of 35

 ShoreTel Workgroup agent status Phone line header Call information

Call button area

Current Call Log (expanded) Call log information

Last three calls display (not expanded) My Calls Today report link ShoreTel logo

ShoreTel Workgroup agent status This control is only useful for ShoreTel Workgroup agents. It displays the agents current Workgroup status and allows it to be changed by selecting a new status from the drop down list. Note: If the user is not a ShoreTel Workgroup call center agent then they will want to hide this control using the tray icon setting. This includes Enterprise Contact Center users as this control only supports ShoreTel Workgroup agents. The agent status shows one of four statuses: 1. Not Ready for Call The agent does not want to receive any workgroup calls. Note that this only applies to workgroup calls. Direct dialed, transferred, or auto attendant calls will ignore this setting. This corresponds to a "Logged Out" status in the ShoreTel Call Manager. 2. Ready for Call The agent is ready to accept workgroup calls and does not have any calls active. This corresponds to a "Logged In" status in the ShoreTel Call Manager when no call is active.
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 15 of 35

3.

4.

On a Call Agent was ready for calls but is currently active on a call. Moving in or out of this state can only be done by ShoreTel system. This corresponds to the "Logged In" status in the ShoreTel Call Manager when a call is active. Wrap Up The agent completed a workgroup call and is in Wrap Up. This corresponds to the "Call WrapUp" status in the ShoreTel Call Manager.

The Agent Status both shows the current agent status and allows the user to change his status. Specifically: From any state, the agent can change their state to "Not Ready for Call" to prevent future workgroup calls. This might be used before taking a break. Similarly, assuming the user is running ShoreTel Version 8.1 or later then, from any state, the agent can change their state to "Wrap Up" to prevent workgroup calls while they perhaps complete paper work. From "Wrap Up", the agent can change their state to "Ready for Call" if they conclude their wrap up early before the automatic timeout. From "Not Ready for Call", the agent can change their state to "Ready for Call" to start accepting workgroup calls. Phone line header This shows the status of the phone line. A status icon changes colors, blinks and provides a text description. You can click the name of the line (Line 1) to show or hide the line's dial pad and call information area. Call information This shows data related to the call, such as the phone number the customer used to dial, the duration of the call, and links to any record associated with the call. Call button area This shows buttons that let you make call commands, such as dialing, hanging up, putting a caller on hold, transferring, conferencing, and opening a second line while on a call in order to place a new call. Current Call Log When the user is connected on an external call, the current call log window automatically expands to allow the user to type in call notes related to the call. The call log subject will default to the date and time of the call but can be changed if desired. In addition, the name field can be set automatically by a hit on a calls phone number or by the user navigating to a specific Salesforce entity while on the call. Last three calls display Expanding this area will display details of up to the last three calls handled by this user. It displays the same information as seen in Current Call Log while the call was active. My Calls Today report link Clicking this linkopens a report of all the calls you've made or received in the last day.
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 16 of 35

ShoreTel logo This displays the ShoreTel logo.

Using the SoftPhone

The SoftPhone allows ShoreTel Salesforce users to: Make calls by dialing a number in the SoftPhone, choosing a number in an online directory, or clicking a phone number in any contact, lead, activity, or account Answer a phone call by clicking Answer when a call arrives or using your telephone to answer the call. Quickly view all Salesforce records that are related to the call, such as contacts, cases, or accounts Transfer a phone call by clicking the Transfer button while on a call. The original call is placed on hold and the user dials to a third party. Once connected, click Complete Transfer to transfer the original party to the third party. Put a caller on hold by clicking the Hold button while on a call. The user can retrieve the call by clicking Retrieve from Hold. Initiate a conference call by clicking the Conference button while on a call. The original call is placed on hold while the user dials the new participant. Once connected, click Complete Conference to place all parties on the same line. Start a new call on a second line by clicking New Line while on a call. Attach comments to an automatic call log by typing text into the Comments text box during a call. Associate Salesforce records with a call by navigating to the record in the main Salesforce window and then selecting it in the call log area. Edit completed call logs by clicking Edit next to the call in the Last Calls area of the SoftPhone.

Specifying Personal SoftPhone Settings

There is one feature of the SoftPhone that is configured by end users directly from Salesforce. This is the setting which controls how that users SoftPhone responds to inbound calls. To edit personal SoftPhone settings click Your Name Setup Call Center Settings My SoftPhone Settings. The following options are available: Automatically log in to your call center when logging into salesforce.com This option is not used by the ShoreTel Adapter and will be ignored. If only one record found on incoming call Select Always open the record automatically to display a single matching record in the main Salesforce window when a call arrives. Select Never open the record automatically to display a single matching record only as a link in the SoftPhone Call Information. You must click the link to display the full record details.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 17 of 35

Administrative Configuration
Administrators can configure Salesforce CRM Call Center by: Customize SoftPhone layouts. Assigning SoftPhone layouts to selected user profiles. Adding phone numbers to call center directories.

Customizing SoftPhone Layouts

Similar to page layouts, you can design custom SoftPhone layouts and assign them to call center users based on their user profile. This shows the SoftPhone layout editor open on the Standard SoftPhone Layout:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 18 of 35

To add a new SoftPhone layout you would follow these steps:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 19 of 35

1) 2) 3) 4)

5)

6) 7)

8)

Click Your Name Setup App Setup Customize Call Center SoftPhone Layouts. Click New to open the SoftPhone Layout Editor. In the Name field, enter a label that uniquely identifies the new layout. In the Select Call Type pick list, choose the type of call for which the currently-displayed SoftPhone layout settings 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 (only 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 record(s) in Salesforce. The following table describes each record-matching row and its screen pop options: Record-Matching Row Screen pops open within Description Use to set where the screen pop displays. Screen Pop Option Existing browser window Select to display in open browser windows. New browser window or tab Select to display in new browser windows or tabs. Don't pop any screen Select if you don't want any screen to display. Pop to new Select to display a new record page you specify from the drop-down list. Pop to Visualforce page Select to display a specific Visualforce page. Don't pop any screen Select if you don't want any screen to display. Pop detail page Select to display the matching record's detail page. Pop to Visualforce page Select to display a specific Visualforce page. Don't pop any screen Select if you don't want any screen to display. Pop to search page Select to display a search page. Pop to Visualforce page Select to display a specific Visualforce page.
Page 20 of 35

No matching records

Use to set the screen pop options for when the details of an inbound call don't match any existing Salesforce records. Use to set the screen pop options for when the details of an inbound call match one existing Salesforce record. Use to set the screen pop options for when the details of an inbound call match more than one existing Salesforce record.

Single-matching record

Multiple-matching records

ShoreTel Salesforce.com Adapter Version 4.x User Guide

To hide expanded record-matching rows, click Collapse. 9) Configure layouts for any remaining call types in the Select Call Type list. 10) Click Save. Previewing SoftPhone Layouts By default, the Preview image shows the SoftPhone layout if more than one call-related record is found. When this occurs, only the name of each record is displayed in the SoftPhone. To preview the SoftPhone layout if only one matching record is found, hover your mouse over the row that lists this object in the If an exact match is found, display these fields section.

Assigning SoftPhone Layouts to Users

To assign a custom SoftPhone layout to a user profile: 1) Click Your Name Setup Customize Call Center SoftPhone Layouts. 2) Click Layout Assignment. 3) For each user profile that appears on the page, select the SoftPhone layout that the profile should use. Profiles are only listed in this page if they include users that are currently assigned to a call center, or if they have already been assigned a custom SoftPhone layout. The number in parentheses shows the number of call center users who are assigned to that profile. 4) Click Save.

Adding Directory Numbers

Every call center includes a directory that lists the phone number of every user assigned to the call center. You can customize call center directories by adding additional directory numbers, either to a single call center or to all defined call centers in your organization. If you have a large number of directory numbers to define, use the Force.com Data Loader to create them in one step. See What is the Force.com Data Loader? in the Salesforce.com Help & Training for details. This shows the Additional Directory Number Editor open on a new directory entry:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 21 of 35

To add a custom directory number: 1) Click Your Name Setup App Setup Customize Call Center Directory Numbers. 2) Click New to show the Additional Directory Number Editor. 3) In the Name field, enter a label that identifies the directory number. 4) In the Phone field, enter the phone number, including any international country codes. Dialing prefixes, such as 9 or 1, do not need to be included. 5) In the Call Center field, select the call center directory to which you want to add the new number. To add the number to every call center in your organization, choose -- Global --. 6) In the Description field, optionally enter text that provides further information about the additional directory number. 7) Click Save.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 22 of 35

Appendix A: Frequently Asked Questions

What versions of Salesforce support the ShoreTel adapter?
Professional, Enterprise, Unlimited and Developer versions are all supported.

What changes were made in Version 4.0?

Salesforce code, which used to be contained in the adapter, has moved to the browser. The adapter has been simplified into a single executable file. CTI 4.0 uses standard Web technologies, which allow for secure hypertext transfer protocol (HTTPS) for your call center. Previous versions of CTI are secure but use Windows technologies. To provide added security see the question in this section, Do I need HTTPS with the CTI Adapter? The ShoreTel XML import file specifies a new Adapter URL and port field from which the adapter can listen for CTI messages. Licensing is now checked when the adapter starts. Previously this was checked when the user logged into Salesforce.com. If the licensing check fails then the client exits and must be restarted once the license issue is resolved before it can be used.

Are there best practices for working with the adapter?

Make sure that support agents' adapters aren't blocked by a firewall. If you're required to encrypt CTI messages using HTTPS, you can add a security certificate to support agents' desktops. Communicate to support agents that they can click the new Reconnect CTI Adapter button on the SoftPhone if their adapters disconnect from the CTI system. Starting with version 4.0, you'll be automatically logged out of the SoftPhone after 8 hours if you have one browser tab open and go to an external Web page, or to a Salesforce page without a sidebar (such as a dashboard). Automatic-logout times can vary because they're based on how your administrator has configured your SoftPhone. To stay logged in, make sure you have at least one browser tab open to a Salesforce page with a sidebar, such as Home or Cases. Automatic logout doesn't occur in the Service Cloud console.

Why do I get an error saying License Failed: when the client starts?

Some things to check:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 23 of 35

Is the Application Licensing Server service, downloadable from http://support.shoretel.com/products/applications (see Install Me First), installed? Is the Application Licensing Server service running on the HQ Server? Is Communicator configured in the Telephony options to point to the ShoreTel HQ server? Note that sometimes, Communicator is incorrectly installed to point to a customers ShoreTel DVS server rather than the customers ShoreTel Headquarters server (see ShoreTel KB 12046). If this is the first time this user is requesting a license, are Salesforce licenses available on the Application Licensing Server as shown here:

Can I run the Softphone in different browsers at the same time (IE + FF + Chrome)?
No. The softphone can only be run in one browser at one time. This means, for example, that the softphone cannot be run with Firefox, Chrome or Internet Explorer at the same time. Agents must log into the Softphone with one browser only. This is because each browser experience with Salesforce represents one user session. Logging into the Softphone in both IE and Chrome represents 2 user sessions. Currently the CTI 4.x adapter can only support 1 user session at a time. The behavior of the Softphone in this scenario is not defined.

Why am I getting a big red error message saying "500 stream:1: XML file has no top-element. All well-formed XML files have a single top-level element."?
A possible cause of this is that the XML subsystem, MSXML6, has not been installed or properly registered. Search for "Unable to start the Softphone XML subsystem" in the Salesforce.com Help & Training for troubleshooting steps. For more details on resolution, see:
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 24 of 35

http://wiki.developerforce.com/page/Troubleshooting_Your_CTI_Adapter#I.27m_getting_a_big_red_error_m essage_saying_.22Unable_to_start_the_Softphone_XML_subsystem..22

I receive a "Do you want to view only the webpage content that was delivered securely" Security Warning in Internet Explorer as shown here:

This warning is a "Mixed Content Warning". It indicates that you are accessing salesforce.com over HTTPS, but communicating with the CTI adapter over HTTP. To resolve this issue you have two options: 1) On each users desktop: Go to Tools -> Internet Options -> Security -> Local Intranet Click "Custom Level" Select "Enable" for "Display mixed content" Click "OK" Click "OK" 2) See the next question on "Do I need HTTPS with the CTI Adapter".

Do I need HTTPS with the CTI Adapter?

This question must be answered by your company's internal IT policy. CTI-4.0 communicates over HTTP with the CTI adapter. However, all communication is restricted to messages originating from the "localhost" domain. This means that only requests originating from the users computer, or "local" requests, will be acknowledged and processed. All other requests will be ignored. This includes requests from within the company network (intranet) or beyond the company network firewall (internet). In this way, the information passed between the browser and the adapter is secured. In certain cases there may be a need to secure CTI communication via HTTPS. The CTI-4.0 Toolkit does respect HTTPS. For this, the customer must generate a security certificate for the localhost domain and bind it to the Salesforce CTI listener. This is sufficient for Internet Explorer. For Firefox and Chrome, the certificate might need to be imported into the browser's certificate store. For more information, see the Appendix on Configuring HTTPS for the ShoreTel CTI Adapter.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 25 of 35

Is there a way I can try the adapter if I dont have a Salesforce.com account?
Salesforce.com makes it very easy to get a developer account for testing. Simply go to the site: http://www.salesforce.com/developers And click on the Get a Free Developer Edition link.

Why isn't my Softphone showing?

Couple things to check: The ShoreTel Adapter must be running for the Softphone to appear. Is the Adapter icon showing in the system tray? Is the user assigned to the ShoreTel Adapter call center? See the section above Installing Clients within the Installation section.

Why isn't the agent area of the Softphone showing?

With the Softphone open in a browser, right click the Adapter tray icon and from the popup context menu, make sure that the "Show Agent Area" choice is checked. If not then check it. If it is grayed out then you are running on a Server platform. Agent features are not supported when the Adapter is run on ShoreTel server platforms.

Softphone shows "Line (xxx) not found"?

Sometimes, when the browser is connecting to the Softphone, this message will be briefly seen. This is normal as the browser connects to the ShoreTel telephony interface asynchronously. However, if the message does not go away, this indicates that the Adapter cannot find either the specified ShoreTel extension or any ShoreTel extension. This could be caused if the Adapter is run on a PC where the ShoreTel Communicator client has not been installed.

Why does my Softphone show "Line xxx unconnected" or "Line xxx out of service"?
If the switch servicing the phone is powered off or unconnected to the ShoreTel server, the phone line will be in an unconnected state. If the phone itself is unplugged, the phone line will be in an out of service state.

Softphone shows "ShoreTel COM object STMLControl.dll not registered or not found"?
This indicates that, the COM object needed by the Adapter has been unregistered or removed. This could be caused by an SDK user uninstalling another application which uses the ShoreTel STMLControl.dll COM object. To rectify this problem you can repair the application in the Windows Add/Remove programs application, or uninstall then reinstall the application, or you can try to manually re-register the DLL using the Windows regsvr32 utility. To try this open a command prompt and

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 26 of 35

navigate to the adapter installation directory, if default location is used (remove the (x86) from the path if you arent running on a 64 bit cpu): C:\Program Files (x86)\ShoreTel\ShoreTel Salesforce.com Call Center Adapter From this location, run: regsvr32 STMLControl.dll If it works, you should see a message: "DLLRegister Server in STMLControl.dll succeeded".

Why isnt the bowser going to the Salesforce entity associated with an offering call?
For the web browser to automatically go to a page associated with an offering call, two things need to be true: The user's Salesforce.com option "If only one record found on incoming call" should be set to "Always open the record automatically". Only one record can be associated with the inbound call. If multiple records are associated then the browser will not attempt to go to the record.

Browser isnt allowing me to navigate when a call is presenting?

If the user's Salesforce.com call center option "If only one record found on incoming call" is set to "Always open the record automatically" and only one record match an offering call's caller ID, then the Softphone will automatically go to that record. In addition, as long as the call is offering, the Softphone will not allow the user to navigate to another Salesforce.com page. This is a feature of the core connector code provided by Salesforce.com. Once the call is no longer offering, the user is free to navigate to another location. This can also be prevented if the user changes their setting to "Never open the record automatically".

Why does my browser cycle between two pages?

For the same reason the browser will not let the user navigate his browser to another page. This occurs when two calls are offering simultaneously. In this case, the connector ends up fighting with itself. Each time the record is changed, the connector sees that a call is offering associated with a different record and goes to that record. Then the reverse occurs, the browser ends up cycling between the two records. Again, this is a feature of the core Salesforce.com software.

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 27 of 35

Appendix B: Configuring HTTPS for a CTI Adapter

You can configure your CTI adapter to use the secure hypertext transfer protocol (HTTPS). HTTPS provides added security for your call center and also helps prevent the Mixed Content warnings that can appear in your browser if your Salesforce organization uses the HTTPS protocol but your call center does not. HTTPS is only available for CTI adapters and call centers using Windows XP and Windows 7. Note: Please contact Salesforce for assistance on HTTPS configuration. ShoreTel Professional Services cannot provide assistance with these procedures. They involve some fairly complex knowledge. They were developed by Salesforce. ShoreTel lacks the expertise to assist in carrying them out. To configure HTTPS for a CTI adapter review and follow these steps: 1) Add the HTTPS URL to your Salesforce organization's call center, as described below in Adding HTTPS to the Call Center. 2) Add the same HTTPS URL to your CTI adapters, as described below in Adding HTTPS to the CTI Adapter. 3) Create and install a security certificate for Windows, as described below in Creating and Installing a Security Certificate. Tip: After you configure HTTPS for a CTI adapter, you might need to add a security exception to users' browsers before they can log in to a call center.

Adding HTTPS to a Call Center

Once you create a call center in your Salesforce organization, you can add HTTPS to it: 1) Click Your Name > Setup > Customize > Call Center > Call Centers. 2) Click the name of the call center. 3) Click Edit. 4) Type the secure URL for your adapter in CTI Adapter URL. For example, https://localhost:11000. 5) Click Save. For more information on creating a call center, see Creating a Call Center in the Salesforce online help.

Adding HTTPS to CTI Adapters

Once you add HTTPS to a call center in your Salesforce organization, you can add HTTPS to CTI adapters: 1) Use a text or XML editor to open SalesforceCTI.exe.config, which is located at the root directory of the drive where the CTI adapter is installed. For example: C:\Program Files\ShoreTel\ShoreTel Salesforce.com Call Center Adapter\SalesforceCTI.exe.config 2) Change the value of the AdapterUrl setting to match the HTTPS URL you added to your call center. For example: https://localhost:11000
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 28 of 35

3) Click Save.

Creating and Installing a Security Certificate

Once you add HTTPS to a call center in your Salesforce organization, and add HTTPS to CTI adapters config file, you can use MakeCert to create a certificate authority. A Certificate authority validates certificates to ensure that encrypted data can only be accessed by designated users or organizations. Important: MakeCert is a third-party product not provided or supported by salesforce.com. Therefore, you might find it necessary to change the steps below to complete the specified tasks. MakeCert is included as part of the Windows SDK, which you can download from Microsoft.

For information about MakeCert, see:

http://msdn.microsoft.com/en-us/library/aa386968%28v=vs.85%29.aspx

For information on using MakeCert, see:

http://msdn.microsoft.com/en-us/library/aa388165%28v=VS.85%29.aspx

For information on configuring a port with an SSL certificate, see:

http://msdn.microsoft.com/en-us/library/ms733791%28v=VS.90%29.aspx

To create and install a security certificate with MakeCert: 1) With administrator privileges, open a command prompt window by clicking Start > All Programs > Accessories > Command Prompt. Alternatively, you can click Start > Run, enter cmd in the Open field, and click OK. 2) In the command window, enter cd\ to navigate to the root directory of the drive where Windows SDK is installed. 3) Navigate to the Windows SDK \bin directory by entering the following command (be sure to replace the file path with the path from your system): cd C:\Program Files\Microsoft SDKs\Windows\v7.1\bin 4) Enter makecert. 5) Create the certificate authority certificate. For example, enter: makecert -n "CN=XXX Authority" -cy authority -a sha1 -sv "XXX_authority.pvk" r "XXX_authority.cer" -sr localmachine -ss ROOT Note that XXX = your company name. 6) Create a certificate for your CTI adapter based on the certificate authority certificate created in the previous step. For example, enter: makecert -n "CN=localhost" -ic "XXX_authority.cer" -iv "XXX_authority.pvk" -a sha1 -sky exchange -pe -sr localmachine -ss MY "cti_adapter.cer" 7) Bind the CTI adapter certificate to the correct port number. For example, on Windows XP), enter: httpcfg set ssl -i 0.0.0.0:<port number> -h <certificate thumbprint> On Windows 7, enter: netsh http add sslcert ipport=0.0.0.0:<port number> certhash=<certificate thumbprint> appid=<application GUID> Note: <port number> is the port number specified in SalesforceCTI.exe.config.
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 29 of 35

<certificate thumbprint> is the thumbprint of the CTI adapter certificate created in the previous step. <application GUID> is any valid GUID, such as {9D06D291-3882-4D7B-A6E55DD6EEE2486F}. 8) Check that the binding was created successfully. For example, on Windows XP, enter: httpcfg query ssl On Windows 7 enter: netsh http show sslcert

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 30 of 35

Appendix C: Application Integration Features

Built into the ShoreTel Adapter are features intended to ease future integration with interactive voice response (IVR), automatic call distribution (ACD) and other applications. These features are available to be used by programmers developing custom solutions using the ShoreTel COM, TAPI, or Web Services SDKs available through the ShoreTel Developer Network. For details on the ShoreTel Developer Network or to sign up, please contact ShoreTel Professional Services. In addition, ShoreTel Professional Services can take advantage of these features in delivering custom solutions to partners and customers. If this is an option that you might want to consider, please contact ShoreTel Professional Services. Note: These procedures require that the customer or partner performing the integration be familiar with the ShoreTel SDK and in particular with how to use the Browser to verify call properties. We will provide support with integration issues involving these features when a paid consulting engagement with ShoreTel Professional Services is in place. When a call presents to the Adapter, it is examined for ShoreTel call properties starting with the prefix "_ST_SF." ShoreTel call properties are named values which can be attached to a call using methods in the ShoreTel TAPI or COM object interfaces. An application could attach properties before sending the call to the extension the Adapter is controlling. For example, an IVR application using a ShoreTel route point could: Receive an inbound call at the route point and automatically answer it Play a prompt to solicit a Salesforce.com case number. Attach the case number to the call as a ShoreTel call property Transfer the call to a user running the Softphone. When the call presents, the Softphone would automatically show the case link and possibly automatically show the associated case details. You will more than likely want to join the Salesforce.com developer program (see Test Salesforce.com Account above) to obtain developer information, including valid object and field names available for use.

Displaying Call Related Records

When a call arrives, the ShoreTel Adapter searches Salesforce.com for any related records. It first searches based on data attached to the call, such as an account number that was entered by the caller during an IVR session. If that search fails, the CTI connector then searches based on the automatic number identification (ANI, the phone number from which the caller is dialing). Any related records that are found during either of these searches are displayed in the user interface of the line containing the call.

Handling Attached Data

This ShoreTel Adapter uses the following mechanism in handing data attached to calls. If you are writing an IVR you should make sure to follow these conventions. The attached data is passed in the form of key-value pairs as ShoreTel call properties attached to the call. The keys should be of the form _ST_SF.Object.FieldName, where:
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 31 of 35

"_ST_SF." is a required prefix to allow the client to recognize properties related to Salesforce.com integration. Object corresponds to the developer name of an object in the Apex API, and FieldName corresponds to the developer name of a field on that object. For example, Case.CaseNumber would be a valid key. The values should correspond to the format of the field in Salesforce.com. For example, Case.CaseNumber, "00001001" would be a valid value. Note: Values must be exact matches for the Salesforce.com record. For example, if "1001" is specified but the case number is actually "00001001," the record is not returned.

Passing Data from Enterprise Contact Center

Starting with Version 5.0 of The ShoreTel Enterprise Contact Center, ECC Call Profile User Fields are now stored as ShoreTel Call Properties. This allows any TAPI application including the ShoreTel Adapter to access those properties. The convention followed by ECC is to store these name the properties it creates with a prefix of "_STCC_". Therefore, to accommodate the ECC prefix, when the Adapter is looking for attached properties it also looks for a prefix of "_STCC_SF" and handles these properties in the same way as _ST_SF. So, for example, an ECC script could gather a customer Salesforce.com case number and then set this user field of the call profile: SF.Case.CaseNumber=00001001 This would result in the ECC system adding a ShoreTel call property of the form: _STCC_SF.Case.CaseNumber=00001001

Examples of Attached Data Search Queries

Salesforce.com Call Center Edition uses attached data to generate an Sforce Object Query Language (SOQL) query. For example, if the attached data contains _ST_SF.Case.CaseNumber="00001001", Call Center Edition generates and executes the following query: SELECT <fields> FROM Case WHERE CaseNumber='00001001' where the value of <fields> is defined by the user's Softphone layout. If the attached data contains two or more key-value pairs that pertain to the same object, Call Center Edition generates a single query with all the conditions specified for that object. For example, if the attached data contains _ST_SF.Case.CaseNumber="00001001" and _ST_SF.Case.Priority="High", the search generates and executes the following query: SELECT <fields> FROM Case WHERE CaseNumber='00001001' AND Priority='High' If the attached data includes two or more key-value pairs that pertain to different objects, Call Center Edition generates a query for each object and adds all of the results to the phone line's display. For

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 32 of 35

example, if the attached data contains _ST_SF.Case.CaseNumber="00001001" and _ST_SF.Account.AccountNumber="1234", the search generates and executes the following queries: SELECT <fields> FROM Case WHERE CaseNumber='00001001' SELECT <fields> FROM Account WHERE AccountNumber='1234'

An Example Using the COM SDK

This section assumes is aimed at developers using the ShoreTel Developer Network's COM SDK. One of the server sample included with the SDK is the ShoreTel Account Capture sample. This application is intended to run on a ShoreTel server. Simply by changing its configuration it can be used to demonstrate attaching data and passing it to a ShoreTel Salesforce.com client user. You should start by reviewing Chapter 4, ShoreTel Account Capture and Account Player in the ShoreTel Server Samples.pdf document included in the COMSDK3\Docs directory of the ShoreTel COM SDK. Once you have installed, used and understand the sample, you are ready to modify the setting to use it in conjunction with the client. The below figure shows the Account Capture sample's settings you need to change:

1. 2. 3.

Set the Account Code Length to collect 8 digits, not the default of 5. Set the Call Property Name to be "_ST_SF.Case.CaseNumber". While not required, you probably want to replace or re-record the Account Code prompt to say something like: "Please enter your 8 digit Salesforce.com case number"

Now, a call to the route point, in this example, extension 156, would cause the sample to ask the user for his Salesforce.com case number, gather the eight digits and attached the digits to the call as a ShoreTel call property named _ST_SF.Case.CaseNumber before sending the call to the transfer destination which in this example is extension 181. If 181 is a user running the ShoreTel Adapter then the user would see a link for the case in their Softphone when the call presents.
ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 33 of 35

The figure below shows the result when the call presents to the agent. Note the case link in the Softphone:

Using the COM SDK Browser to Pass Salesforce.com Properties

The SDK server sample, the STMLBrowser, can also be used to test attached data scenarios. This allows you to ensure that the Softphone will correctly handle the data you attach before you build the application which would do so. For example, the below figure displays the call property pane of the browser showing both a case number and account number set on a call:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 34 of 35

Using the browser, the call is then transferred to extension 211. The below figure shows the SoftPhone results when the call presents at 211. Note both the Account and Case links:

ShoreTel Salesforce.com Adapter Version 4.x User Guide

Page 35 of 35