Avaya Interaction Center Client SDK Programmer Guide

Transcription

1 Avaya Interaction Center Cient SDK Programmer Guide Reease 7.2 May 2013 Issue 1.1

2 2013 Avaya Inc. A Rights Reserved. Notice Whie reasonabe efforts were made to ensure that the information in this document was compete and accurate at the time of printing, Avaya Inc. can assume no iabiity for any errors. Changes and corrections to the information in this document might be incorporated in future reeases. Documentation discaimer Avaya Inc. is not responsibe for any modifications, additions, or deetions to the origina pubished version of this documentation uness such modifications, additions, or deetions were performed by Avaya. Customer and/or End User agree to indemnify and hod harmess Avaya, Avaya's agents, servants and empoyees against a caims, awsuits, demands and judgments arising out of, or in connection with, subsequent modifications, additions or deetions to this documentation to the extent made by the Customer or End User. Link discaimer Avaya Inc. is not responsibe for the contents or reiabiity of any inked Web sites referenced esewhere within this documentation, and Avaya does not necessariy endorse the products, services, or information described or offered within them. We cannot guarantee that these inks wi work a the time and we have no contro over the avaiabiity of the inked pages. Warranty Avaya Inc. provides a imited warranty on this product. Refer to your saes agreement to estabish the terms of the imited warranty. In addition, Avaya s standard warranty anguage, as we as information regarding support for this product, whie under warranty, is avaiabe through the Avaya Support Web site: License USE OR INSTALLATION OF THE PRODUCT INDICATES THE END USER'S ACCEPTANCE OF THE TERMS SET FORTH HEREIN AND THE GENERAL LICENSE TERMS AVAILABLE ON THE AVAYA WEB SITE ("GENERAL LICENSE TERMS"). IF YOU DO NOT WISH TO BE BOUND BY THESE TERMS, YOU MUST RETURN THE PRODUCT(S) TO THE POINT OF PURCHASE WITHIN TEN (10) DAYS OF DELIVERY FOR A REFUND OR CREDIT. Avaya grants End User a icense within the scope of the icense types described beow. The appicabe number of icenses and units of capacity for which the icense is granted wi be one (1), uness a different number of icenses or units of capacity is specified in the Documentation or other materias avaiabe to End User. "Designated Processor" means a singe stand-aone computing device. "Server" means a Designated Processor that hosts a software appication to be accessed by mutipe users. "Software" means the computer programs in object code, originay icensed by Avaya and utimatey utiized by End User, whether as stand-aone Products or pre-instaed on Hardware. "Hardware" means the standard hardware Products, originay sod by Avaya and utimatey utiized by End User. License type(s) Concurrent User License (CU). End User may insta and use the Software on mutipe Designated Processors or one or more Servers, so ong as ony the icensed number of Units are accessing and using the Software at any given time. A "Unit" means the unit on which Avaya, at its soe discretion, bases the pricing of its icenses and can be, without imitation, an agent, port or user, an e-mai or voice mai account in the name of a person or corporate function (e.g., webmaster or hepdesk), or a directory entry in the administrative database utiized by the Product that permits one user to interface with the Software. Units may be inked to a specific, identified Server. Copyright Except where expressy stated otherwise, the Product is protected by copyright and other aws respecting proprietary rights. Unauthorized reproduction, transfer, and or use can be a crimina, as we as a civi, offense under the appicabe aw. Third-party components Certain software programs or portions thereof incuded in the Product may contain software distributed under third party agreements ("Third Party Components"), which may contain terms that expand or imit rights to use certain portions of the Product ("Third Party Terms"). Information identifying Third Party Components and the Third Party Terms that appy to them is avaiabe on the Avaya Support Web site: Preventing to fraud "To fraud" is the unauthorized use of your teecommunications system by an unauthorized party (for exampe, a person who is not a corporate empoyee, agent, subcontractor, or is not working on your company's behaf). Be aware that there can be a risk of to fraud associated with your system and that, if to fraud occurs, it can resut in substantia additiona charges for your teecommunications services. Avaya fraud intervention If you suspect that you are being victimized by to fraud and you need technica assistance or support, ca Technica Service Center To Fraud Intervention Hotine at for the United States and Canada. For additiona support teephone numbers, see the Avaya Support Web site: Trademarks Avaya and the Avaya ogo are either registered trademarks or trademarks of Avaya Inc. in the United States of America and/or other jurisdictions. A other trademarks are the property of their respective owners. Downoading documents For the most current versions of documentation, see the Avaya Support Web site: Avaya support Avaya provides a teephone number for you to use to report probems or to ask questions about your product. The support teephone number is in the United States. For additiona support teephone numbers, see the Avaya Support Web site:

3 Contents Preface Purpose Audience Reason for Re-issue Reated documents Avaiabiity Chapter 1: Introduction Features of the Cient SDK Limitations of the Cient SDK Architecture of the Cient SDK Cient components Custom appication Cient API SDK cient framework Hierarchica Data Store Server components SDK server bridge Web container Messaging providers Basic services User Object Mode Cient-side integration Server-side integration Additiona documentation for the Cient SDK Chapter 2: Cient API object mode Communication through the Cient SDK Deivery of communications to appication users Deivery of outbound communications from appication users Work items and the Current concept Reationship between Current and the Working state Identifying the Current work item How a work item becomes Current Effect of makecurrent() Reationship between Current and Voice Traiing Events in the Cient SDK Operations Method cas Avaya IC Cient SDK Programmer Guide May

4 Contents Event registration Overview of the object mode Cient API objects Appication Session User Channe VoiceChanne EmaiChanne ChatChanne WorkList WorkItem MediaInteraction VoiceMediaInteraction ChatMediaInteraction Document EmaiDocument DraftDocument EmaiDraft Attributes on the WorkItem object Attribute storage in the EDU WorkItem functions for attribute storage Data integration with a custom appication Attribute data in the Contact tabe Exampe: moving data from a contact routing workfow to the database Chapter 3: Sampe cients Overview Features not supported in the sampe cients About the Java sampe cient User interface of the Java sampe cient Source code for the Java sampe cient Design configuration fies for the Java sampe cient Resources for the Java sampe cient Dependencies of the Java sampe cient Deveoping a custom Java sampe cient Running a Java sampe cient from an SDK server system Running a Java sampe cient from a non-sdk server system About the.net sampe cient User interface of the.net sampe cient Avaya IC Cient SDK Programmer Guide May 2013

5 Contents Code and resources for the.net sampe cient Dependencies of the.net sampe cient Deveoping a custom.net sampe cient Running a.net sampe cient from an SDK server system Running a.net sampe cient from a non-sdk server system Chapter 4: Guideines for using the Cient API Chat interaction guideines Methods not aowed for chat interactions Hande TranscriptLine events for chat interactions Do not use Datawake method Voice interaction guideines Using VoiceChanne.Reset Setting the force mutipe cas option on the switch Impact of network recovery on voice interaction Caback guideines Time and date duration guideine History API guideines Retrieving the history for a WorkItem or Customer WorkItemHistory record CustomerHistory record Formatting dates for the history of an object Exampe: retrieve WorkItem history for Java appication Exampe: retrieve Customer history for Java appication AddressBook API guideines Retrieving the AddressBook object Impementing Address Book searches Exampe: Finding a subset of agents based on criteria Exampe: Finding a subset of queues based on criteria WrapupSeection API guideine Event handing guideines Register isteners for events before caing Session.Initiaize Create a separate istener for each event Avoid bocking operations in event handing Hande ConnectionStatusChange and SessionShutdown events State guideines Check object for the appropriate state Check status of WorkItem Log in and og out guideines Simutaneous og in and og out for Chat and Emai Avaya IC Cient SDK Programmer Guide May

6 Contents Check WorkItem status during ogout Exception handing guideines NuPointerException and ArgumentNuException ConnectionException AuthenticationException Operation faiure and success guideines OperationFaied OperationSuccess Nu return vaue guideines Customization guideines Customization directory Customization fies SDKEduAttributesToFiter.properties SDKWorkItemAttributesFiter.properties SDKSessionAttributesFiter.properties SDKWrapupCodesCategoryGroups.properties SDKSupportedCharsets.properties SDKICPropertiesSections.properties Depoying a configuration fie Performance considerations Using WebAppContext Configuring the messaging service Chapter 5: Compiing and debugging a custom appication Supported compiers Logging Logging at the modue boundaries Cient SDK server ogging Cient SDK cient ogging Logging guideines Tracing issues through Cient SDK ogs Sampe og messages Error messages Cient SDK diagnostic information Using the diagnostic API When the Hierarchica Data Store is updated Viewing the HDS diagnostic information in the sampe cients Using the HDS diagnostic information to identify probems Debugging probems found with the HDS diagnostic information Opening the Diagnostic Viewer Avaya IC Cient SDK Programmer Guide May 2013

7 Contents Debugging common probems Custom appication cannot communicate with Cient SDK server Chat or emai work item is not deivered WorkItem state does not change NET cient encounters socket exception error during og in Getting support Chapter 6: Locaization and internationaization Appendix A: Sampe scenarios Login scenario Logout scenario Agent avaiabiity scenario Dispay channe properties scenario Workitem ifecyce scenario Workitem coaboration scenario OnHod/OffHod indication scenario Dispay text message scenario Dispay emai scenario New Outbound emai scenario Repy to emai scenario Dispay WorkItem History scenario Dispay Customer History scenario AddressBook scenario Retrieving Workitem Contact Attributes scenario Voice Ca scenario Appendix B: Additiona sampe scenarios Appication object scenario Password change scenario Session object scenarios Session status scenario Connectivity status scenario Session shutdown request scenario Enabe and disabe operationa state scenario Channe object scenario Enabe and disabe channe operationa state scenario WorkItem object scenarios Dispay assigned work items scenario Avaya IC Cient SDK Programmer Guide May

8 Contents Prompt on WorkItem arriva scenario Enabe and disabe work item operationa state scenario Access work item attributes scenario Voice interaction scenario OnHod aert on threshod scenario Chat interaction scenarios Inactivity aert on threshod scenario Language fiter scenario Customer-generated aert scenario Emai document scenarios Appy signatures scenario Support for attachments scenario Wrapup scenarios Access wrapup codes scenario Wrapup diaog box scenario Use terminate reasons scenario Supervisory scenario Join-Us Scenario Appendix C: Error messages MajorCodes MinorCodes Index Avaya IC Cient SDK Programmer Guide May 2013

9 Preface This section contains the foowing topics: Purpose on page 9 Audience on page 9 Reason for Re-issue on page 9 Reated documents on page 10 Avaiabiity on page 10 Purpose The purpose of this guide is to provide detaied information about the Cient Software Deveopment Kit (Cient SDK) for Avaya Interaction Center 7.2. Audience This guide is intended primariy for those who use the Cient SDK for Avaya Interaction Center 7.2. You shoud use this guide as an information source for deveoping a custom appication with the Cient SDK. Reason for Re-issue Updates to the foowing chapter: Sampe cients on page 55 Avaya IC Cient SDK Programmer Guide May

10 Preface Reated documents This document provides programming and deveopment information for the Cient SDK. Additiona information reated to the Cient API is avaiabe in the foowing Avaya IC documentation. Cient API documentation: The Cient API documentation is avaiabe in JavaDoc and ndoc formats. The Cient API documentation incudes detaied information about the object mode, such as methods, casses, fieds, and constructors. For more information, see Additiona documentation for the Cient SDK on page 19. IC Instaation Panning and Prerequisites: This document provides information about the supported third-party patforms and other prerequisites required for the Cient SDK, incuding instaation information for those patforms. IC Instaation Panning and Prerequisites aso incudes panning and depoyment information for the Cient SDK. IC Instaation and Configuration: This document provides instaation information for a Avaya IC components, incuding the Cient SDK. Avaya IC Readme: This document provides ast-minute information that was not avaiabe for the pubication of this document. Avaya IC Readme Addendum: This document provides ast-minute information that became avaiabe after the reease of Avaya Interaction Center 7.2. Avaiabiity Copies of this document are avaiabe on the Avaya support Web site, support. Note: Note: There is no charge for downoading documents from the Avaya Web site. 10 Avaya IC Cient SDK Programmer Guide May 2013

11 Chapter 1: Introduction The Avaya Interaction Center (Avaya IC) Cient Software Deveopment Kit (Cient SDK) is a cient-side tookit. Using this tookit, you can: Deveop a custom agent desktop appication that can access Avaya IC core functions. Upgrade the existing custom agent desktop appications to access the Avaya IC core functionaity. Aow a third-party agent framework or appication to work with Avaya IC. Integrate your custom appication or custom code on cients or on servers. This section incudes the foowing topics: Features of the Cient SDK on page 11 Limitations of the Cient SDK on page 12 Architecture of the Cient SDK on page 14 Cient components on page 15 Server components on page 17 Cient-side integration on page 19 Server-side integration on page 19 Additiona documentation for the Cient SDK on page 19 Features of the Cient SDK A custom agent desktop appication deveoped using the APIs (Appication Programming Interface) from the cient SDK can: Save vauabe screen rea estate. The agent desktop does not need to dispay an Avaya IC agent appication. Minimize functionaity to the features that ony required for a specific impementation. The custom appication does not have to incude features that are not required for an agent in the contact center. The Cient SDK incudes the foowing features: Cient API: This cient-side API incudes an appication-eve protoco that hides communication and session management and provides interfaces that are meaningfu to custom appications. Avaya designed the Cient API to support future Avaya IC enhancements. Avaya IC Cient SDK Programmer Guide May

12 Chapter 1: Introduction Supported technoogies: Incudes.NET and Java ibraries for custom appication deveopment. Works with NAT, firewas, and proxy servers. Security: The Cient SDK supports the foowing security: Secure Socket Layer (SSL) for synchronous communication Advanced Encryption Standard (AES) for asynchronous communication Supported integrations: The Cient SDK supports server-side and cient-side integrations with an Avaya IC core system. Supported scaabiity: The Cient SDK provides the foowing support for scaabiity: Up to 500 agents per Cient SDK server Custered depoyment option for mutipe Cient SDK servers Support for internationaization: The Cient SDK provides internationaization support for custom appications in anguages other than US Engish. For more information, see Locaization and internationaization on page 123. Limitations of the Cient SDK The Cient SDK has some imitations in Avaya IC 7.2. These imitations might impact the deveopment of custom appications and the interoperabiity of custom appications with Avaya IC agent desktop appications. The Cient SDK imposes the foowing imitations on a custom appication: Deveopment imitations of the Cient SDK: The Cient SDK imposes the foowing imitations on how you use the Cient SDK to deveop appications: You can not customize Avaya IC agent desktop appications with the Cient SDK. For information, see Avaya Agent Integration and Avaya Agent Web Cient Customization guides. You do not have a generaized Enterprise Appication Integration (EAI) interface to access Avaya IC databases. However, you can use Avaya IC workfows to access data in the Avaya IC databases. 12 Avaya IC Cient SDK Programmer Guide May 2013

13 Limitations of the Cient SDK Interoperabiity imitations with Avaya IC agent desktop appications: The Cient SDK does not support more than one agent desktop appication that works with Avaya IC on the agent desktop at one time. For exampe, an appication user cannot run a custom appication deveoped with the Cient SDK and Avaya Agent on a computer at the same time. Limitations of the Cient API: The Cient API does not provide methods to access agent or goba resources, emai tempates, or the suggested responses generated by Avaya Content Anayzer. However, you can deveop a custom scheme to store and access the resources in your custom appication. Functionaity imitations of custom appications: Custom appications deveoped with Cient SDK do not support the foowing functionaity that is avaiabe with the Avaya IC agent desktop appications: Abiity to monitor queues and teephone events. Manua contro of the aowabe workoad for individua channes. For exampe, the appication user cannot change the chat workoad. Administration of Avaya IC components. For exampe, you cannot administer agents for Avaya IC through a custom appication. Abiity to monitor rea-time statistics. Access to Datawake records. The foowing Avaya Agent chat features: - Coaborative Form Fiing - Shared Browsing - Datawake Avaya IC Cient SDK Programmer Guide May

14 Chapter 1: Introduction Architecture of the Cient SDK The foowing diagram shows the Cient SDK architecture and how the components work together. 14 Avaya IC Cient SDK Programmer Guide May 2013

15 Cient components Cient components You can use the cient components of the Cient SDK to: Deveop custom agent desktop appications. Embed an existing agent desktop appication at the Avaya IC integration points. This section incudes the foowing topics: Custom appication on page 15 Cient API on page 15 SDK cient framework on page 16 Hierarchica Data Store on page 16 Custom appication Custom appication is the code deveoped with the Cient SDK. You can host the custom code on a cient or a server machine. The custom code can create a session for one or more appication users. Usuay, mutipe user sessions can be used if the custom appication is hosted on a server machine. Custom appication must use the Cient API to access a Avaya IC functions. Cient API Cient API exposes some of the Avaya IC agent functionaity that you can use to deveop custom agent desktop appications. You can deveop a custom appication that can use the Cient API to access the foowing functionaity of an Avaya IC core system: Agent functionaity Advanced routing and work deivery capabiities A casses in the Cient API use the same object mode. The object mode incudes objects such as Session, Channe, and WorkItem. Each object incude methods that correspond to operations. For exampe, the Accept method avaiabe in the WorkItem object. Caing the Accept method on the WorkItem object means the appication user wants to accept the work item that is deivered. The objects in the Cient API determine what happens with a particuar cient or API request. For exampe, a request can go directy to the oca data store or to a server through messaging. For more information about the Cient API, see Cient API object mode on page 21 and the Cient API reference documentation. Avaya IC Cient SDK Programmer Guide May

16 Chapter 1: Introduction SDK cient framework The SDK cient framework provides the infrastructure for the Cient API casses. This infrastructure incudes events, interface with communication ayers, and error handing. The SDK cient framework ets you: Send events to a server. Receive events from server. Access the Hierarchica data store. Hierarchica Data Store The Hierarchica Data Store (HDS) is a cient-side data repository or cache for event data received from the Cient SDK server components. This cache reduces the number of cas that a custom appication needs to make to a server. The SDK cient framework can access data through the Hierarchica Data Store. The Hierarchica Data Store de-seriaizes data events from the server into a memory cache. The Cient SDK incudes an API that obtains HDS diagnostic information. This diagnostic information provides a snapshot of data of a the objects in the Cient API that are cached in the HDS. The Diagnostic Viewer provided with the sampe cients dispays the data obtained by the Cient API. You can use the data provided by the Cient API to diagnose errors that occur with your custom appications. 16 Avaya IC Cient SDK Programmer Guide May 2013

17 Server components Server components The Cient SDK server is a Web appication that is depoyed on a Tomcat server. The SDK cient components use the Cient SDK server to communicate with an Avaya IC core system. The compete server-side code is written using Java. This section incudes the foowing topics: SDK server bridge on page 17 Web container on page 17 Messaging providers on page 18 Basic services on page 18 User Object Mode on page 18 SDK server bridge The SDK server bridge provides the foowing functionaity for the Cient SDK: Communication between the core Avaya IC services and the custom appication through the server messaging provider. Interface to interact with the User Object Mode (UOM). The SDK server bridge receives events from the SDK cient framework through the server messaging component. Depending on the event received, the SDK server bridge makes the appropriate cas to the UOM. The SDK server bridge uses the Cient SDK server objects to determine which cas to make to the UOM. The SDK server bridge can aso receive events from the UOM. The SDK server bridge then uses the cient messaging provider to send these events to the Cient SDK cient framework. The Cient SDK server objects perform a mapping required between the Cient SDK and the UOM. The Cient SDK server objects are simiar to the Cient API object mode. These objects can: Be a wrapper on existing UOM objects. Reference the corresponding UOM objects. Use their own rues to construct their state based on the UOM objects. Web container The Web container is the Tomcat servet engine and Web server used by the Cient SDK server. Avaya IC Cient SDK Programmer Guide May

18 Chapter 1: Introduction Messaging providers The SDK mediator incudes the foowing messaging providers that are used for asynchronous communication between the cient and server: Cient messaging provider: The SDK cient components use the cient messaging provider to send or receive events. Server messaging provider: The SDK server components use the server messaging provider to send or receive events. Basic services The Cient SDK uses the basic services component to communicate with the Avaya IC core system. User Object Mode The UOM is a representation of an appication user and the state of an appication user without UI. The UOM consists of a ive object mode and a we-defined set of access methods. The access methods aow your custom appication to retrieve and update the state of a currenty connected appication users. The UOM ayer is buit on the top of VESP Binding and supports the Cient SDK. The VESP Binding provides access to the Avaya IC servers. The UOM is imited stricty to representing the appication user and associated services and channes. A separate instance of the UOM exists for each appication user connected through the Cient SDK. This UOM is assembed when a new appication user ogs in. The appication user receives the channes and services determined in the appication user profie. For exampe, services and channes maintained by a supervisor can be different from those maintained by an agent. This UOM persists for the duration of an appication user session. The UOM resides in the midde tier and encompasses much of the higher-eve functionaity behind the Cient SDK. For each appication user, this ayer maintains representations of the foowing items: User Channes configured for the user, such as voice, emai, or chat Media interactions and documents, such as voice, emai, or chat, associated with the channes 18 Avaya IC Cient SDK Programmer Guide May 2013

19 Cient-side integration Participants associated with the interactions Work items that group together reated interactions Services, such as interaction service and bending service Cient-side integration For a cient-side integration, a singe user program creates the integration with the Cient SDK and the core Avaya IC system. This user program usuay runs on an agent desktop. In a cient-side integration, this user program must: Use the Cient API. Create ony one user session per instance of the user program. Server-side integration For a server-side integration, a server process creates the integration with the Cient SDK and the core Avaya IC system. This server process supports mutipe user sessions in a singe process. Each user session represents a unique Avaya IC ogin ID. Usuay, the agent desktop appication communicates to this server, either directy or through other servers, to use the Avaya IC functionaity. In a server-side integration, the Cient SDK: Does not have any presence on the agent desktops. Is present ony on the server machine. Additiona documentation for the Cient SDK Avaya IC aso provides some additiona documentation for the Cient SDK. You can access this information on the Avaya IC CD-ROMs. Object mode and state modes: The foowing diagrams are avaiabe in PDF format: Object mode: sdkobjectmode.pdf State modes for a statefu Cient SDK objects: sdkstatemodes.pdf Avaya IC Cient SDK Programmer Guide May

20 Chapter 1: Introduction These diagrams are incuded on the Avaya IC 7.2 Documentation CD-ROM and are instaed in the foowing ocation: IC_INSTALL_DIR\IC72\sdk\design Cient API documentation: The Cient API documentation is avaiabe in JavaDoc and ndoc formats. The Cient API documentation incudes detaied information about the object mode, such as methods, casses, fieds, and constructors. The foowing tabe ists the ocations where the Cient API documentation is instaed. Format Cient API documentation for the.net API Cient API documentation for the Java API. Instaation ocation IC_INSTALL_DIR\IC72\sdk\design\dotnet\doc IC_INSTALL_DIR\IC72\sdk\design\java\doc 20 Avaya IC Cient SDK Programmer Guide May 2013

21 Chapter 2: Cient API object mode The Cient API is an object oriented Interface. The Cient API exposes Avaya IC functionaity as casses, methods, and contextua events. The event istener objects consume Avaya IC events. The Java and.net casses of the Cient API use the same object mode. This object mode incudes a objects, casses, and methods that you can use to determine what happens with a cient or API request. This section incudes the foowing topics. Communication through the Cient SDK on page 21 Work items and the Current concept on page 23 Events in the Cient SDK on page 26 Overview of the object mode on page 28 Cient API objects on page 29 Attributes on the WorkItem object on page 50 Communication through the Cient SDK Communication through the Cient SDK is different from communication through the Avaya IC agent desktop appications. This section incudes the foowing topics: Deivery of communications to appication users on page 21 Deivery of outbound communications from appication users on page 22 Deivery of communications to appication users In the Avaya IC agent desktop appications, the deivery of communications from customers to appication users focuses on the voice, emai, and chat channes. Each communication is a contact in Avaya Agent or a work item in Avaya Agent Web Cient. The Avaya IC agent desktop appications have a 1:1 ratio of communication to contact or work item deivered to the appication user. Each contact or work item represents one communication from a customer. These communications are deivered as communication media to the agent desktop appication. Avaya IC Cient SDK Programmer Guide May

22 Chapter 2: Cient API object mode The Cient SDK starts with the assumption that a communications are not equa. Communications have different quaities and nuances that need to be considered. Voice takes the argest amount of focus because the communication is interactive and rea-time. Chat is aso interactive and rea-time, but the communication is sower, and a textua transcript aows for context shifts between mutipe communications. Emai is static in content, not interactive or rea-time. The Cient SDK uses a 1:1 ratio of communication to item deivered to an appication user. Instead of deivering a contact or work item as a communication media, the Cient SDK deivers a work item in a WorkItem object. A WorkItem can contain the communication as a media interaction or as a static document. The WorkItem aows future enhancements to Avaya IC, such as routing of work that does not initiay contain a communication. In the Cient SDK: Voice and chat communications are media interactions. Emai communications are static documents. For more information about the WorkItem and other objects in the Cient API object mode, see Cient API object mode on page 21. Deivery of outbound communications from appication users In Avaya IC agent desktop appications and through the Cient SDK, appication users can initiate work. In Avaya IC 7.2, this work is imited to outbound emai messages and voice cas. Because outbound work is not associated with an existing WorkItem, the custom appication must use the channe to create an outbound communication. As a resut of this operation, the Cient SDK creates a WorkItem. That WorkItem must use the channe that represents the required type of communication. For exampe, a MakeCa on the Channe.VoiceChanne object initiates a new outbound voice contact. This MakeCa provides a WorkItem with a VoiceMediaInteraction to represent the new outbound voice communication. Simiary, a NewEmai ca on the Channe.EmaiChanne creates a WorkItem where a new emai draft can be inked. Note: Note: In case of caback scenario, an outbound voice ca is paced using workitem object, so that both the chat and voice media interactions can be grouped together in a singe workitem object. 22 Avaya IC Cient SDK Programmer Guide May 2013

23 Work items and the Current concept Work items and the Current concept The Cient SDK uses the concept of Current for work items that are assigned to an appication user. The Current concept is aso used in the Avaya Agent Web Cient, but is not used in Avaya Agent. To deveop an appication in the Cient SDK, you must understand the concept of Current. This section incudes the foowing topics: Reationship between Current and the Working state on page 23 Identifying the Current work item on page 23 How a work item becomes Current on page 24 Effect of makecurrent() on page 24 Reationship between Current and Voice Traiing on page 25 Reationship between Current and the Working state The Current concept was introduced to address the foowing issues that can occur when the Working state is used to indicate the work item that is being handed by an appication user: Mutipe work items can be considered Working at the same time: For exampe, an appication user taks on the teephone to a customer and has an emai work item open in the Emai appication. Because both items are in Working state, Avaya IC cannot determine which work item the appication user is actuay handing. This probem can skew reporting for that appication user. A work item in Wrapup state cannot be Working: If mutipe work items are in the Wrapup state, Avaya IC cannot track which wrapped work item the appication user is actuay handing. This probem can skew reporting. Identifying the Current work item In the Cient SDK, a work item is considered Current if that work item has primary focus in the appication. Current indicates that the appication user is activey handing the work item and that the work item is gathering time for reporting purposes. Current is not the same as the Working state for work items. A work item need not be working to become a Current workitem. However, a Working work item must be Current or Voice Traiing. Avaya IC Cient SDK Programmer Guide May

24 Chapter 2: Cient API object mode When a work item becomes Current, Avaya IC fags that work item. This fag identifies the work item as the one that has primary focus and is currenty being handed. Ony one work item can be Current and considered to be the item that an appication user is handing. For exampe, an appication user can have mutipe work items in the Wrapped state, but ony one of those work items can be Current. You cannot have an additiona Current work item, even if a second work item is of a different media type. How a work item becomes Current A work item becomes Current when you ca makecurrent() on the work item. Usuay this ca occurs when an appication user seects that work item in the appication.! Important: Important: If you want accurate reporting, you must ca makecurrent() on the work item at the correct time. For exampe, if an emai does not become Current when opened by an appication user, you cannot capture and report on the time the appication user worked on that emai. Work items raise a CURRENT_CONTEXT_CHANGED event to et consumers know of a change in their Current status. For exampe, if WorkItem A is current, and makecurrent() is caed on WorkItem B: 1. The Current fag is ceared from WorkItem A, which generates the WorkItem.CurrentContextChanged event. An iscurrent() ca on WorkItem A now returns fase. 2. WorkItem B is fagged as the Current work item, which generates a WorkItem.CurrentContextChanged event. An iscurrent() ca on WorkItem B now returns true. Effect of makecurrent() When makecurrent() is invoked on WorkItem A, the foowing events are triggered: 1. If WorkItem B is Current: a. The Current fag is ceared from WorkItem B. b. WorkItem B raises an event that indicates a change in its Current context. c. iscurrent() on WorkItem B returns fase. 2. If WorkItem B can be deferred or paused: a. The defer() method is invoked. b. WorkItem B transitions into the inactive Paused or Deferred state. 24 Avaya IC Cient SDK Programmer Guide May 2013

25 Work items and the Current concept c. A state change event is raised for WorkItem B. 3. WorkItem A is fagged as Current: a. WorkItem A raises a WorkItem.CurrentContextChanged event. b. iscurrent() returns true. 4. If WorkItem A can be activated: a. The activate() method is invoked. b. WorkItem A transitions into the Working state. c. A state change event is raised for WorkItem A. For exampe, if WorkItem A is inactive when makecurrent() is invoked, WorkItem A is fagged Current and is activated. However, if WorkItem A is in Wrapped state when makecurrent() is invoked, WorkItem A is fagged Current but is not activated. A WorkItem cannot transition from Wrapped state to Working state. Reationship between Current and Voice Traiing With voice traiing, an appication user can mutitask in a mutimedia environment that uses the Current concept. For exampe, with voice traiing, an appication user can repy to an emai and continue to speak to a customer on the teephone. In the Cient SDK, ony one work item can be current. This imit impies that an appication user can have ony one Working work item and cannot mutitask. For exampe, if an appication user taks on the teephone to a customer and seects an emai work item, the Current concept inactivates the voice work item. This inactivation automaticay paces the teephone ca on hod. Voice traiing avoids this automatic inactivation of a voice work item. With voice traiing, a voice work item can be Working but not Current. With voice traiing, a voice work item can continue to trai after an appication user seects an emai work item to hande. Both work items remain Working, and the appication user can hande them simutaneousy. However, the Cient SDK considers ony the emai work item to be Current. You can configure voice traiing through Avaya IC properties. For more information, see IC Administration Voume 2: Agents, Customers, & Queues. Usuay, voice traiing can be determined by the foowing query: WorkItem.isCurrent() == fase and WorkItem.getState() == WorkItem.State.WORKING Important:! Important: Ony voice work items can be paced in a voice traiing state. Chat cannot satisfy the above query, except during state transitions, which are transient in nature. When a chat transitions out of the Current state, the work item is paused. Avaya IC Cient SDK Programmer Guide May

26 Chapter 2: Cient API object mode Events in the Cient SDK The Cient API defines the events for the objects in the Cient SDK. This section incudes the foowing topics: Operations on page 26 Method cas on page 26 Event registration on page 27 Operations The objects in the Cient API expose methods. Each method represents an operation that can be performed on these objects. Any operation has the foowing basic outcomes: Succeeded Faied A successfu operation can incude data that needs to be returned as a resut of that operation. Method cas With the Cient API, method cas can be either synchronous or asynchronous. Synchronous method cas If the method ca is synchronous, the outcome can be easiy determined. For exampe, a return vaue can indicate the outcome or return data, or the method can throw an exception. Exampes of synchronous communication with the Cient API incude ogging in, and fetching and upoading emai attachments. Asynchronous method cas If the method ca is asynchronous, the outcome or return data can be known ony through notifications by the Cient SDK. This notification is done through events. A asynchronous operations performed on an object must resut in an event. The event indicates whether the operation succeeded or faied. Asynchronous communications use the cient messaging provider and the server messaging provider. 26 Avaya IC Cient SDK Programmer Guide May 2013

27 Events in the Cient SDK A faiure event is aways expicity raised if an operation fais. An exception is an expicit indication of faiure. An exception might be thrown if the state of an object is invaid. A success event can be impicit or expicit. Impicit indication of success: An impicit success indication occurs when an operation causes a change in the object state that ceary indicates the action succeeded. In this case, the state change of the object is sufficient to determine that the operation was successfu. For exampe, an impicit indication of a successfu operation occurs when an appication user tries to reease or defer a WorkItem: If the WorkItem is successfuy reeased, the WorkItem enters the Wrapped state. If the reease fais, an OPERATION_FAILED event is generated. If the WorkItem is successfuy deferred, the WorkItem enters the Deferred state. If the deferra fais, an OPERATION_FAILED event is generated. Expicit indication of success: An expicit indication occurs in one of the foowing cases: An operation does not cause a state change. An operation invoves a process where a state change does occur, but the process cannot uniquey identify that an operation has competed successfuy. In such cases, a unique event is generated that indicates success of that operation. For exampe, an expicit indication of a successfu operation occurs when you set WorkItem attributes: If the attributes are written successfuy, an OPERATION_SUCCEEDED event is generated. If the write fais, an OPERATION_FAILED event is generated. Event registration The Cient SDK provides a mechanism for cients to register with objects that generate events. Your custom appication must add itsef as a istener to objects for a events that matters to the appication. When an event change occurs within an object, the Cient SDK generates an event that is propagated to a isteners to that object. Usuay, these events are raised as a resut of: User operations on a particuar object Changes in the object driven by the core Avaya IC system Avaya IC Cient SDK Programmer Guide May

28 Chapter 2: Cient API object mode Overview of the object mode The foowing diagram shows the object mode that forms the base of the Cient API. For more information about each object, see Cient API objects on page 29. For information about how to access a diagram of the compete object mode, see Additiona documentation for the Cient SDK on page Avaya IC Cient SDK Programmer Guide May 2013

29 Cient API objects Cient API objects This section provides an overview of the objects in the Cient API object mode. For more information about the casses and methods within these objects, see the API reference documentation provided with the Cient API. This section incudes the foowing topics: Appication on page 29 Session on page 30 User on page 33 Channe on page 33 VoiceChanne on page 35 EmaiChanne on page 36 ChatChanne on page 36 WorkList on page 37 WorkItem on page 38 MediaInteraction on page 41 VoiceMediaInteraction on page 42 ChatMediaInteraction on page 45 Document on page 48 EmaiDocument on page 48 DraftDocument on page 49 EmaiDraft on page 49 Appication Description Limitations Appication is the starting point for the Cient SDK. You can use the Login method of the Appication object to provide a Session object. None. Avaya IC Cient SDK Programmer Guide May

30 Chapter 2: Cient API object mode Sampe scenarios This object is used in the foowing scenarios: Login scenario on page 126 Logout scenario on page 128 Password change scenario on page 156 Session status scenario on page 157 Connectivity status scenario on page 158 Session shutdown request scenario on page 159 Session Description Session represents the Avaya IC session for a ogged in appication user. In the Cient SDK, Session performs a centra roe of the primary object that you use to access other objects. You use this object to register for any pubished events on Cient SDK objects. Session aso provides the events reated to the oad, connectivity, and state of an appication user. You can use Session to: Register isteners for a pubished Cient SDK object events. Limitations Receive events regarding agent state, workoad, and agent connectivity. Manage avaiabiity and Auxwork statuses. Manage supervisory routines. Get system codes for Auxwork, ogout, and wrapup. Access appication user ADU data through the session attribute functions. Get character sets and Avaya IC properties. Get other objects incuding Channe and WorkList. The Session object has the foowing imitations: To use the GetSessionAttribute and SetSessionAttribute functions, you must have to customize the Cient SDK to specify the ADU eements that are avaiabe to the function cas. To use character sets and Avaya IC properties, you must have to customize the Cient SDK to make them avaiabe to the function cas. 30 Avaya IC Cient SDK Programmer Guide May 2013

31 Cient API objects To use wrapup codes, Aux codes, and reease reason codes, you must have to customize the Cient SDK to make them avaiabe to the function cas. For more information, see Customization guideines on page 90. Session state mode diagram The foowing diagram shows the state mode for Session. Avaya IC Cient SDK Programmer Guide May

32 Chapter 2: Cient API object mode State definitions The foowing tabe describes the state definitions incuded in the state mode for Session. State Logged_in Initiaized Init_auxwork Auxwork Init_avaiabe Avaiabe Logged_out Definition Appication user is successfuy ogged in, but active state has not yet been determined. Logged_in is the initia state reported to cients through the Cient SDK. Session was successfuy initiaized. This state is transitiona. Appication user submits request to enter Auxwork state. The Avaya IC system uses this state to acknowedge the request and prevent the deivery of new WorkItems. Appication user has successfuy entered Auxwork state. This state confirms that a WorkItems are in a state that supports Auxwork. No WorkItems wi be deivered unti the appication user enters Avaiabe state. Appication user submits request to enter Avaiabe state. The Avaya IC system uses this state to acknowedge the request and prepare for the avaiabiity of the appication user. Appication user has successfuy entered Avaiabe state. This state confirms that the Avaya IC system competed the request from the appication user to become avaiabe. The appication user can now receive WorkItems on active channes. Appication user has successfuy ogged out. A WorkItems in the WorkList are in an acceptabe ogout aowabe state, such as deferred. Avaya IC has competed the ogout. Sampe scenarios This object is used in the foowing scenarios: Login scenario on page 126 Agent avaiabiity scenario on page 129 Session status scenario on page 157 Connectivity status scenario on page 158 Session shutdown request scenario on page 159 Enabe and disabe operationa state scenario on page 160 Dispay channe properties scenario on page 131 AddressBook scenario on page 150 Prompt on WorkItem arriva scenario on page Avaya IC Cient SDK Programmer Guide May 2013

33 Cient API objects Wrapup diaog box scenario on page 172 Use terminate reasons scenario on page 173 User Description Limitations User represents the appication user profie attributes such as name and ogin ID. You can use the User object to access core appication user attributes and retrieve agent information and roe. Some channe specific data is unavaiabe unti the Session is initiaized. Channe Description Channe is a generic representation of a path for a communication. You can use Channe to: Access functions specific to a media, independent of an existing WorkItem. Receive heath and state events specific to the configured media. Retrieve configured task oads and ceiings for a given channe. Log in to, og out of, or reset a connection for a channe. Create a new WorkItem with outbound intent for voice or emai. In Avaya IC 7.2, the channes are VoiceChanne, EmaiChanne, and ChatChanne. Limitations None. Avaya IC Cient SDK Programmer Guide May

34 Chapter 2: Cient API object mode Channe state mode diagram The foowing diagram shows the state mode for Channe. State definitions Each ChanneConnection maintains channe state. The state of a channe determines the abiity of the system to assign work items to a particuar channe. The channe state is triggered by the user. 34 Avaya IC Cient SDK Programmer Guide May 2013

35 Cient API objects The foowing tabe describes the state definitions incuded in the state mode for Channe. State oggedout ide busy occupied active Definition The appication user is not currenty signed in or ogged into the channe. The appication user is avaiabe to receive work item on the channe, but does not currenty have any work items. The appication user does not want to be avaiabe to receive new work items and has set his or her state accordingy. For exampe, the user is in AuxWork. The appication user is handing the maximum number of work items permitted by his or her current endpoint setting. The appication user is handing at east one work item, but is avaiabe to receive more work items. Sampe scenarios This object is used in the foowing scenarios: Dispay channe properties scenario on page 131 Enabe and disabe channe operationa state scenario on page 161 VoiceChanne Description VoiceChanne represents the channe that you use to work with voice interactions. You can use VoiceChanne to: Limitations None. Log in to and og out of the voice channe. Initiate new outbound voice communications, resuting in a new WorkItem with a voice media interaction. Reset the connection for the voice channe when the hard phone and soft phone get out of sync. Avaya IC Cient SDK Programmer Guide May

36 Chapter 2: Cient API object mode Sampe scenarios This object is used in the foowing scenarios: Dispay channe properties scenario on page 131 Enabe and disabe channe operationa state scenario on page 161 EmaiChanne Description EmaiChanne represents the channe that you use to work with emai documents. You can use EmaiChanne to: Limitations Log in to and og out of the emai and chat channes. Initiate new outbound emai communications, resuting in a new WorkItem through which the emai draft can be composed. Reset the connections for the chat and emai channes. Resetting, ogging in, and ogging out of the emai channe aso affect the chat channe. Sampe scenarios This object is used in the foowing scenarios: Dispay channe properties scenario on page 131 Enabe and disabe channe operationa state scenario on page 161 ChatChanne Description ChatChanne represents the channe that you use to work with chat interactions. You can use ChatChanne to: Log in to and og out of the chat and emai channes Reset the connections for the chat and emai channes 36 Avaya IC Cient SDK Programmer Guide May 2013

37 Cient API objects Limitations ChatChanne has the foowing imitations: ChatChanne works with inbound communications ony. An appication user cannot initiate a chat. Sampe scenarios Resetting, ogging in, and ogging out of the chat channe aso affect the emai channe. This object is used in the foowing scenarios: Dispay channe properties scenario on page 131 Enabe and disabe channe operationa state scenario on page 161 WorkList Description WorkList represents the structure that contains every WorkItem assigned to an appication user. You can use WorkList to: Limitations None. Sampe scenarios Receive notification that a WorkItem was added to or removed from the work ist of an appication user. Get the WorkItem objects assigned to an appication user. This object is used in the foowing scenarios: Dispay assigned work items scenario on page 162 Prompt on WorkItem arriva scenario on page 163 Workitem ifecyce scenario on page 133 Avaya IC Cient SDK Programmer Guide May

38 Chapter 2: Cient API object mode WorkItem Description WorkItem is the primary processing object for the Cient SDK and performs the foowing tasks: Represents the work assigned to an appication user without regard to the associated media, aowing a WorkItem to exist without active media. Groups together reated MediaInteraction and Document objects. You can use WorkItem to: Aow an appication user to accept, coaborate on, and compete assigned work. Track the time spent by an appication user on the Current WorkItem. A coaboration occurs when an appication user communicates with another party about an active WorkItem. When an appication user starts a coaboration, the appication must decare the intent of the coaboration: conference, consutation, or transfer. A conference competes when a active parties are joined in the same media that was used to initiate the conference. A consutation keeps a participants separate and competes when the new party is reeased. A transfer is a bind handoff of a WorkItem to another party. Limitations The WorkItem object has the foowing imitations: Ony one appication user can own a WorkItem at any given time. Each WorkItem can contain either VoiceMediaInteraction, ChatMediaInteraction, EmaiDocument or both VoiceMediaInteraction and ChatMediaInteraction as reated media interactions in case of caback. A WorkItem must be associated with a VoiceMediaInteraction, ChatMediaInteraction, or EmaiDocument. For a conference or consutation, a WorkItem must be associated with an interactive media, such as VoiceMediaInteraction or ChatMediaInteraction. 38 Avaya IC Cient SDK Programmer Guide May 2013

39 Cient API objects WorkItem state mode diagram The foowing diagram shows the state mode for WorkItem. Avaya IC Cient SDK Programmer Guide May

40 Chapter 2: Cient API object mode State definitions The foowing tabe describes the state definitions incuded in the state mode for WorkItem. State Initiating Nonviabe Aerting Paused Deferred Working Transferring Conferencing Definition An appication user initiates a WorkItem. This state occurs when an appication user makes an outbound phone ca. The WorkItem is in an unusabe state. Usuay a WorkItem does not get deivered in this state or is ony in this state temporariy. The foowing scenarios might cause a WorkItem to be deivered in the Nonviabe state: An appication user has worked on a Session that contains a WorkItem with an active VoiceMediaInteraction, and that Session terminated abnormay through a process crash. The next time the appication user ogs in, the appication user receives the WorkItem with the VoiceMediaInteraction in a Nonviabe state. The appication user can reease the WorkItem. An appication user receives a new WorkItem that contains a VoiceMediaInteraction. Auto-accept is not enabed. Therefore, the WorkItem is in the Nonviabe state ony unti the state changes to Aerting. This scenario is usuay caused by a time ag after the server receives the ca from the Teephony server and before the server receives the attributes of the ca from the EDU server. Nonviabe is an exception state. You wi see a WorkItem in this state for an extended duration ony if there is a probem. A WorkItem can be in this state for a transient period of time. The WorkItem was deivered to an appication user. The Avaya IC system is waiting for the appication user to accept the WorkItem. The Workitem was accepted but is not current. This state usuay indicates that the appication user is working on a different task. The appication user has postponed the WorkItem to be worked on ater. A WorkItem in the Deferred state does not count against the current workoad eves of an appication user. This state is ony vaid for WorkItems that do not contain interactive media, such as emai. The WorkItem is active and gathering time. A WorkItem in the Working state counts against the current workoad eves of an appication user. The WorkItem is being processed as a bind transfer. Transferring is a transitiona state. The Avaya IC system is estabishing a conference with a new party for the WorkItem. The conference incudes the party that originated the WorkItem. 40 Avaya IC Cient SDK Programmer Guide May 2013

41 Cient API objects State Consuting Wrapup Competed Definition The Avaya IC system is estabishing a conference with a new party for the WorkItem. The conference wi not incude the party that originated the WorkItem. The WorkItem was reeased. The Cient SDK integration must ca compete to exit this state and have the WorkItem compete. Wrapup was competed. Competed is an interna Avaya IC state for ceanup of the WorkItem. Sampe scenarios The WorkItem object is used in the foowing scenarios: Session shutdown request scenario on page 159 Dispay assigned work items scenario on page 162 Prompt on WorkItem arriva scenario on page 163 Prompt on WorkItem arriva scenario on page 163 Enabe and disabe work item operationa state scenario on page 165 Workitem ifecyce scenario on page 133 Workitem coaboration scenario on page 136 Access work item attributes scenario on page 165 Wrapup diaog box scenario on page 172 Use terminate reasons scenario on page 173 Dispay emai scenario on page 142 Dispay WorkItem History scenario on page 146 Dispay Customer History scenario on page 148 MediaInteraction Description MediaInteraction is a generic representation of rea-time, interactive communication with one or more parties. A MediaInteraction must be associated with a WorkItem. MediaInteraction provides access to generic media events for states and operations. Capabiities and media-specific events are provided through the VoiceMediaInteraction and ChatMediaInteraction subcasses. Avaya IC Cient SDK Programmer Guide May

42 Chapter 2: Cient API object mode For Avaya IC 7.2, the communication paths for MediaInteration are voice and chat ony. Limitations None. Sampe scenarios This object is used in the foowing scenarios: Dispay assigned work items scenario on page 162 Prompt on WorkItem arriva scenario on page 163 Enabe and disabe work item operationa state scenario on page 165 OnHod/OffHod indication scenario on page 138 VoiceMediaInteraction Description VoiceMediaInteraction represents rea-time work on the voice channe. VoiceMediaInteraction provides access to features and events that are specific to voice communication. You can use VoiceMediaInteraction to: Limitations None. Put a voice ca on hod. Reconnect to a voice ca. Send DTMF digits. Receive events that are specific to voice interaction processing. 42 Avaya IC Cient SDK Programmer Guide May 2013

43 Cient API objects VoiceMediaInteraction state mode diagram The foowing diagram shows the state mode for VoiceMediaInteraction. Avaya IC Cient SDK Programmer Guide May

44 Chapter 2: Cient API object mode State definitions The foowing tabe describes the state definitions incuded in the state mode for VoiceMediaInteraction. State Initiating Nonviabe Deivered Active Inactive Disconnected Competed Definition An appication user initiates a WorkItem. This state occurs when an appication user makes an outbound phone ca. The WorkItem associated with the VoiceMediaInteration is in an unusabe state. Usuay a WorkItem does not get deivered in this state or is ony in this state temporariy. The foowing scenarios might cause a WorkItem to be deivered in the Nonviabe state: An appication user has worked on a Session that contains a WorkItem with an active VoiceMediaInteraction, and that Session terminated abnormay through a process crash. The next time the appication user ogs in, the appication user receives the WorkItem with the VoiceMediaInteraction in a Nonviabe state. The appication user can reease the WorkItem. An appication user receives a new WorkItem that contains a VoiceMediaInteraction. Auto-accept is not enabed. Therefore, the WorkItem is in the Nonviabe state ony unti the state changes to Aerting. This scenario is usuay caused by a time ag after the server receives the ca from the Teephony server and before the server receives the attributes of the ca from the EDU server. Nonviabe is an exception state. You wi see a WorkItem in this state for an extended duration ony if there is a probem. A WorkItem can be in this state for a transient period of time. The WorkItem associated with the VoiceMediaInteraction was deivered to an appication user. The Avaya IC system is waiting for the appication user to accept the WorkItem that contains the VoiceMediaInteraction. The VoiceMediaInteraction is active with the appication user and the initia party. The ca associated with the VoiceMediaInteraction is on hod. Usuay, this state occurs because the appication user needs to compete another activity, or initiate a transfer, conference or consut. The ca associated with the VoiceMediaInteraction was disconnected. Competed is an interna Avaya IC state for ceanup of VoiceMediaInteractions. 44 Avaya IC Cient SDK Programmer Guide May 2013

45 Cient API objects Sampe scenarios This object is used in the foowing scenarios: Workitem coaboration scenario on page 136 OnHod/OffHod indication scenario on page 138 OnHod aert on threshod scenario on page 166 ChatMediaInteraction Description ChatMediaInteraction represents rea-time work on the chat channe. ChatMediaInteraction provides access to features and events specific to chat communication. You can use ChatMediaInteraction to: Limitations Access the chat transcripts as documents associated with the WorkItem. Receive events that are specific to chat interaction processing. Send text or URLs to chat participants. Retrieve caback information and using WorkItem object to pace voice ca back to customer. Create joinus hande for invoving additiona peope in ongoing chat communication. Monitor chat interactions of agents. ChatMediaInteraction has the foowing imitations: Outbound chat initiated by an appication user is not supported. Datawake is not supported. Avaya IC Cient SDK Programmer Guide May

46 Chapter 2: Cient API object mode ChatMediaInteraction state mode diagram The foowing diagram shows the state mode for ChatMediaInteraction. 46 Avaya IC Cient SDK Programmer Guide May 2013

47 Cient API objects State definitions The foowing tabe describes the state definitions incuded in the state mode for ChatMediaInteraction. State Deivered Active Inactive Disconnected Competed Definition The ChatMediaInteraction was deivered to an appication user. The Avaya IC system is waiting for the appication user to accept and activate the ChatMediaInteraction. The appication user is in the chat room, activey handing the chat work item. The WorkItem associated with the ChatMediaInteraction is in a Working state. The appication user is not activey handing the chat work item. The WorkItem associated with the ChatMediaInteraction is not in a Working state. Usuay, this state occurs because the appication user has switched to work on a different WorkItem. The chat associated with the ChatMediaInteraction was disconnected. Competed is an interna Avaya IC state for ceanup of ChatMediaInteractions. Sampe scenarios This object is used in the foowing scenarios: Dispay text message scenario on page 139 Inactivity aert on threshod scenario on page 167 Language fiter scenario on page 168 Customer-generated aert scenario on page 169 Avaya IC Cient SDK Programmer Guide May

48 Chapter 2: Cient API object mode Document Description Document is a container for noninteractive information. From the Document object, you can perform the foowing operations: Limitations Get the contents of the document. Get the WorkItem object associated with the document. Get the document type. Receive events on changes to the document. A Document must be associated with a WorkItem. None. Sampe scenarios This object is used in the foowing scenario: Enabe and disabe work item operationa state scenario on page 165 EmaiDocument Description EmaiDocument represents work on the emai channe. You can use EmaiDocument to: Limitations None. Deiver the contents of an emai to the requesting custom appication. Access the contents and attributes of the emai, such as the header fieds, anguage, body, and attachments. Create an EmaiDraft reated to the existing emai, such as repy or forward. 48 Avaya IC Cient SDK Programmer Guide May 2013

49 Cient API objects Sampe scenarios This object is used in the foowing scenarios: Dispay emai scenario on page 142 New Outbound emai scenario on page 143 Repy to emai scenario on page 144 Appy signatures scenario on page 169 Support for attachments scenario on page 170 DraftDocument Description DraftDocument is a generic representation of an outbound document. Drafts can be saved for ater access by an appication user. However, a draft document is private and cannot be shared with other appication users. The structure of DraftDocument is purposefuy generic to enabe future support of other deivery mechanisms. Limitations The DraftDocument object supports ony EmaiDraft in Avaya IC 7.2. EmaiDraft Description EmaiDraft represents an outbound emai. EmaiDraft incudes severa types of drafts, based on the type of outbound message the draft wi create. These types of drafts incude: Repy Forward Repy Request Subject Matter Expert (SME) Request Request for additiona information Avaya IC Cient SDK Programmer Guide May

50 Chapter 2: Cient API object mode Limitations EmaiDraft supports ony one draft of each type at any given time for EmaiDocument. For exampe, an appication user can have a draft repy, a draft forward to another appication user, and a draft request for information from an externa agent simutaneousy. However, an appication user cannot have two draft repies. Sampe scenarios This object is used in the foowing scenarios: Repy to emai scenario on page 144 Appy signatures scenario on page 169 Attributes on the WorkItem object The Cient SDK provides a structure around attributes that improves the integration of the Cient SDK with the Avaya IC system, IC Repository database, and with other systems. This structure is provided by an EDU container that hods a Cient SDK attributes for a work item. You must use this EDU container to access and set data associated with a work item. This section incudes the foowing topics: Attribute storage in the EDU on page 50 WorkItem functions for attribute storage on page 51 Data integration with a custom appication on page 51 Attribute data in the Contact tabe on page 51 Exampe: moving data from a contact routing workfow to the database on page 52 Attribute storage in the EDU The EDU incudes the contact_attr.<name> container that stores attributes for a work item. The contact_attr container has ony one entry for each named attribute. You can manipuate every eement in the container with the ContactAttribute functions on the WorkItem object. The contact_attr container can maintain one vaue for each attribute on a work item. If the container aready has a vaue for an attribute, the Cient SDK wi overwrite the existing vaue with a new vaue. 50 Avaya IC Cient SDK Programmer Guide May 2013

51 Attributes on the WorkItem object WorkItem functions for attribute storage The foowing tabe ists the functions on the WorkItem object that can access the contact_attr container in the EDU. Function SetContactAttribute(NameVaueList) GetContactAttribute Description Takes a NameVaueList object that contains the name vaue pairs to be inserted in the contact_attr container. Returns a NameVaueList object containing a entries in the contact_attr container. Data integration with a custom appication The Cient SDK and a custom appication perform most data ookups in the Avaya IC system through processes, such as workfows. However, a custom appication must have access to and be abe to manipuate, dispay, or reference data. To write data for the Cient SDK into the contact_attr container, a workfow or other Avaya IC process must prefix the key with contact_attr. Then, the WorkItem ContactAttribute functions can update and fetch the data. Attribute data in the Contact tabe When a user competes a work item, the Avaya IC system retires the associated EDU. The Report server then processes that EDU and saves the EDU data to the Contact tabe in IC Repository. By defaut, this EDU data does not incude the contact_attr container. To add data from the contact_attr container into the database, you must create fied expression records in the mapping rues structures for each EDU attribute you want to save. Note: Note: Avaya recommends that you store the data in separate fieds. Do not share a fied with mixed eements. To save attribute data in the Contact tabe of IC Repository, you must: 1. Add the required new fieds to the Contact tabe in IC Repository. 2. Create new fied expression records for the contact creation rue. Avaya IC Cient SDK Programmer Guide May

52 Chapter 2: Cient API object mode Exampe: moving data from a contact routing workfow to the database This exampe shows how a custom appication can: Obtain customer information from the database through a contact routing workfow. Return information to the database after the appication user competes the work item. Coumns required in the Contact tabe This exampe requires that you add the foowing coumns to the Contact tabe with Database Designer: Contact fiedname account_no customer_vaue promised_payment promised_date Fied expression records required for the contact create rue This exampe requires that you add the foowing fied expression records for the contact create rue: Create rue Fied name Fied vaue Contact account_no contact_attr.account_no Contact customer_vaue contact_attr.customer_vaue Contact promised_payment contact_attr.promised_payment Contact promised_date contact_attr.promised_date 52 Avaya IC Cient SDK Programmer Guide May 2013

53 Attributes on the WorkItem object How the data moves through the Avaya IC system 1. The contact routing workfow performs a database ookup on the customer for the foowing information: account_no customer_vaue account_baance 2. The database ookup returns the foowing information to the workfow: Fied name Vaue account_no customer_vaue A God account_baance $ Because the custom appication needs this information, the workfow writes the data to the contact_attr container of the EDU, as foows: Container eement Vaue contact_attr.account_no contact_attr.customer_vaue A God contact_attr.account_baance $ The workfow routes the work item to an appication user through the Cient SDK. 5. To use the information in the contact_attr container in a screen pop or other function, the custom appication: a. Cas workitem.getcontactattribute. b. Receives a NameVaueList with the foowing data: Name Vaue account_no customer_vaue A God account_baance $ During the conversation between the appication user and the customer, the customer makes a promise to pay $200 on March 13, Avaya IC Cient SDK Programmer Guide May

54 Chapter 2: Cient API object mode 7. To record this information for historica data, the custom appication: a. Cas workitem.setcontactattribute. b. Passes a NameVaueList that contains: Name Vaue promised_payment $200 promised_date March 13, The Cient SDK updates the contact_attr container of the EDU, as foows: Container eement Vaue contact_attr.account_no contact_attr.customer_vaue A 9. After the processing is compete, the EDU retires to the Report server. 10. Because the coumns aready exist in the Contact tabe, and the rows aready exist in the fied expression tabe, the Report server automaticay writes the data to the Contact tabe. God contact_attr.account_baance $300 contact_attr.promised_payment $200 contact_attr.promised_date March 13, Avaya IC Cient SDK Programmer Guide May 2013

55 Chapter 3: Sampe cients The Cient SDK incudes two sampe cients that you can use in a test or deveopment environment to test functionaity that can be accessed through the Cient API. This section incudes the foowing topics: Overview on page 55 Features not supported in the sampe cients on page 56 About the Java sampe cient on page 56 About the.net sampe cient on page 61 Overview The Cient SDK incudes foowing sampe cients: A sampe cient written in Java. A sampe cient written in C# for.net. The above sampe cients are not designed for use in a production environment.! Important: Important: Avaya does not support the use of the sampe cients in a production environment. Avaya wi respond ony to sampe cient issues in a test or deveopment environment, if you use the sampe cient to test functionaity that can be accessed through the Cient API. The user interfaces of the sampe cients have a very different ook and fee. They provide two exampes of the types of custom appications that you can deveop with the Cient SDK. You can access the source code of both sampe cients. The source code is extensivey commented to provide assistance with the Cient API and to show exampes of best practices. You can modify sections of the source code for use in your custom appications. Avaya IC Cient SDK Programmer Guide May

56 Chapter 3: Sampe cients Features not supported in the sampe cients The sampe cients do not support a of the features avaiabe with the Cient SDK. The foowing feature is not supported by either sampe cient: HTML Emai Features supported in the Java sampe cient but not supported in the.net sampe cient: Login and ogout of channes New Outbound emai Push URL in the Chat window About the Java sampe cient The Java sampe cient is deveoped using Swing in Java. The Java sampe cient is packaged in JAR fies. This section incudes the foowing topics: User interface of the Java sampe cient on page 57 Source code for the Java sampe cient on page 57 Dependencies of the Java sampe cient on page 59 Deveoping a custom Java sampe cient on page 59 Running a Java sampe cient from an SDK server system on page 60 Running a Java sampe cient from a non-sdk server system on page Avaya IC Cient SDK Programmer Guide May 2013

57 About the Java sampe cient User interface of the Java sampe cient The interface of the Java sampe cient is based on the Avaya Agent Web Cient interface. The Java sampe cient takes up minima space on the desktop when the pop-up windows are cosed. The pop-up windows incude an Emai appication and a Chat appication. The foowing figure shows the Java sampe cient with an active outbound voice work item. Source code for the Java sampe cient You can find the source code for the Java sampe cient in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\java\sampe\src The foowing tabe describes the fies that contain the source code for the Java sampe cient. Package name com.avaya.ic.sdk.sampe com.avaya.ic.sdk.sampe.ui com.avaya.ic.sdk.sampe.ui. command com.avaya.ic.sdk.sampe.ui. components com.avaya.ic.sdk.sampe.ui.event com.avaya.ic.sdk.sampe.ui.mode com.avaya.ic.sdk.sampe.ui. controers Contents Sampe cient cass that is the entry point to the appication PresentationSession that forms the gue between the mode, view, and controer components Code that manages appication user action commands Code for a the user interface and view components Casses that manage eventing between the view and controer components Casses that form the mode for the more compex user interface eements, such as ist Casses that provide a communication bridge between view components and the Cient SDK. Avaya IC Cient SDK Programmer Guide May

58 Chapter 3: Sampe cients Package name com.avaya.ic.sdk.sampe.ui. resources com.avaya.ic.sdk.sampe.uti Contents Resource management casses Some utiity casses Design configuration fies for the Java sampe cient You can find the design configuration fies for the Java sampe cient in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\java\sampe\config The foowing tabe describes the fies that contain the design for the Java sampe cient. Fie name Appication.properties CientActions.properties CientInterface.properties CientMessages.properties Contents Layout information for appication components, such as toobars and ists. Information on a actions defined for the appication. You can tie an action to mutipe user interface eements, such as toobar buttons, toobar menus, and hot keys. Information that ties property names to images used by the appication. Messages that the sampe cient dispays in the user interface. Resources for the Java sampe cient The resources used by the Java sampe cient are images. A images for the Java sampe cient are instaed in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\java\sampe\images 58 Avaya IC Cient SDK Programmer Guide May 2013

59 About the Java sampe cient Dependencies of the Java sampe cient The Java sampe cient depends on the foowing ibraries that are instaed with the Cient SDK design fies: avaya-common.jar avayaiccommon.jar common-base.jar avaya-ic-sdk-cient.jar avaya-ic-sdk-common.jar commons-ogging.jar commons-ogging-api.jar og4j jar mai.jar These ibraries are instaed in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\java\ib Deveoping a custom Java sampe cient To deveop a custom Java sampe cient using the Ecipse appication: 1. From the system where you configured the SDK server, copy the \\ <Avaya_IC72_HOME>\sdk\design\Java directory. 2. Start the Ecipse appication. 3. In Ecipse, create a new Java project and create a new Java project: Project name Location 4. Right-cick the new Java project and seect Configure Buid Path. 5. In the Properties for Custom Cient diaog box, cick Libraries. 6. Cick Add Externa JARs. 7. From the.ib directory, seect and add a the.jar fies. 8. In the navigation pane, cick Java Compier. 9. In the right pane, seect the Enabe project specific settings check box. 10. In the Cick compiance settings fied, cick JRE version 1.6. Avaya IC Cient SDK Programmer Guide May

60 Chapter 3: Sampe cients 11. Cick OK. The Ecipse appication rebuids the compete project. 12. Right-cick Project and seect Import Fie System. 13. Cick Next. 14. In the Fie system diaog box, cick Browse and seect the Java/sampe/images directory. 15. Cick Finish. 16. Right-cick Project and seect Import Fie System. 17. Cick Next. 18. In the Fie system diaog box, cick Browse and seect the Java/sampe/config directory. 19. Cick Finish. 20. Right-cick Project and navigate to com.avaya.ic.sdk.sampe. 21. Right-cick Sampecient.java and seect Run as Java appication. 22. In the Log in diaog box, enter the foowing: User Name Password SDK Server URL 23. Cick Log in. 24. Verify that the sampe cient starts and you can og in from the Java sampe cient. Running a Java sampe cient from an SDK server system 1. Navigate to the IC_INSTALL_DIR\IC72\sdk\design\Java\sampe\bin directory. 2. Doube-cick the RunCient.bat fie. 3. In the Login diaog box, enter the foowing: User Name Password Server URL. For exampe, Server name or IP address>:9700/ icsdk. 4. Cick Log in. You are ogged in the Avaya IC system from the Java sampe cient. 60 Avaya IC Cient SDK Programmer Guide May 2013

61 About the.net sampe cient Running a Java sampe cient from a non-sdk server system 1. From the system where you configured the SDK server, copy the IC_INSTALL_DIR\ IC72\sdk\design\Java directory to the system where you want to run the Java sampe cient. 2. From the \Java directory, open the RunCient.bat fie and repace the vaue for DIR with <JRE_HOME>\bin. Save the RunCient.bat fie. 3. In the \Java directory, doube-cick the RunCient.bat fie. 4. In the Login diaog box, enter the foowing: User Name Password Server URL. For exampe, Server name or IP address>:9700/ icsdk. 5. Cick Log in. You are ogged in the Avaya IC system from the Java sampe cient. About the.net sampe cient The.NET sampe cient is written in C#. The.NET sampe cient is packaged in assemby and DLL fies. This section incudes the foowing topics: User interface of the.net sampe cient on page 62 Code and resources for the.net sampe cient on page 62 Dependencies of the.net sampe cient on page 63 Deveoping a custom.net sampe cient on page 63 Running a.net sampe cient from an SDK server system on page 64 Running a.net sampe cient from a non-sdk server system on page 65 Avaya IC Cient SDK Programmer Guide May

62 Chapter 3: Sampe cients User interface of the.net sampe cient The.NET sampe cient can be positioned anywhere on the agent desktop. A components of the appication incuding the work ist opens within the appication. The foowing figure shows the.net sampe cient. Code and resources for the.net sampe cient The foowing topics describe the fies that contain the code and resources for the.net sampe cient: Com.Avaya.Ic.Sdk.Sampecient.Ui on page 62 Com.Avaya.Ic.Sdk.SampeCient.Controer on page 63 Com.Avaya.Ic.Sdk.Sampecient.Ui Description: Contains the forms and the supporting code for the forms. A images are embedded in the forms. Instaation ocation: The Com.Avaya.Ic.Sdk.Sampecient.Ui fies are instaed in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\dotnet\sampe\src\ Com.Avaya.Ic.Sdk.Sampecient\Ui 62 Avaya IC Cient SDK Programmer Guide May 2013

63 About the.net sampe cient Com.Avaya.Ic.Sdk.SampeCient.Controer Description: Contains the Controer casses. The Controer casses do the foowing: Contain a of the Cient SDK reated code. Maintain a reference to the view. Update the view when events are received from the Cient API. Instaation ocation: The Com.Avaya.Ic.Sdk.SampeCient.Controer fies are instaed in the foowing directory: IC_INSTALL_DIR\IC72\sdk\design\dotnet\sampe\src\ Com.Avaya.Ic.Sdk.Sampecient\Controer Dependencies of the.net sampe cient The.NET sampe cient depends on the foowing DLLs that are instaed with the Cient SDK design fies: Com.Avaya.Uti.d Com.Avaya.Uti.Messaging.d ICSharpCode.SharpZipLib.d og4net.d AvayaICSDKCient.d These ibraries are instaed in the foowing directory: IC_INSTALL_DIR\IC72\sdk\dotnet\sampe\bin Deveoping a custom.net sampe cient To deveop a custom.net sampe cient using Microsoft Visua Studio: 1. From the system where you configured the SDK server, copy the \\ <AVAYA_IC72_HOME>\sdk\design\dotnet directory. 2. Navigate to the \\<AVAYA_IC72_HOME>\sdk\design\dotnet\sampe\src directory. 3. Open the SampeCient.soution directory in Microsoft Visua Studio. 4. In the eft navigation pane, right-cick Reference and seect Add Reference. 5. In the Add Reference diaog box, cick Browse. Avaya IC Cient SDK Programmer Guide May

64 Chapter 3: Sampe cients 6. In the Look in fied, seect the directory where you copied the \\<AVAYA_IC72_HOME>\ sdk\design\dotnet directory. 7. Navigate to the \\<AVAYA_IC72_HOME>\sdk\design\dotnet\ib directory and seect a the.d fies and cick OK. 8. To start the sampe cient in reease mode: 1. In Microsoft Visua Studio, from the drop-down ist, seect Reease. 2. Cick Start Debugging. The system dispays the diaog box with a message indicating that the you are running the.net sampe cient in the reease mode. 3. Cick OK. 9. To start the sampe cient in the Debug mode: 1. In Microsoft Visua Studio, from the drop-down ist, seect Debug. 2. To debug a specific area of the.net sampe cient code, enter the debug point in the code and then run the sampe cient. 3. In the Login diaog box, enter the foowing: Login Password SDK server URL. For exampe, Cick Login. The system dispays the.net sampe cient interface. Running a.net sampe cient from an SDK server system 1. Navigate to the \\IC_INSTALL_DIR\IC72\sdk\design\dotnet\sampe\bin directory. 2. Doube-cick the RunCient.bet fie. 3. In the Login diaog box, enter the foowing: User Name Password Server URL. For exampe, Server Name or IP address>:9700/ icsdk. 4. Cick Login. You are ogged in the Avaya IC system through a.net sampe cient. 64 Avaya IC Cient SDK Programmer Guide May 2013

65 About the.net sampe cient Running a.net sampe cient from a non-sdk server system Important:! Important: Ensure that you have.net 3.5 or ater on the non-sdk system. 1. From the system where you configured the SDK server, copy the IC_INSTALL_DIR\ IC72\sdk\design\dotnet directory to the system where you want to run the.net sampe cient. 2. In the \dotnet directory, doube-cick the RunCient.bat fie. 3. In the Login diaog box, enter the foowing: User Name Password Server URL. For exampe, Server name or IP address>:9700/ icsdk. 4. Cick Log in. You are ogged in the Avaya IC system from the.net sampe cient. Avaya IC Cient SDK Programmer Guide May

66 Chapter 3: Sampe cients 66 Avaya IC Cient SDK Programmer Guide May 2013

67 Chapter 4: Guideines for using the Cient API Avaya recommends that you consider the foowing guideines when you deveop a custom appication or integration with the Cient API. This section incudes the foowing topics: Chat interaction guideines on page 68 Voice interaction guideines on page 69 Caback guideines on page 70 Time and date duration guideine on page 72 History API guideines on page 73 AddressBook API guideines on page 76 WrapupSeection API guideine on page 78 Event handing guideines on page 79 State guideines on page 85 Log in and og out guideines on page 86 Exception handing guideines on page 87 Operation faiure and success guideines on page 88 Nu return vaue guideines on page 89 Customization guideines on page 90 Performance considerations on page 93 Important:! Important: The code provided in this section is for exampe ony. Last minute changes to the Cient SDK may resut in differences between the sampes in this section and the actua code in the Cient SDK. Before you impement any of these guideines, review the Cient API documentation and code in the Cient SDK. Avaya IC Cient SDK Programmer Guide May

68 Chapter 4: Guideines for using the Cient API Chat interaction guideines Avaya recommends that you shoud be aware of the foowing guideines when you deveop your custom code: Methods not aowed for chat interactions on page 68 Hande TranscriptLine events for chat interactions on page 68 Do not use Datawake method on page 69 Methods not aowed for chat interactions The foowing methods are not aowed for chat interactions: coaborationcompete for conference and consut coaborationcance for conference and consut Hande TranscriptLine events for chat interactions Reason If your custom appication incudes chat, ensure your code: Monitors the appication user and customer ide time. Generates ideness and other aerts as needed by the custom appication. The Cient SDK provides an event stream that you can use to monitor ide times. However, your custom code must incude timers to monitor the events against the threshod settings to ensure that aerts are generated. Ideness aerts ensure that appication user in a chat room is aerted if the participants are waiting for a response to a message. For exampe, an appication user handes two chats with two different customers. After sending a message to the first customer, the appication user starts a chat with the second customer. If the first customer responds, the appication user needs to be aerted that a message has arrived in the first chat room. If the appication user does not respond within the specified time, your custom appication generates an aert. The aert notifies the appication user that the customer is sti waiting for a response. 68 Avaya IC Cient SDK Programmer Guide May 2013

69 Voice interaction guideines Coding information When a message is sent or received by an appication user, the Cient SDK: 1. Creates a TranscriptLine object. 2. Provides the TranscriptLine object to the consumer through a TRANSCRIPT_LINE_ADDED event on the TranscriptDocument. The TranscriptLine object represents a message sent into the chat room. TranscriptLine incudes the OriginatorHande property that provides the originator of the message. This originator can be agent, caer, system, or unknown. Use these objects and the OriginatorHande property when you code the aerts in your custom appication. You can create, start, and reset timers based on the context carried in those objects. For more information about TranscriptLine, see the Cient API documentation. Do not use Datawake method The Cient SDK does not support Datawake. Do not use the getdatawakeurl(); method in your custom appication. That method wi return a NULL. Voice interaction guideines Avaya recommends that you shoud be aware of the foowing guideines when you deveop your custom code: Using VoiceChanne.Reset on page 69 Setting the force mutipe cas option on the switch on page 70 Impact of network recovery on voice interaction on page 70 Using VoiceChanne.Reset VoiceChanne.Reset does not hang up any teephone cas. The API is supposed to terminate a the EDUs associated with the softphone and set the agent into "ready" or "notready" state depending on the API ca. Ony use VoiceChanne.Reset if the softphone state is out of sync with the hardphone operation. Do not use this API to hang up a teephone ca. Avaya IC Cient SDK Programmer Guide May

70 Chapter 4: Guideines for using the Cient API Setting the force mutipe cas option on the switch If an appication user accepts a voice ca and is made busy from the softphone, the user can sti receive a second voice ca. The switch is unaware that the user is busy and may send a second ca. This probem occurs ony when the force mutipe cas option is enabed on the hunt group where the user has ogged in. The task oad and ceiings set on Avaya IC for the voice channe are not enforced on the voice channe. Impact of network recovery on voice interaction Reason If a network recovery that requires an appication user to og in back occurs when an appication user is handing a voice interaction on the hardphone, the voice channe wi not connect to the Teephony server. The user wi not have access to any softphone contros, because the softphone is out of sync. The voice channe does not automaticay connect to the Teephony server because this connection can drop the current ca on the hardphone. User expectations Under these circumstances, the Cient SDK expects the appication user to perform the foowing steps in sequence: 1. End the ca on the hardphone. 2. Wrapup and compete the contact that corresponds to the EDU associated with the ca. The voice channe shoud automaticay og in as soon as a hardphone contacts have been wrapped and ceared from the task ist. Caback guideines Chat and Caback feature aows the customer to specify the caback number whie initiating a chat from IC website. On receiving the workitem, agent can retrieve the caback number from ChatMediaInteraction object and can pace an outbound ca to the customer. In this case, the voice ca gets associated with chat interaction and is grouped together in the same workitem. 70 Avaya IC Cient SDK Programmer Guide May 2013

71 Caback guideines This section wi detai out the impementation considerations, guideines and imitations of caback feature. Note: Note: From the feature impementation perspective the Chat and Caback, Web Schedue Caback, and Chat and VoIP are same. Impementation considerations 1. In order to associate the Chat and Voice media interactions: Report Server must be present either in the Web domain or in its faiover domain. A EDU Server must be present either in the domain of the Report server or in its faiover domain. 2. For a workitem with chat and voice media interactions grouped together, SDK treats chat as parent media interaction and voice as chid media interaction. 3. For coaborating a mutimedia interaction, agent must be searched using the agent ID or the address book and not using the station ID. Guideines for impementing chat and caback This scenario requires the foowing steps: 1. Register isteners for the WorkItemAdded and WorkItemRemoved events. 2. Register isteners for the MediaInteractionAdded and MediaInteractionRemoved events. 3. Create handers to receive above events. 4. Update the user interface to dispay workitem and media interaction separatey. 5. Update the user interface to dispay caback number after the chat media interaction is received. 6. Provide a mechanism to pace a voice caback on the Workitem object. Guideines for coaborating chat and caback As chat and voice media interactions are grouped together in a singe workitem, you need to ensure that the coaborated agent receive both the interactions as a singe workitem. Foowing are the high eve steps: 1. Register isteners for AudioSourceChanged and PartyAdded events. 2. Provide handers for these events. 3. Conference or consut voice media interaction by invoking coaborationbegin() API on a Workitem object, with VoiceMediaInteraction as a parameter. 4. On receiving AudioSourceChanged event, coaborate Chat media interaction by invoking coaborationbegin() API on a Workitem object. Avaya IC Cient SDK Programmer Guide May

72 Chapter 4: Guideines for using the Cient API 5. On receiving PartyAdded event, invoke coaborationcompete() API on a Workitem object. Guideines for competing chat and caback As mentioned earier, for a workitem with chat and voice media interactions grouped together, SDK treats chat as parent media interaction and voice as chid media interaction. Therefore invoking the compete() API on a workitem removes both chat and voice interactions. If ony voice interaction needs to be removed, invoke compete() API on the VoiceMediaInteraction object. Coect the wrapup codes when the parent media interaction is removed. Limitations Coaborating of chat and caback interaction to a queue is not supported. Doing so wi raise OperationFaied event. Time and date duration guideine The SDK server does not cacuate specific durations. The Cient SDK provide APIs that aow a custom appication to perform these cacuations if needed. If your custom appication requires the cacuation of a specific duration, use the create date vaue or the deivered date vaue to do the required cacuation. For exampe, your custom code can cacuate the age of a particuar work item in miiseconds by subtracting the current time in ms from the create date vaue. Use the foowing APIs in your cacuations: WorkItem.getDeiveredDate() WorkItem.getCreateDate() WorkItem.getQueueTime() Document.getCreateDate() 72 Avaya IC Cient SDK Programmer Guide May 2013

73 History API guideines History API guideines Avaya recommends that you shoud be aware of these guideines when you use the History API in your custom code: Retrieving the history for a WorkItem or Customer on page 73 WorkItemHistory record on page 74 CustomerHistory record on page 74 Formatting dates for the history of an object on page 75 Exampe: retrieve WorkItem history for Java appication on page 75 Exampe: retrieve Customer history for Java appication on page 76 Retrieving the history for a WorkItem or Customer When a WorkItem arrives at a custom appication, the Cient SDK does not automaticay send the WorkItemHistory or the CustomerHistory for that WorkItem. This process ensures that the Cient SDK can deiver the WorkItem to the appication user as quicky as possibe, and avoid the time-consuming ook ups required for WorkItemHistory and CustomerHistory. The Cient SDK is optimized to aow your custom appication to retrieve the WorkItemHistory or CustomerHistory. The retrieva of the most recent WorkItemHistory and CustomerHistory is asynchronous. When the history data arrives at the custom appication, the Cient SDK automaticay caches the data on the cient. For the CustomerHistory, your custom appication must specificay request every piece of information that you want to dispay to the user. When you retrieve the history, aways foow this two-step process: 1. Request the history. 2. Retrieve the history data. Avaya IC Cient SDK Programmer Guide May

74 Chapter 4: Guideines for using the Cient API WorkItemHistory record The Cient SDK obtains information for a WorkItemHistory record from the EDU for a VoiceMediaInteraction and a ChatMediaInteraction. For an EmaiDocument, the WorkItemHistory record is the same as the TrackingHistory. The Cient SDK server retrieves that information from the IC Emai server, which retrieves the information from the database. This information does not incude the time spent by an emai in queue. Each WorkItemHistory record has a type of NameVaueList. Each fied in the record has a type of NameVaue. By defaut, each WorkItemHistory record contains the foowing fieds: starttime origin description CustomerHistory record Your custom appication can potentiay retrieve more information for a CustomerHistory record. Each CustomerHistory record corresponds to a previous interaction that the customer had with the contact center. This interaction can be a singe historica MediaInteraction or a singe historica EmaiMessage exchanged between the customer and the contact center. Data provided with a CustomerHistory record: In addition to the data provided with a WorkItemHistory, the CustomerHistory can aso incude: WrapupRecords for a types of WorkItems WorkItemHistory for a types of WorkItems Transcripts for ChatMediaInteractions EmaiMessages for EmaiDocuments Fieds in a CustomerHistory record: Each CustomerHistory record has a type of NameVaueList. Each fied in the record has a type of NameVaue. By defaut, each CustomerHistory record contains the foowing fieds: type state topic time 74 Avaya IC Cient SDK Programmer Guide May 2013

75 History API guideines Rues for database queries: The CustomerHistory record fieds represent the summary information avaiabe for the CustomerHistory record. This summary information is obtained through a database query. The query criteria must obey the foowing rues: If a customerkey is present in the EDU for the MediaInteraction or Document, the query must use the customerkey to perform the customer history query. If no customerkey is present in the EDU, the query must use the foowing query criteria: - ANI for VoiceMediaInteractions - Emai Address for EmaiDocuments - Chat Hande for ChatMediaInteractions Formatting dates for the history of an object The Cient SDK does not provide a formatted string for the date. The History API returns a string that contains a miisecond vaue. For Java, the miisecond vaue is from January 1, For.NET, the miisecond vaue is from January 1, Your custom appication needs to appy a ocae specific pattern when parsing the date string. To use the date format in your custom appication: 1. Convert the miisecond vaue to a Long. 2. Add the Long to a date object. 3. Retrieve the formatted string from the date object. Exampe: retrieve WorkItem history for Java appication Note: Note: This exampe uses the API names for the Java API of the Cient SDK. A.NET appication shoud foow the same steps. For information about the corresponding API cas for.net, see the.net API documentation provided with the Cient SDK. For more information, see Dispay WorkItem History scenario on page 146. To retrieve the history for a WorkItem requires the foowing steps: 1. Ca Workitem.requestHistory to request the WorkItem history. 2. Wait unti the Workitem.RequestHistoryResponse event is received. This event indicates that the WorkItem history is received and avaiabe in the HDS. 3. Retrieve the WorkItem object from the Workitem.RequestHistoryResponse event. 4. Ca Workitem.getHistory to retrieve the history data. Avaya IC Cient SDK Programmer Guide May

76 Chapter 4: Guideines for using the Cient API Exampe: retrieve Customer history for Java appication Note: Note: This exampe uses the API names for the Java API of the Cient SDK. A.NET appication shoud foow the same steps. For information about the corresponding API cas for.net, see the.net API documentation provided with the Cient SDK. For more information, see Dispay Customer History scenario on page 148. To retrieve the history for a Customer requires the foowing steps: 1. Ca Workitem.requestCustomerHistory with the appropriate search criteria to request the customer history. 2. Wait unti the Workitem.RequestCustomerHistoryResponse event is received. This event indicates that the customer history is received and avaiabe in the HDS. 3. Retrieve the WorkItem object from the Workitem.RequestCustomerHistoryResponse event. 4. Ca Workitem.getCustomerHistory to retrieve the customer history data. AddressBook API guideines Avaya recommends that you shoud be aware of the foowing guideines when you deveop your custom code: Retrieving the AddressBook object on page 76 Impementing Address Book searches on page 77 Exampe: Finding a subset of agents based on criteria on page 77 Exampe: Finding a subset of queues based on criteria on page 78 Retrieving the AddressBook object When an appication user initiates an Avaya IC session, the system does not send AddressBook data to the appication by defaut. However, you can use AddressBook APIs in the Cient API to retrieve agents and queues on the AddressBook object. Use the Session.getAddressBook() API to retrieve the AddressBook object. The AddressBook object contains a of the addressabe agents and queues in the Avaya IC system. 76 Avaya IC Cient SDK Programmer Guide May 2013

77 AddressBook API guideines Impementing Address Book searches You can impement your custom appication to do either of the foowing AddressBook searches: Perform a defaut search for AddressBook data with the findagents or findqueues methods. Coect query information from the appication users and use that information in your AddressBook search. These searches return either a FindAgentsResponse or FindQueuesResponse event that contains the reevant records. Tip: Tip: You can use search criteria to specify and retrieve a subset of agents or queues for the Address Book, instead of a agents or queues in the Avaya IC system. For information about the search criteria, see the Cient API documentation. Exampe: Finding a subset of agents based on criteria Note: Note: This exampe uses the API names for the Java API of the Cient SDK. A.NET appication shoud foow the same steps. For information about the corresponding API cas for.net, see the.net API documentation provided with the Cient SDK. For an exampe scenario with more detaied information, see AddressBook scenario on page 150. To retrieve a subset of agents based on criteria requires the foowing steps: 1. Ca Session.getAddressBook to retrieve the AddressBook object. 2. Ca AddressBook.findAgents with the appropriate criteria to request the subset of agents. 3. Wait unti the AddressBook.FindAgentsResponse is received. This event indicates that the agent subset is received and avaiabe in the HDS. 4. Ca AddressBook.FindAgentsResponse.getAgentRecords to retrieve the subset of agents. Avaya IC Cient SDK Programmer Guide May

78 Chapter 4: Guideines for using the Cient API Exampe: Finding a subset of queues based on criteria Note: Note: This exampe uses the API names for the Java API of the Cient SDK. A.NET appication shoud foow the same steps. For information about the corresponding API cas for.net, see the.net API documentation provided with the Cient SDK. For an exampe scenario with more detaied information, see AddressBook scenario on page 150. To retrieve a subset of queues based on criteria requires the foowing steps: 1. Ca Session.getAddressBook to retrieve the AddressBook object. 2. Ca AddressBook.findQueues with the appropriate criteria to request the subset of queues. 3. Wait unti the AddressBook.FindQueuesResponse is received. This event indicates that the queue subset is received and avaiabe in the HDS. 4. Ca AddressBook.FindQueuesResponse.getQueueRecords to retrieve the subset of queues. WrapupSeection API guideine The WrapupSeectionList represents a ist of WrapupSeections that has been set on a WorkItem. If you use the WrapupSeection API do not expect the WrapupSeectionList method addwrapupseection to add the wrapup seection to the ist. addwriapup Seection adds the WrapupSeection to a cache. 78 Avaya IC Cient SDK Programmer Guide May 2013

79 Event handing guideines Recommended sampe code pubic void foo{... WrapupSeectionList ist = wi.getwrapupseectionlist(); ist.addwrapupseection(new WrapupSeectionImp(categoryCode, reasoncode, outcomecode); wi.setwrapupseectionlist(ist); //add the cached wrapupseection to the ist. This ca sends an event to the server. You now need to wait for OperationSucceeded event before caing getwrapupseections to see if the wrapup seection was added. } pubic static void WorkItemOperationSucceededListener impements SessionListener{ pubic void onevent(event evt){ WorkItem.OperationSucceeded success = (WorkItem.OperationSucceeded) evt; if(success.getoperationname() == WorkItem.Operation.SETWRAPUPSELECTIONLIST.toString()){ wi.getwrapupseectionlist().getwrapupseections(); //this wi contain the newy added wrapup seection. } } } Sampe of code to avoid Important:! Important: Do not foow the practice shown in the beow sampe code when you create isteners. pubic void foo(){... WrapupSeectionList ist = wi.getwrapupseectionlist(); ist.addwrapupseection(new WrapupSeectionImp(categoryCode, reasoncode, outcomecode); ist.getwrapupseections(); //returned coection wi not have... } Event handing guideines Avaya recommends that you consider the foowing guideines when you deveop event handing in your custom code: Register isteners for events before caing Session.Initiaize on page 80 Create a separate istener for each event on page 80 Avoid bocking operations in event handing on page 83 Hande ConnectionStatusChange and SessionShutdown events on page 83 Avaya IC Cient SDK Programmer Guide May

80 Chapter 4: Guideines for using the Cient API Register isteners for events before caing Session.Initiaize Reason Register a or most of your isteners between the ca to Appication.Login and Session.Initiaize. If you do not register isteners before Session.Initiaize, timing reasons can cause events to arrive before the isteners are registered. An event that arrives before registration of the appropriate istener might be ost. Recommended sampe code.net sampe code... ISession _session = _app.login(user, password); _session.sessionstatechanged += new SessionStateChangedHander(HandeSessionStateChanged);.... _session.initiaize(); Java sampe code Session _session = appication.ogin(user, pass); _session.registerlistener(session.statechanged.type, new SessionStateChangedListener()); _session.initiaize(); Create a separate istener for each event Do not use the same istener to hande more than one event. Note: Note:.NET enforces this behavior automaticay. Reason The Cient API does not prevent you from using the same istener to hande more than one event. However, if you use the same istener for mutipe events, your code must repeatedy instruct the Cient API to perform the interna check for which istener to ca. This practice resuts in inefficient, spaghetti hander code. 80 Avaya IC Cient SDK Programmer Guide May 2013

81 Event handing guideines Recommended sampe code Java sampe code //Registration code _session.registerlistener(session.statechanged.type, new SessionStateChangedListener()); _session.registerlistener(worklist.workitemadded.type, new WorkItemAddedListener()); _session.registerlistener(channe.statechanged.type, new ChanneStateChangedListener()); //Hander code private static cass SessionStateChangedListener impements SessionListener{ pubic void onevent(event evt){ //hande the event here } } private static cass WorkItemAddedListener impements SessionListener{ pubic void onevent(event evt){ //hande the event here } } private static cass ChanneStateChangedListener impements SessionListener{ pubic void onevent(event evt){ //hande the event here } } Avaya IC Cient SDK Programmer Guide May

82 Chapter 4: Guideines for using the Cient API.NET sampe code _session.sessionstatechanged += new SessionStateChangedHander(HandeSessionStateChanged); _session.worklistworkitemadded += new WorkListWorkItemAddedHander(HandeWorkItemAdded); _session.channestatechanged += new ChanneStateChangedHander(HandeChanneStateChange); //Hander code private void HandeSessionStateChanged(SessionStateChangedEventArgs earg) { } private void HandeWorkItemAdded(WorkListWorkItemAddedEventArgs earg) { } private void HandeChanneStateChange(ChanneStateChangedEventArgs earg) { } Sampe of code to avoid Important:! Important: Do not foow the practice shown in the beow sampe code when you create isteners. //Registration code _istener = new AEventListener(); _session.registerlistener(session.statechanged.type, _istener); _session.registerlistener(worklist.workitemadded.type, _istener); _session.registerlistener(channe.statechanged.type, _istener); //Hander code private static cass AEventListener impements EventListener{ pubic void onevent(event evt){ if(evt instanceof SessionStateChanged){ handesessionstatechanged(); } ese if(evt instanceof WorkListWorkItemAdded){ handeworkitemadded(); } ese if(evt instanceof ChanneStateChanged){ handechannestatechanged(); } } } 82 Avaya IC Cient SDK Programmer Guide May 2013

83 Event handing guideines Avoid bocking operations in event handing Reason Do not use bocking operations or operations that require a significant amount of processing in the event handers. Exampes of such operations are: Painting appication windows Impementing I/O Paying media Writing a oop that oops for a ong time A events from the Cient API arrive on a singe thread that processes a inbound messages from the server. For server-side integration, a bocking operation or an operation that requires a significant amount of processing can cause message queues to back up and impact performance. Hande ConnectionStatusChange and SessionShutdown events Reason Do not use Cient API objects in your code after a ConnectionStatusChange event is received and the ConnectionStatus is equa to FAILED. Aways use a ogout operation after that event. After a custom appication receives a SessionShutdown event or the ConnectionStatus of the Session changes to Faied, the Session object and a other objects that beong to that session become unusabe. A ogout is the ony vaid operation after these events. A custom code that uses the Cient API must register for these events and gracefuy og out of the session after the events occur. If your custom code uses Cient API objects after a Connection faiure event or a SessionShutdown event, the Communication component wi usuay throw an error. The Cient SDK throws a CommunicationException when the connection is impaired or disabed. For more information about this custom exception, see the API documentation. These errors are runtime exceptions in Java. The Cient API does not expect appication users to hande these exceptions. Therefore, your custom code must hande these events propery to provide an acceptabe appication user experience. Avaya IC Cient SDK Programmer Guide May

84 Chapter 4: Guideines for using the Cient API Recommended sampe code Java sampe code //Registration code _session.registerlistener(session.shutdown.type, new SessionShutdownListener()); _session.registerlistener(session.connectionstatuschange.type, new ConnectionStatusChangeListener()); //Hander code private static cass SessionShutdownListener impements SessionListener{ pubic void onevent(event evt){ //Check the reason for shutdown and dispay message to user (or) do additiona handing } } //at the end just ogout the user _appication.ogout(_session.getuser().getloginid()); private static cass ConnectionStatusChangeListener impements SessionListener{ pubic void onevent(event evt){ Session.ConnectionStatusChange csc = (Session.ConnectionStatusChange) evt; if(csc.getconnectionstatus() == ConnectionStatus.FAILED){ _appication.ogout(_session.getuser().getloginid()); } } } 84 Avaya IC Cient SDK Programmer Guide May 2013

85 State guideines.net sampe code _session.sessionshutdown += new SessionShutDownHander(HandeSessionShutDown); _session.sessionconnectionstatuschanged += new SessionConnectionStatusChangedHander(HandeSessionConnectionStatusChanged); //Hander code private void HandeSessionShutDown(SessionShutDownEventArgs earg) { //Check the reason for shutdown and dispay message to user (or) do additiona handing //at the end just ogout the user _appication.ogout(_session.user.loginid); } private void HandeSessionConnectionStatusChanged(SessionConnectionStatusChangedEventArgs earg) { } if (earg.connectionstatus == SessionConnectionStatus.FAILED){ _appication.ogout(_session.getuser().getloginid()); } State guideines Avaya recommends that you consider the foowing guideines with respect to object states in your custom code: Check object for the appropriate state on page 85 Check status of WorkItem on page 86 Check object for the appropriate state For a objects with defined state modes, your custom code must: 1. Check for the appropriate state. 2. If the object is in the required state, make a Cient API ca on that object. Avaya IC Cient SDK Programmer Guide May

86 Chapter 4: Guideines for using the Cient API Reason The Cient SDK performs state vaidations on the SDK server. If the custom code does not check for the state of the object before making a Cient API ca, your custom appication wi have to perform unnecessary round trip checks to the server. Objects with state modes The foowing tabe shows those objects that have a state mode. Object State mode Session Session state mode diagram on page 31 WorkItem WorkItem state mode diagram on page 39 Voice MediaInteraction VoiceMediaInteraction state mode diagram on page 43 ChatMediaInteraction ChatMediaInteraction state mode diagram on page 46 Check status of WorkItem Reason For a operations on a WorkItem and the media interaction or document contained in that WorkItem, your custom code must check whether the WorkItem is Current before making most ife cyce cas. For more information, see WorkItem state mode diagram on page 39. Some ifecyce operations on WorkItem are vaid ony if the WorkItem is the Current WorkItem. Your custom code must therefore: 1. Check if a WorkItem is Current. 2. If the WorkItem is Current, perform a ifecyce operation. Log in and og out guideines Avaya recommends that you consider the foowing guideines with respect to ogging in and ogging out of the appication in your custom code: Simutaneous og in and og out for Chat and Emai on page 87 Check WorkItem status during ogout on page Avaya IC Cient SDK Programmer Guide May 2013

87 Exception handing guideines Simutaneous og in and og out for Chat and Emai Reason An appication user must og in or out of the Chat and Emai channe simutaneousy. A user cannot perform a singe channe og in to or og out of the Chat channe or the Emai channe. In Avaya IC, the chat and emai channes are not excusive. Logging in or out of one of those channes wi aways og the user in or out of the other channe. Check WorkItem status during ogout Reason When an appication user ogs out of your custom appication, your custom code must check the state of a WorkItems in the WorkItemList. If the ist incudes an active or Current WorkItem, your custom code must prevent the user from ogging out. Neither the Avaya IC system nor the Cient SDK prevent an appication user from ogging out if the user has active work items. Exception handing guideines Avaya recommends that you avoid the foowing exception in your custom code: NuPointerException and ArgumentNuException on page 87 Avaya recommends that you hande the foowing exceptions in your custom code: ConnectionException on page 88 AuthenticationException on page 88 NuPointerException and ArgumentNuException Your custom code must avoid NuPointerException and ArgumentNuException. These exceptions occur if both of the foowing are true: Nu parameters are passed to the Cient API. Methods used in the custom code did not expect nu parameters. Avaya IC Cient SDK Programmer Guide May

88 Chapter 4: Guideines for using the Cient API ConnectionException Reason Your custom code must hande ConnectionException, according to the requirements of the programming anguage: In Java, ConnectionException is a checked exception. In C#, your custom code must hande the exception. C# does not enforce this exception. This exception occurs during the foowing events: Log in Log out Add or get an emai attachment AuthenticationException Reason Your custom code must hande AuthenticationException, according to the requirements of the programming anguage: In Java, AuthenticationException is a checked exception. In C#, your code must hande the exception. C# does not enforce this exception. This exception occurs if an appication user provides: An invaid username or password An expired password Operation faiure and success guideines Severa objects in the Cient API have OperationFaied or OperationSucceeded events. Avaya recommends that you consider the foowing guideines when you hande these events in your custom code: OperationFaied on page 89 OperationSuccess on page Avaya IC Cient SDK Programmer Guide May 2013

89 Nu return vaue guideines OperationFaied Reason Your custom code must hande an OperationFaied event where avaiabe. An operation faiure event can indicate a probem with Avaya IC. This event can occur for operations that are asynchronous in Avaya IC. An OperationFaied event can occur when certain cas fai at Avaya IC servers. For exampe, a CoaborationBegin ca can raise an OperationFaied event if the wrong destination is provided. An OperationFaied event aso occurs if an appication user tries to execute an invaid operation. OperationSuccess Reason An OperationSuccess event occurs rarey. However, your custom code must hande an OperationSuccess event where avaiabe. An OperationSuccess event occurs in rare cases in which the appication user needs feedback on the success of an operation. For exampe, an EmaiDraft.Send event wi raise an OperationSuccess event to acknowedge that an outbound emai was sent. Nu return vaue guideines The Cient API has many scenarios where a method ca can return a nu vaue. Your custom code must expect nu return vaues. Avaya recommends that you code carefuy to avoid unexpected NuPointerExceptions. For exampe, NuPointerExceptions can be raised: Because an Emai Cc is not a mandatory method, getcc() might return a nu vaue. If an appication user is not enabed for a channes, the Session method getchanne() might return a nu vaue. Avaya IC Cient SDK Programmer Guide May

90 Chapter 4: Guideines for using the Cient API Customization guideines You can configure the Cient SDK to customize access to the foowing items: Avaya IC agent properties EDU and ADU attributes Wrapup codes This section incudes the foowing topics: Customization directory on page 90 Customization fies on page 90 Depoying a configuration fie on page 92 Customization directory Avaya IC instas the Cient SDK customizing fies in the foowing directory on a computer that hosts the Cient SDK server: IC_INSTALL_DIR\IC72\sdk\server\icsdk\custom\config\sdk\ Customization fies! Important: Important: If your custom appication does not require customizing, do not modify the entries in these fies. Fiter and send data to a custom appication ony if the data is absoutey necessary. For exampe, do not send a Avaya IC property sections or cache and fiter a EDU data. If you send more than required data to the custom appication, server performance might be severey impacted. This section incudes the foowing topics that describe the customizing fies provided with the Cient SDK: SDKEduAttributesToFiter.properties on page 91 SDKWorkItemAttributesFiter.properties on page 91 SDKSessionAttributesFiter.properties on page 91 SDKWrapupCodesCategoryGroups.properties on page 92 SDKSupportedCharsets.properties on page 92 SDKICPropertiesSections.properties on page Avaya IC Cient SDK Programmer Guide May 2013

91 Customization guideines SDKEduAttributesToFiter.properties Description: Determines which EDU fieds are sent as MediaInteraction and Document attributes. Methods: Use the foowing methods to access the EDU fieds: MediaInteraction.getAttributes() Document.getAttributes() Note: Note: The EDU fieds must be avaiabe at the SDK server bridge before they can be fitered. Define the EDU fieds to be made avaiabe at the SDK server bridge in the EDUFiedsToCache.properties fie. This properties fie is in the configuration directory. SDKWorkItemAttributesFiter.properties Description: Determines which EDU fieds are sent as WorkItem attributes. Methods: Use the WorkItem.getAttributes() method to access the EDU fieds. Note: Note: The EDU fieds must be avaiabe at the SDK server bridge before they can be fitered. Define the EDU fieds to be made avaiabe at the SDK server bridge in the EDUFiedsToCache.properties fie. This properties fie is in the configuration directory. SDKSessionAttributesFiter.properties Description: Determines which ADU fieds are sent as Session attributes. Methods: Use the Session.getAttributes() method to access the EDU fieds. Note: Note: The ADU fieds must be avaiabe at the SDK server bridge before they can be fitered. Define the ADU fieds to be made avaiabe at the SDK server bridge in the ADUFiedsToCache.properties fie. This properties fie is in the configuration directory. Avaya IC Cient SDK Programmer Guide May

92 Chapter 4: Guideines for using the Cient API SDKWrapupCodesCategoryGroups.properties Description: Determines which wrapup codes are sent to the custom appication. Methods: Use the Session.getWrapupCodes() method to access the wrapup codes. SDKSupportedCharsets.properties Description: Determines which character sets are: Supported by Avaya IC Exposed to the custom appication Used when emais are sent Methods: Use the Session.getSupportedCharsets() method to access the character sets. SDKICPropertiesSections.properties Description: Determines which Avaya IC agent property sections are avaiabe to the custom appication. Methods: Use the Session.getICProperties() method to access the properties. Tip: Tip: For information about the IC_INSTALL_DIR\IC72\sdk\server\icsdk\ custom\config\icpropertiessections.properties fie that you can use to customize the UOM, see Avaya Agent Web Cient Customization. Depoying a configuration fie After you update a configuration, pace a copy of the fie in the foowing directory on the machine that hosts the Cient SDK server: /WEB-INF/casses/com/avaya/ic/sdk/customization 92 Avaya IC Cient SDK Programmer Guide May 2013

93 Performance considerations Performance considerations You can configure and tune the Cient SDK to improve the performance of a custom appication. This section incudes the foowing topics: Using WebAppContext on page 93 Configuring the messaging service on page 95 Using WebAppContext This configuration uses WebAppContext and SDKAppContext. Avaya recommends that you create and configure a singe instance of the WebAppContext for each Cient SDK process or custom appication. This section incudes the foowing topics: Creating and configuring WebAppContext on page 93 Using the setter methods of WebAppContext on page 94 Creating and configuring WebAppContext You can use the foowing methods to create and configure an instance of WebAppContext: WebAppContext(URI appuri): Aows an appication to connect to the server directy with specified URI. This mechanism requires the foowing: The URI must contain the Web appication context root. The server address and port specified in the URI must be directy accessibe from the cient machine. A of the ports specified in the server appication depoyment descriptor (web.xm) with the messaging.istener.port.range parameter must be directy addressabe. WebAppContext(URI appuri, URI proxyuri): Aows an appication to connect to the server indirecty through a proxy server. This mechanism requires the foowing: The URI must be provided as a second parameter to the proxy server. Ony the address and port of the proxy server can be directy addressabe from the cient machine. The proxy server must meet a requirements isted for WebAppContext(URI appuri). Avaya IC Cient SDK Programmer Guide May

94 Chapter 4: Guideines for using the Cient API WebAppContext(URI appuri, booean usesystemproxy): Aows an appication to connect to the server indirecty through a proxy server. This mechanism uses the system properties to specify the proxy server. For.NET, this mechanism uses the proxy specified in the Internet Exporer configuration. Using the setter methods of WebAppContext The foowing setter methods of the WebAppContext cass provide additiona tuning: setmessagingoutboundpoosize(int messagingoutboundpoosize): Specifies the number of threads in the thread poo that process outbound messages by forwarding them to the TCP transport ayer. These threads perform network-reated activities for the outbound traffic. The defaut vaue is 1. setmessaginginboundpoosize(int messaginginboundpoosize): Specifies the number of threads in the thread poo that process inbound messages by notifying a message isteners. The defaut vaue is 1. Avaya recommends that you graduay increase a number of threads in this thread poo as the number of concurrent agent sessions grows. Use this method for server-side integration ony. setmessagingseectorpoosize(int messagingseectorpoosize): Specifies the number of threads that service transport activity for asynchronous socket communications. For vaues of 1 or greater, a poo of specified number of threads are created and each agent session uses individua asynchronous dupex connections to the server. If the agent session communicates through a proxy, two separate asynchronous connections are estabished per agent. The defaut vaue is 1. You can aso set a vaue of 0. If you use a vaue of 0, no thread poo is used for the transport. Each agent session creates its own istener thread to service inbound traffic. Two separate synchronous connections are estabished to the server per agent. setmessagingscheduerpoosize(int messagingscheduerpoosize): Specifies the number of threads in the thread poo, in addition to the timer thread, that assists with schedued tasks. The primary task is network status monitoring. Important:! Important: Do not use setmessagingscheduerpoosize(int messagingscheduerpoosize) for.net. Avaya recommends that you eave the vaue at 0. With that vaue, no thread poo is created in addition to the timer main thread. 94 Avaya IC Cient SDK Programmer Guide May 2013

95 Performance considerations Configuring the messaging service You can configure the Cient SDK messaging server. Some parameters in this section are aready incuded in the appication depoyment descriptor (web.xm). You can specify the additiona parameters in that fie if needed. This section incudes the foowing properties: Service/transport properties on page 95 Workoad capacity properties on page 96 Functiona properties on page 97 Service/transport properties avaya.ic.webcient.ur: Binds the messaging service to the correct IP address on the server machine. If you specify the IP address incorrecty, the server raises a binding exception during startup. messaging.istener.port.range: Specifies the server ports that you want the Messaging Service to bind. This property works in conjunction with avaya.ic.webcient.ur. The server requires the address and the port to perform binding. If the specified port is aready occupied by another process, the binding agorithm wi repeat an attempt with the next vaue specified with the range. The binding agorithm wi aso repeat attempts if the Messaging Service has mutipe isteners to start. The agorithm fais ony if no ports are avaiabe in the specified range. The defaut vaue is This vaue provides a range of 1000 subsequent ports. Other exampes of acceptabe port ranges are: 8001: a singe port 8001,8010,9001,9010: a comma separated ist of ports for a tota of 4 ports , : a comma separated ist of subranges of ports for a tota of 20 ports Important:! Important: Your server must have the specified ports avaiabe and open for externa access by the end-cients or proxy server. Avaya IC Cient SDK Programmer Guide May

96 Chapter 4: Guideines for using the Cient API messaging.istener.config: Specifies the number of isteners to start so that inbound and outbound activities can be serviced. You can set this property to ony 1 or 2. The defaut vaue is 2. This vaue means that two isteners wi be started. One istener wi service cient connections for inbound work. The second istener wi service cient connections for outbound work. A connections are estabished and maintained by the cient. If you set the vaue to 1, the Messaging Service starts the inbound istener ony. That istener must accept a cient connections. If the custom appication opens ony one connection per agent session for inbound and outbound work, the inbound istener wi accept a connections. messaging.istener.backog: Specifies the maximum queue ength for incoming connection indications. Each indication is a request to connect. If a connection indication arrives when the queue is fu, the server refuses the connection. The backog vaue must be a positive vaue greater than 0. If the vaue passed is equa or ess than 0, then the Java patform defaut vaue wi be assumed. The defaut vaue is -1. The Java defaut on Windows is 50 for the socket backog. To be abe to hande a high number of concurrent requests to connect, set the vaue of the socket backog at a much higher vaue than the defaut or even higher is a recommended vaue for the Messaging Service isteners. messaging.socket.timeout: Specifies a time-out for socket operations. The defaut is vaue is -1. This vaue means that the socket operations wi never expire, providing a time-out of infinity. This property appies ony to synchronous socket operations. messaging.inbound.capacity: Specifies the number of threads that wi service transport activity for cient connections for inbound work. This property is simiar to the messagingseectorpoosize property of the SDK cient. The defaut vaue is 1. Note: Note: This property does not create a thread poo. The Cient SDK uses a simpe round-robin agorithm to assign work to the threads. messaging.outbound.capacity: This property is usefu if the SDK cients work through a proxy server and need to estabish separate connections for outbound and inbound work. The defaut vaue is 1. This property is not usefu if you configure ony an inbound istener configured. This property aso does not have any vaue if a cients estabish ony one asynchronous dupex connection per agent session. Workoad capacity properties messaging.inbound.thread.poo.size: Specifies the number of threads in the thread poo that wi process inbound messages by notifying a message isteners. This property is the same as the messaginginboundpoosize property of the SDK cient. 96 Avaya IC Cient SDK Programmer Guide May 2013

97 Performance considerations messaging.outbound.thread.poo.size: Specifies the number of threads in the thread poo that wi process outbound messages by forwarding them to the TCP transport ayer. These threads wi perform network reated activities for outbound traffic. This property is the same as the messagingoutboundpoosize property of the SDK cient. Functiona properties messaging.session.timeout: Specifies the duration of time after which session connectivity wi be considered ost. For exampe, this time period can be invoked after the Cient SDK detect a oss of cient-server connectivity. After this time period expires, the system wi send a shutdown signa. This signa is symmetric for both cient and server. The defaut vaue is 600 seconds, or 10 minutes. messaging.session.heartbeat: Specifies the ping interva for monitoring cient-server connectivity. The defaut vaue is 60 seconds. Avaya IC Cient SDK Programmer Guide May

98 Chapter 4: Guideines for using the Cient API 98 Avaya IC Cient SDK Programmer Guide May 2013

99 Chapter 5: Compiing and debugging a custom appication This section incudes the foowing topics. Supported compiers on page 99 Logging on page 99 Error messages on page 114 Cient SDK diagnostic information on page 114 Debugging common probems on page 117 Getting support on page 121 Supported compiers The foowing tabe shows the compiers that the Cient SDK supports for each cient patform. Cient patform Supported compier.net.net 2.0 Java Java 1.6.0_10 Logging The Cient SDK ogging generates severa ogs. Wherever possibe, these ogs: Show the execution path in the Cient SDK. Distinguish whether a probem occurred in a component of the Cient SDK or in the code of a custom appication. Avaya IC Cient SDK Programmer Guide May

100 Chapter 5: Compiing and debugging a custom appication This section incudes the foowing topics: Logging at the modue boundaries on page 100 Cient SDK server ogging on page 101 Cient SDK cient ogging on page 104 Logging guideines on page 105 Tracing issues through Cient SDK ogs on page 106 Sampe og messages on page 107 Logging at the modue boundaries The foowing diagram shows the modue boundaries where the Cient SDK performs ogging. For more information about how to trace issues across the modue boundaries, see Tracing issues through Cient SDK ogs on page Avaya IC Cient SDK Programmer Guide May 2013