IVR SDK 8.5 XML. Developer s Guide

Transcription

1 SDK 8.5 XML Developer s Guide

2 The information contained herein is proprietary and confidential and cannot be disclosed or duplicated without the prior written consent of Genesys Telecommunications Laboratories, Inc. Copyright Genesys Telecommunications Laboratories, Inc. All rights reserved. About Genesys Genesys is the world's leading provider of customer service and contact center software with more than 4,000 customers in 80 countries. Drawing on its more than 20 years of customer service innovation and experience, Genesys is uniquely positioned to help companies bring their people, insights and customer channels together to effectively drive today s customer conversation. Genesys software directs more than 100 million interactions every day, maximizing the value of customer engagement and differentiating the experience by driving personalization and multichannel customer service and extending customer service across the enterprise to optimize processes and the performance of customer-facing employees. Go to for more information. Each product has its own documentation for online viewing at the Genesys Documentation website or on the Documentation Library DVD, which is available from Genesys upon request. For more information, contact your sales representative. Notice Although reasonable effort is made to ensure that the information in this document is complete and accurate at the time of release, Genesys Telecommunications Laboratories, Inc., cannot assume responsibility for any existing errors. Changes and/or corrections to the information contained in this document may be incorporated in future versions. Your Responsibility for Your System s Security You are responsible for the security of your system. Product administration to prevent unauthorized use is your responsibility. Your system administrator should read all documents provided with this product to fully understand the features available that reduce your risk of incurring charges for unlicensed use of Genesys products. Trademarks Genesys and the Genesys logo are registered trademarks of Genesys Telecommunications Laboratories, Inc. All other company names and logos may be trademarks or registered trademarks of their respective holders. The Crystal monospace font is used by permission of Software Renovation Corporation, Technical Support from VARs If you have purchased support from a value-added reseller (VAR), please contact the VAR for technical support. Customer Care from Genesys If you have purchased support directly from Genesys, please contact Genesys Customer Care. Before contacting Customer Care, please refer to the Genesys Care Program Guide for complete contact information and procedures. Ordering and Licensing Information Complete information on ordering and licensing Genesys products can be found in the Genesys Licensing Guide. Released by Genesys Telecommunications Laboratories, Inc. Document Version: 85sdk_dev_ivr-xml_ _v

3 Table of Contents Preface About SDK XML New In Release Intended Audience Usage Guidelines Making Comments on This Document Contacting Genesys Customer Care Document Change History Part 1 Use of XML and Modes of Operation Chapter 1 How s Use XML How Uses XML XML Concepts Architecture Stack Layers The GDI Specification The GLI Specification XML Message Guidelines Attached Data Sockets, Ports, Channels, and DNs Chapter 2 Modes of Operation for Server High-Availability Modes Server Operational Modes Implications of the Different Modes Determination of Mode Individual Message Support and Behavior Supported Messages Mode Behavioral Differences Developer s Guide 3

4 Table of Contents Part 2 Server In-Front and Behind Mode Chapter 3 In-Front and Behind State Machine Diagrams Overview Call Routing States Transfer States Conference States Call Treatment States Make Call States Additional Event Messages Anytime Messages After CallStatus (Ringing) Messages Error Messages Configuring Stat Server Statistics Chapter 4 In-Front and Behind Call Flow Diagrams Overview Call Routing Call Flow Call Treatment Call Treatment Failed Call Treatment Interrupted MakeCall Call Flow MakeCall (Busy) Conference Call Flow Diagrams One-Step Conference One-Step Conference, Scenario Conference Consult Call Conference Consult Call, Scenario Conference Consult Call (Busy) Conference Consult Call (Failed) Transfer Call Flow Diagrams Transfer to Remote Site Single-Step Transfer Transfer Consult Call Transfer Consult Call (Busy) Transfer Consult Call (Failed) Chapter 5 XML Protocol Messages and Parameters Overview Important Message Constraints General Messages SDK 8.5 XML

5 Table of Contents LoginReq LoginResp LogMsg Reset MonitorInfo Server Subtype Port Subtype Agent Subtype AgentQuery AgentLogin AgentLogout AgentReady AgentNotReady FlowControl New Call and Call Routing Messages NewCall RouteRequest RouteResponse EndCall Call Treatment Messages TreatCall TreatStatus Cancel CancelCompleted External Routing Messages AccessNumGet AccessNumCancel AccessNumResp Transfer/Conferencing Messages OneStepXfer OneStepConf InitXfer InitConf CompleteXfer CompleteConf RetrieveCall CallStatus CallError Call Information Messages CallInfoReq CallInfoResp Statistics Messages PeekStatReq GetStatReq Developer s Guide 5

6 Table of Contents StatResp User Data Messages UDataGet UDataGetAll UDataSet UDataDel UDataResp Outbound Messages DialOutRegistry DialOutRegistryResp DialOut DialOutError DialOutInit Message Parameters UDataEx ExtnsEx Chapter 6 Using the XML Protocol: Examples GLI Header Call-Scenario Examples Interaction Format Further Information A Typical Call Flow NewCall CallStatus (Ringing) and CallStatus (Established) Messages CallInfoReq and CallInfoResp Messages InitXfer CallStatus (Held), CallStatus (Dialing), and CallStatus (Established)102 CompleteXfer CallStatus (XferComplete) EndCall Routing RouteRequest RouteResponse Connected Call Treatment Operation TreatCall TreatStatus (Started) and TreatStatus (Completed) MakeCall Operation MakeCall CallStatus (Dialing) CallStatus (Established) One-Step Conference Operation SDK 8.5 XML

