CTI Toolkit Developer's Guide

Transcription

1 CTI Toolkit Developer's Guide: Salesforce Summer '07 CTI Toolkit Developer's Guide Copyright salesforce.com, inc. All rights reserved. Salesforce.com and the no software logo are registered trademarks, and AppExchange, Success On Demand, and The Business Web are trademarks of salesforce.com, inc. All other trademarks mentioned in this document are the properties of their respective owners.

2

3 Table of Contents Table of Contents Introduction to Call Center Edition...5 About This Guide...5 About Call Center Edition Documentation...6 System Requirements...7 Chapter 1: System Architecture...8 About CTI Systems...9 About CTI Adapters...9 About CTI Connectors...9 About SoftPhone Connectors...10 Processing Events from a CTI System...10 Processing Commands from a SoftPhone...10 Registering a CTI adapter with a CTI System...11 About Salesforce...11 About SoftPhones...11 Chapter 2: The Salesforce CTI Toolkit...14 Contents of the CTI Toolkit Code Package...14 The Demo Adapter...15 Setting Up the Demo Adapter...15 Using the Demo Adapter...15 Customizing the Demo Adapter...16 CTI Connector Classes...16 Best Practices for Coding with the CTI Toolkit...20 The CTIConstants.h File...20 The 'L' Literal and Character Prefix...20 Method Name in CCTIUserInterface...20 Specifying a Valid CTI Client Key...21 Chapter 3: Customizing Call Center Edition...22 Customizing a CTI Connector...22 Building a New CTI Connector...23 Setting Up a New CTI Connector Project...23 Building a CTI Connector Project in Visual Studio...23 Adding a COM Base Class to a CTI Connector Project...25 Instantiating a CCTIUserInterface Subclass...27 Writing an Event Sink...28 Determining the CTI System Events that Require an Event Sink Handler...28 Writing an Event Sink Handler...29 SoftPhone Modification Options...30 Using the "Virtual" Keyword in Your CCTIUserInterface.h File...31 i

4 Table of Contents Implementing Call Center User Command Messages...31 Writing the Initialize Method for CCTIUserInterface...33 Enabling Call Center User Login...33 Enabling One-Step Transfers and Conferences...36 Enabling a Set of Buttons...36 Changing the Display Order of SoftPhone Buttons...37 Adding a Button...37 Enabling Reason Codes...38 Mapping CTI System Agent States tocall Center Edition User States...40 Displaying Call Center Edition User States...42 Adding a New Call Center Edition User State...42 Adding a Custom Logo...43 Modifying Displayed Call Information...44 Customizing Automatically-Generated Call Logs...46 Defining Custom SoftPhone Labels...47 Translating Custom SoftPhone Labels...47 Chapter 4: Call Center Definition Files...49 Call Center Definition File XML Format...49 Required Call Center Elements and Attributes...51 Specifying Values for <item> Elements...51 Sample Call Center Definition File...52 Chapter 5: Packaging and Publishing a CTI Adapter...53 Packaging a CTI Adapter...53 Publishing a CTI Adapter on the AppExchange...54 Determining the Developer and Publisher Roles for your Listing...54 (Developer) Requesting a Blank Listing...54 (Publisher) Creating a Publishing Profile...54 (Developer) Associating a Publisher Profile with a Listing...55 (Developer or Publisher) Editing a Listing...55 (Developer or Publisher) Assigning a Listing to an Exchange and Category...57 (Developer or Publisher) Preparing a Listing for ARB Review...57 (Publisher) Submitting a Listing to ARB Review...58 (Publisher) Posting an Approved Listing on the AppExchange...58 (Publisher or Developer) Editing or Deleting a Public Listing...58 Chapter 6: CTI Adapter Log Files...60 Chapter 7: SoftPhone XML Format Reference...61 CTIUserInterface...63 CTIAgent...64 CTIAgentState...64 CTIForm...65 CTILine...65 CTILogo...66 ii

5 Table of Contents CTIPreviousCalls...66 CTIReasonCodeSet...67 CTIReasonCode...67 CTIElementSet...67 CTIStaticText...68 CTITimer...68 CTIProgressBar...69 CTIParty...69 Transferred Call Scenario...70 Conference Call Scenario...70 CTIInfoField...71 CTIRelatedObjectSet...71 CTIRelatedObject...72 CTIField...72 CTILink...73 CTICallLog...73 CTIComments...74 CTIWho...74 CTIWhat...74 CTIInteractiveControlContainer...75 CTIButton...75 CTIEditBox...76 CTICheckBox...77 CTIComboBox...77 CTIComboBoxValue...77 CTILineOnlyElementSet...78 CTIDialPad...78 Chapter 8: Call Center Edition API Reference...79 describesoftphonelayout...80 CallCenter...81 AdditionalNumber...82 Chapter 9: Frequently Asked Questions...85 Q: What is the difference between Call Center Edition and the CTI Toolkit?...85 Q: Why does Call Center Edition involve a client-side application? Isn't salesforce.com the "No Software" company?...85 Q: Does the CTI adapter support multiple telephone lines?...85 Q: Is it possible to have multiple CTI adapters working in parallel against the same switch?...85 Q: Does a CTI adapter require any investment or changes to a switch?...85 Q: Does Call Center Edition require VoIP?...86 Q: Why was the CTI Toolkit written in C++ instead of.net or Java?...86 Q: How long does it usually take for a partner to write a custom CTI adapter?...86 Q: Is there a list of the telephony platforms that are currently covered?...86 Q: How can I demo a CTI adapter?...86 iii

6 Table of Contents Q: If I'm using a machine that has multiple CTI connector.dll files installed, how does the SoftPhone connector know which CTI connector to use when I log in to Salesforce?...86 Q: I'm seeing 'L' prefixes in front of all the string and character literals in the CTI Toolkit code. Why are these present?...87 Q: My SoftPhone is not behaving the way that I expect it to. How can I troubleshoot it?...87 Glossary...88 Index...91 iv

7 Introduction to Call Center Edition Call Center Edition seamlessly integrates Salesforce with third-party computer-telephony integration (CTI) systems. After a lightweight CTI adapter program has been installed on a Salesforce user's machine, the user can use the features of a CTI system through the Salesforce SoftPhone, a customizable call control tool that appears in the sidebar of every Salesforce page. The SoftPhone allows 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 Receive calls Quickly view all Salesforce records that are related to the call, such as contacts, cases, or accounts Transfer calls Initiate conference calls Put callers on hold Attach records to calls Generate automatic call logs Administrators can configure Call Center Edition by: Modifying SoftPhone layouts and assigning them to selected user profiles Adding phone numbers to call center directories Developers can use Salesforce Call Center Edition code libraries to: Customize the functionality of existing CTI adapters Build new CTI adapters for phone systems that are not yet supported About This Guide The CTI Toolkit Developer's Guide is a reference for developers who want to customize Call Center Edition beyond the scope of what is currently offered by salesforce.com. This guide includes the following information: Chapter Introduction to Call Center Edition Call Center Edition overview, documentation, and system requirements See About Call Center Edition Documentation on page 6 and System Requirements on page 7 for details. System Architecture Call Center Edition system architecture, including CTI systems, CTI adapters, the role of the Salesforce database, and SoftPhones See System Architecture on page 8 for details. 5

8 About Call Center Edition Documentation Chapter The CTI Toolkit Customizing Call Center Edition Call Center Definition Files Deploying a CTI Adapter CTI Adapter Log Files SoftPhone XML Format Reference Call Center Edition API Reference Frequently Asked Questions Glossary s of the types of files that are included in a CTI adapter code package and notes on CTI Toolkit coding practices See The Salesforce CTI Toolkit on page 14 for details. Options for customizing Call Center Edition, including project setup, event sink implementation, and SoftPhone modification options See Customizing Call Center Edition on page 22 for details. How to define a default XML call center definition file for a new CTI adapter See "Call Center Definition Files" in the Salesforce online help for details. Steps for bundling new CTI adapter code libraries into an installer and publishing it on the AppExchange. See Packaging and Publishing a CTI Adapter on page 53 for details. A description of the location and format of CTI adapter log files See CTI Adapter Log Files on page 60 for details. The XML rules that define how a SoftPhone is displayed See SoftPhone XML Format Reference on page 61 for details. Apex API objects and methods that relate to Call Center Edition See Call Center Edition API Reference on page 79 for details. A set of frequently-asked questions regarding troubleshooting and CTI adapter architecture See Frequently Asked Questions on page 85 for details. A glossary of terms related to Call Center Edition See Glossary on page 88 for details. About Call Center Edition Documentation For a complete understanding of Call Center Edition, the CTI Toolkit Developer's Guide should be read in conjunction with the following additional documentation: Getting Started with your SoftPhone - a tip sheet that provides an overview of Call Center Edition functionality for call center users. Getting Started with Setting Up Call Centers - a tip sheet that provides an overview of how an administrator can configure Call Center Edition for an organization. Using the Call Center Edition Demo Adapter - a tip sheet that provides an overview of the Call Center Edition demo adapter. Salesforce CTI Toolkit Code Reference - an online help system that provides detailed information about the objects and methods in the Call Center Edition source code that salesforce.com provides Cisco IPCC Enterprise Adapter Guide - a developer guide that details Cisco-specific implementation notes for the Cisco IPCC Enterprise SoftPhone CTI adapter Standard Call Center Edition functionality is also fully documented in the Salesforce online help. 6

9 System Requirements System Requirements Call Center Edition requires the installation of a light-weight computer-telephony integration (CTI) adapter on every Salesforce user's machine. The minimum system requirements for this adapter are: Internet Explorer 6.0 Windows XP 256 MB of RAM (512 MB recommended) 20 MB disk space minimum P2 500Mhz processor or above Pre-built adapters for several different CTI systems are available on In addition, salesforce.com provides downloadable code for a CTI adapter that runs with Cisco IPCC Enterprise on the Apex Developer's Network. You can use this code as a starting point for your own custom CTI adapter implementations. 7

10 Chapter 1 System Architecture This diagram shows the system architecture of Call Center Edition: Salesforce Call Center Edition uses the following components: CTI system CTI adapter Salesforce SoftPhone A set of telephony hardware and software that supports integration with other computer systems. The CTI system provides the base framework for the calls that are made and received through a SoftPhone For more information, see About CTI Systems on page 9. A light-weight software program that controls the appearance and behavior of a Salesforce SoftPhone. The adapter acts as an intermediary between a third-party CTI system, Salesforce, and a Call Center Edition user. It must be installed on any machine that needs access to Call Center Edition functionality. For more information, see About CTI Adapters on page 9. The source of call-related data and SoftPhone layout instructions. In addition to providing access to records that are related to an incoming call, Salesforce stores call center connection information and directories, SoftPhone layouts, and automatic call logs. For more information, see About Salesforce on page 11. A customizable call control tool that appears in the sidebar of every Salesforce page. A SoftPhone requires a connection to a third-party CTI system to make or receive phone calls. 8

11 About CTI Systems About CTI Systems For more information, see About SoftPhones on page 11. A Computer-Telephony Integration (CTI) system is a set of telephony hardware and software that supports integration with other computer systems. The CTI system provides the base framework for the calls that are made and received through a SoftPhone. Call Center Edition supports any CTI system that operates using an event model, in which a CTI system sends an event to all registered listeners for any action that occurs in the phone system. For example, when a user's telephone rings, a CTI system broadcasts a "RINGING" event. A CTI adapter, the Call Center Edition component that acts as a listener, receives this event and updates the SoftPhone as appropriate. About CTI Adapters A CTI adapter is a light-weight software program that controls the appearance and behavior of a Salesforce SoftPhone. The adapter acts as an intermediary between a third-party CTI system, Salesforce, and a Call Center Edition user. It must be installed on any machine that needs access to Call Center Edition functionality. Because a CTI adapter communicates directly with an individual CTI system, an organization must use a different CTI adapter for each type of CTI system that is in use. For example, if an organization wants to integrate one call center that runs Cisco IPCC Enterprise and one call center that runs Cisco IPCC Express, the organization must have two CTI adapters available. A call center user's machine only requires the SoftPhone CTI adapter for the call center to which it connects. A number of prebuilt CTI adapters for different CTI systems are available on the AppExchange at If your CTI system is not currently supported, you can still use Call Center Edition, but you must either build a new CTI adapter, or customize sample CTI adapter code provided by salesforce.com. As illustrated in this diagram, a CTI adapter consists of two components: a CTI connector that maintains an XML representation of the SoftPhone and communicates directly with the CTI system, and a SoftPhone connector that converts SoftPhone XML to HTML and distributes it to a call center user's browser. About CTI Connectors A CTI connector is the component of a CTI adapter that controls the functionality and appearance of a call center user's SoftPhone. The CTI connector receives CTI system events, displays SoftPhone user interface elements, and searches for Salesforce records that are related to incoming calls. During a call the CTI adapter generates an automatic call log, and when 9