7 Table of Contents OneStepConf CallStatus (ConfPartyAdd) Conference Consult Operation InitConf CallStatus (Held) CallStatus (Dialing) CallStatus (Established) CompleteConf CallStatus (Retrieved) CallStatus (ConfPartyAdd) Transfer to Remote Site Operation AccessNumGet AccessNumResp One-Step Transfer Operation OneStepXfer CallStatus (XferComplete) Transfer Consult Operation RouteRequest RouteResponse InitXfer CallStatus (Held) CallStatus (Dialing) CallStatus (Established) CompleteXfer CallStatus (XferComplete) Agent Login Interface Server Side Model Client Side Model Login Port Status Agent State Query Agent Control Error Case Outbound Dialing Registration Request Timeout Dialer Error Connection Failure Successful Call Flow Developer s Guide 7

8 Table of Contents Part 3 Server Network Mode Chapter 7 Network State Machine Diagrams Call Control Call Information Logging Statistics User Data Control Error Responses Chapter 8 Network Call Flow Diagrams Overview Simple Routing (Network Control) Simple Routing (Genesys Control) Failed Routing Routing Timeout Simple Treatment Failed Treatment Treatment Interrupted by a Routing Request Treatment Interrupted by Another Treatment Unsolicited Connect Chapter 9 XML Protocol Messages and Parameters Overview New Call and Call-Routing Messages NewCall RouteRequest RouteResponse Connected EndCall Failure Call Treatment Messages TreatCall TreatStatus Cancel CancelCompleted Call Information Messages CallInfoReq CallInfoResp Statistics Messages GetStatReq SDK 8.5 XML

9 Table of Contents PeekStatReq StatResp User Data Messages UDataGet UDataGetAll UDataResp UDataSet Transfer/Conferencing Messages CallError General Messages LogMsg Appendix The Server DTD Supplements Related Documentation Resources Document Conventions Index Developer s Guide 9

10 Table of Contents 10 SDK 8.5 XML

11 Preface Welcome to the SDK 8.5 XML Developer s Guide. This guide introduces you to the concepts, terminology, and procedures relevant to the Genesys SDK XML, the tool for building drivers that allow your (Interactive Voice Response Unit) to communicate with the Genesys Server. This document is valid only for the 8.5 release(s) of this product. Note: For versions of this document created for other releases of this product, visit the Genesys Documentation website, or request the Documentation Library DVD, which you can order by from Genesys Order Management at orderman@genesys.com. This preface contains the following sections: About SDK XML, page 11 New In Release 8.5, page 12 Intended Audience, page 12 Usage Guidelines, page 12 Making Comments on This Document, page 14 Contacting Genesys Customer Care, page 14 Document Change History, page 14 For information about related resources and about the conventions that are used in this document, see the supplementary material starting on page 181. About SDK XML In brief, this guide includes the following information: An overview of how Server implements the Extensible Markup Language (XML) and of architecture as it pertains to an XML-based client application. Sample call flows indicating request-response interactions for a variety of transaction types. Developer s Guide 11

12 Preface New In Release 8.5 Diagrams displaying client states and the transitions from each state to all other possible states. Detailed explanations of all Genesys -specific XML messages and parameters. A step-by-step analysis of several common interaction types showing call flows and sample XML messages used to communicate between your driver application and the Genesys Server. The complete text of the IServer.dtd file. New In Release 8.5 The following changes have been implemented in release 8.5: Support for new operating systems. Refer to the Genesys Supported Operating Environment Reference Guide for details. Intended Audience This guide, primarily intended for contact center administrators, contact center managers, operations personnel, and developers, assumes that you have a basic understanding of: Computer-telephony integration (CTI) concepts, processes, terminology, and applications. Network design and operation. Your own network configurations. You should also be familiar with the Extensible Markup Language (XML). Usage Guidelines The Genesys developer materials outlined in this document are intended to be used for the following purposes: Creation of contact-center agent desktop applications associated with Genesys software implementations. Server-side integration between Genesys software and third-party software. Creation of a specialized client application specific to customer needs. The Genesys software functions available for development are clearly documented. No undocumented functionality is to be utilized without Genesys s express written consent. 12 SDK 8.5 XML

13 Preface Usage Guidelines The following Use Conditions apply in all cases for developers employing the Genesys developer materials outlined in this document: 1. Possession of interface documentation does not imply a right to use by a third party. Genesys conditions for use, as outlined below or in the Genesys Developer Program Guide, must be met. 2. This interface shall not be used unless the developer is a member in good standing of the Genesys Interacts program or has a valid Master Software License and Services Agreement with Genesys. 3. A developer shall not be entitled to use any licenses granted hereunder unless the developer s organization has met or obtained all prerequisite licensing and software as set out by Genesys. 4. A developer shall not be entitled to use any licenses granted hereunder if the developer s organization is delinquent in any payments or amounts owed to Genesys. 5. A developer shall not use the Genesys developer materials outlined in this document for any general application development purposes that are not associated with the above-mentioned intended purposes for the use of the Genesys developer materials outlined in this document. 6. A developer shall disclose the developer materials outlined in this document only to those employees who have a direct need to create, debug, and/or test one or more participant-specific objects and/or software files that access, communicate, or interoperate with the Genesys API. 7. The developed works and Genesys software running in conjunction with one another (hereinafter referred to together as the integrated solutions ) should not compromise data integrity. For example, if both the Genesys software and the integrated solutions can modify the same data, then modifications by either product must not circumvent the other product s data integrity rules. In addition, the integration should not cause duplicate copies of data to exist in both participant and Genesys databases, unless it can be assured that data modifications propagate all copies within the time required by typical users. 8. The integrated solutions shall not compromise data or application security, access, or visibility restrictions that are enforced by either the Genesys software or the developed works. 9. The integrated solutions shall conform to design and implementation guidelines and restrictions described in the Genesys Developer Program Guide and Genesys software documentation. For example: a. The integration must use only published interfaces to access Genesys data. b. The integration shall not modify data in Genesys database tables directly using SQL. c. The integration shall not introduce database triggers or stored procedures that operate on Genesys database tables. Developer s Guide 13

14 Preface Making Comments on This Document Any schema extension to Genesys database tables must be carried out using Genesys Developer software through documented methods and features. The Genesys developer materials outlined in this document are not intended to be used for the creation of any product with functionality comparable to any Genesys products, including products similar or substantially similar to Genesys s current general-availability, beta, and announced products. Any attempt to use the Genesys developer materials outlined in this document or any Genesys Developer software contrary to this clause shall be deemed a material breach with immediate termination of this addendum, and Genesys shall be entitled to seek to protect its interests, including but not limited to, preliminary and permanent injunctive relief, as well as money damages. Making Comments on This Document If you especially like or dislike anything about this document, feel free to your comments to Techpubs.webadmin@genesys.com You can comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this document. Please limit your comments to the scope of this document only and to the way in which the information is presented. Contact your Genesys Account Representative or Genesys Customer Care if you have suggestions about the product itself. When you send us comments, you grant Genesys a nonexclusive right to use or distribute your comments in any way it believes appropriate, without incurring any obligation to you. Contacting Genesys Customer Care If you have purchased support directly from Genesys, please contact Genesys Customer Care. Before contacting Customer Care, please refer to the Genesys Care Program Guide for complete contact information and procedures. Document Change History This is the first release of the SDK 8.5 XML Developer s Guide. In the future, this section will list topics that are new or that have changed significantly since the first release of this document. 14 SDK 8.5 XML

15 Part 1 Use of XML and Modes of Operation Part One of the SDK 8.5 XML Developer s Guide provides a general overview of the SDK components that use XML, introduces the XML skills necessary in order to develop applications that communicate with those components, and presents system requirements. It also explains the three modes of operation that s use, how a mode is determined, and what operations are supported by each mode. The information in Part One is divided between the following chapters: Chapter 1, How s Use XML, on page 17, explains how components use XML, introduces basic XML skills, and presents system requirements. Chapter 2, Modes of Operation for, on page 23, explains the three modes of operation, how a mode is determined, and what operations are supported by each mode. Developer s Guide 15

16 Part 1: Use of XML and Modes of Operation 16 SDK 8.5 XML

17 Chapter 1 How s Use XML This chapter provides a general overview of the SDK components that use XML, introduces the XML skills necessary in order to develop applications that communicate with those components, and presents system requirements. This chapter contains these sections: How Uses XML, page 17 XML Concepts, page 17 Architecture, page 18 XML Message Guidelines, page 20 How Uses XML XML Concepts The Genesys Interactive Voice Response () application programming interface (API) enables communication between a third-party and the Genesys Server. To establish this communication, you must create an application that functions as an driver. This driver communicates with Server using Extensible Markup Language (XML). Server uses a customized document type declaration (DTD), that defines the Genesys-defined XML elements and attributes necessary to create call flows that are appropriate to your enterprise. For the text of the DTD, see Appendix, The Server DTD, on page 173. This guide assumes that you have a thorough understanding of XML data modeling. You should be familiar with the standards set in the XML specification v1.0. In addition, you need to know how to use an external (DTD) (in this case the IServer.dtd file located on your software CD). Developer s Guide 17

18 Chapter 1: How s Use XML Architecture Architecture Figure 1 shows how the XML interface connects the customer-developed driver to Server, which then communicates with Genesys Framework components. C Driver Library (C wrapper for XML) T-Server XML Driver XML XML Parser Server Configuration Server Stat Server Universal Routing Server Figure 1: Genesys Architecture Stack Layers Figure 2 contains a basic representation of the stack layers, that handle the communication among the components: Descriptions of these stack layers follow: Application XML GLI TCP IP Figure 2: Stack Layers Application layer Represents the XML-based client application built by the user to function as an interpreter between the and the Genesys Server. XML layer Shows that XML is the language the application uses to communicate. 18 SDK 8.5 XML