12 About CTI Adapters a call is over it allows the call center user to enter reason codes for why the call ended, or for why the user wishes to log out of the CTI system. The CTI connector works by maintaining an XML representation of the SoftPhone that it updates whenever it receives relevant CTI system events or SoftPhone connector messages. After the CTI connector updates its XML, it fires a UIRefresh event. This event signals the SoftPhone connector that the SoftPhone needs to be updated in the call center user's browser. You can customize a CTI connector implementation with new functionality, or build a new CTI connector if you want to support a CTI system that does not already have an adapter. Although a CTI connector can be written in any language that supports COM, salesforce.com only provides code for CTI connectors that are written in unmanaged C++ using the CTI library (CTIAdapterLib) that salesforce.com provides. When you customize a CTI connector, you extend the objects and methods already defined in CTIAdapterLib. For more information on CTI connector customization options, see Customizing a CTI Connector on page 22. For information on the XML format that the CTI connector uses to represent a SoftPhone, see SoftPhone XML Format Reference on page 61 About SoftPhone Connectors A SoftPhone connector is the component of a CTI adapter that converts SoftPhone XML into HTML and distributes it to a call center user's browser. Every time a call center user begins a new Salesforce session, the SoftPhone connector downloads SoftPhone labels and layouts from Salesforce. The SoftPhone connector uses these labels and layouts to generate SoftPhone HTML from the XML passed in by the CTI connector's UIRefresh event. When the SoftPhone connector receives a new set of XML from the CTI connector through the UIRefresh event: 1. The SoftPhone connector converts the attached XML into HTML. All labels and layouts are resolved during this step. 2. The call center user's browser maintains a continuous link with the SoftPhone connector through COM automation. When the browser connector generates new SoftPhone HTML, it updates the SoftPhone in the user's browser. Processing Events from a CTI System CTI system events are messages from a CTI system to its registered listeners, such as a CTI adapter. An adapter handles events from a CTI system as follows: 1. When a CTI system broadcasts an event, the adapter's CTI connector receives it through its event sink class. The event sink converts any data that is attached to the event into a standard format, and then calls the corresponding event handler in the CTI connector's CCTIUserInterface class. CTI system events that do not affect the SoftPhone, such as those that provide statistical data, are ignored by the event sink. 2. The CCTIUserInterface event handler updates the XML representation of the SoftPhone by hiding and revealing individual SoftPhone components, such as buttons and dial pads, and by performing searches for related Salesforce records, such as contacts and accounts. When finished, the CTI connector broadcasts a UIRefresh event to the SoftPhone connector. 3. The SoftPhone connector uses the XML attached to the UIRefresh event to render an HTML version of the SoftPhone. 4. The call center user's browser maintains a continuous link with the SoftPhone connector through COM automation. When the browser connector generates new SoftPhone HTML, it updates the SoftPhone in the user's browser. Processing Commands from a SoftPhone Commands are messages from a call center user's SoftPhone to a CTI system. An adapter handles SoftPhone commands as follows: 1. When a call center user clicks a button in the SoftPhone (for example, Hang Up), the SoftPhone sends an HTML command message to the SoftPhone connector that includes the ID of the button that was clicked (for example, 10

13 About Salesforce 2. The SoftPhone connector translates the button click into an XML message, and then sends it to the CTI connector with the UIAction method. 3. When the CTI connector receives the message from the SoftPhone connector, one of two actions takes place: The UIHandleMessage method in CCTIUserInterface forwards the message to the CTI system and no other changes occur until the CTI system sends a new event. For example, the HANGUP message is passed to the CTI system so that the connected call can be terminated. Once the call ends in the phone system, the CTI system broadcasts a hang-up confirmation event and the CTI connector proceeds as described in Processing Events from a CTI System on page 10. The UIHandleMessage method in CCTIUserInterface updates the CTI connector's XML representation of the SoftPhone by hiding and revealing individual SoftPhone components, such as buttons and dial pads, and by performing searches for related Salesforce records, such as contacts and accounts. When finished, the CTI connector broadcasts a UIRefresh event to the SoftPhone connector. The SoftPhone connector receives the XML and uses it to render an updated SoftPhone. Registering a CTI adapter with a CTI System When a call center user logs in to Salesforce, the CTI adapter that is installed on the user's machine must first register with a CTI system before it can receive CTI events. Registration occurs as follows: 1. Upon logging in to Salesforce, the browser acquires a session ID that authenticates the user for the duration of their Salesforce session. The CTI adapter uses this session ID to query Salesforce for information related to the user's assigned call center. All data associated with the call center is returned to the adapter. 2. The adapter's CTILogin method uses the call center data to connect with the specified CTI system. In most cases the call center user must provide authentication information to the CTI system. After logging in for the first time, users have the option of saving their CTI system credentials within Salesforce for automatic login in the future. About Salesforce The Salesforce database stores call center connection information, SoftPhone formatting instructions, and call center directory numbers. In addition, the CTI connector component of a CTI adapter uses Sforce Object Query Language (SOQL) and Sforce Object Search Language (SOSL) to retrieve Salesforce records that are associated with data attached to incoming calls, such as an account number (SOQL) or the phone number from which a customer is calling (SOSL). About SoftPhones A SoftPhone is a customizable call control tool that appears in the sidebar of every Salesforce page if a user is assigned to a call center and is working on a machine on which a CTI adapter has been installed. Although SoftPhones can be extensively customized by Salesforce administrators and developers, most SoftPhones include the following components, as illustrated in this screen shot: 11

14 About SoftPhones Call center state area This area includes a drop-down list that allows a user to specify whether he or she is ready to receive calls. Phone line header This area displays the status of the phone line, both with a status icon that changes colors and blinks ( ), and a text description. Users can click the name of the line ("Line 1") to show or hide the line's dial pad and call information area. Call information area This area displays data related to the call, such as the phone number from which the customer dialed, the duration of the call, and links to any Salesforce records that are associated with the call. Call button area This area displays buttons that allow a user to execute call commands, such as dialing, hanging up, putting a caller on hold, transferring, conferencing, and opening up a second line while on a call. Current call log area This area displays log information for the call. By default, the Subject field includes the date and time of the call, but users can edit this field as desired. The Name field allows users to specify a related contact, lead, or person account, while the Related To field allows them to attach an additionalsalesforce record to the call log once the call ends. Users can enter additional information about the call in the Comments 12

15 About SoftPhones Recent calls area text box. Call logs are saved in an activity record that can be retrieved from the recent calls area of the SoftPhone, or the Activity History related list of the associated records. This area displays saved logs for calls that have recently completed. Click a log's Subject link to open the call log's details page, or a log's Name or Related To link to open the associated record. Click Edit to reopen a call log for editing in the SoftPhone window. My Calls Today report This link opens a report of all calls that you have made or received in the last day. SoftPhone logo This area displays a logo that can be customized for each CTI adapter. 13

16 Chapter 2 The Salesforce CTI Toolkit The Salesforce CTI Toolkit provides you with all of the source code, libraries, and files you need to develop your own custom CTI adapter. You can download the CTI Toolkit by visiting the Apex Developer Network at Contents of the CTI Toolkit Code Package All CTI toolkit code packages include the following components: SoftPhone connector executable (SalesforceCTI.exe) This component runs the SoftPhone connector portion of a SoftPhone CTI adapter. It comes as a pre-compiled executable file with the logo. CTI connector code package (<cti_system_adapter_name>.primary Output) This Visual Studio.NET 2003 code package contains the classes that make up a CTI connector for the specified CTI system. Once you have customized this code package, it is compiled into a.dll file. See CTI Connector Classes on page 16 for a description of the classes in this package. Demo CTI connector code package (DemoAdapter.Primary Output) This Visual Studio.NET 2003 code package contains the classes that make up the CTI connector for the Call Center Edition Demo Adapter. For more information, see The Demo Adapter on page 15. Note: A compiled version of the demo adapter is also available on the Apex Developer Network for quick installation. The salesforce.com Office Toolkit Library (SF_MSApi4.dll) This.dll component is required for access to the Salesforce Apex API. Microsoft XML Library 6 (msxml6.dll and msxml6r.dll) These.dll files allow the SoftPhone connector to translate the SoftPhone user interface XML into HTML. Any dynamically-linked libraries that are required for the CTI system Most CTI adapter implementations require additional CTI-system-specific.dll files to enable communication. Default call center definition files (<cti_system_adapter_name>.xml or DemoAdapter.xml) These XML files provide the default definition format for a call center that uses the specified adapter. For more information, see Call Center Definition Files on page 49. For a complete list of the files that are included with a particular CTI adapter code package, see its associated Adapter Guide. 14

17 The Demo Adapter The Demo Adapter Included with the Salesforce CTI Toolkit is the Call Center Edition demo adapter, an executable that can be used to mimic SoftPhone functionality without requiring an operational CTI system. Users can manually trigger CTI system events such as an incoming call with an automatic number identification (ANI) value, an incoming call without an ANI value, an incoming conference call, and an incoming transfer request. The SoftPhone operates as if these events had been triggered by a valid CTI system and allows the user to view associated records and generate call logs as if they had been real. As a developer, you can use the demo adapter to quickly prototype new SoftPhone functionality, or as a template for a new CTI connector implementation. Setting Up the Demo Adapter To install and set up a Call Center Edition demo adapter: 1. Download the demo adapter installation package from the Apex Developer Network at 2. From the demo adapter's installation directory, run Setup.exe as a Windows administrator user. 3. Log in to Salesforce as an administrator user. 4. Click Setup Customize Call Center Edition Call Centers. 5. Click Import. 6. Click Browse and navigate to the call center definition file in your demo adapter installation directory. In default installations, this file is located at C:\Program Files\salesforce.com\Demo Adapter\DemoAdapter.xml. 7. Click Import. 8. Click Demo Call Center Adapter. 9. Click Manage Call Center Users. 10. Click Add More Users. 11. Enter search criteria to find a Salesforce user who can be a demo adapter user. Click Find. 12. Select the checkbox next to the name of one or more users who should have access to the demo adapter. Click Add to Call Center. 13. Log in to Salesforce as a demo adapter user. 14. Log in to the SoftPhone. The demo adapter's login screen accepts any values as valid credentials. Using the Demo Adapter Once you have logged in to the demo adapter you can use it like a normal SoftPhone. To trigger a CTI system event while you are using the demo adapter SoftPhone: 1. Right-click the CTI adapter system tray icon ( ) in the lower right corner of your computer screen. 2. Select Go To Wrapup After Call if you want to view wrap-up reasons after ending a demo call. 3. Select one of these demo CTI system events: Demo CTI System Event Call From Call Via IVR (Case 1001) Transfer From x8120 Conference From x8120 An inbound call from (415) that does not include interactive voice response (IVR) data. You can also initiate this event by typing Winkey-Shift-Z. An inbound call from (415) that includes IVR data identifying case You can also initiate this event by typing Winkey-Shift-X. A call that has been transferred from another call center user at extension x8120 A conference request from another call center user at extension x

18 CTI Connector Classes Note: When the demo adapter receives a call, your computer plays a ring tone. When the demo adapter initiates a call via click-to-dial, your computer plays a dialing sound. Customizing the Demo Adapter You can customize the demo adapter system tray menu and the logo that displays at the bottom of the SoftPhone by modifying demo_menu.xml in the installation directory. To customize the first system tray menu item, edit the menu item label or automatic number identification (ANI) attributes in the following line: <ITEM ID="MENU_CALL_FROM_PHONE" LABEL="Call From " ANI=" "/> To customize the second system tray menu item, edit the menu item label, ANI, search field, or search value attributes in the following line: <ITEM ID="MENU_CALL_FROM_IVR" LABEL="Call Via IVR (Case 1001)" ANI=" " SEARCHFIELD="Case.CaseNumber" SEARCHVALUE=" "/> Note: For the SEARCHFIELD attribute, any object-field pair can be used. For example, Case.CaseNumber, Account.AccountNumber, and Support_Program c.program_number c are all valid. To customize the SoftPhone logo, edit the image URL in the following line: <LOGO IMAGE_URL=" Note: To ensure that SoftPhone logo images are available on any machine, save your logo image as an externally available document in the Documents tab of any salesforce.com organization. CTI Connector Classes When a developer wants to customize a CTI adapter, he or she modifies its CTI connector component. This diagram shows the classes that make up a CTI connector. s of each class follow: 16

19 CTI Connector Classes ILockable A container for classes that can lock and release resources CCritical Section A wrapper class for the Win32 CRITICAL_SECTION object. Objects that must be thread-safe should derive from this class. CCTILogger A class that logs CTI Adapter events to a file and classifies them by level (Low, Medium and High). Low-level events are used for errors only, medium-level events are used for informational messages, and high-level events are used for granular information such as the specific XML that was sent back and forth in messages. CMutex A wrapper class for the Win32 MUTEX object CCTIAdapter An interface between the CCTIUserInterface class and the base COM class of the CTI connector. This class provides a common way for methods in CCTIUserInterface to fire a UIRefresh event. CCTIAppExchange An interface between CCTIUserInterface and the Apex API CCTIAppExchangeSaveThread Encapsulates a thread for saving items to the salesforce.com database with the Apex API. When using this thread, data can be saved in the background without freezing the Salesforce user interface. For example, this class is used to create and update task objects for call logs, and saves user login parameters. CCTIAppExchangeSearchThread Encapsulates a thread for searching for items in the salesforce.com database with the Apex API. When using this thread, search can occur in the background without freezing the Salesforce user interface. For 17

20 CTI Connector Classes example, this class is used to search for automatic number identifiers (ANIs) and interactive voice response (IVR) data. CCTICallLogThread Encapsulates a thread for creating and updating task objects for call logs using the Apex API. When using this thread, tasks can be created in the background without freezing the Salesforce user interface. <Your Event Sink Class> Normally a subclass of a library provided by a CTI system vendor, an event sink captures interesting events broadcast by a CTI system. This class should receive events, populate attached data into a PARAM_MAP structure, and call the corresponding event handlers in CCTIUserInterface. CCTIObject A base class for all visual objects in a SoftPhone. It provides common functionality such as determining when an object is hidden or visible, attribute handling, and serialization to XML. CCTIAgent A class that represents the call center state picklist in a SoftPhone. A call center state indicates whether the user is ready to receive calls. CCTIDialpad A class that represents the dial pad for a single phone line in a SoftPhone CCTIForm A class that represents a set of related combo boxes, edit boxes, check boxes, buttons, and other user interface elements in a SoftPhone. When this form is rendered, all element values are sent in a group when a user presses a submit button. CCTIIdLabelObject A class that represents any CCTIObject that requires a label and ID. At runtime, the browser controller uses an object's ID to translate any text to the proper language for the call center user. If the browser controller does not have a mapping for a particular ID, the label associated with the object is used instead. CCTIButton A class that represents a button in a SoftPhone CCTICallLog A class that represents a call log for a current or previous call in a SoftPhone CCTICheckbox A class that represents a checkbox in a SoftPhone CCTIProgressBar A class that represents a progress bar control that indicates that processing is occurring. This class can exist within the context of CCTIUserInterface or CCTILine. CCTIReasonCodeSet A class that represents a set of reason codes in a SoftPhone. A reason code is an explanation that users can select when they want to enter wrap-up mode after a call, set their user status to Not Ready for Calls, or log out of a CTI system entirely. Organizations can define sets of reason codes to track the activities of their call center users. This class does not distinguish between wrap-up, not ready and logout reason codes. CCTIRelatedObject A class that represents a single related record (like an individual contact or account) in a SoftPhone CCTIRelatedObjectSet A class that represents a set of related records (like contacts or accounts) in a SoftPhone 18

21 CTI Connector Classes CCTISelectableIdLabelObject A base class that represents any object with an ID, Label, and Selected parameter in a SoftPhone CCTIAgentState A class that represents a single call center state in a SoftPhone, such as Not Ready for Calls CCTIStatic A class that represents a static text element in a SoftPhone CCTITimer A class that represents a timer that ticks in real-time in a SoftPhone. A CCTITimer can only be attached to a phone line. CCTIValueObject A class that represents any CCTIIdLabelObject that also requires a value CCTIEditBox A class that represents an edit field in a SoftPhone CCTIField A class that represents a single field from a CTIRelatedObject in a SoftPhone CCTILine A class that represents a single phone line in a SoftPhone CCTILogo A class that represents the logo section of a SoftPhone CCTIPreviousCalls A class that represents a single phone line in a SoftPhone CCTIUserInterface A class that encapsulates the connection between a CTI server and a SoftPhone. All CTI connectors should subclass this class, overriding the command methods to actually perform the described actions. CCTIUserInterface should also include methods for events that are captured in an event sink. CCTIWhoWhat A class that holds data about any record that is related to a call log. A call log can be related to one contact, lead, or person account record (the "who"), and one additional record of any other type (the "what"). CSearchThreadInfo A class that provides information to CCTIAppExchangeSearchThread. This class generally does not need to be instantiated by classes other than CCTIAppExchangeSearchThread. CSaveThreadInfo A class that provides information to CCTIAppExchangeSaveThread. This class generally does not need to be instantiated by classes other than CCTIAppExchangeSaveThread. LockImpl<T> A resource grabber class that automatically locks a resource on construction and releases the resource on destruction CCTIUtils A utility class for convenience methods such as conversions to and from COM data types For more information about the methods and attributes associated with these classes, see the Salesforce CTI Toolkit Code Reference. 19

22 Best Practices for Coding with the CTI Toolkit Best Practices for Coding with the CTI Toolkit The CTIConstants.h File In addition to the.h files that are included for every class, the CTI Toolkit also includes CTIConstants.h. This file contains all of the constant values that are used to control the display of the SoftPhone, as well as constants for all commonly used terms that appear in the CTI Toolkit code. The 'L' Literal and Character Prefix The Salesforce CTI Toolkit includes an 'L' character in front of all literal strings and characters. The 'L' prefix indicates that the string will be stored as an array of wide (2-byte) characters, which are necessary to support Unicode character encoding. Salesforce.com enforces the use of this prefix on all string values to support localization. For example, in this constant definition, the 'L' is placed in front of the constant's literal string value: #define CTI_CLIENT_KEY L"/cti/1.0/" If an 'L' prefix is not placed in front of a string's first " character, the following type of error appears when you attempt to compile: CTICallLog.cpp(193) : error C2665: 'CCTILogger::Log' : none of the 11 overloads can convert parameter 2 from type 'const char [93]' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(96): could be 'void CCTILogger::Log(int,const wchar_t *,const wchar_t *,const wchar_t *,const wchar_t *,const wchar_t *)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(101):or 'void CCTILogger::Log(int,const wchar_t *,long,const wchar_t *,const wchar_t *)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(106): or 'void CCTILogger::Log(int,const wchar_t *,long,long,const wchar_t *)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(111):or 'void CCTILogger::Log(int,const wchar_t *,const wchar_t *,long,const wchar_t *)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(121): or 'void CCTILogger::Log(int,const wchar_t *,const std::wstring &,const std::wstring &)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(126): or 'void CCTILogger::Log(int,const wchar_t *,const std::wstring &,const wchar_t *)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(141): or 'void CCTILogger::Log(int,const wchar_t *,long,const std::wstring &)' c:\dev\144\clients\salesforce_cti\ctiadapterlib\include\ctilogger.h(146): or 'void CCTILogger::Log(int,const wchar_t *,const std::wstring &,long)' while trying to match the argument list '(int, const char [93], std::wstring, std::wstring)' Method Name in CCTIUserInterface This table shows the naming convention for most methods in CCTIUserInterface: 20

23 Best Practices for Coding with the CTI Toolkit Naming Convention CallXxx (for example, CallInitiate) CreateXxx (for example, CreateParty) CTIXxx (for example, CTIChangeAgentState) DestroyXxx (for example, DestroyVirtualLine) GetXxx (for example, GetAppExchange) OnXxx (for example, OnAgentStateChange) OnCallXxx (for example, OnCallAttemptFailed) QueueXxx (for example, QueueChangeAgentState) SetXxx (for example, SetAllowDialpad ForAllLines) UIXxx (for example, UIRefresh) A method that initiates or somehow affects an active call A method that allocates memory for a new object A method that affects the overall state of the call center user in the CTI system but does not pertain to any specific call A method that deallocates memory that was created for a specific object A method that provides access to a property or sub-object of CCTIUserInteface A CTI event A CTI event pertaining to a specific call A method that implements the specific action after some precondition has completed A method that sets a property on CCTIUserInterface or on one of its sub-objects A method that renders the SoftPhone user interface or handles input from it Specifying a Valid CTI Client Key If you are developing a CTI adapter that will be published on the AppExchange you must provide a valid client key in CTIAppExchange.h. A client key allows an organization to download and deploy your CTI adapter even if the organization does not normally have access to the Apex API. All CTI adapters require access to the API in order to communicate with the Salesforce database. If you are creating a CTI adapter from a third-party vendor's adapter source code, a valid client key is already specified in CTIAppExchange.h. You do not need to provide a new client key. If you are creating a CTI adapter directly from a salesforce.com CTI Toolkit, request a client key from Salesforce Support and use it to update the following constant in CTIAppExchange.h: #define CTI_CLIENT_KEY L"<your_client_key_value_here>" 21

24 Chapter 3 Customizing Call Center Edition While the AppExchange offers prebuilt CTI adapters for several CTI systems, many organizations want to implement additional features for these adapters or use a CTI system for which an adapter has not yet been built. In either case, an organization can customize a CTI adapter by modifying the CTI connector source code provided by salesforce.com. You can either customize an existing CTI connector or build a new one for a CTI system that is not yet supported. Customizing a CTI Connector Salesforce allows you to customize CTI adapters that have already been built and posted on the AppExchange. To do so: 1. Download the CTI adapter code package. (See The Salesforce CTI Toolkit on page 14 for information.) 2. Read the entirety of this guide to understand how a CTI connector should work with other CTI adapter components, and how it can be customized. 3. Use Visual Studio.NET 2003 to customize the CTI connector code base. For example, you can: Use any CTI system event to update the SoftPhone for a user. For example, a warning icon can blink if customers are forced to be on hold for more than five minutes. (See Writing an Event Sink Handler on page 29 for information.) Define new commands for call center users. For example, you can add a Record button that allows a user to record his or her phone conversations. (See Implementing Call Center User Command Messages on page 31 for information.) Customize the buttons that are displayed in a SoftPhone. For example, you can modify the length, icon, and placement of any button. (See Adding a Button on page 37 and Changing the Display Order of SoftPhone Buttons on page 37 for information.) Display custom Salesforce fields in a SoftPhone layout. For example, you can display a field that shows the local time of the person who is calling. (See Modifying Displayed Call Information on page 44 for information.) Customize the call center user login screen. For example, an organization that allows free seating might require their users to enter a desk number when they log in. (See Enabling Call Center User Login on page 33 for information.) Enable one-step (blind) transfers and conference calls. For example, a call center user might wish to transfer a caller to another party without speaking to them first. (See Enabling One-Step Transfers and Conferences on page 36 for information.) Manage wrap-up, not-ready, and logout reason codes. For example, you can ensure that a user specifies why they cannot take a new call before they enter the Not Ready for Calls state. (See Enabling Reason Codes on page 38 for information.) Modify the logo at the bottom of the SoftPhone. For example, you can display the logo for your organization rather than the logo of the CTI system. (See Adding a Custom Logo on page 43 for information.) Customize the search for call-related Salesforce records. For example, you can query other data repositories in your organization for information before searching Salesforce. (See Displaying Call-Related Records on page 45 for information.) Customize automatically-generated call logs. For example, you can add a field to a call's activity record that shows the amount of time a caller was left on hold. (See Customizing Automatically-Generated Call Logs on page 46 for information.) Translate SoftPhone labels. For example, you can display French labels for your call center in Paris and Japanese labels for your center in Tokyo. (See Translating Custom SoftPhone Labels on page 47 for information.) 22

25 Building a New CTI Connector 4. Update the CTI adapter's call center definition file as required. (See Call Center Definition Files on page 49 for information.) 5. Compile the CTI connector.dll and test it with the Call Center Edition SoftPhone connector. 6. Deploy your adapter. (See Packaging and Publishing a CTI Adapter on page 53 for information.) Building a New CTI Connector If you want to use Call Center Edition with a CTI system that does not currently have a CTI adapter, you must build a new CTI connector. Building a new CTI connector is similar to customizing an existing CTI connector, except that in addition to performing the customizations outlined in the previous section, you must also build an event sink. To build a new CTI connector: 1. Read the entirety of this guide to understand how a CTI connector should work with other CTI adapter components, and how it can be customized. 2. Download the CTI connector files from salesforce.com. (See The Salesforce CTI Toolkit on page 14 for information.) 3. Use Visual Studio.NET 2003 to build a CTI connector project. (See Setting Up a New CTI Connector Project on page 23 for information.) 4. Write an event sink for your new CTI connector to handle events that are generated by your CTI system. (See Writing an Event Sink on page 28 for information.) 5. Write subclasses of CCTIUserInterface and CCTIAppExchange to maintain a representation of a SoftPhone based on CTI system events and user commands. (See SoftPhone Modification Options on page 30 for information.) 6. Update the CTI adapter's call center definition file as required. (See Call Center Definition Files on page 49 for information.) 7. Compile the CTI connector.dll and test it with the Call Center Edition SoftPhone connector. 8. Deploy your adapter. (See Packaging and Publishing a CTI Adapter on page 53 for information.) Setting Up a New CTI Connector Project If you are building a new CTI connector for a CTI system that does not currently have a CTI adapter, you must set up a new project in Visual Studio.NET If you simply want to customize an existing CTI connector, it is not necessary to perform these steps. To set up a project for a new CTI connector: 1. Build a CTI connector project in Visual Studio.NET 2003, as described in Building a CTI Connector Project in Visual Studio on page Add the COM base class to your project, as described in Adding a COM Base Class to a CTI Connector Project on page Instantiate a subclass of CCTIUserInterface, as described in Instantiating a CCTIUserInterface Subclass on page 27. Building a CTI Connector Project in Visual Studio If your organization uses a CTI system that does not have a SoftPhone CTI adapter built by salesforce.com, you must first build a CTI connector project in Visual Studio.NET 2003: 1. Download the Call Center Edition libraries. See The Salesforce CTI Toolkit on page 14 for details. 2. In Visual Studio, click File New... Project. 3. In the Project Types area, select Visual C++ Projects ATL. 4. In the Templates area, select ATL Project. 5. Specify a name and location for your CTI connector, and click OK. 6. In the ATL Project Wizard, click Finish. Two projects are created: one with the name you specified and another with the name you specified and a postfix of "PS" (for example, "MyCTIConnector" and "MyCTIConnectorPS"). The second "PS" project is not necessary and can be removed from your solution. 23

26 Setting Up a New CTI Connector Project 7. Right-click the CTI connector project you just created and select Properties. 8. Select Configuration Properties C/C++ General. a. Set the Configuration picklist to All Configurations and make the following changes: In the Additional Include Directories field, add the CTIAdapterLib include directory (for example,..\ctiadapterlib\include). In the Debug Information Format field, specify Program Database for Edit & Continue (/ZI). In the Warning Level field, specify Level 3 (/W3). In the Detect 64-bit Portability Issues, specify Yes (/Wp64). b. Set the Configuration picklist to Release. c. Change the Debug Information Format field to Line Numbers Only (/Zd). 9. Select Configuration Properties C/C++ Code Generation. a. Set the Configuration picklist to All Configurations and make the following changes: In the Enable Minimal Rebuild field, specify Yes (/Gm). In the Basic Runtime Checks field, specify Both (/RTC1, equiv. to /RTCsu). In the Runtime Library field, specify Multithreaded Debug DLL (/MDd). In the Enable Function-Level Linking field, specify Yes (/Gy). b. Set the Configuration picklist to Release. c. Change the Runtime Library field to Multithreaded (/MT). 10. Select Configuration Properties C/C++ Language. a. Set the Configuration picklist to All Configurations. b. In the Enable Run-Time Type Info field, specify Yes (/GR). 11. Select Configuration Properties Linker Input. a. Set the Configuration picklist to Debug. b. In the Additional Dependencies field, include the debug version of the CTIAdapterLib library, CTIAdapterLibD.lib (for example,..\ctiadapterlib\debug\ctiadapterlibd.lib). c. Set the Configuration picklist to Release. d. In the Additional Dependencies field, include the release version of the CTIAdapterLib library, CTIAdapterLib.lib (for example,..\ctiadapterlib\debug\ctiadapterlib.lib). e. Click OK to close the Properties window and save your changes. 12. In your project, open stdafx.h and add the following lines to the bottom of the file if they are not already there: #include <atlbase.h> #include <atlcom.h> #include <atlwin.h> #include <atltypes.h> #include <atlctl.h> #include <atlhost.h> #include <comutil.h> using namespace ATL; 24

27 Setting Up a New CTI Connector Project Adding a COM Base Class to a CTI Connector Project Once you have built a CTI connector project, you must add the base adapter class that implements the provided COM interface: 1. Right-click your adapter project and select Add Class. 2. Choose the ATL Simple Object template, and click Open. 3. Click Names in the left navigation pane. Specify object names according to the following guidelines: Choose a Class and ProgID name that represent the CTI system with which you are integrating. In the Interface field, specify ISalesforceCTIAdapter. Make a note of the value that you choose for ProgID. You will need it again when you define a call center that uses your custom CTI adapter. To serve as examples in the remainder of the procedure, suppose you specified the following names: Short name = MyAdapterBase.h file = MyAdapterBase.h Class = CMyAdapterBase.cpp file = MyAdapterBase.cpp Type = MyAdapterBase Class Interface = ISalesforceCTIAdapter ProgID = MyAdapter.MyAdapter 4. Click Options in the left navigation pane. 5. Select the Connection points checkbox, and click Finish. 6. By default, the wizard automatically creates a new interface called ISalesforceCTIAdapter. You will need the version of ISalesforceCTIAdapter that has been defined by salesforce.com for your new CTI connector. To use salesforce.com's version, open the.h file that the wizard generated (MyAdapterBase.h in the example above). In this file: a. Delete the entry for interface ISalesforceCTIAdapter : IDispatch and its corresponding attributes and comments. b. Add the following lines to the #include statement section: #include "CTIAdapter.h" #include "ISalesforceCTIAdapter.h" c. Edit the class so that it inherits from ISalesforceCTIAdapter and CCTIAdapter, as follows: class ATL_NO_VTABLE CMyAdapterBase : public ISalesforceCTIAdapter, public CCTIAdapter d. Reset a default event linkage that the wizard created. In the example above, the wizard created: event interface _IMyAdapterBaseEvents; Replace that line with: event interface _ISalesforceCTIAdapterEvents; 25

28 Setting Up a New CTI Connector Project e. Add the following four methods to the public: section of the class header. Your class must implement each: public: /** * Returns the name and author of the adapter (for * example "Salesforce.com CTI Adapter For Cisco IPCC * Enterprise"). * bsname Contains the return value. */ STDMETHOD(GetAdapterName)(BSTR* bsname); /** * Returns the version of the adapter, (for example "1.01b"). * bsname Contains the return value. */ STDMETHOD(GetAdapterVersion)(BSTR* bsversion); /** * Receives an inbound XML-formatted message via COM * from the browser controller. It should be formatted * as (with as many parameters as needed): * <MESSAGE ID="MESSAGE_ID"> * <PARAMETER NAME="PARAM1" VALUE="VALUE1"/> * <PARAMETER NAME="PARAM2" VALUE="VALUE2"/> * </MESSAGE> * message The XML-formatted message to handle An HRESULT indicating whether the message * was successfully received and parsed */ STDMETHOD(UIAction)(BSTR message); /** * A method that takes in an XML string and generates a * COM UIRefresh event with it. * xml The XML to include with the event. */ virtual void SendUIRefreshEvent(_bstr_t xml); f. Save your changes and close the file. 7. Open the.cpp file that the wizard generated (MyAdapterBase.cpp in the example above). Add bodies for the following methods: STDMETHODIMP CMyAdapterBase::GetAdapterName(BSTR* bsname) { *bsname = SysAlloc(L"My Sample CTI Adapter"); } return S_OK; STDMETHODIMP CMyAdapterBase::GetAdapterVersion(BSTR* bsname) { *bsname = SysAlloc(L"1.0 Candidate 2"); } return S_OK; STDMETHODIMP CMyAdapterBase::UIAction(BSTR message) { //Do something with the incoming XML message here 26

29 Setting Up a New CTI Connector Project return S_OK; } void CMyAdapterBase::SendUIRefreshEvent(_bstr_t xml) { CCTILogger::Log(LOGLEVEL_HIGH,"Sending XML (len %d): %s",xml.length(),(wchar_t*)xml); _ISalesforceCTIAdapterEvents_UIRefresh(xml); } 8. Compile the project. You now have a functioning COM object that can send and receive XML. Instantiating a CCTIUserInterface Subclass The CTI connector class that provides the link between Salesforce, the end user, and a CTI system is called CCTIUserInterface. This class receives commands sent by the user, interprets events coming from the CTI server, and contains a representation of the SoftPhone user interface. Every CTI connector must have a subclass of CCTIUserInterface instantiated in its base COM class. The subclass implements the command methods specified in CCTIUserInterface and calls the event methods of the base class when appropriate to update the SoftPhone. Use the FinalConstruct method of the CTI connector's base class to instantiate a subclass of CCTIUserInterface. For example: HRESULT CMyAdapterBase::FinalConstruct() { m_pui = new CMyUserInterface(this); m_pui->initialize(); } Note: Always call the Initialize method after the CCTIUserInterface subclass is instantiated. This allows the SoftPhone to create all of its child user interface objects in advance. The subclass s constructor passes a pointer to the CTI connector base class and the number of available phone lines to the superclass constructor. For example: CMyUserInterface:: CMyUserInterface (CMyAdapterBase* padapter) :CCTIUserInterface(pAdapter,2) In this example, CMyUserInterface supports two phone lines. Your CMyUserInterface subclass needs to specify the maximum number of lines that can be used by a single call center user. This allows CCTIUserInterface to create those phone lines in advance. Use the FinalRelease method of the CTI connector's base class to delete your instance of CCTIUserInterface. This action terminates all related threads, allowing the.dll to be unloaded. For example: void CMyAdapterBase::FinalRelease() { if (m_pui) { delete m_pui; } CoUninitialize(); } 27

30 Writing an Event Sink Writing an Event Sink A CTI connector requires an event sink class that receives events from its associated CTI system and calls the appropriate event methods in the CCTIUserInterface subclass. As illustrated in this diagram, an event sink only requires a handler method for CTI system events that affect the appearance or functionality of a SoftPhone. These handler methods can then call one or more methods in CCTIUserInterface: Event sink implementations vary for each CTI system depending on the interfaces that a vendor makes available. For each implementation: 1. Determine the CTI system events that your event sink must capture. See Determining the CTI System Events that Require an Event Sink Handler on page 28 for information. 2. For each CTI system event that must be captured, write an event handler that calls the appropriate methods in your CCTIUserInterface subclass. See Writing an Event Sink Handler on page 29 for sample event sink handler code. Determining the CTI System Events that Require an Event Sink Handler In general, any CTI system event that affects a user's SoftPhone requires a handler in your event sink. While events vary from system to system, some common events that need a handler include: Events related to a user's CTI server connection Events related to a user's state (Ready for Calls, On a Call, Not Ready for Calls, and so on) Events related to the types of buttons that should be enabled Call events that affect the SoftPhone, such as the start and end of a call, or the fact that a caller has been put on hold Although the following types of events do not require event sink handlers for default Call Center Edition functionality, you may want to add event sink handlers for some of these events if you are implementing a new SoftPhone feature: Statistical events that appraise a user of CTI system usage, such as the number of call center users that are currently on a call Chat, , or other channel events that Call Center Edition does not currently support Informational events that apprise a user of activity on the system, such as the fact that another call center user has just logged in Call events that do not affect the SoftPhone, such as the fact that a call has been queued 28

31 Writing an Event Sink Writing an Event Sink Handler Event handlers in an event sink pass data related to an event directly to a comparable method in CCTIUserInterface. Some event handlers consist of single one-line calls to CCTIUserInterface, while others require deeper levels of processing. Simple Event Handler: OnCallEnd The following simple event handler passes an OnCallEnd event directly to the OnCallEnd method in CCTIUserInterface. The first parameter value indicates the ID of the call that is affected, while the second specifies whether the log for this call should be moved to the Previous Calls section of the SoftPhone: void CMyEventSink::OnCallEnd(EventArguments* parguments) { std::wstring scallobjectid = parguments->getvalue("callobjectid"); m_pui->oncallend(scallobjectid,true); } Complex Event Handler: OnCallRinging More complex event handlers perform additional processing and often must pass one or more PARAM_MAP parameters into CCTIUserInterface. A PARAM_MAP is a map of the form std::map<std::wstring,std::wstring>. Elements of a PARAM_MAP can be obtained by calling map["paramname"]. For example, OnCallRinging is a CTI system event that occurs when a call has arrived on any phone line. For incoming calls, OnCallRinging marks the start of a phone conversation and maps to the OnCallRinging method in CCTIUserInterface. For outgoing calls, OnCallRinging marks the start of the dialing process and maps to the OnCallDialing method in CCTIUserInterface. In addition to their other parameters, both the OnCallRinging and OnCallDialing methods in CCTIUserInterface require a PARAM_MAP attribute called mapinfofields. In addition, OnCallRinging requires a second PARAM_MAP attribute called mapattacheddata: mapinfofields includes information that pertains to the incoming call, such as the automatic number identification (ANI,the number from which the caller is calling), dialed number identification service (DNIS, the number the caller dialed), and any other custom fields that you add. This data displays in the SoftPhone. mapattacheddata includes all other data attached to an OnCallRinging event, such as account data generated from an interactive voice response (IVR) system. This data is used for performing SOSL and SOQL searches of Salesforce data and generally is not displayed in the SoftPhone interface. The following sample code implements the OnCallRinging handler in an event sink. For more information about the parameters in these calls, see the Salesforce CTI Toolkit Code Reference: void CMyEventSink::OnCallRinging(EventArguments* parguments) { PARAM_MAP mapinfofields; PARAM_MAP mapattacheddata; //First convert the attached data to a parameter map so that we //can later pass it to OnCallRinging() in CCTIUserInterface. //To simplify this example, this conversion is represented by //a call to a method called ResolveAttachedData(). //In practice, salesforce.com adapters handle this with several //lines of inline code. See the OnCallRinging() implementation //for your adapter for details. ResolveAttachedData(pArguments,mapAttachedData); //Determine the call object ID std::wstring scallobjectid = parguments->getvalue("callobjectid"); 29

32 SoftPhone Modification Options //We always perform a search bool bperformsearch = true; //We don't log internal calls bool blogcall =!parguments->isinternal(); //Check whether the call is incoming or outbound if (parguments->isincoming()) { //Assume that the call is from an external number (since those //calls do not have an associated call type), but if it is //internal, change it to CALLTYPE_INTERNAL int ncalltype = CALLTYPE_INBOUND; if (parguments->isinternal()) ncalltype = CALLTYPE_INTERNAL; //Pull the DNIS and ANI (the number from which the //caller is dialing), and put these values in mapinfofields std::wstring sani = parguments->getvalue("ani"); mapinfofields[key_ani]=sani; std::wstring sdnis = parguments->getvalue("dnis"); mapinfofields[key_dnis]=sdnis; //Call the OnCallRinging() event handler in CCTIUserInterface m_pui->oncallringing(scallobjectid,ncalltype,bperformsearch,blogcall,mapinfofields,mapattacheddata); } else { //If outbound, call the OnCallDialing() event handler in //CCTIUserInterface, and attach the mapinfofields PARAM_MAP. m_pui->oncalldialing(scallobjectid,mapinfofields,bperformsearch,blogcall); } } SoftPhone Modification Options You can modify CCTIUserInterface and CCTIAppExchange to customize the appearance and functionality of a SoftPhone. Whether you are building a new CTI connector or customizing one that has already been built by salesforce.com, you should read the following topics to understand how the code works and what elements are required to make a SoftPhone operational: Using the "Virtual" Keyword in Your CCTIUserInterface.h File on page 31 Implementing Call Center User Command Messages on page 31 Writing the Initialize Method for CCTIUserInterface on page 33 Enabling Call Center User Login on page 33 Enabling One-Step Transfers and Conferences on page 36 Enabling a Set of Buttons on page 36 Changing the Display Order of SoftPhone Buttons on page 37 Adding a Button on page 37 Enabling Reason Codes on page 38 Mapping CTI System Agent States tocall Center Edition User States on page 40 Adding a Custom Logo on page 43 Modifying Displayed Call Information on page 44 Customizing Automatically-Generated Call Logs on page 46 Translating Custom SoftPhone Labels on page 47 For more detailed information about the objects and methods in the Call Center Edition source code that salesforce.com provides, see the Salesforce CTI Toolkit Code Reference. 30

33 SoftPhone Modification Options Using the "Virtual" Keyword in Your CCTIUserInterface.h File When you write the.h file for your CCTIUserInterface subclass, you must use the virtual keyword for all the methods that you override, other than the constructor. This ensures that CTILib and other parts of the CTI connector call the correct method for your extended objects, regardless of how they are declared. For example, the interface for a subclass of CCTIUserInterface might include a constructor, destructor, and two additional overridden methods: #pragma once #include ctiuserinterface.h" class CMyAdapterBase; class CMyAdapterUserInterface : public CCTIUserInterface { public: CMyAdapterUserInterface(CMyAdapterBase* padapter); virtual ~CMyAdapterUserInterface(void); virtual void Initialize(); virtual void CallInitiate(PARAM_MAP& parameters); }; If the following method were to receive a MyAdapterUserInterface object instead of the CCTIUserInterface object that the method declaration expects, the virtual keyword prevents the code from calling the wrong implementation of the CallInitiate method : void foo(cctiuserinterface *x, PARAM_MAP parameters) { x->callinitiate(parameters); } Implementing Call Center User Command Messages As illustrated below, a CTI connector receives call center user command messages from the SoftPhone connector. These messages arrive formatted in XML and are received by the UIParseIncomingXMLMessage method of CCTIUserInterface. This method parses the incoming command message into a command ID and a set of parameters, and then passes the data to its UIHandleMessage method. UIHandleMessage routes the command message to the proper handler based on its command ID. If you need to override UIHandleMessage to add a call to a custom command message, your implementation should handle your custom message first and then make a call to the base UIHandleMessage method. For example, the following 31

34 SoftPhone Modification Options UIHandleMessage override handles a custom command message called "EXIT." Once "EXIT" is processed, the base UIHandleMessage method in CCTIUserInterface is called: void CDemoUserInterface::UIHandleMessage(std::wstring& message, PARAM_MAP& parameters) { if (message=="exit") { m_peventsink->setshellvisible(false); } CCTIUserInterface::UIHandleMessage(message,parameters); } Commands That Require Implementation in a CCTIUserInterface Subclass At minimum, a subclass of CCTIUserInterface must implement the following command methods: virtual void CTIConnect (PARAM_MAP &parameters); virtual void CTIDisconnect (PARAM_MAP &parameters); virtual void CTILogin (PARAM_MAP &parameters); virtual void CTILogout (PARAM_MAP &parameters); virtual void CallAlternate (PARAM_MAP &parameters); virtual void CallInitiate (PARAM_MAP &parameters); virtual void CallRelease (PARAM_MAP &parameters); virtual void CTIChangeAgentState (PARAM_MAP &parameters); virtual void CallAnswer (PARAM_MAP &parameters); virtual void CallHold (PARAM_MAP &parameters); virtual void CallRetrieve (PARAM_MAP &parameters); virtual void CallSetWrapupCode (PARAM_MAP &parameters); virtual void CallSaveWrapup(); virtual void CallInitiateTransfer (PARAM_MAP &parameters); virtual void CallInitiateConference (PARAM_MAP &parameters); virtual void CallOneStepTransfer (PARAM_MAP &parameters); virtual void CallOneStepConference (PARAM_MAP &parameters); virtual void CallCompleteTransfer (PARAM_MAP &parameters); virtual void CallCompleteConference (PARAM_MAP &parameters); virtual void CallAttachData (std::wstring scallobjectid, PARAM_MAP mapattacheddata); virtual CCTIForm* CreateLoginForm(); Note: You do not need to implement a command method if it is not supported by your CTI system. In most methods above, a PARAM_MAP is included that contains parameters relevant to the command. A PARAM_MAP is a map of the form std::map<std::wstring,std::wstring>. Elements of a PARAM_MAP can be obtained by calling map["paramname"]. For details on any required values in an individual command's PARAM_MAP, see the CCTIUserInterface documentation in the Salesforce CTI Connector Code Reference. Important: With the exception of UIHandleMessage, all subclass method implementations must first call their base class method implementation before performing any additional processing. For example: void MyAdapterUserInterface::CallInitiateTransfer(PARAM_MAP& parameters) { CCTIUserInterface::CallInitiateTransfer(parameters); 32

35 SoftPhone Modification Options <remaining code...> } In most cases UIHandleMessage should also call its base class, but if it is intercepting a message for special handling, it does not need to be called. Commands That Do Not Require Implementation in a CCTIUserInterface Subclass The following commands generally do not require implementation by a subclass of CCTIUserInterface. These commands only affect the SoftPhone and are not intended to have any effect on the underlying CTI system: UIUpdateSid (PARAM_MAP &parameters) CallUpdateComments (PARAM_MAP &parameters) ToggleComments (int nlinenumber) UIShowDialpad (int nlinenumber, int ndialpadtype, bool bupdatexml) UIHideDialpad (int nlinenumber, int ndialpadtype, bool bupdatexml) Writing the Initialize Method for CCTIUserInterface In general, the Initialize method of CCTIUserInterface is responsible for the following tasks: Establishing a connection between the CTI system and a user's machine Logging the user into the CTI system Associating the CTI connector's event sink with the CTI system and user session, where applicable In addition, Initialize is typically the method in which visual elements of the SoftPhone are defined, including the login form, the call center state area, reason codes, phone lines, the SoftPhone logo, and buttons. Once defined, these objects can then be shown or hidden by the other CTI connector methods as needed. Enabling Call Center User Login Two CCTIUserInterface methods are responsible for logging a call center user into a CTI system: CreateLoginForm() defines the user interface in which call center users enter their authentication information, such as a username and password. CTILogin() uses the data that a user provided in a login form to connect to the associated CTI system. CreateLoginForm() Method To implement a call center user login form, override the CreateLoginForm method in your CCTIUserInterface subclass. This method returns a CCTIForm, which is a container for the following types of form elements: Form Element Type CCTIStatic CCTIEditBox CCTICheckbox CCTIButton A static text element in the user interface, such as a welcome message A text box in which a call center user can enter a string A checkbox that a call center user can select and deselect A button that a call center user can click 33

36 SoftPhone Modification Options An individual login form element is identified and labeled according to its SID. By default, Salesforce includes SIDs and standardized, translated labels for the following commonly-used login form elements: AGENT_ID USER_ID LOGIN_NAME AGENT_NAME PASSWORD DN POSITION_ID QUEUE SKILL PLACE PERIPHERAL_ID SWITCH EXTENSION ROUTE_POINT DOMAIN LOGIN* (this SID is reserved for the mandatory "Login" button that is required on all Login forms) If you require a login form element that does not appear in the list above, use one of the ten custom element SIDs (CUSTOM1, CUSTOM2,... CUSTOM10) that Salesforce also provides, and specify its label with the SetLabel method. It is your responsibility to ensure that a custom login form element has the correct label for every language that your CTI adapter supports. For information, see Translating Custom SoftPhone Labels on page 47. Caution: A Salesforce-provided SID must be used for every element in your login form to ensure that user login information is properly saved by the application. Login form elements are displayed in the SoftPhone login form in the same order that they are added to the form. There must be at least one CCTIButton element with a SID of LOGIN that performs the actual login function. For example, the following CreateLoginForm method implementation creates a form with text boxes for Agent ID, Password, Peripheral ID, and MyCustomLoginField. It also includes a Save Values check box and a large green login button: CCTIForm* CMyAdapterUserInterface::CreateLoginForm() { CCTIForm* pform = new CCTIForm(); std::wstring sagentid; std::wstring spassword; std::wstring speripheralid; std::wstring smycustomloginfield; //Add form elements in the order they should appear. CCTIEditBox* pagentid = pform->addeditbox("agent_id"); pagentid->setvalue(sagentid); CCTIEditBox* ppassword = pform->addeditbox("password"); ppassword->setvalue(spassword); ppassword->setpassword(true); CCTIEditBox* pperipheralid = pform->addeditbox("peripheral_id"); pperipheralid->setvalue(speripheralid); //Use one of the custom SIDs for the custom field 34

37 SoftPhone Modification Options CCTIEditBox* pcustom = pform->addeditbox("custom1"); pcustom->setvalue(smycustomloginfield); //Use the SetLabel() method to specify the custom //field's label pcustom->setlabel( My Custom Login Field Label ); pform->addcheckbox("save_values","",true); CCTIButton* plogin = pform->addbutton("login"); plogin->setcolor("green"); plogin->setlongstyle(true); return pform; } CTILogin() Method When your CTILogin implementation is called, its parameter map contains the SIDs and values of the visual elements that you specified in the login form. You can use this data to connect directly to the CTI server and perform other user initialization functions. For example, the following CTILogin method implementation: 1. Performs some basic error checking 2. Initializes a user object and an event sink for receiving CTI system events 3. Makes a call tomyctisystemlib::ctilogin to finish the user's login void CMyAdapterUserInterface::CTILogin(PARAM_MAP& parameters) { // Check to see if we are already connected if (!GetConnected()) { CCTILogger::Log(LOGLEVEL_LOW,"Must be connected first to log in!"); return; } // Check to see if we are already logged in if (GetLoggedIn()) { CCTILogger::Log(LOGLEVEL_LOW,"Login attempted while already logged in."); return; } // Create a new call center user object to handle the login if (m_pagent!=null) m_pagent.release(); m_pagent.createinstance("myctisystemlib.comagent"); // Initialize the event sink m_peventsink->setagentptr(m_pagent); // Set the call center user object m_pagent->setvalue("agentid", parameters["agent_id"]); m_pagent->setvalue("agentpassword", parameters["password"]); m_pagent->setvalue("agentperipheralid", parameters["peripheral_id"]); // Log in to the CTI system m_pmyctisystemlib->ctilogin(m_pagent);} 35

38 SoftPhone Modification Options Enabling One-Step Transfers and Conferences In Call Center Edition, performing a transfer or conference while on a call can be either a one- or two-step process. In a two-step process: 1. The user clicks Transfer or Conference in the SoftPhone. This action places the first call on hold and displays a dial pad in which the user can enter a phone number. 2. The user clicks Dial to connect with the new phone number. After speaking with the third party, the user can click Complete Transfer or Complete Conference to complete the operation. In a one-step process, the user clicks Transfer or Conference, enters a number into the dial pad that is displayed, and clicks One-Step Transfer or One-Step Conference to complete the operation without speaking separately to the third party. Note: Other common terms for "one-step" transfers or conferences include "blind," "mute," "cold," or "single-step." Because not all CTI systems allow one-step transfer and conference functionality, CTI connector code disables one-step transfers and conferences by default. If you want to enable this functionality, call the SetOneStepTransferEnabled and SetOneStepConferenceEnabled methods at any time. For example, to call these methods in the Initialize method of your CCTIUserInterface subclass, use code similar to the following: void CMyAdapterUserInterface::Initialize() { //First call the Initialize() method of the base class. CCTIUserInterface::Initialize();... //Then enable one-step transfers and conferences later in //the method. CCTIUserInterface::SetOneStepTransferEnabled(TRUE); CCTIUserInterface::SetOneStepConferenceEnabled(TRUE);... } When a user clicks Transfer or Conference in a SoftPhone, the CTI connector code uses the CallInitiateTransfer or CallInitiateConference methods to transfer or conference the call in two steps. When a user clicks One-Step Transfer or One-Step Conference in a SoftPhone, the CTI connector code uses the CallOneStepTransfer or CallOneStepConference methods to transfer or conference the call in a single step. If your CTI system does not transmit the automatic number identifier (ANI) of the original call to the third party when a transfer or conference is initiated, you must attach this value to the call in CallOneStepTransfer, CallOneStepConference, CallInitiateTransfer, and CallInitiateConference. To do so, use the key "ANI" to attach the data as shown in this example: CCTILine* pline = GetLine(nLineNumber); CallAttachSingleItem(nLineNumber,"ANI",pLine->GetANI()); Attaching the ANI to the call in this manner allows the CTI adapter of the third party to interpret this value as the true ANI for the call. Enabling a Set of Buttons By default, a SoftPhone line is created with the following buttons (the ID that identifies each button in the CTI connector code is listed in parentheses): Answer (BUTTON_ANSWER) Reject (BUTTON_REJECT) Release (BUTTON_RELEASE) 36

39 SoftPhone Modification Options Hold (BUTTON_HOLD) Retrieve (BUTTON_RETRIEVE) Transfer (BUTTON_TRANSFER) Accept Transfer (BUTTON_ACCEPT_TRANSFER) Complete Transfer (BUTTON_COMPLETE_TRANSFER) Conference (BUTTON_CONFERENCE) Accept Conference (BUTTON_ACCEPT_CONFERENCE) Complete Conference (BUTTON_COMPLETE_CONFERENCE) All buttons are created when a line is initialized and are shown when necessary using the OnButtonEnablementChange event in CCTIUserInterface. To display a set of buttons in the SoftPhone, call OnButtonEnablementChange with the number of the affected line and the list of button IDs that should be shown. The system automatically shows the buttons in the list and hides all other buttons. For example, the following code displays the Answer and Reject buttons in line one: std::list<int> listenabledbuttons; listenabledbuttons.push_back(button_answer); listenabledbuttons.push_back(button_reject); CCTIUserInterface::OnButtonEnablementChange(1, listenabledbuttons) Changing the Display Order of SoftPhone Buttons SoftPhone buttons are displayed whenever they are enabled through the OnButtonEnablementChange event in CCTIUserInterface. The order in which they are displayed is controlled by the index values they are assigned in CTIConstants.h: #define BUTTON_ANSWER 10 #define BUTTON_REJECT 20 #define BUTTON_RELEASE 30 #define BUTTON_HOLD 40 #define BUTTON_RETRIEVE 50 #define BUTTON_TRANSFER 60 #define BUTTON_ACCEPT_TRANSFER 70 #define BUTTON_COMPLETE_TRANSFER 80 #define BUTTON_CONFERENCE 90 #define BUTTON_ACCEPT_CONFERENCE 100 #define BUTTON_COMPLETE_CONFERENCE 110 Buttons that have a lower index value are listed first in the SoftPhone, above buttons with greater index values. For example, if the Conference, Hold, Release, and Transfer buttons are enabled during a call, they appear in the following order: Release (ID=30) Hold (ID=40) Transfer (ID=60) Conference (ID=90) Adding a Button To add a new button to your SoftPhone: 1. Override the Initialize method of CCTIUserInterface: a. Call your base Initialize method first. 37

40 SoftPhone Modification Options b. Create a CCTIButton object with the ID and label that you want your button to have. c. Specify the width of the button with the SetLongStyle method. By passing FALSE into this method, your button will be short and you will be able to display an icon with the label. By passing TRUE into this method, your button will be long and will not have an associated icon. d. If you passed TRUE into the SetLongStyle method, specify the color of your button with the SetColor method. Color constant names are specified in CTIObject.h. e. If you passed FALSE into the SetLongStyle method, specify the URL of the icon that should be displayed within the button with the SetIconURL method. Icons should be exactly 46 pixels wide by 17 pixels high. Note: Salesforce.com recommends storing any button icons in your organization's Documents tab. See Adding a Custom Logo on page 43 for information. f. Make a call to UIAddButtonToAllLines that includes the index of where the new button should be placed in relation to other buttons. For example, if you added a button with an index value of 15, it would appear between the Answer and Reject buttons, if both of those buttons were visible (see Changing the Display Order of SoftPhone Buttons on page 37). 2. Add a method to your CCTIUserInterface subclass that handles the message that is sent to the CTI connector when the new button is clicked. 3. Override the UIHandleMessage method of CCTIUserInterface so that it calls the method you specify when the new button is clicked. The SoftPhone connector will pass the button's ID as the command message when this button is clicked. The following code sample shows an overridden Initialize method that adds a short Begin Recording button to the SoftPhone: //Define the index value for the new button. A value of 15 places //the new button just after the Answer button, or at the top of the //button list if the Answer button is not visible. Note that default //button indexes are stored in CTIObject.h. #define BEGIN_RECORDING 15 void CMyAdapterUserInterface::Initialize() { //First call the Initialize() method of the base class. CCTIUserInterface::Initialize(); //Then add the new button. Note that its ID, BEGIN_RECORDING, is //the command message that will be passed to the UIHandleMessage //method whenever this button is clicked. CCTIButton precordbutton("begin_recording","begin Recording"); //Set the size and icon of the button. precordbutton.setlongstyle(false); precordbutton.seticonurl(" //Add a copy of this button to all phone lines, in the location specified by //the BEGIN_RECORDING constant. UIAddButtonToAllLines(BEGIN_RECORDING,&pRecordButton); } Enabling Reason Codes A reason code is an explanation that users can select when they want to enter wrap-up mode after a call, set their user status to Not Ready for Calls, or log out of a CTI system entirely. Organizations can define sets of reason codes to track the activities of their call center users. 38

41 SoftPhone Modification Options Enabling Wrap-Up Reason Codes Wrap-up mode allows a call center user to complete work related to a call, such as filling out a call log, without interruption from a new inbound call. When wrap-up mode is available, some organizations require their users to enter reason codes before entering this mode so that their time can be more accurately tracked. To enable wrap-up codes for your CTI SoftPhone adapter, you must initialize them either in the Initialization method of CCTIUserInterface or when receiving an appropriate event. To initialize wrap-up codes in one of these methods: 1. Convert the codes to a PARAM_MAP in which the keys are the wrap-up code IDs and the values are the wrap-up code labels. A PARAM_MAP is a map of the form std::map<std::wstring,std::wstring>. Elements of a PARAM_MAP can be obtained by calling map["paramname"]. 2. Call the SetWrapupReasonCodes method in CCTIUserInterface with the PARAM_MAP as its only parameter. If this method is called multiple times, the existing wrap-up codes are replaced by the newly-specified ones. Once enabled, wrap-up codes are automatically displayed in the SoftPhone when a call center user's state is set to Wrap-Up. Enabling Not-Ready Reason Codes Not-ready reason codes allow an organization to track the reasons why a user cannot take a new inbound call. To enable not-ready reason codes: 1. In the CCTIUserInterface::Initialize method or just after user login, make a call to CCTIUserInterface::SetNotReadyReasonRequired. When this method is set to TRUE, a user is prompted to enter a reason code when he or she changes state to Not Ready for Calls. 2. Specify the reason codes for changing to the Not Ready for Calls state: a. Convert the not-ready reason codes to a PARAM_MAP in which the keys are the reason code IDs and the values are the reason code labels. A PARAM_MAP is a map of the form std::map<std::wstring,std::wstring>. Elements of a PARAM_MAP can be obtained by calling map["paramname"]. b. Call CCTIUserInterface::SetNotReadyReasonCodes with the PARAM_MAP as its only parameter. If this method is called multiple times, the existing codes are replaced by the newly-specified ones. Enabling Logout Reason Codes Similarly to wrap-up and not-ready reason codes, logout codes allow an organization to track the reasons why a call center user is logging out of the CTI system. To enable logout reason codes: 1. In the CCTIUserInterface::Initialize method or just after user login, make a call to CCTIUserInterface::SetLogoutReasonRequired for logout reason codes. When this method is set to TRUE, a user is prompted to enter a reason code when he or she attempts to log out. 2. Specify the reason codes for logout: a. Convert the logout reason codes to a PARAM_MAP in which the keys are the reason code IDs and the values are the reason code labels. A PARAM_MAP is a map of the form std::map<std::wstring,std::wstring>. Elements of a PARAM_MAP can be obtained by calling map["paramname"]. b. Call CCTIUserInterface::SetLogoutReasonCodes with the PARAM_MAP as its only parameter. If this method is called multiple times, the existing codes are replaced by the newly-specified ones. 39

42 SoftPhone Modification Options Example: Enabling Wrap-Up, Not-Ready, and Logout Reason Codes The following example shows an event sink method that might be called just after a user logs in to a CTI system.the attached data (parguments) specifies whether wrap-up, not-ready, and logout reasons are required, and if so, what the valid reason codes are: void MyAdapterEventSink::OnJustLoggedIn(EventArguments* parguments) { PARAM_MAP mapreasoncodes; // First extract the wrap-up codes from parguments if they // exist, and put them in the mapreasoncodes PARAM_MAP. EventArguments* preasoncodes=parguments->getvaluearray("incomingwrapups"); if (preasoncodes!=null) { for (int i=0;i<=preasoncodes->numelements();i++) { std::wstring sid = preasoncodes->getelementkey(i); std::wstring slabel = preasoncodes->getelement(i); mapreasoncodes[sid]=slabel; } // Make the call to SetNotReadyReasonCodes with the // mapreasoncodes PARAM_MAP. m_pui->setwrapupreasoncodes(mapreasoncodes); } // Next, extract the not-ready codes from parguments if // they exist, and put them in the mapreasoncodes PARAM_MAP. EventArguments* pnrreasoncodes=parguments->getvaluearray("notreadyreasoncodes"); if (pnrreasoncodes!=null) { mapreasoncodes.clear(); for (int i=1;i<=pnrreasoncodes->numelements();i++) { std::wstring sid = pnrreasoncodes->getelementkey(i); std::wstring slabel = pnrreasoncodes->getelement(i); mapreasoncodes[sid]=slabel; } } // Make the call to SetNotReadyReasonCodes with the // mapreasoncodes PARAM_MAP. m_pui->setnotreadyreasoncodes(mapreasoncodes); // Finally, extract the logout codes from parguments if // they exist, and put them in the mapreasoncodes PARAM_MAP. EventArguments* plogoutreasoncodes=parguments->getvaluearray("logoutreasoncodes"); if (plogoutreasoncodes!=null) { mapreasoncodes.clear(); for (int i=1;i<=plogoutreasoncodes->numelements();i++) { std::wstring sid = plogoutreasoncodes->getelementkey(i); std::wstring slabel = plogoutreasoncodes->getelement(i); mapreasoncodes[sid]=slabel; } // Make the call to SetLogoutReasonCodes with the // mapreasoncodes PARAM_MAP. m_pui->setlogoutreasoncodes(mapreasoncodes); } } Mapping CTI System Agent States tocall Center Edition User States By default, a Salesforce CTI adapter allows call center users to be in one of the following states while using Call Center Edition (the call center state ID that is used in the CTI connector code is also listed): 40

43 SoftPhone Modification Options Call Center State Log Out Ready for Calls Not Ready for Calls On a Call Wrap-Up Logged In Call Center State ID AGENTSTATE_LOGOUT AGENTSTATE_READY AGENTSTATE_NOT_READY AGENTSTATE_BUSY AGENTSTATE_WRAPUP AGENTSTATE_LOGGED_IN The user is not logged in to a CTI system. The user is not currently on a call, and is prepared to accept the next inbound call. The user is not currently on a call, and is not prepared to receive the next inbound call. The user is currently connected to a caller. The user is currently connected to a caller, and wishes to go directly to the Not Ready for Calls state when the call is complete. The user is logged into the system. Note that this state is meant to be used in those CTI systems that do not support call center user states. All CTI system agent states must be mapped to one of the Call Center Edition states for the SoftPhone to behave appropriately. For example, a CTI system might have a state for talking on the phone and another state for waiting on hold. In both cases, these states should be mapped to the Call Center Edition Busy state so that the SoftPhone does not display functionality that should not be available when a user is on a call. To map CTI system agent states to Call Center Edition user states, modify the AgentStateTo method in your CCTIUserInterface subclass. AgentStateTo is used by the OnAgentStateChange event handler to map your CTI system agent state values to the correctcall Center Edition user state. For example: std::wstring MyAdapterUserInterface::AgentStateTo(enumMY_AgentState State) { switch( State ) { case Logout: return AGENTSTATE_LOGOUT; case NotReady: case Login: return AGENTSTATE_NOT_READY; case Available: return AGENTSTATE_READY; case BusyOther: case Talking: case Reserved: case Hold: case Unknown: return AGENTSTATE_BUSY; case WorkNotReady: case WorkReady: return AGENTSTATE_WRAPUP; default: return ""; } } 41

44 SoftPhone Modification Options Displaying Call Center Edition User States All call center states are created when a line is initialized and are selectively displayed in the SoftPhone's call center state drop-down list using the OnAgentStateEnablementChange event in CCTIUserInterface. To change the set of call center states that are available in the SoftPhone at any one time, call OnButtonEnablementChange with the list of call center states that should be available and the ID of the currently selected state. The SoftPhone automatically updates the call center state drop-down list. For example, the following event sink method creates a list of enabled agent states depending on the current agent state and then makes a call to OnAgentStateEnablementChange: void CCTIOSEventSink::SetAgentStateEnablement(std::wstring& sagentstate) { std::list<std::wstring> listenabledagentstates; if (sagentstate == AGENTSTATE_LOGOUT) { // do nothing } else if (sagentstate == AGENTSTATE_NOT_READY sagentstate == AGENTSTATE_READY) { listenabledagentstates.push_back(agentstate_ready); listenabledagentstates.push_back(agentstate_not_ready); listenabledagentstates.push_back(agentstate_logout); } else if (sagentstate == AGENTSTATE_BUSY) { // if an agent is busy (on a call), show busy status and wrapup (allow agent to queue wrapup) listenabledagentstates.push_back(agentstate_busy); listenabledagentstates.push_back(agentstate_wrapup); } else if (sagentstate == AGENTSTATE_WRAPUP) { listenabledagentstates.push_back(agentstate_wrapup); } else if (sagentstate == AGENTSTATE_LOGGED_IN) { // do nothing } m_pui->onagentstateenablementchange(listenabledagentstates, sagentstate); } Adding a New Call Center Edition User State To add a new call center state to your SoftPhone: 1. Override the Initialize method of CCTIUserInterface: a. Call your base Initialize() method first. b. Make a call to UIAddAgentState() with the ID, display order, and label for your new call center state. Display order is specified as an integer with the lowest number displaying first in the list. The display order values for default call center states are: AGENTSTATE_READY AGENTSTATE_NOT_READY AGENTSTATE_WRAPUP AGENTSTATE_BUSY AGENTSTATE_LOGOUT If two or more call center states are assigned the same display order number, the state that was most recently defined appears first. For example, if you add a new call center state with display order "2," the new call center state is displayed 42

45 SoftPhone Modification Options between AGENTSTATE_NOT_READY and AGENTSTATE_WRAPUP, since the default call center states were already defined in the base Initialize() method. 2. Override the CTIChangeAgentState method of CCTIUserInterface so that the SoftPhone displays the correct behavior when your new call center state is selected. 3. Override the CTIIsOccupiedAgentState method of CCTIUserInterface so that the method returns the appropriate boolean value when your new call center state is selected. OnAgentStateChange uses CTIIsOccupiedAgentState to determine whether it is time to move an open call log to the Previous Calls section of the SoftPhone: When CTIIsOccupiedAgentState returns True, the call log remains open for editing. When CTIIsOccupiedAgentState returns False, the call log is saved and moved to the Previous Calls section. By default, the two states that return True are AGENTSTATE_BUSY ( On a Call ) and AGENTSTATE_WRAPUP. If your new call center state indicates that a phone line is engaged, then it should also return True when passed in to this method. The following code sample shows an overridden Initialize method that adds a "Processing Account" call center state: void CMyAdapterUserInterface::Initialize() { //First call the Initialize() method of the base class. CCTIUserInterface::Initialize(); } //Then add the new call center state. Note that its ID, PROCESSING_ACCOUNT, is //the command message that will be passed to the CTIChangeAgentState() //method whenever this call center state is selected. UIAddAgentState(L"PROCESSING_ACCOUNT",5,L"Processing Account"); Adding a Custom Logo You can customize the logo that appears at the bottom of a SoftPhone by calling SetLogoImageUrl from an overridden Initialize method in your CCTIUserInterface subclass. For example: void CMyAdapterUserInterface::Initialize() { //First call the Initialize() method of the base class. CCTIUserInterface::Initialize();... //Then set the logo URL in the body of the method. SetLogoImageUrl(" } Logos must be no more than 116 pixels wide by 31 pixels high and must be stored on a server that is accessible to all Call Center Edition users. Salesforce.com recommends that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. To determine the URL of a logo that is stored in the Documents tab: 1. View the document detail page in Salesforce. 2. Right-click on the logo image and select Properties. The logo URL is located next to the Address (URL) or Location parameter in the dialog. It should be of the form 43

46 SoftPhone Modification Options Modifying Displayed Call Information By default, two types of call-related information are displayed in the SoftPhone when a call begins: Call information fields show information about the call itself, such as the number from which the caller is dialing (the automatic number identification or ANI) and the number that was dialed (the dialed number identification service or DNIS). These fields are specified in the &mapinfofields parameter of CCTIUserInterface::OnCallRinging. For information about modifying these fields, see Adding a Call Information Field on page 44. Call-related records show Salesforce records that are related to the call, such as contacts, leads, activities, or accounts. These records are discovered by running the CTIAppExchange::Search method on the ANI and any data in the &mapattacheddata parameter from CCTIUserInterface::OnCallRinging. For more information, see Displaying Call-Related Records on page 45. Adding a Call Information Field To add a custom call information field to a SoftPhone, simply add the field to the mapinfofields PARAM_MAP in CCTIUserInterface::OnCallRinging. For example, the following implementation of OnCallRinging adds fields for the number from which the caller is dialing (the automatic number identification or ANI), and the number that was dialed (the dialed number identification service or DNIS). You can use parguments to add any other field that is passed in from your CTI system: void CMyEventSink::OnCallRinging(EventArguments* parguments) { PARAM_MAP mapinfofields; PARAM_MAP mapattacheddata; //First convert the attached data to a parameter map so that we //can later pass it to OnCallRinging() in CCTIUserInterface. //To simplify this example, this conversion is represented by //a call to a method called ResolveAttachedData(). //In practice, salesforce.com adapters handle this with several //lines of inline code. See the OnCallRinging() implementation //for your adapter for details. ResolveAttachedData(pArguments,mapAttachedData); //Determine the call object ID std::wstring scallobjectid = parguments->getvalue("callobjectid"); //We always perform a search bool bperformsearch = true; //We don't log internal calls bool blogcall =!parguments->isinternal(); //Check whether the call is incoming or outbound if (parguments->isincoming()) { //Assume that the call is from an external number (since those //calls do not have an associated call type), but if it is //internal, change it to CALLTYPE_INTERNAL int ncalltype = CALLTYPE_INBOUND; if (parguments->isinternal()) ncalltype = CALLTYPE_INTERNAL; //Pull the DNIS and ANI (the number from which the //caller is dialing), and put these values in mapinfofields std::wstring sani = parguments->getvalue("ani"); mapinfofields[key_ani]=sani; std::wstring sdnis = parguments->getvalue("dnis"); mapinfofields[key_dnis]=sdnis; 44

47 SoftPhone Modification Options //Call the OnCallRinging() event handler in CCTIUserInterface m_pui->oncallringing(scallobjectid,ncalltype,bperformsearch,blogcall,mapinfofields,mapattacheddata); } else { //If outbound, call the OnCallDialing() event handler in //CCTIUserInterface, and attach the mapinfofields PARAM_MAP. m_pui->oncalldialing(scallobjectid,mapinfofields,bperformsearch,blogcall); } } Displaying Call-Related Records When a call arrives, the CTI connector searches Salesforce for any related records using the Apex API. The CTI connector first searches based on data attached to the call, such as an account number that was entered by the caller during an interactive voice response (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 A CTI connector built by salesforce.com implements a default method of handling data attached to calls. If you are writing a new IVR script, you can either follow this default method to format attached data or modify the CTI connector code to handle the attached data in the format your existing script uses. The default Salesforce method expects attached data in the form of key-value pairs: The keys should be of the form Object.FieldName, where 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. For example, for Case.CaseNumber, " " would be a valid value. Note: Values must be exact matches for the Salesforce record. For example, if "1001" is specified but the case number is actually " ," the record is not returned. If your IVR attaches data that is not in this format, but you wish to trigger a search using the attached data, you can resolve it in your implementation of OnCallRinging. In this method you can convert the data into a format that Call Center Edition can use. OnCallRinging should return a PARAM_MAP that contains valid key-value pairs. Examples of Attached Data Search Queries Call Center Edition uses attached data to generate an Sforce Obejct Query Language (SOQL) query. For example, if the attached data contains Case.CaseNumber=" ", Call Center Edition generates and executes the following query: SELECT <fields> FROM Case WHERE CaseNumber=' ' 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 Case.CaseNumber=" " and Case.Priority="High", the search generates and executes the following query: SELECT <fields> FROM Case WHERE CaseNumber=' ' 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 example, if the attached data contains 45

48 SoftPhone Modification Options Case.CaseNumber=" " and Account.AccountNumber="1234", the search generates and executes the following queries: SELECT <fields> FROM Case WHERE CaseNumber=' ' SELECT <fields> FROM Account WHERE AccountNumber='1234' Handling Automatic Number Identification (ANI) Search If the search on attached data produces no results or if no attached data was found, Call Center Edition performs an Sforce Object Search Language (SOSL) search on the automatic number identification (ANI) field (the number from which a caller is dialing). The search is only performed on objects that are defined in the user's SoftPhone layout, and only returns the fields that the layout specifies. For example, if the ANI is and the user's SoftPhone layout specifies that only the First Name, Last Name, and fields of contact records should be displayed, Call Center Edition generates and executes the following SOSL query: FIND { } IN PHONE FIELDS RETURNING Contact ( , FirstName, LastName) Note: ANIs should be stripped of all non-standard digits. For example, if your phone system generates ANIs preceded by a "1," like , the first "1" should be stripped off the number for the search to return successfully. Overriding Default Search Behavior To override the default search behavior and implement your own query generators: 1. Create a subclass of CTIAppExchange. 2. Override the method CCTIUserInterface::GetSearch to return an instance of your Apex search object. All calls to search will now use your search instead of the default. See the Salesforce CTI Toolkit Code Reference for details. 3. Override the method CCTIAppExchange::Search to implement your own query generators. Customizing Automatically-Generated Call Logs By default, the AddCallLog method of CCTIAppExchange automatically generates a closed task record for every completed SoftPhone call. This call log task record includes the following information about the call: The call object ID, a field that uniquely identifies a single call in Salesforce The date that the call occurred The duration of the call, in seconds The type of call that took place (inbound, outbound, or internal) The owner of the call record (typically the user who initiated an outbound or internal call, or the user who received an inbound call) The text, if any, that was entered in the SoftPhone comments text box In addition, the call log task record can also include one link to an account, one link to either a contact, lead, or person account (a "who"), and one link to any other Salesforce record that is not a contact, lead, or person account (a "what"). Associating Call Logs with Multiple Records Because there is a restriction on the number of records that can be associated with a task, AddCallLog must choose how to handle calls with multiple account, "who," or "what" records. For example, a support user might need to create two cases ("what" objects) while on a call because a customer has two separate problems. Since only one case can be associated with a single call log, AddCallLog must choose which case to associate. By default, AddCallLog handles this type of situation as follows: 46

49 SoftPhone Modification Options Multiple accounts: AddCallLog chooses one account record to associate with the call log, and nothing is associated with the other account objects. Multiple "who"s: AddCallLog chooses one "who" record to associate with the call log, and nothing is associated with the other "who" records. Multiple "what"s: AddCallLog does not associate the call log with any of the "what" records. You can customize the strategy for handling multiple records by modifying the AddCallLog method in your own CTIAppExchange subclass. One strategy to consider is to make duplicate call log tasks for multiple records of a particular type. In the example above, AddCallLog would make two identical call log task records - one for each case that was generated during the call. When using this strategy, Call Center Edition reports must be modified to group call logs by the Call Object ID field so that duplicate call logs are not counted as two separate calls. In addition, reports that sum call duration must be filtered so that the same call is not included twice. Defining Custom SoftPhone Labels You can define custom labels for call information fields with the SetInfoFieldLabel() method of CCTIUserInterface. To do so, modify the Initialize() method of your CCTIUserInterface subclass with a call to SetInfoFieldLabel() for every label that you want to specify. SetInfoFieldLabel() takes two strings as parameters: the sid of the field that you want to rename, and the custom label. For example, to change the label for the QUEUE info field to "Customer List," add the following line to your Initialize() method: SetInfoFieldLabel("QUEUE", "Customer List"); When a field with the sid of "QUEUE" is placed in the mapinfofields PARAM_MAP in CCTIUserInterface::OnCallRinging, the field is displayed in the SoftPhone with a label of "Customer List". This table lists the default labels for call information fields that are built into Salesforce CTI adapters: Call Information Field sid ANI DNIS Queue Segment Customer Type Default Label Caller ID # Dialed # Queue Segment Customer Type You can modify the labels for these default fields, or define labels for custom call information fields that you add to the mapinfofields PARAM_MAP of your CCTIUserInterface::OnCallRinging method implementation. Translating Custom SoftPhone Labels By default, all standard SoftPhone labels are translated and displayed in the language of the call center user. If you need to support localized labels for a custom SoftPhone component or call information fields, you can use one of two strategies: Create a different CTI adapter for each locale that you want to support With this strategy, the labels are hard-coded in the supported language of the adapter. While easy to implement, this method can lead to maintenance issues if you need to support adapters for several different languages. Create a single CTI adapter that supports all languages 47

50 SoftPhone Modification Options With this strategy, the adapter performs a search for the user's language and then adjust the label text accordingly. This method can take longer to implement, but simplifies maintenance if you need to support adapters for several different languages. Labels for all SoftPhone components are specified with the LABEL attribute on associated SoftPhone XML elements. For more information, see SoftPhone XML Format Reference on page

51 Chapter 4 Call Center Definition Files A call center definition file specifies a set of fields and values that are used to define a call center in Salesforce for a particular CTI adapter. Salesforce uses call center definition files in order to support the integration of Call Center Edition with multiple CTI system vendors. By default, any CTI adapter installation package includes a default call center definition file that works specifically with that adapter. This XML file is located in the adapter installation directory and is named after the CTI system that it supports. For example, the Cisco IPCC Enterprise adapter's default call center definition file is named CiscoIPCCEnterprise7x.xml. The first instance of a call center for a particular CTI adapter must be defined by importing the adapter's call center definition file into Salesforce. Subsequent call centers can be created by cloning the original call center that was created with the import. If your organization modifies an adapter or builds a new one, you must customize the adapter's call center definition file so that it includes any additional call center information that is required. For example, if you are building a CTI adapter for a system that supports a backup server, your call center definition file should include fields for the backup server's IP address and port number. CTI adapters for systems that do not make use of a backup server do not need those fields in their associated call center definition files. Note: Once a call center definition file has been imported into Salesforce, the set of fields that were specified in the file cannot be modified. The values assigned to those fields, however, can be changed within Salesforce. If you have built a custom CTI adapter you must write a call center definition file to support it. Use a text or XML editor to define an XML file according to the guidelines in the following topics. Call Center Definition File XML Format A call center definition file consists of three XML elements: callcenter, section, and item. The following list provides details about the properties and attributes of each element: callcenter This element represents a definition for a single call center phone system. At least one <callcenter> element must be included in every call center definition file. A <callcenter> element consists of one or more <section> elements. section This element represents a grouping of related data fields, such as server information or dialing prefixes. When a call center is edited in Salesforce, fields are organized by the section to which they are assigned. A <section> element belongs to a single <callcenter> element, and consists of one or more <item> elements. Attributes: 49

52 Call Center Definition File XML Format Name Type Required? sortorder Positive Integer Required The order in which the section should appear when the call center is edited in Salesforce. For example, a section with sortorder="1" comes just before a section with sortorder="2". The values for sortorder must be non-negative integers, and no numbers can be skipped within a single call center definition. For example, if there are three section elements in a call center definition file, one <section> element must have sortorder="0", one <section> element must have sortorder="1", and one <section> element must have sortorder="2". name Required The internal name of the section as defined in the Salesforce database. You can use this value to refer to the section when writing custom adapter code. Names must be composed of only alphanumeric characters with no white space or other punctuation. They are limited to 40 characters each. Names beginning with "req" are reserved for required Salesforce sections only (see "Required Call Center Elements and Attributes" in the Salesforce online help). Other reserved words that cannot be used for the name attribute include label, sortorder, internalnamelabel, and displaynamelabel. label The name of the section when viewed in Salesforce. Labels can be composed of any string of UTF-8 characters. They are limited to 1000 characters each. item This element represents a single field in a call center definition, such as the IP address of a primary server or the dialing prefix for international calls. When call centers are edited in Salesforce, each <item> element is listed under the section to which it belongs. You can have multiple <item> elements in a <section> element. Attributes: Name Type Required? sortorder Positive Integer Required The order in which the item should appear when the call center is edited in Salesforce. For example, an item with sortorder="1" comes just before an item with sortorder="2". The values for sortorder must be non-negative integers, and no numbers can be skipped within a single call center definition. For example, if there are three item elements in a call center definition file, one <item> element must have sortorder="0", one 50

53 Required Call Center Elements and Attributes Name Type Required? <item> element must have sortorder="1", and one <item> element must have sortorder="2". name Required The internal name of the item as defined in the Salesforce database. You can use this value to refer to the item when writing custom adapter code. Names must be composed of only alphanumeric characters with no white space or other punctuation. They are limited to 40 characters each. Names beginning with "req" are reserved for required Salesforce sections only (see "Required Call Center Elements and Attributes" in the Salesforce online help). Other reserved words that cannot be used for the name attribute include label, sortorder, internalnamelabel, and displaynamelabel. label The name of the item when viewed in Salesforce. Labels can be composed of any string of UTF-8 characters. They are limited to 1000 characters each. Required Call Center Elements and Attributes There must be one <section> that includes <item> elements with the following names in every call center definition file: <item> Name reqinternalname reqdisplayname req reqprogid Represents the unique identifier for the call center in the database. It must have a sortorder value of "0", and its value must be specified in the call center definition (see "Specifying Values for <item> Elements" in the Salesforce online help). A value for "reqinternalname" must be composed of no more than 40 alphanumeric characters with no white space or other punctuation. It must start with an alphabetic character and must be unique from the "reqinternalname" of all other call centers defined in your organization. Represents the name of the call center as displayed in Salesforce. It must have a sortorder value of "1". A value for "reqdisplayname" has a maximum length of 1000 UTF-8 characters. Represents a description of the call center. A value for "req" has a maximum length of 1000 UTF-8 characters. Represents the Program ID (progid) of the CTI adapter that should be used for this call center. This value is specified in the default call center definition file that comes bundled with every CTI adapter installer, or in the base COM class of a custom CTI adapter. Specifying Values for <item> Elements With the exception of the "reqinternalname" <item>, whose value must always be specified in a call center definition file, you can specify <item> values either in the call center definition file or in Salesforce once the definition file has been imported. 51

54 Sample Call Center Definition File To specify a value for an <item> element in a cell center definition file, place the value between the opening and closing tags of the <item>. For example: <item sortorder="0" name="reqinternalname" label="call Center Internal Label">MyCallCenter</item> sets the value of the "reqinternalname" <item> to "MyCallCenter". Note that any <item> value other than the value for "reqinternalname" can be edited in Salesforce after the call center definition is imported. Sample Call Center Definition File The following XML code makes up a sample call center definition file: <!-- All sections and items whose name value begins with "req" are required in a valid call center definition file. The sortorder and label attributes can be changed for all required sections and items except reqgeneralinfo, reqinternalname, and reqdisplayname, in which only the label attribute can be altered. Note that the value for the reqinternalname item is limited to 40 alphanumeric characters and must start with an alphabetic character. reqinternalname must be unique for all call centers that you define. --> <callcenter> <section sortorder="0" name="reqgeneralinfo" label="general Info"> <item sortorder="0" name="reqinternalname" label="internal Name">callCenter001</item> <item sortorder="1" name="reqdisplayname" label="display Name">My Call Center</item> <item sortorder="2" name="req" label="">located in San Francisco, CA</item> <item sortorder="3" name="reqprogid" label="cti Connector ProgId">MyAdapter.MyAdapter.1</item> </section> <section sortorder="1" name="serverinfo" label="cti Server Info"> <item sortorder="0" name="hosta" label="host A">Host A</item> <item sortorder="1" name="porta" label="port A">Port A</item> <item sortorder="2" name="hostb" label="host B">Host B</item> <item sortorder="3" name="portb" label="port B">Port B</item> <item sortorder="4" name="peripheralid" label="peripheral ID">1000</item> </section> <section sortorder="2" name="dialingoptions" label="dialing Options"> <item sortorder="0" name="outsideprefix" label="outside Prefix">1</item> <item sortorder="1" name="longdistprefix" label="long Distance Prefix">9</item> <item sortorder="2" name="internationalprefix" label="international Prefix">01</item> </section> </callcenter> 52

55 Chapter 5 Packaging and Publishing a CTI Adapter Once you have finished updating your CTI connector code, you can package it into a fully functional CTI adapter and publish it on the AppExchange. Packaging a CTI Adapter To package your CTI connector code into a CTI adapter: 1. Update the GetAdapterName() and GetAdapterVersion() methods in your COM base class as appropriate. See Steps 6 and 7 in Adding a COM Base Class to a CTI Connector Project on page 25 for details. 2. Verify that you have specified a valid client key in CTIAppExchange.h. For more information, see Specifying a Valid CTI Client Key on page Compile the CTI connector into a.dll and test it with the Call Center Edition SoftPhone connector. 4. Bundle the required files to create a complete CTI adapter package. While the contents of a CTI adapter code package will vary, all CTI adapter code packages include the following: The SoftPhone connector executable (SalesforceCTI.exe) The SoftPhone connector portion of a SoftPhone CTI adapter. This file comes as a pre-compiled executable with the logo. Your CTI connector.dll (<your_cti_system_adapter_name>.dll The.dll component that makes up your customized CTI connector Any dynamically-linked libraries that are required for the CTI system Most CTI adapter implementations require additional CTI-system-specific.dll files to enable communication. The salesforce.com Office Toolkit Library (SF_MSApi4.dll) The.dll component that is required to access the Salesforce Apex API. Microsoft XML Library 6 (msxml6.dll and msxml6r.dll) The.dll files that enable the SoftPhone connector to translate the SoftPhone user interface XML into HTML. A default call center definition file (<your_cti_system_adapter_name>.xml) The default call center definition file for a call center that uses your custom adapter. For more information, see Call Center Definition Files on page Create an installer for the CTI adapter package. To rapidly deploy the adapter to all machines in a call center at once, generate an.msi file that can be used with your preferred Software Management System. 53

56 Publishing a CTI Adapter on the AppExchange Publishing a CTI Adapter on the AppExchange You can publish customized CTI adapters on the AppExchange so that other Salesforce users can purchase and use them in their own organizations. To do so you'll need to perform the following tasks. Each task is further detailed in the sections that follow: 1. Decide who will be the developer and publisher. 2. (Developer) Request a blank listing for your adapter. 3. (Publisher) Create a publisher profile. 4. (Developer) Associate a publisher profile with your listing. 5. (Developer or publisher) Edit your listing. 6. (Developer or publisher) Assign your listing to an Exchange and category. 7. (Developer or publisher) Prepare your listing for the AppExchange Application Review Board (ARB). 8. (Publisher) Submit your listing to the ARB. 9. (Publisher) Publicly display your listing on the AppExchange after approval. Determining the Developer and Publisher Roles for your Listing Every AppExchange listing is associated with two roles: The Developer The Publisher Manages the CTI adapter installation package and optionally assigns the publisher role to another person Manages the content of the CTI adapter listing and acts as the point person for the listing's ARB review The developer and the publisher can be the same person, but typically the developer is the person who built the CTI adapter while the publisher is a member of an organization's marketing department. Only the developer can assign or change the designated publisher for a listing. (Developer) Requesting a Blank Listing Because a CTI adapter installation package is not a traditional AppExchange app, the developer must first request a blank listing to publish it on the AppExchange: 1. Log in to by clicking AppExchange Login at the top of the page. Use your Salesforce username and password. 2. Read and accept the terms of use and click Continue. 3. In the Manage My Apps tab, click Request Assistance. In the form that appears, specify that you want to post a new CTI adapter and that you need a blank AppExchange listing. A salesforce.com representative will contact you when the listing becomes available in your AppExchange account. (Publisher) Creating a Publishing Profile A listing's publishing profile identifies the person or organization responsible for supporting the product featured in the listing. When visitors view a CTI adapter listing on the AppExchange, they see its publishing profile's name, description, and public information in the Publisher tab of the listing. The publisher is responsible for creating the publishing profile: 1. Log in to by clicking AppExchange Login at the top of the page. Use your Salesforce username and password. 2. Click the Manage My Publishing Profile tab. 3. Click Create a Profile. 54

57 Publishing a CTI Adapter on the AppExchange 4. Enter profile information according to the table below: Field Name Username Phone Publisher Name Publisher Web Site URL Support URL Contact Phone The publisher's username The publisher's phone number The name of the individual or organization responsible for supporting the CTI adapter A description of the publisher or publisher's organization A website that users can visit to learn about the publisher's organization A website that users can visit for CTI adapter support The phone number of the publisher or publisher's organization Publicly or Privately Viewable Private Private Public Public Public Public Public 5. Click Save. (Developer) Associating a Publisher Profile with a Listing An AppExchange listing must be associated with a publisher profile before it can be submitted for ARB review. Only the developer can change the publisher profile for a listing: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Click Change Publisher. 3. If you assumed both the developer and publisher roles for this listing, select My Publisher Profile. If there is a separate publisher for this listing, select Name and enter their Salesforce username (for example, [email protected]). 4. Click Assign Publisher. When you enter the username for a valid publisher, the publisher will see the listing on their Manage My Apps tab. The publisher can then carry out the appropriate tasks as described in the remainder of this chapter. If you specify an invalid publisher username, your listing cannot be submitted for ARB review. (Developer or Publisher) Editing a Listing To edit the content of your CTI adapter listing: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Click Edit. 3. Enter listing information according to the table below: Field Name Public Application Title The name of your CTI adapter as you would like it to appear on the AppExchange (for example, "Acme CTI Adapter For Cisco IPCC Enterprise"). 55

58 Publishing a CTI Adapter on the AppExchange Field Name Application Abstract Application Feature Bullets Compatible salesforce.com editions Additional System Requirements Screenshot Thumbnail Link to Presentation Datasheet Customization Guide Demo User Name Demo Password Sales Pricing Info A brief summary of what your CTI adapter does. This abstract is limited to 255 characters. A longer description of what your CTI adapter does and how a user can benefit from it. In writing your description, please note the following: Avoid the use of marketing terms, value judgments, jargon, and exaggerated claims. Provide contact information for at least one support channel, including a valid address, phone number, or a URL that points to a contact form. Limit your description to 1200 characters. Up to three short statements about the main features of your CTI adapter. This is a good place to highlight what makes your CTI adapter different from others that are currently available. The Salesforce Editions that are compatible with your CTI adapter. Any requirements specific to your CTI adapter, such as supported browsers, call center systems, operating systems, minimum memory, and add-on Salesforce features, such as Territory Management. A screenshot that illustrates your CTI adapter. Screenshots should be no larger than 850 x 600 pixels. Click Change to upload an image. A smaller version of your screenshot. Thumbnails should be no larger than 165 x 115 pixels. Click Change to upload an image. A link to a Breeze, Flash, or other online presentation that showcases your CTI adapter (for example, A PDF datasheet that includes highlights of your CTI adapter at a glance. A Microsoft Word template for this datasheet is available at Click Change to upload a datasheet. A PDF guide that highlights implementation and customization details for your CTI adapter. Click Change to upload a customization guide. Not applicable Not applicable If you are offering your CTI adapter for no charge, include a statement to this effect. If you are selling your CTI adapter: Specify the cost and pricing structure (such as subscription, per seat license fee, or a one-time license). 56

59 Publishing a CTI Adapter on the AppExchange Field Name Sales Contact Sales Contact URL Sales Contact Phone License Agreement If users are eligible for a free trial before prices take effect, say so, but make it clear that you offer a fee-based service. If pricing is variable or only established via communication with a sales representative, provide those details. The address of a sales contact at your organization. The URL for a page where users can purchase your CTI adapter. The phone number of a sales contact at your organization. Your organization's licensing agreement text if you are selling your CTI adapter. If you do not provide text, the default AppExchange agreement is displayed. 4. Click Save. A preview of your listing displays. 5. Click Manage to return to the My AppExchange listing window. 6. Click Logo next to the name of your listing. Browse to a.gif,.jpg, or.png file that includes your company's logo and is exactly 60 x 60 pixels. 7. Click Upload and then click Close. (Developer or Publisher) Assigning a Listing to an Exchange and Category An AppExchange listing must be associated with a particular exchange, such as the US exchange, and a category: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Next to the Exchange heading, click Assign. 3. Select the exchange on which you want to list the CTI adapter. Once you make this selection, you cannot reassign the listing to a different exchange. 4. Click Assign. 5. Click Categorize. 6. Select the Contact Centers category under Service & Support. 7. Click Save. (Developer or Publisher) Preparing a Listing for ARB Review To publicly post your listing on the AppExchange, you must first submit it to the Application Review Board (ARB) for review. In this process, the ARB evaluates your listing based on: Functionality Your online presentation/demo Supporting documentation Functionality Requirements When the ARB receives a listing, they first perform a functionality review. To perform this review, they will contact you to gain access to your CTI adapter installation package and then review it to ensure your adapter: Uses a unique client ID for all API calls 57

60 Publishing a CTI Adapter on the AppExchange Supports the editions identified in your listing (Group, Professional, Enterprise, and Unlimited) Supports your stated minimum requirements for operating systems and versions, disk space, and any other applications or capabilities Displays the same look-and-feel as other Salesforce applications Includes functionality that is both user-friendly and bug-free Online Presentation Requirements Because users cannot test drive your CTI adapter in the same way that they can demo other applications listed on the AppExchange, you must provide the URL for a Breeze presentation, Flash demo, or a set of captioned screenshots that detail what your CTI adapter offers. Documentation Requirements A CTI adapter must be accompanied by documentation that clearly explains how to install and use it. When writing your listing and providing documentation for your adapter, note the following: Avoid submitting documentation that provides overly confusing or complex directions. Such documentation will not pass review. Avoid the use of marketing terms, value judgments, jargon, and exaggerated claims. Marketing-centric descriptions that use comparative terms such as "premier" and "best of breed" are not useful. Provide contact information for at least one support channel, including a valid address, phone number, or a URL that points to a contact form. (Publisher) Submitting a Listing to ARB Review Once you have finalized the information that you want to feature on your listing, you can submit it to the Application Review Board (ARB) for review: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Click Submit for Publication. 3. Review and agree to the terms of use. 4. Click Submit for Publication again. Note: Once you have submitted your listing, you will no longer be able to make any changes to its content. Once your listing is submitted, the ARB will contact you to gain access to your CTI adapter installation package and to follow up with additional listing questions that are not specified on the standard listing form. (Publisher) Posting an Approved Listing on the AppExchange When your listing has been approved by the ARB, you can post it publicly on the AppExchange. To do so: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Select the Listed checkbox that now appears. Your listing is made public and appears on the AppExchange within a short time. (Publisher or Developer) Editing or Deleting a Public Listing To modify a listing that has already been published on the AppExchange: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 58

61 Publishing a CTI Adapter on the AppExchange 2. Click Change Listing Info. 3. Fill out the form that appears and include all changes that you want to make in the Comments field. 4. Click Submit. Depending on the extent of the changes that you want to make, the ARB will either make the edits you request, or they will unlock your listing so that you can edit it yourself. Note: Every time you edit your listing, you must resubmit it for ARB review. To delete a listing that has been published on the AppExchange: 1. Click the Manage My Apps tab, then find the title of the listing for your CTI adapter. 2. Click Delete next to the adapter name, then click Delete again to confirm. Note: If you want to repost a listing after deleting it, you must resubmit your listing beginning with the first step of the publishing process. 59

62 Chapter 6 CTI Adapter Log Files Every CTI adapter generates two log files in the installation directory of the machine where the adapter is installed: cti_adapter.log includes information about the CTI connector component. browser_connector.log includes information about the SoftPhone connector component. In default installations, the installation directory is C:\Program Files\salesforce.com\<adapterName>\, where <adaptername> is the name of the CTI adapter that was installed (for example, C:\Program Files\salesforce.com\Cisco IPCC Enterprise Adapter). The log files document all CTI adapter activity and can be configured to report at three levels of verbosity: Log Level Errors Only Medium Error messages only Error messages, warnings, and information about significant actions that occur, such as setting a URL or authenticating a new user Note: A warning is any irregular condition that is not fatal. For example, if a call arrives and there is no available phone line, the code issues a warning and creates a virtual line just for that call. High Error messages, warnings, information about significant actions that occur, and the complete text of all method calls that send data into and out of the specified component By default, CTI adapters are installed with the Errors Only log level enabled. If you want to change the log level, right-click the adapter icon ( ) in the system tray of the call center machine and choose the desired setting. 60

63 Chapter 7 SoftPhone XML Format Reference A CTI connector maintains an XML representation of the SoftPhone user interface according to the following XML format. It is this XML that is transmitted to the SoftPhone connector through the CTI connector's UIRefresh event. The following diagram shows the relationship between each element in the SoftPhone XML format. Elements in italic bold are broken out separately below the main diagram: 61

64 The sections that follow include descriptions of each element, as organized by parent. Italicized elements are broken out separately in their own section: CTIUserInterface on page 63 CTIAgent on page 64 CTIAgentState on page 64 CTICallLog on page 73 CTIElementSet on page 67 CTIForm on page 65 CTIInteractiveControlContainer on page 75 CTILine on page 65 CTIElementSet on page 67 CTILineOnlyElementSet on page 78 CTILogo on page 66 CTIPreviousCalls on page 66 CTICallLog on page 73 62

65 CTIUserInterface CTIElementSet on page 67 CTIReasonCodeSet on page 67 CTIReasonCode on page 67 CTIInteractiveControlContainer on page 75 CTITimer on page 68 CTIStaticText on page 68 CTIProgressBar on page 69 CTILink on page 73 CTIParty on page 69 CTIProgressBar on page 69 CTIInfoField on page 71 CTIRelatedObjectSet on page 71 CTIRelatedObject on page 72 CTIField on page 72 CTICallLog on page 73 CTIComments on page 74 CTIWho on page 74 CTIWhat on page 74 CTIInteractiveControlContainer on page 75 CTIButton on page 75 CTIEditBox on page 76 CTICheckBox on page 77 CTIComboBox on page 77 CTILineOnlyElementSet on page 78 CTIUserInterface CTIComboBoxValue on page 77 CTIDialPad on page 78 CTIComments on page 74 This element encapsulates the entire SoftPhone. Properties Children content=complex CTIAgent, CTILine, CTIStaticText, CTIProgressBar, CTILink, CTIParty, CTITimer, CTIEditBox, CTIComboBox, CTICheckbox, CTIButton, CTIForm, CTIReasonCodeSet, CTICallLog, CTIPreviousCalls, CTILogo 63

66 CTIAgent CTIAgent This element encapsulates the call center state section of the SoftPhone interface. If this section is left blank, then no call center state picklist or icon is displayed. Properties Parent Children Attributes isref=0; minocc=0; maxocc=1; content=complex CTIUserInterface CTIAgentState Attribute Name Type Required? ICON_URL Specifies your own image for the call center state section of the SoftPhone. Salesforce.com recommends that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. For information on how to determine the URL of an image that is stored in the Documents tab, see Adding a Custom Logo on page 43. CTIAgentState This element encapsulates a call center state that is available in the call center state picklist (for example, Not Ready for Calls). If the SELECTED attribute of a call center state is set to True, this is the state that is currently active. Properties Parent Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIAgent Attribute Name Type Required? SELECTED If set to True, this call center state value is displayed as currently active. The default value for this attribute is False. ORDER Integer The order in which this call center state is displayed in the call center state picklist. States are displayed in ascending order according to their ORDER attributes. ID Required Identifies the call center state within the CTI adapter code LABEL Specifies the text that is used for the call center state in the SoftPhone 64

67 CTIForm CTIForm This element encapsulates a set of controls in the SoftPhone user interface that allows a user to specify data. When a button in the form is clicked, the data contained in the form is sent to the SoftPhone CTI adapter on the query string of the button command. Properties Parent Children CTILine isref=0; minocc=0; maxocc=unbounded; content=complex CTIUserInterface CTIEditBox, CTIComboBox, CTICheckbox, CTIButton This element encapsulates a single phone line in the SoftPhone user interface. Properties Parent Children Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIUserInterface CTIStaticText, CTIProgressBar, CTILink, CTIParty, CTITimer, CTIEditBox, CTIComboBox, CTICheckbox, CTIButton, CTIButton, CTIDialpad, CTIComments Attribute Name LINE_NUMBER STATE CALL_OBJECT_ID EXTENSION ALLOW_ALTERNATE ALLOW_DIAL_PAD Type Positive Integer Boolean Boolean Required? Required Required Specifies the sequential number that identifies the line in the SoftPhone. For example, line 1, line 2, line 3, and so on. Specifies the current status of the line. Possible values include Open, Ringing, and Busy. Specifies the unique ID of the call that this line contains. If the line does not contain a call, this value can remain unspecified. Specifies the extension number that is associated with the phone line. If set to True, the name of this line (for example, "Line 1") is displayed as a link, which, when clicked, sets the line as the currently active line. This attribute should not be set to True when ALLOW_DIAL_PAD is set to True. If set to True, the name of this line (for example, "Line 1") is displayed as a link, which, when clicked, shows the dial pad for the line. This attribute should not be set to True when ALLOW_ALTERNATE is set to True. 65

68 CTILogo CTILogo This element encapsulates the logo section at the bottom of the SoftPhone. Properties isref=0; minocc=0; maxocc=1; content=complex Parent CTIUserInterface Attributes Attribute Name Type Required? IMAGE_URL Required Specifies the URL of your own logo image. Logos should be exactly 116 pixels wide by 31 pixels high. Salesforce.com recommends that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. For information on how to determine the URL of an image that is stored in the Documents tab, see Adding a Custom Logo on page 43. LINK_URL If specified, this value places a link at the top left corner of the logo area with the label that is specified in LINK_TEXT. If you specify a URL, you should also specify values for LINK_TEXT, WINDOW_WIDTH, and WINDOW_HEIGHT. LINK_TEXT The label at the top left corner of the logo area that links to the URL that is specified in LINK_URL WINDOW_WIDTH Integer The width, in pixels, of the popup window that displays when the link specified by LINK_URL and LINK_TEXT is clicked WINDOW_HEIGHT Integer The height, in pixels, of the popup window that displays when the link specified by LINK_URL and LINK_TEXT is clicked CTIPreviousCalls This element encapsulates a group of logs for calls that have been completed. Properties isref=0; minocc=0; maxocc=1; content=complex Parent CTIUserInterface Children CTICallLog 66

69 CTIReasonCodeSet Attributes Attribute Name Type Required? OPEN Boolean Required If set to True, the collapsible list of previous call logs should be displayed in its open state CTIReasonCodeSet This element encapsulates a set of reason codes in the SoftPhone user interface. Some organizations might require users to choose a reason code from a reason code set when the user wants to end a call, enter the Not Ready for Calls state, or log out. Properties Parent Children Attributes isref=0; minocc=0; maxocc=1; content=complex CTIUserInterface CTIReasonCode Attribute Name Type Required? ID Required Identifies the reason code set within the CTI adapter code LABEL Specifies the text that is used for the reason code set in the SoftPhone CTIReasonCode This element encapsulates a single reason code in the SoftPhone user interface. Some organizations might require users to choose a reason code from a reason code set when the user wants to end a call, enter the Not Ready for Calls state, or log out. Properties Parent Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIReasonCodeSet Attribute Name Type Required? ID Required Identifies the reason code within the CTI adapter code LABEL Specifies the text that is used for the reason code in the SoftPhone CTIElementSet This group is comprised of the set of available elements that can exist in the SoftPhone. 67

70 CTIStaticText Parents Children CTIUserInterface, CTILine CTIStaticText, CTIProgressBar, CTILink, CTIParty, CTITimer, CTIEditBox, CTIComboBox, CTICheckbox, CTIButton CTIStaticText This element represents an read-only text field. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIElementSet Attributes Attribute Name Type Required? ID Required Specifies the developer name for the static text LABEL Specifies the text to use for the static text in the SoftPhone ERROR Boolean If set to True, this static text displays in red. CTITimer This element represents a clock that counts the number of seconds and minutes that have passed since a particular moment. For example, a timer can be used to track a call's duration, or the amount of time a caller has been on hold. Properties Parent Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIElementSet Attribute Name Type Required? ID Required Specifies the name of the timer within the CTI adapter code LABEL Specifies the text that is used for the timer in the SoftPhone MINUTES Integer Specifies the starting value that should be displayed for the number of minutes SECONDS Integer Specifies the starting value that should be displayed for the number of seconds 68

71 CTIProgressBar CTIProgressBar This element represents a progress bar or "throbber" that shows work is occurring. This element does not track actual progress time. Properties Parents Attributes isref=0; minocc=0; maxocc=1; content=complex CTIElementSet, CTIParty Attribute Name Type Required? ID Required Specifies the developer name for the progress bar LABEL Specifies the text to use for the progress bar in the SoftPhone CTIParty This element represents a single participant in a call on a line. Properties isref=0; minocc=0; maxocc=unbounded; content=complex; mixed=false Parent CTIElementSet Children CTIInfoField, CTIProgressBar, CTIRelatedObjectSet Attributes Attribute Name Type Required? TYPE Specifies the role of someone on a call from the perspective of the SoftPhone user: <unspecified> If the TYPE attribute is left unspecified, the SoftPhone user knows of only one other person on the call. The majority of calls fall into this category. TRANSFERRED_FROM The person who initiated a transfer. When this party type is specified, another party with a type of ORIGINAL_CALL_PARTICIPANT is also known to the SoftPhone user. CONFERENCED_FROM The person who initiated a conference call. When this party type is specified, another party with a type of ORIGINAL_CALL_PARTICIPANT is also known to the SoftPhone user. 69

72 CTIParty Attribute Name Type Required? ORIGINAL_CALL_PARTICIPANT The person who was on the original call but who did not initiate a conference or transfer. This party type is specified when transfers or conferences are initiated, or while a transferred call is in progress CONFERENCED_PARTY Any party who is actively participating in a conference call. This party type is specified for all participants of a conference as soon as a conference call request has been accepted by a third party. Transferred Call Scenario For an example of how the Type attribute is used when a call is transferred, suppose there are three call center users: Marco, Rupert, and Caroline. 1. Marco calls Rupert. At this point, the TYPE attribute for both Marco and Rupert is left unspecified because Marco is only connected to Rupert and Rupert is only connected to Marco. 2. Marco initiates a transfer of the call to Caroline: From Marco's perspective, he has two separate calls occurring at the same time, both of which are with only one party. The TYPE attribute for Rupert's party and Caroline's party both remain unspecfied in Marco's SoftPhone. From Rupert's perspective, Marco has put him on hold and is still the only party on his call. The TYPE attribute for Marco's party remains unspecified in Rupert's SoftPhone. From Caroline's perspective, she is receiving a transfer request from Marco to handle a call with Rupert. The TYPE attribute for Marco's party is TRANSFERRED_FROM in her SoftPhone, while Rupert's party is ORIGINAL_CALL_PARTICIPANT. 3. Caroline accepts the transferred call: From Marco's perspective he is no longer on any call. From Rupert's perspective, he is still on a call with one other person. The TYPE attribute for Caroline's party remains unspecified. From Caroline's perspective, Marco's and Rupert's party types remain TRANSFERRED_FROM and ORIGINAL_CALL_PARTICIPANT in her SoftPhone, even though Marco is no longer on the call. Conference Call Scenario For an example of how the Type attribute is used in a conference call, suppose there are three call center users: Marco, Rupert, and Caroline. 1. Marco calls Rupert. At this point, the TYPE attribute for both Marco and Rupert is left unspecified because Marco is only connected to Rupert and Rupert is only connected to Marco. 2. Marco initiates a conference call with Caroline: From Marco's perspective, he has two separate calls occurring at the same time, both of which are with only one party. The TYPE attribute for Rupert's party and Caroline's party both remain unspecfied in Marco's SoftPhone. 70

73 CTIInfoField From Rupert's perspective, Marco has put him on hold and is still the only party on his call. The TYPE attribute for Marco's party remains unspecified in Rupert's SoftPhone. From Caroline's perspective, she is receiving a conference request from Marco to join a call with Rupert. The TYPE attribute for Marco's party is CONFERENCED_FROM in her SoftPhone, while Rupert's party is ORIGINAL_CALL_PARTICIPANT. 3. Caroline accepts the conferenced call. Marco, Rupert, and Caroline are now all on a call with two other parties, both of whom have type CONFERENCED_PARTY. CTIInfoField This element represents an information field that is not derived from a Salesforce record. Properties Parent Attributes isref=0; minocc=0; maxocc=unbounded; content=complex; mixed=false CTIParty Attribute Name Type Required? ID Required Specifies the developer name for the information field LABEL Specifies the text to use for the information field in the SoftPhone VALUE Specifies the content of the information field HREF Specifies the URL to link to from the information field value TARGET Specifies the target of the HTML anchor tag if an HREF attribute is included CTIRelatedObjectSet This element represents a set of links to Salesforce records that are related to an incoming call. You should define one CTIRelatedObjectSet for each type of record that should be displayed. For example, if you wanted to display a set of cases and a set of accounts, you should define two CTIRelatedObjectSets. Properties Parent Children Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIParty CTIRelatedObject Attribute Name Type Required? ID Required Specifies the name for an object within Salesforce. You can find these names in the Apex Explorer. See the 71

74 CTIRelatedObject Attribute Name Type Required? Apex API documentation for details ( LABEL Specifies the text that is used for the related object set in the SoftPhone. This value is usually generated by Salesforce according to the object's ID. CTIRelatedObject This element represents a link to a single Salesforce record that is related to an incoming call. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIRelatedObjectSet Children CTIField Attributes Attribute Name Type Required? ID Required Specifies the Salesforce ID for the record (for example, "003x G") LABEL Specifies the text that is used for the record's link in the SoftPhone user interface CTIField This element represents a single field of a Salesforce record that is related to an incoming call. Properties isref=0; minocc=0; maxocc=unbounded; content=complex; mixed=false Parent CTIRelatedObject Attributes Attribute Name Type Required? ID Required Specifies the developer name for the field (for example, Account_Name) LABEL Specifies the text that is used to display the field name in the SoftPhone (for example, "Account Name") VALUE Specifies the content of the field (for example, "salesforce.com, inc.") 72

75 CTILink CTILink This element represents a single link to a URL. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIElementSet Attributes Attribute Name Type Required? TEXT Required Specifies the text that should be used to display the link in the SoftPhone HREF Required Specifies the URL destination of the link TARGET Specifies the window in which this link should open CTICallLog This element represents a log for a single phone call. If this element occurs within a CTIPreviousCalls element, this is a previous call and will be displayed in a group with other previous calls. If this element does not occur within a CTIPreviousCalls element, this is the log for the call that is currently in progress and is displayed as such. Properties Parents Children Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTIUserInterface, CTIPreviousCalls CTIWho, CTIWhat, CTIComments Attribute Name Type Required? ID (Previous call logs only) Specifies the Salesforce ID of the call log task that is associated with this call. Current call logs do not require this value because call log tasks are not created until the call ends. LABEL Required Specifies the subject field of the call log task that will be (or was) created for this call log OPEN Boolean (Current call logs only) If set to True, specifies that the call log should be displayed in the SoftPhone as an expanded collapsible section. If set to False, this collapsible section is closed and the call log should not be displayed. LINE (Current call logs only) Specifies the line number to which this call pertains 73

76 CTIComments CTIComments This element represents the text box (for a current call log), or the static text (for a previous call log), that displays any call comments that the user wants to associate with this call log. Properties Parents Attributes isref=0; minocc=0; maxocc=1; content=complex CTILineOnlyElementSet, CTICallLog Attribute Name Type Required? VALUE Specifies the text that should appear in the comments area CTIWho This element represents an available option for the "Who" portion of a call log. A "Who" can be a contact, lead, or person account. Properties Parent Attributes isref=0; minocc=0; maxocc=unbounded; content=complex CTICallLog Attribute Name Type Required? ID Required Specifies the Salesforce ID of the contact, lead, or person account LABEL Specifies the formatted text that should be used to display the contact, lead, or person account in the SoftPhone (for example, "Contact: Henry James") SELECTED Boolean If set to True, specifies that this contact, lead, or person account is currently selected in the SoftPhone CTIWhat This element represents an available option for the "What" portion of a call log. A "What" can be any object other than a contact, lead, or person account. Properties Parent isref=0; minocc=0; maxocc=unbounded; content=complex CTICallLog 74

77 CTIInteractiveControlContainer Attributes Attribute Name Type Required? ID Required Specifies the Salesforce ID of the object LABEL Specifies the formatted text that should be used to display the object (for example, "Case: ") SELECTED Boolean If set to True, specifies that this contact, lead, or person account is currently selected in the SoftPhone CTIInteractiveControlContainer This group is comprised of the set of elements that show controls with which an agent can interact. Parents CTIElementSet, CTIForm Children CTIEditBox, CTIComboBox, CTICheckbox, CTIButton CTIButton This element encapsulates a single button in the SoftPhone user interface. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIInteractiveControlContainer Attributes Attribute Name Type Required? ID Required Specifies the developer name of the button, as well as the command that is passed back to the SoftPhone connector when the button is clicked LABEL Specifies the text that is used for the button in the SoftPhone ICON_URL Specifies the URL of an image to use as the icon for this button. Button icons must be no more than 46 pixels wide by 17 pixels high.the image can be served from any host, but Salesforce.com recommends that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. For information on how to determine the URL of an image that is stored in the Documents tab, see Adding a Custom Logo on page

78 CTIEditBox Attribute Name Type Required? PRESSED_ICON_URL Specifies the URL of an image to use as the icon for this button when it is pushed or toggled. Button icons must be no more than 46 pixels wide by 17 pixels high. If unspecified, the button will always appear as ICON_URL or a standard HTML button if ICON_URL is unspecified. This value must always be specified if ICON_URL is specified and TOGGLE_BUTTON is set to True. COLOR Specifies the HTML hexadecimal code for the button's color (for example, FFFFFF) TOGGLE_BUTTON Boolean If set to True, this button acts as a toggle button that can be in one of two states at any time (for example, on or off ). If specified, TOGGLE_STATE must be specified as well. TOGGLE_STATE Boolean Specifies the state of the button if TOGGLE_BUTTON is set to True. When TOGGLE_STATE is set to True, the button is in its toggled (pressed down) state. When TOGGLE_STATE is set to False, the button appears unpressed. This attribute has no effect if TOGGLE_BUTTON is set to False. LONG_STYLE Boolean If set to True, this button displays across the width of the SoftPhone, and no icon is displayed. LINK_URL Specifies a URL that opens in a new window when the button is clicked. If specified, the button opens a new window without sending a message to the CTI adapter. CTIEditBox This element encapsulates an editable text box and label. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIInteractiveControlContainer Attributes Attribute Name Type Required? ID Required Specifies the developer name of the text box LABEL Specifies the text to use for the text box in the SoftPhone VALUE Specifies the content of the text box when it is initially displayed PASSWORD Boolean If set to True, this text box masks any input as it is entered. 76

79 CTICheckBox CTICheckBox This element encapsulates a checkbox and label. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIInteractiveControlContainer Attributes Attribute Name Type Required? ID Required Specifies the developer name for the checkbox LABEL Specifies the text to user for the checkbox in the SoftPhone CHECKED Boolean If set to True, this checkbox is in its checked state. CTIComboBox This element encapsulates a drop-down list of values. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIInteractiveControlContainer Children CTIComboBoxValue Attributes Attribute Name Type Required? ID Required Specifies the developer name for the combo box LABEL Specifies the text that is used for the combo box in the SoftPhone user interface CTIComboBoxValue This element encapsulates a single option in a drop-down list of values. Properties isref=0; minocc=0; maxocc=unbounded; content=complex Parent CTIComboBox Attributes Attribute Name Type Required? ID Required Specifies the developer name for the combo box value 77

80 CTILineOnlyElementSet Attribute Name Type Required? LABEL Specifies the text that is used for the combo box value in the SoftPhone user interface SELECTED Boolean If set to True, this value is currently selected in its combo box. CTILineOnlyElementSet This group is comprised of the set of elements that can exist within the context of a phone line. Parent CTILine Children CTIDialPad, CTIComments CTIDialPad This element encapsulates the key pad that can be used to dial a phone number in a line. Properties isref=0; minocc=0; maxocc=1; content=complex Parent CTILineOnlyElementSet Attributes Attribute Name Type Required? SHOW_BUTTONS Boolean If set to True or if left unspecified, the dial pad is displayed as a text box above a set of numbered buttons. If set to False, only a text box is displayed. TYPE Required Specifies the kind of call that is being made, and the call button that should be displayed below the dial pad. Possible types include DIAL, TRANSFER, and CONFERENCE. ALLOW_SINGLE_STEP Boolean If set to True, a One-Step Transfer or One-Step Conference button is also displayed for calls of type TRANSFER or CONFERENCE, respectively. NUMBER Specifies the phone number that should appear in the dial pad's edit box 78

81 Chapter 8 Call Center Edition API Reference The API provides access to information about computer telephony integration (CTI) call centers with the describesoftphonelayout call. You must have the CTI Integration feature enabled for your organization. Contact your account representative for assistance. The API supports limited access to call center-related objects, including being able to create call centers, and create or modify additional numbers for the call center: Topic CallCenter AdditionalNumber Call Center object description, including fields and usage. Configuration settings that allow you to add an additional number if it cannot easily be categorized as a user, contact, lead, account, or any other object. Examples include phone queues or conference rooms. In addition, several fields have been added to existing objects to support call centers. The following fields provide configuration settings for operation of a call center: Object Name Field Name Field Type Field Properties OpenActivity ActivityHistory Task CallDisposition string Create (Task only) Filter Nillable Update (Task only) Represents the result of a given call, for example, "we'll call back," or "call unsuccessful." Limit is 255 characters. For the Task object, corresponds to the Salesforce user interface label Call Result. You can also create and update values for this field in Task. OpenActivity ActivityHistory Task CallDurationInSeconds int Create (Task only) Filter Duration of the call in seconds. For Task, you can also create and update values for this field. Nillable Update (Task only) 79

82 describesoftphonelayout Object Name Field Name Field Type Field Properties OpenActivity ActivityHistory Task CallObject string Filter Nillable Update (Task only) Name of a call center. Limit is 255 characters. For Task, you can also create and update values for this field. OpenActivity ActivityHistory Task CallType picklist Create (Task only) Filter Nillable The type of call being answered: Inbound, Internal, or Outbound. For Task, you can also create and update values for this field. Restricted picklist Update User CallCenterId reference Create Filter The unique identifier for the call center associated with this user. Nillable Update User UserPermissionsCall CenterAutoLogin boolean Create Update Indicates whether a user will be automatically logged in to a call center when logging in to the Salesforce application (true) or not (false). describesoftphonelayout Retrieves layout information for a Call Center Edition SoftPhone. Syntax DescribeSoftphoneLayoutResult[] = sfdc.describesoftphonelayout(); Usage Use this call to obtain information about the layout of a SoftPhone. Use only in the context of Call Center Edition; do not call directly from client programs. Arguments This call does not take any objects. Response The response is a DescribeSoftphoneLayoutResult object: 80

83 CallCenter Name CallType id name Type string ID string A set of attributes that associated with each allowed call type. A call type may be Inbound, Outbound, or Internal. ID of layout. Note that layout objects are not exposed via the API. Name of the call type: Inbound, Outbound, or Internal. CallType Each describesoftphonelayoutresult object contains one or more call types: Name infofields (may be more than one) name Sections Type name string string The name of an information field in the SoftPhone layout that does not correspond to a Salesforce object. For example, caller ID may be specified in an information field. Information fields hold static information about the call type. Name of the layout. A set of object names and the corresponding item name in the SoftPhone layout, one section for each object in a call type. Sections Each call type returned in a describesoftphonelayoutresult object contains one section for each call type. Each section contains object-item pairs: Name entityapiname itemapiname Type string string The name of an object in the Salesforce application that corresponds to an item displayed in the SoftPhone layout, for example, a set of accounts or cases. The name of a record in the Salesforce application that corresponds to an item displayed in the SoftPhone layout, for example, the Acme account. CallCenter This object represents a call center, which is a logical representation of a single computer telephony integration (CTI) system instance in an organization. Supported Calls ccreate, qquery, rretrieve, describesobject, describesobjects Special Access Rules Customer Portal users cannot access this object. 81

84 AdditionalNumber Fields Field Field Type Field Properties CreatedById reference Defaulted on create System field that contains the ID of the user who created this call center. Filter CreatedDate datetime Defaulted on create System field that contains the date and time that this call center was created. Filter Id ID Defaulted on create Filter System field that uniquely identifies this call center. Label is Call Center ID. This ID is created automatically when the call center is created. InternalName string Create Filter Nillable The internal name of the call center. Limit is 255 characters. LastModifiedById reference Defaulted on create System field that contains the ID of the user who last modified this call center. Filter LastModifiedDate datetime Defaulted on create System field that contains the date and time this call center was last modified. Filter Name string Create Filter idlookup The name of the call center. Limit is 80 characters. SystemModstamp datetime Defaulted on create System field that contains the date and time that this call center was last modified by a user or a workflow process. Filter Usage Create a call center or query an existing call center. AdditionalNumber This object represents an optional additional number for a call center. This additional number is visible in the call center's phone directory. Supported Calls ccreate, qquery, rretrieve, describesobject, describesobjects 82

85 AdditionalNumber Special Access Rules Customer Portal users cannot access this object. Fields Field CallCenterId Field Type reference Field Properties Create Filter Nillable Update System field that contains the ID of the user who created the call center associated with this additional number. If value is null, this additional number is displayed in every call center's phone directory. CreatedById reference Defaulted on create System field that contains the ID of the user who created the call center associated with this additional number. Filter CreatedDate datetime Defaulted on create System field that contains the date and time that the call center associated with this additional number was created. Filter string Create Filter of the additional number, such as Conference Room B. Nillable Limit: 255 characters. Update Id ID Defaulted on create ID that uniquely identifies this call center. Label is Additional Directory Number ID. Filter IsDeleted boolean Create Filter Indicates whether the additional number has been deleted (true) or not (false). Nillable Label is Deleted. LastModifiedById reference Defaulted on create System field that contains the ID of the user who last modified this additional number. Filter LastModifiedDate datetime Defaulted on create System field that contains the date and time this additional number was last modified. Filter Name string Create Filter idlookup The name of the additional number. Limit: 80 characters. 83

86 AdditionalNumber Field Phone Field Type phone Field Properties Create Filter Update The phone number that corresponds to this additional number. SystemModstamp datetime Defaulted on create Filter System field that contains the date and time that this additional number was last modified by a user or a workflow process. Usage Create an additional number for a call center directory. Use this object if the number is not easily categorized as a User, Contact, Lead, Account, or the other object. Examples include phone queues or conference rooms. 84

87 Chapter 9 Frequently Asked Questions Q: What is the difference between Call Center Edition and the CTI Toolkit? Call Center Edition is an "edition" of Salesforce in the mold of Outlook Edition or Offline Edition. Salesforce.com does not charge for this edition, and it can be enabled in Developer Edition, Group Edition, Professional Edition, Enterprise Edition, and Unlimited Edition. The CTI Toolkit is a body of C++ code that allows partners to integrate telephony systems with Salesforce using Call Center Edition. It creates a client-side application that resides in the Windows system tray and abstracts access to the Apex Web Services API. Salesforce.com is not selling any CTI adapters for any phone systems. Instead, salesforce.com is providing the CTI Toolkit to its partners so that they can develop Call Center Edition integrations with a consistent user interface. Q: Why does Call Center Edition involve a client-side application? Isn't salesforce.com the "No Software" company? Salesforce.com continues to be the "No Software" company, except in those cases when it is necessary to integrate with a service that sits behind a firewall. In such situations, salesforce.com provides small pieces of software to perform that integration. Other examples of salesforce.com software include Lotus Notes Edition and Outlook Edition. Q: Does the CTI adapter support multiple telephone lines? Yes. The salesforce.com CTI adapter supports multiple fixed lines and multiple calls for the same line, for which it creates "virtual" lines that disappear after the call has ended. In total, the adapter supports up to five fixed or virtual lines at once. Q: Is it possible to have multiple CTI adapters working in parallel against the same switch? This is possible for the vast majority of switches, though some switches restrict the same agent from logging in to more than one CTI adapter at the same time. Q: Does a CTI adapter require any investment or changes to a switch? This depends on your organization's needs. There are two types of CTI adapters: those that integrate with a public-branch exchange (PBX), and those that integrate with an automatic call distributer (ACD). 85

88 Q: Does Call Center Edition require VoIP? Those that integrate with a PBX do not have a notion of agent presence, and do not receive any data attached to a call. This means that a call center user cannot specify whether he or she is ready to receive calls. Instead, the adapter will simply display a new call whenever the phone rings. Additionally, PBX-level integrations cannot generate screen pops based on interactive voice response (IVR) data, such as when a caller enters an account number before being connected to a user. PBX-level integrations typically can only generate screen pops based on the incoming caller ID (the automatic number identification, or ANI). Those that integrate with an ACD allow call center users to specify whether they are ready to take calls and can receive data attached to calls, such as an account number. If your organization has a PBX system but wants ACD integration, you must buy an ACD system. Additionally, some salesforce.com partners provide a middleware server that sits between the telephony system and the call center user and normalized the messages passing between the two. If your organization chooses a partner such as this, you must install the partner's middleware. Q: Does Call Center Edition require VoIP? No, Call Center Edition can work with regular telephone service switches, as long as they have a CTI server attached to them. Q: Why was the CTI Toolkit written in C++ instead of.net or Java? Salesforce.com used C++ because many CTI vendor C++ toolkits are more robust and mature than their.net and Java counterparts. In the CTI world,.net and Java are still considered new technologies, and support for those managed languages for many vendors arrived only in the last year. Although.NET does integrate well with C++/COM applications, some salesforce.com customers expressed concern about installing the 30Mb.NET framework on all agent desktops.this issue will be less of a concern once Windows Vista is released, since.net is built in. Q: How long does it usually take for a partner to write a custom CTI adapter? Salesforce.com generally estimates that it should take three to six weeks of development time and three to six weeks of testing time to write a new CTI adapter. Q: Is there a list of the telephony platforms that are currently covered? Yes. Please contact your salesforce.com representative to learn about the commitments that have already been made by other partners. Q: How can I demo a CTI adapter? Salesforce.com has provided a "demo adapter" that does not require any phone system behind it, but that can simulate incoming and outgoing calls. See The Demo Adapter on page 15 for information. Q: If I'm using a machine that has multiple CTI connector.dll files installed, how does the SoftPhone connector know which CTI connector to use when I log in to Salesforce? Multiple CTI connector.dll files can coexist on the same machine because every CTI connector is uniquely identified by its ProgId, a value specified in the CTI connector's base COM class. Similarly, every call center definition includes the ProgId of the CTI connector that works with the call center. 86

89 Q: I'm seeing 'L' prefixes in front of all the string and character literals in the CTI Toolkit code. Why are these present? When a call center user logs in to Salesforce, the SoftPhone connector accesses the ProgId in the user's associated call center definition and uses the matching CTI connector.dll for the duration of the user's session. Q: I'm seeing 'L' prefixes in front of all the string and character literals in the CTI Toolkit code. Why are these present? The 'L' prefix indicates that the string will be stored as an array of wide (2-byte) characters, which are necessary to support Unicode character encoding. Salesforce.com enforces the use of this prefix on all string values to support localization. For more information, see The 'L' Literal and Character Prefix on page 20. Q: My SoftPhone is not behaving the way that I expect it to. How can I troubleshoot it? If you are experiencing difficulties with a SoftPhone: Verify that you are running Internet Explorer V Call Center Edition is not supported with any other browser. Try logging out of Salesforce and then logging back in. Try stopping and restarting your CTI adapter: 1. Right-click the CTI adapter system tray icon ( ) in the lower-right corner of your computer screen and select Exit. 2. From your machine's Start menu, choose Programs salesforce.com <Your_CTI_Adapter_Name> Salesforce.com CTI Adapter. If you are still experiencing difficulties, examine the CTI adapter log files for more information. For information, see CTI Adapter Log Files on page

90 Glossary Agent Automatic Number Identification (ANI) Call Call Center Edition Computer-Telephony Integration (CTI) Consult Call CTI Adapter CTI Connector CTI System Dial-Tone Multi-Frequency (DTMF) A Salesforce call center user who handles inbound or outbound calls. An agent is usually identified by a four-digit number that serves as the agent's ID within the associated CTI system. The number from which a caller is dialing. Any inbound, outbound, consult, or internal voice connection via telephone. A Salesforce feature that seamlessly integrates Salesforce with third-party computer-telephony integration (CTI) systems. For more information, see "What is Salesforce Call Center Edition?" in the Salesforce online help. The linkage between a telephone system and a computer that facilitates incoming- and outgoing-call handling and control. A call that results from a call center user initiating a conference or transfer. A light-weight software program that controls the appearance and behavior of a Salesforce SoftPhone. The adapter acts as an intermediary between a third-party CTI system, Salesforce, and a Call Center Edition user. It must be installed on any machine that needs access to Call Center Edition functionality. For more information, see About CTI Adapters on page 9. A component of a CTI adapter that maintains an in-memory representation of a call center user's SoftPhone, including the phone numbers, records, and status associated with a call. The CTI connector is the component of a CTI adapter that can be customized by an organization. For more information, see About CTI Connectors on page 9. The hardware and software that implements computer-telephony integration (CTI) for a particular call center. For more information, see About CTI Systems on page 9. The system that informs a switch of the number that is being pressed by a caller. 88

91 Dialed Number Identification Service (DNIS) Direct Inward Dial (DID) Directory Number (DN) Event Event Sink Inbound Call Interactive Voice Response (IVR) Internal Call Outbound Call Private Branch Exchange (PBX) Queue Routing Point SoftPhone SoftPhone Connector The number a caller dialed. A phone number that allows a call center user to be reached directly from outside the call center. DIDs can be used in place of extensions, which require a caller to first dial the main private branch exchange number and then enter an extension. Any internal number that is configured on a public branch exchange. You can define additional directory numbers through the Call Center Edition setup within Salesforce. A message broadcast from a CTI system that alerts any registered listeners that an action has taken place in the phone system. For example, when a user's telephone rings, a CTI system broadcasts a "RINGING" event. A CTI adapter, the Call Center Edition component that acts as a listener, receives this event and updates the SoftPhone as appropriate. An object in a CTI connector that receives CTI system events and routes them to other methods for processing. For more information, see Writing an Event Sink on page 28. A call that originates from another party. The hardware and software that prompts a caller to enter specific digits, such as a menu selection, or an account number. IVR is also known as a Voice Response Unit (VRU). A call between users in the same call center. Any call that originates from a user to a number outside of the call center. A telephony switch that is used exclusively by a single call center to route calls. A mechanism for storing one or more inbound calls that cannot be immediately answered by a call center user. Some CTI systems use multiple queues to differentiate between different types of calls. A mechanism that determines the queue that should control an incoming call. The telephone interface that a call center user sees in the sidebar of a Salesforce page while using Call Center Edition. For more information, see About SoftPhones on page 11. A component of a CTI adapter that converts SoftPhone XML into HTML and distributes it to a call center user's browser. For more information, see About SoftPhone Connectors on page

92 Voice Response Unit (VRU) See Interactive Voice Response (IVR) on page

93 Index Index 'L' prefix on string literals 20 A Adapters. See CTI adapters. 7 AdditionalNumber object 82 Agent states adding 42 displaying 42 mapping 40 AgentStateTo method 40 ANI search 46 API 79 AppExchange publishing CTI adapters ARB review 57 assigning to an exchange 57 associating a publishing profile 55 categorizing 57 creating a publishing profile 54 deleting 58 editing 58 editing a listing 55 posting publicly 58 publisher and developer roles 54 requesting a blank listing 54 ARB review of AppExchange listings 57 Attached data search 45, 46 B Blind transfers and conferences 36 browser_connector.log 60 Buttons, SoftPhone 37 enabling 36 C Call center definition files 49 default 14 Call center states adding 42 displaying 42 mapping 40 Call centers associating with an adapter 85 ProgID 85 Call centers and the API 79 Call information field labels 47 Call information fields 44 Call information, displaying 44 Call logs customizing 46 CallCenter object 81 CallInitiateConference method 36 CallInitiateTransfer method 36 calls describesoftphonelayout 80 CCTISearch 16 CCTIUserInterface 16 event handlers 10 CCTIUserInterface (continued) method names 20 SetInfoFieldLabel() method 47 SoftPhone command routing 10 CCTIUserInterface class adding a call information field 44 adding a custom logo 43 adding buttons 37 adding call center states 42 button layout 37 CallInitiateConference method 36 CallInitiateTransfer method 36 CreateLoginForm method 33 CTIChangeAgentState() method 42 CTIIsOccupiedAgentState() method 42 CTILogin method 33, 35 customizing 30 customizing call logs 46 displaying call center states 42 displaying call information 44 displaying call-related records 45 enabling buttons 36 enabling reason codes 38, 40 implementing an event sink 28 implementing call center user commands 31 Initialize method 33 Initialize() method 42 mapping call center states 40 non-required subclass commands 33 OnCallDialing event handler 29 OnCallRinging event handler 29 required subclass commands 32 SetOneStepConferenceEnabled method 36 SetOneStepTransferEnabled method 36 subclassing 27 UIAddAgentState() method 42 UIHandleMessage method 31 UIParseIncomingXMLMessage method 31 Virtual keyword 31 CCTIUserInterface subclass SoftPhone XML format 61 Client keys 21 COM base classes 25 Command messages implementing 31 Command routing 10 Conferences 36 Constants 20 CreateLoginForm method, CCTIUserInterface 33 CTI adapter displaying call information 44 CTI adapters about 9 associating with a call center 85 building a CTI connector project 23 building new CTI connectors 23 code package contents 14 CTI connectors 9 customizing 22 demo adapter 15, 16 log files 60 packaging 53 91

94 CTI adapters (continued) ProgID 85 publishing on the AppExchange ARB review 57 assigning to an exchange 57 associating a publishing profile 55 categorizing 57 creating a publishing profile 54 deleting 58 editing 58 editing a listing 55 posting publicly 58 publisher and developer roles 54 requesting a blank listing 54 registering with CTI systems 11 setting up a new CTI connector project 23 SoftPhone connectors 10 system requirements 7 CTI client keys 21 CTI connector source code 14 CTI connectors 9 adding a COM base class 25 building a project 23 building new 23 CCTIUserInterface commands 32, 33 classes 16 Commands, call center user 31 customizing 22 event sinks 28, 29 processing CTI system events 10 ProgID 25 setting up a new project 23 SoftPhone command routing 10 subclassing CCTIUserInterface 27 CTI systems 9 registering adapters 11 CTI toolkit 14 CTI Toolkit Developer's Guide about 5 cti_adapter.log 60 CTIAgent 64 CTIAgentState 64 CTIButton 75 CTICallLog 73 CTIChangeAgentState() method 42 CTICheckBox 77 CTIComboBox 77 CTIComboBoxValue 77 CTIComments 74 CTIConstants.h 20 CTIDialPad 78 CTIEditBox 76 CTIElementSet 67 CTIField 72 CTIForm 65 CTIInfoField 71 CTIInteractiveControlContainer 75 CTIIsOccupiedAgentState() method 42 CTILine 65 CTILineOnlyElementSet 78 CTILink 73 CTILogin method, CCTIUserInterface 33, 35 CTILogo 66 CTIParty 69, 70 CTIPreviousCalls 66 CTIProgressBar 69 CTIReasonCode 67 CTIReasonCodeSet 67 CTIRelatedObject 72 CTIRelatedObjectSet 71 CTIStaticText 68 CTITimer 68 CTIUserInterface 63 CTIWhat 74 CTIWho 74 Custom SoftPhone labels 47 D Database Salesforce 11 Demo adapter 15 customizing 16 setting up 15 using 15 describesoftphonelayout call 80 Developer role, AppExchange 54 Documentation about 6 E Event sinks 10, 28 OnCallRinging event handler 29 required event handlers 28 Event sinks, CTI connector 16 F Frequently asked questions 85 G GetAdapterName() method 25 GetAdapterVersion() method 25 Glossary 88 I Initialize method, CCTIUserInterface 33 Initialize() method 42 L Layout, SoftPhone buttons 37 Localizing SoftPhones 47 Log files 60 Logos, custom SoftPhone 43 Logout reason codes, enabling 38, 39 Logs, call customizing 46 M Messages call center user command 31 Mute transfers and conferences 36 N Not-ready reason codes, enabling 38, 39 Index 92

95 O objects AdditionalNumber 82 CallCenter 81 Office Toolkit library 14 OnAgentStateChange method 40 OnAgentStateEnablementChange() method 42 OnButtonEnablementChange method 36 OnCallDialing event handler, CCTIUserInterface 29 OnCallRinging event handler, CCTIUserInterface 29, 44, 45, 47 One-step transfers and conferences 36 P PARAM_MAPs 29 ProgID 25, 85 Publisher role, AppExchange 54 Publishing profiles associating with a listing 55 creating 54 R Reason codes, enabling 38, 40 S Salesforce database 11 Search, modifying 45, 46 SendUIRefreshEvent() method 25 SetAgentStateEnablement() method 42 SetInfoFieldLabel() method 47 SetLogoutReasonCodes method 38, 39 SetLogoutReasonRequired method 38, 39 SetNotReadyReasonCodes method 38, 39 SetNotReadyReasonRequired method 38, 39 SetOneStepConferenceEnabled method 36 SetOneStepTransferEnabled method 36 SetWrapUpReasonCodes method 38, 39 Single-step transfers and conferences 36 SoftPhone adding buttons 37 displaying call-related records 45 enabling buttons 36 SoftPhone connector executable 14 SoftPhone connectors 10 processing CTI system events 10 SoftPhone command routing 10 SoftPhone layouts buttons 37 SoftPhone XML format 61 CTIAgent 64 CTIAgentState 64 CTIButton 75 CTICallLog 73 CTICheckBox 77 CTIComboBox 77 CTIComboBoxValue 77 CTIComments 74 CTIDialPad 78 CTIEditBox 76 CTIElementSet 67 CTIField 72 SoftPhone XML format (continued) CTIForm 65 CTIInfoField 71 CTIInteractiveControlContainer 75 CTILine 65 CTILineOnlyElementSet 78 CTILink 73 CTILogo 66 CTIParty 69, 70 CTIPreviousCalls 66 CTIProgressBar 69 CTIReasonCode 67 CTIReasonCodeSet 67 CTIRelatedObject 72 CTIRelatedObjectSet 71 CTIStaticText 68 CTITimer 68 CTIUserInterface 63 CTIWhat 74 CTIWho 74 SoftPhones 11 adding a custom logo 43 custom labels 47 customizing 30 translating labels 47 troubleshooting 85 SOQL 11 SOSL 11 literals and the 'L' prefix 20 System architecture 8 System events 10 System requirements 7 T Transfers 36 Translating SoftPhone labels 47 Troubleshooting tips 85 U UIAction() method 10, 25 UIAddAgentState() method 42 UIAddButtonToAllLines method 37 UIHandleMessage method 31 UIHandleMessage() method 10 UIParseIncomingXMLMessage method 31 UIRefresh event 9, 10 User states adding 42 displaying 42 mapping 40 V Virtual keyword 31 W Wrap-up reason codes, enabling 38, 39 X XML format, SoftPhone 61 Index 93

96