19 Chapter 1: How s Use XML Architecture The GDI Specification The GLI Specification GDI Link Interface (GLI) layer Responsible for link-layer functions such as load balancing over multiple network interfaces and connection-failure detection using Keep-Alive messages. It is a proprietary transport protocol used to structure TCP/IP messages, and is a subset of the Generic Data Interface (GDI) protocol from Telcordia (formerly Bellcore). For details on the GDI, see The GDI Specification. Transmission Control Protocol (TCP) layer Provides transport functions. Internet Protocol (IP) layer Provides routing capability. The GDI protocol is a service-independent interface specification created by Telcordia Technologies, Inc. (formerly Bellcore). This protocol defines both link layer features (load balancing, link monitoring, and so on) as well as application/presentation layer features (ASN.1 data types and TCAP for session management). You can obtain a copy of this specification directly from the Telcordia Store at The specification is a Special Report, SR The full title of the document is ISCP Generic Data Interface Specification for TCP/IP: Using GR-246-CORE ANSI TCAP encoding. The GLI protocol used by Server is a strict subset of the GDI protocol, and contains only the link layer features of GDI described in Chapter 2 of the GDI specification. The application/presentation layer aspects of GDI related to TCAP and ASN.1 are not used by GLI and may be ignored. For GLI code examples, See GLI Header on page 95. Reliability The following notes indicate how the GLI subset of the GDI handles connections and supports keep-alive functions. Link Failure Keep-Alive Error Messages The client initiates the TCP/IP connection to the Genesys Server. In the event of a link failure, the client reinitiates the connection with the server. For details, see the GDI specification, Section 2.1. When the client receives a Keep-Alive request, it replies with Keep-Alive response. For the format of these messages, see the GDI specification, Sections 2.2, 2.2.2, and When it receives an Error message, the client closes the current connection and initiates a new one. Error messages consist of the GDI header and an Error Code. For the definition of these Error Codes, see the GDI specification, Section Developer s Guide 19

20 Chapter 1: How s Use XML XML Message Guidelines Multiple Circuit Connections Security Timeout Errors can be generated in the following scenarios: The client is not authorized to connect to the server (client access is enabled by using the Genesys Configuration Manager). The version number (part of the GDI header) is invalid. The client can use Multiple Circuit Connections to connect with the Genesys Server. For details, see the GDI specification, Section 2.3. Only the server side enforces security implementation. Security implementation is not included in the client. For details, see the GDI specification, Section 2.4. The server side may also enforce Transport Level Security (TLS) which is the industry standard protocol for secure communications on the Internet and the successor of SSL 3.0. For detailed information refer to the Genesys 8.0 Security Deployment Guide. The client generates a timeout in the event of a lack-of-response condition of the server. For details, see the GDI specification, Section XML Message Guidelines The following points indicate important message considerations. Note: Keys in Key/Data pairs cannot include colons :. An error message appears if keys include this character. Special Character Encoding The characters <, >, &,, and must be coded in escape form in order for the parser to interpret them correctly. This applies to all portions of the messages. Table 1 lists the escape forms: Table 1: Escape Form for Certain Characters Character Escape Form < < > > & & " &apos; 20 SDK 8.5 XML

21 Chapter 1: How s Use XML XML Message Guidelines Note: The messaging protocol used between Server and Clients (for instance, Genesys Drivers, Genesys Voice Platform [GVP], and custom-built SDK clients) is XML, and certain character codes are not valid in an XML document. Characters with a value less than hexadecimal number 0x20 are not valid, with the exception of the characters 0x09, 0x0A, and 0x0D. These exceptions correspond to the ASCII control characters TAB, LINE FEED, and CARRIAGE RETURN. Application user-data keys or values should not contain any of the disallowed character codes. Header Structure For the GDI header structure, see the GDI specification, Section 2.2. Data Message Type MessageLength The CallId Parameter Error Message Type Keep-Alive Message Types The XML-encoded application layer messages are considered data messages. The value for this message type is 03. Data messages are sent from the client to the Genesys Server. The MessageLength includes the one-byte VersionNumber and the one-byte ApplicationID in its count. Key/Data pairs to be passed to T-Server are limited to 16 K in size. Other messages, including the header, can be 64 K in size. For details, see the GDI specification, Section 2.2. The driver assigns a CallId value at the time of the initial NewCall or MakeCall request. This CallId may be present in subsequent message for this call. The value can be any valid character string. Note: The CallId parameter must be unique for every concurrently active call handled by an Server application. This means not only that each individual client application has to generate unique CallIds, but if multiple clients connect to the same Server application, those clients must ensure that they do not use the same CallIds. The client can receive Error messages from the server. The message type for the Error message has a value of 02. The message type of a Keep-Alive request has a value of 00. The message type for the Keep-Alive response has a value of 01. VersionNumber The VersionNumber must have a value of 2. ApplicationID Value The only valid value for the ApplicationID is 0. Attached Data Message extensions are optional parameters that are included in some messages. They can be used by routing strategies, scripts, and the client application. The Genesys Server does not interpret these values, it simply forwards them between the Genesys Universal Routing Service (URS) and the client application. Developer s Guide 21

22 Chapter 1: How s Use XML XML Message Guidelines Attaching CED The UDataEx Parameter CED is an optional parameter for RouteRequest and TreatStatus messages. If provided, the value of CED will be present in the AttributeCollectedDigits parameter of the T-Library message that the Genesys Server forwards back from the Genesys T-Server. The TLib message is either EventRouteRequest or EventTreatmentEnd, depending on which message started the sequence. UDataEx is an optional parameter that you can include in almost every message from your client application to the Genesys Server. When Server receives data in the UDataEx parameter, it attaches the data to the call as user data, thus providing a convenient way to combine attached data with another request. For example, sending RouteRequest with UDataEx attached is equivalent to calling UDataSet, followed by a RouteRequest. Sockets, Ports, Channels, and DNs For both In-Front and Behind configurations, Server uses a list of DNs and ports that correspond to a particular. The association between ports and DNs is defined in the Configuration Layer, and it is used by Server to correlate a given port number (supplied by a client) with a DN configured on the switch. (See the Interface Option 8.0 Server System Administrator's Guide for more information.) The port related to a call is specified as the callednum parameter in the NewCall XML message. (See NewCall on page 99.) All of the message exchanges for a given and Server pair can be made using a single TCP/IP socket connection, and this is the recommended approach. It is possible to implement alternative connection handling methods, but special care must be taken when doing so. 22 SDK 8.5 XML

23 Chapter 2 Modes of Operation for This chapter provides a general overview of the SDK s three modes of operation (Behind, In-Front, and Network), how a mode is determined, and what operations are supported by each mode. This chapter contains these sections: Server High-Availability Modes, page 23 Server Operational Modes, page 25 Individual Message Support and Behavior, page 28 Server High-Availability Modes Table 2 summarizes high-availability options supported by Server. Table 2: Server High-Availability Modes Type Load Balancing Hot Standby Warm Standby No HA Definition driver assigns (and tracks) XML calls to more than one Server driver writes all XML messages to both the primary and backup Servers driver writes and reads to the current primary Server driver writes and reads all XML for all calls to and from one Server Developer s Guide 23

24 Chapter 2: Modes of Operation for Server High-Availability Modes Load Balancing The driver sends the Login message to each of N servers and then decides how to map an call to a single Server. Typically, round-robin is chosen. If an Server fails and drops its connection, the mapping is changed to send subsequent calls to the available Server(s). The failed Server is added to a reconnect list, from which it is returned to the pool of available servers. After reconnecting, the Login must be repeated. Once a call is started on a chosen Server, it must remain there. All calls on the failed Server are lost. Hot Standby The driver must send all XML requests to both the primary and backup Servers, with exactly the same information. The current primary Server responds to the request. The only exception to this is the LoginReq, LoginResp, and FlowControl messages for the In-Front and Behind operation modes, in which case both the primary and backup Servers will respond. If the connection to the primary Server fails, the driver continues to send messages for all calls to the backup Server which, after failure of the primary server, will start sending the return messages. Warm Standby The driver sends the Login message and subsequently all calls from the to the current primary Server. When that connection fails, the driver attempts to connect to the backup Server. (The Login will be necessary.) All calls on the failed Server are lost. No HA The driver sends the Login message and subsequently all calls from the to one Server. Note: See the Server System Administrator s Guide for details on how the Server is configured and works in these modes, and advantages, disadvantages, and limitations. Note that Load Balancing and Hot Standby modes are mutually exclusive. 24 SDK 8.5 XML

25 Chapter 2: Modes of Operation for Server Operational Modes Server Operational Modes A running Server application has three different modes in which it may operate: The Behind-the-switch mode is a basic configuration in which a T-Server connected to the premise switch can monitor the call activity on channels. In In-Front-of-the-switch mode, a Computer Telephony Integration (CTI) link is not involved with the call processing. In Network mode, the Server (an T-Server running in Network mode) is a link to a user-provided Network application. A routing strategy and a Genesys Network T-Server route calls to the Network for processing. In this document, these three modes are referred to as In-Front, Behind, and Network, respectively. For more information regarding these modes of operation and their configuration, refer to The Interface Option 8.5 Server System Administrator s Guide. Depending on the mode in which your Server is deployed, call flows vary, and certain messages may, or may not be supported. Implications of the Different Modes Generally speaking, In-Front and Behind modes behave identically. The exception is that with In-Front, Server is a client of itself. By contrast, with Behind mode, the Server is a client of another T-Server. This has repercussions in that some premise T-Servers support functionality that Server s T-Server does not, such as conferencing. On the other hand, Network mode is at times dramatically different and more akin to the GenSpec XMLbased Network T-Server. (See any Network T-Server Deployment Guide for details.) Modes and Their Uses of Interfaces Server contains several different client and server interfaces for use during operation. Although technically all of the interfaces are available, regardless of mode, logically they are not. The relevant interfaces are: XML/GLI server Provides access to XML-based clients, such as drivers. T-Server A fully functioning Genesys T-Server that generates various T-Library events. T-Library client A T-Server client for interfacing with other Genesys T-Servers. Developer s Guide 25

26 Chapter 2: Modes of Operation for Server Operational Modes StatServer client Interfaces with Genesys Stat Server to provide statistics lookup. ConfigServer client Client for establishing and maintaining configuration information relevant to Server. Behind Mode and Interfaces The T-Server interface is not utilized and should be considered unavailable if your have deployed Behind mode. For this particular mode, Server is a client of a foreign T-Server generally, a premise T-Server. It is important to note that any T-Server events, such as EventRouteRequest, cannot be sent in a Behind mode call since this is a function of the T-Server interface. In-Front Mode and Interfaces When the mode for a given call is In-Front, all interfaces are active (or available, depending on the specific configuration). In this case, the T-Library client interface connects to the T-Server interface, and Server becomes a client of itself. This can cause some confusion in reading logs, because messages seem to appear more often than they should. Network Mode and Interfaces Determination of Mode The T-Library client interface is not used and requires no configuration for Network mode. Additionally, if Server is running only in Network mode, an Server application is not required in Configuration Manager. If this setup is chosen, the StatServer and ConfigServer interfaces will also be offline. At any given time, an Server application is in one of the three types of modes. This means that individual calls are associated with a particular mode at call origination (either NewCall or MakeCall). You can determine the mode by using the CalledNum value of NewCall or the OrigNum value of MakeCall messages. Figure 3 provides a diagram of the decision process. 26 SDK 8.5 XML

27 Chapter 2: Modes of Operation for Server Operational Modes Retrieve CallNum or OrigNum value Is value a registered route DN? Yes Call is in network mode No Is origination logged in? No Call is in error and no mode is associated No Yes No Using logged in name, retrieve information about the port Is there a port to dn mapping? Yes Is the T-Server associated with the port connected? Yes Call is in behind mode No Is the type In-Front switch? Retrieve the switch type of the assoc. T-Server Yes Call is in In-Front mode Figure 3: Mode Determination Process When a call is in error, an EndCall message with EndCause=FeatureNotSupported is returned. This particular type of message usually indicates a configuration error. The decision block that determines whether a T-Server is connected relates to the Connections tab of the Server Application object, not a network connection. Developer s Guide 27

28 Chapter 2: Modes of Operation for Individual Message Support and Behavior Individual Message Support and Behavior Supported Messages Table 3: XML Message Support After you determine the mode of the call, any subsequent messages received for that call behave according to the call model for its type. Table 3 lists all the Server XML client messages, and indicates whether they are supported for each type. XML Message PGF Event Name Supported In-Front Behind Network AccessNumCancel Cancel Call Data Transfer Yes Yes No AccessNumGet Call Data Transfer Yes Yes No CallInfoReq Call Info Request Yes Yes Yes CancelCompleted Cancel Yes Yes Yes CompleteXfer Consult Conference No Yes No Connected Connected Yes Yes Yes EndCall End Call Yes Yes Yes Failure Route Failed Yes Yes Yes GetStatReq Get Stat Yes Yes Yes InitXfer Consult Transfer No Yes No LoginReq Login Request Yes Yes Yes LogMsg Log Message Yes Yes Yes MakeCall Make Call No Yes No NewCall(CallControlMode=Genesys) New Call Genesys No No Yes NewCall(CallControlMode=Network) New Call Network Yes Yes Yes OneStepConf Single Step Conference No Yes No OneStepXfer Single Step Transfer No Yes No PeekStatReq Peek Stat Yes Yes Yes 28 SDK 8.5 XML

29 Chapter 2: Modes of Operation for Individual Message Support and Behavior Table 3: XML Message Support (Continued) XML Message PGF Event Name Supported Reset N/A N/A N/A N/A RetrieveCall Retrieve No Yes No RouteRequest Route Request Yes Yes Yes TreatStatus (Status=Completed) Treatment Complete Yes Yes Yes TreatStatus (Status=NotStarted) Treatment Not Started Yes Yes Yes TreatStatus (Status=Started) Treatment Started Yes Yes Yes UDataDel Delete User Data Yes Yes No UDataGet Get User Data Yes Yes Yes UDataGetAll Get All User Data Yes Yes Yes UDataSet Update User Data Yes Yes Yes Mode Behavioral Differences Support of a message in a particular mode does not mean that this message will prompt the same behavior by the server in all modes. In addition, some supported messages might be required for proper operation of one mode, but might be entirely optional for another. This section details those messages that exhibit exceptions across modes. NewCall (CallControlMode=Network) In Network mode, no CallStatus messages are generated because there are no agents or extensions involved. With In-Front mode, ringing and established status messages are always generated. However, in Behind mode, they are dependent on EventRinging and EventEstablished events occurring on the associated premise T-Server. If the premise T-Server generates both EventRinging and EventEstablished for calls directed to the, the behavior for In-Front and Behind modes is the same. RouteRequest In-Front Behind Network Network mode uses route type DNs for all call processing. Routing requests are generated on the same number as CalledNum from the NewCall message. In addition, Network mode calls can use a subset of the called number as the Developer s Guide 29

30 Chapter 2: Modes of Operation for Individual Message Support and Behavior actual DN. (See the called-num-subset option in the Administrator s Guide.) This setting is not used in In-Front or Behind mode. Also, the RouteDN attribute of RouteRequest is required for In-Front and Behind modes, but it is disregarded in Network mode. In Network mode, only a single RouteRequest can be made for a call. However, since it is possible for routing failures to be indicated, target selection can occur multiple times for the same RouteRequest. Since routing failure conditions cannot be indicated for In-Front or Behind mode (see Failure ), these modes support multiple RouteRequest / RouteResponse interactions for a call. Connected This message must be sent for a Network mode call in order to properly complete the routing interaction. For In-Front and Behind modes routing cannot fail, and the use of the Connected message is highly discouraged. Sending the Connected message for In-Front or Behind mode calls will cause the routing interaction to be canceled. This is used to implement the Route Abort feature that is required for compatibility purposes in some drivers, although it is considered deprecated. Failure The Failure message maps to EventError in Network mode, and it can be used to indicate routing problems. For In-Front and Behind modes, routing cannot fail, and the use of the Failure message is not recommended. LoginReq This message is necessary for proper determination of In-Front and Behind modes. 30 SDK 8.5 XML

31 Part 2 Server In-Front and Behind Mode Part Two of the SDK 8.5 XML Developer s Guide familiarizes you with the Genesys SDK XML, the tool for building drivers that allow your (Interactive Voice Response Unit) to communicate with the Genesys Server. This portion of the guide introduces you to the relevant concepts, terminology, and procedures used by the Genesys SDK XML in standard integration situations. The information in Part Two is divided among the following chapters: Chapter 3, In-Front and Behind State Machine Diagrams, on page 33, contains state machine diagrams from the viewpoint of the driver. This chapter also includes messages that can be sent from any state, error messages, and the procedure for configuring the statistics used in the statistics messages. Chapter 4, In-Front and Behind Call Flow Diagrams, on page 43, provides call flow diagrams for many common scenarios. It is intended as a reference. Chapter 5, XML Protocol Messages and Parameters, on page 61, contains tables showing the parameters for each message, the message direction, and whether the parameters are required or optional. Chapter 6, Using the XML Protocol: Examples, on page 95, presents sample XML messages and comments for a number of commonly-encountered call flow scenarios. These sample XML messages are intended as starting points for building your driver application. Developer s Guide 31

32 Part 2: Server In-Front and Behind Mode 32 SDK 8.5 XML

33 Chapter 3 In-Front and Behind State Machine Diagrams This chapter includes diagrams showing sequences of events and transitions from state to state in a standard application using an driver. This chapter contains these sections: Overview, page 33 Call Routing States, page 34 Transfer States, page 35 Conference States, page 36 Call Treatment States, page 38 Make Call States, page 39 Additional Event Messages, page 39 Error Messages, page 41 Configuring Stat Server Statistics, page 42 Overview The following diagrams outline the states available to the client-server system, shown from the perspective of the client driver application. Events in the diagrams that are prefaced with are generated by the and sent to the client driver application. All other events are sent from the Server to the driver. Developer s Guide 33

34 Chapter 3: In-Front and Behind State Machine Diagrams Call Routing States Note: The messages in these diagrams are designed to represent typical messages that your sends to your driver client application. The messages might differ somewhat from those given below, depending on the hardware and software your enterprise uses. Notice that the EndCall message can arrive at anytime from the after the call has started. The first diagram in this chapter, Figure 4 on page 35, shows the initiation of a call and marks the points where a call treatment, transfer, or conference could begin. Remote transfers, local transfers, conferencing, and call treatments are shown in separate state machine diagrams that follow this Call Routing example. The final state machine diagram, Figure 8 on page 39, shows a MakeCall call flow. With MakeCall, the system (or an outbound calling program that uses the ) initiates the call. This is an alternative to NewCall and is therefore shown separately. Call Routing States Figure 4 on page 35 includes the initial NewCall messages that lead to the Call Started or Connecting state the starting points for transfers and conferencing followed by the driver states found in a routing call flow. NewCall is the starting point for the subsequent diagrams and tables, with the exception of the MakeCall call flow ( Make Call States on page 39). 34 SDK 8.5 XML

35 Chapter 3: In-Front and Behind State Machine Diagrams Transfer States Call Routing ** Call Treatments can occur from the Waiting For Instructions state. This is detailed in a different state machine fragment. Waiting For Instructions NewCall (Network) (1) Call Started* *Must wait for Established. CallStatus (Ringing, Established) RouteResponse RouteRequest (3) RouteRequest Connecting* * Transfer of calls and conference calls can occur from either the Call Started or Connecting states. For simplicity, these state machine fragments are shown below. Connected (10) Connected EndCall (11) Figure 4: Call Routing States Diagram Transfer States The following diagram shows the driver states encountered during a transfer. Throughout these transfer sequences, the and the Genesys Server communicate through your driver application. Note: The transfer events and their branches, shown in Figure 5 on page 36, are only available when the Server is running in Behind mode. Developer s Guide 35

36 Chapter 3: In-Front and Behind State Machine Diagrams Conference States The Server supports two types of transfers, one-step and consult. One-step transfers are made as quickly as the switch can perform them. They are most useful for predictive dialing situations. Consult transfers place the original call on hold and establish that the transfer line is available before completing the transfer. Note: Not all switches support one-step transferring. If you receive an Unsupported Operation error message when making a one-step transfer, use the consult transfer instead. In case of an error message, the original call is reactivated. Transfer Connecting or Call Started OneStepXfer (14) CallError CallError CallStatus (Retrieved) CallStatus (Held, Dialing, Established, XferComplete) Single Step Xfer InitXfer (15) Consult Xfer Aborted Retrieve (17) CallStatus (Held, Consult Dialing, Xfer Established, Busy) EndCall (18) Complete Xfer (16) EndCall (19) Consult Xfer Complete CallStatus (XferComplete) Figure 5: Transfer State Machine Conference States The following diagram shows the driver states encountered when conferencing a call. Throughout these conferencing sequences, the and the Server communicate via your driver application. Note: The conference events and their branches, shown in Figure 6 on page 37, are only available when the Server is running in -Behind mode. 36 SDK 8.5 XML

37 Chapter 3: In-Front and Behind State Machine Diagrams Conference States The Server supports two types of conferencing, one-step and consult. One-step conferences are made as quickly as the switch can perform them. Consult conferencing places the original call on hold and establishes that the new conference line is available before completing the conference. Note: Not all switches support one-step conferencing. If you receive an Unsupported Operation error message when attempting a one-step conference, use the consult conference method instead. In case of an error message, the original call is reactivated. Conference Connecting or Call Started CallError InitConf (21) CallStatus (Retrieved) CallError CallStatus (ConfPartyDeleted) CallStatus (ConfPartyDeleted) CallStatus (Held, Dialing, Established, Busy) OneStepConf (20) Consult Conf Complete Conf (22) Retrieve (23) CallStatus (ConfPartyAdded) Single Step Conf EndCall (24) Consult Conf Complete EndCall (25) CallStatus (Retrieve, ConfPartyAdded) Consult Conf Aborted Figure 6: Call-Conferencing States Developer s Guide 37

38 Chapter 3: In-Front and Behind State Machine Diagrams Call Treatment States Call Treatment States A call treatment is an operation performed on a call and can be one of a number of types. These types can be sequences of automated questions that collect caller information, music on hold, or some other handling of the call. Invoking a call treatment application involves the states shown in the following diagram, Figure 7. Call Treatments Failure (9) Waiting For Instructions RouteResponse TreatStatusNotStarted (4) TreatCall TreatStatusCompleted (5) Connecting TreatCall RouteResponse Connected (10) Connected RouteResponse Starting Treatment TreatStatusStarted (6) Cancel Treatment Started TreatCall EndCall (11) TreatStatusCompleted (8) Treatment Cancelled Cancelling Treatment Cancelled (7) Figure 7: Call Treatment States 38 SDK 8.5 XML

39 Chapter 3: In-Front and Behind State Machine Diagrams Make Call States Make Call States The MakeCall operation is an alternative to the NewCall scenario. In a MakeCall call flow, the initial call is outbound rather than inbound. Figure 8 shows the states that can occur during an MakeCall operation. Make Call MakeCall (26) Making Call CallStatus (Dialing, Busy) CallStatus (Established) EndCall (11) Call Started *** *** Make Call is a separate state machine that connects to the main Call Routing state machine. In the Make Call scenario, the CallStatus(Ringing) and CallStatus(Established) events do not occur in the Call Started state. See the Call Routing state machine for comparison. Figure 8: MakeCall States Additional Event Messages Anytime Messages In addition to the events included in the diagrams above, you can have the driver send the following messages to the Server. Messages that can be sent at any point in a call after the NewCall message: PeekStatReq Requests statistical information from Stat Server. You can request two statistics, CurrNumberWaitingCalls and ExpectedWaitTime. These allow you to inform the caller how long the expected wait time is. Developer s Guide 39

40 Chapter 3: In-Front and Behind State Machine Diagrams Additional Event Messages GetStatReq Requests statistical information from Stat Server. You can request two statistics, CurrNumberWaitingCalls and ExpectedWaitTime. These allow you to inform the caller how long the expected wait time is. Note: These statistics must be configured in the Stat Server application. See Configuring Stat Server Statistics on page 42 for the statistic parameters. LogMsg Writes data to a log file. This file can be local or on the Server. Set the log location in the Data Options Transport section of the Server Application in Configuration Manager. After CallStatus (Ringing) Messages Messages that can be sent after the Server has sent a CallStatus (Ringing) message: UDataSet, UDataGet, UDataGetAll, UDataResp, UDataDel These user data messages allow you to set up and manipulate key/value lists that are stored in T-Server for the duration of an interaction. These lists can include multiple key/value pairs that contains customer data such as current account information. The requests this information, which the driver forwards to T-Server by way of the Server. UDataSet Requests T-Server to add specified key/value pairs to the call object. To replace data, use UDataSet with Action set to Replace. UDataGet Requests data for an existing key or keys. UDataGetAll Requests data for all existing keys. UDataResp The response to a previous UData request. If the request was Get and Result was set to Success, the data is in the response. If the request was Set or Del and Result was set to Success, the operation was successful and no data is returned. If the operation was not successful, it failed for the specified reason: NoSuchCall, NoMatch (no such key), FeatureNotSupported (cannot add key/value pairs), or MiscError. UDataDel Removes one or all key/value pairs for a call. To remove one, use Action set to DeleteKey. To delete all keys, use Action set to DeleteAll. CallInfoReq A request from the for T-Server call data, forwarded to T-Server by the driver via the Server. The data can include: ANI The calling party s number. DNIS The number or switch alias called by the caller. CalledNum The port number of the call. The port numbers are configured in the application in the Configuration Layer. 40 SDK 8.5 XML