Platform SDK Developer's Guide Platform SDK 9.0.x 3/6/2020 Table of Contents Welcome to the Developer's Guide! 4 Introductory Topics 6 Introducing the Platform SDK 7 Architecture of the Platform SDK 12 Connecting to a Server 14 Configuring Platform SDK Channel Encoding for String Values 32 Using the Warm Standby Application Block 33 Using the Application Template Application Block 42 Using the Cluster Protocol Application Block 74 Event Handling 88 Setting up Logging in Platform SDK 100 Additional Logging Features 106 Log4j2 Configuration with the Application Template Application Block 116 Advanced Platform SDK Topics 132 Using Kerberos Authentication in Platform SDK 133 Secure connections using TLS 137 Quick Start 143 TLS and the Platform SDK Commons Library 147 TLS and the Application Template Application Block 160 Configuring TLS Parameters in Configuration Manager 167 Using and Configuring Security Providers 190 OpenSSL Configuration File 201 Use Cases 208 Using and Configuring TLS Protocol Versions 211 Lazy Parsing of Message Attributes 214 Log Filtering 218 Hide or Tag Sensitive Data in Logs 230 Profiling and Performance Services 237 IPv6 Resolution 243 Managing Protocol Configuration 248 Friendly Reaction to Unsupported Messages 252 Creating Custom Protocols 258 JSON Support 267 Working with Custom Servers 276 Bidirectional Messaging 282 Hide Message Attributes in Logs 287 Resources Releasing in an Application Container 289 Transport Layer Substitution 292 Server-Specific Overviews 301 Telephony (T-Server) 302 Introduction to TLib Functions and Data 314 Configuration 317 Connecting Using UTF-8 Character Encoding 330 Change Password On Next Login 335 Getting the Last Login Info 337 Using the Configuration Object Model Application Block 340 Introduction to the Configuration Layer Objects 377 Stat Server 380 Custom Statistics: Getting Agent State for All Channels 394 Interaction Server 399 Universal Contact Server 404 Creating an Email 413 Chat 426 E-Mail Server 433 Outbound 437 Management Layer 439 LCA Protocol Usage Samples 453 LCA Hang-Up Detection Support 460 Handle Application "Graceful Stop" with the LCA Protocol 466 Routing Server 468 Component Overviews 479 Using the Log Library 480 Migration Overview 496 Migration from Message Broker Application Block Usage 497 Migration from Protocol Manager Application Block Usage 505 Legacy Topics 510 Using the Message Broker Application Block 511 Event Handling Using the Message Broker Application Block 523 Using the Protocol Manager Application Block 539 Connecting to a Server Using the Protocol Manager Application Block 560 Legacy Warm Standby Application Block Description 569 Welcome to the Developer's Guide! Welcome to the Developer's Guide! This guide offers a collection of articles that will help you to get started with Platform SDK development. For detailed information about the Platform SDKs, please refer to the Platform SDK API Reference for your specific release. Getting Started Working Directly with Genesys Servers Learn about the Platform SDK architecture and Understand how Platform SDK allows your how to begin creating your own custom application to interact directly with the desired applications. Genesys Server. Introducing the Platform SDK Connecting to a Server Architecture and Design Telephony (T-Server) Event Handling More... More... Using Application Blocks to Aid Commonly Used Features Development These features are not specific to a Genesys Find out about the architecture of Genesys Co- server, and can be used in most applications. browse. Channel Encoding for String Values Application Template Application Block Logging Configuration Warm Standby Application Block Secure Connections Using TLS Configuration Object Model Application Block More... Platform SDK Developer's Guide 4 Welcome to the Developer's Guide! Additional Resources Additional articles to support Platform SDK developers. Migration Overview Legacy Support Platform SDK API Reference Platform SDK Developer's Guide 5 Introductory Topics Introductory Topics The following articles give information about common Platform SDK functionality and protocol usage that all developers should be aware of: • Introducing the Platform SDK • Architecture of the Platform SDK • Connecting to a Server • Configure Platform SDK Channel Encoding for String Values • Using the Warm Standby Application Block • Using the Application Template Application Block • Using the Cluster Protocol Application Block • Event Handling • Setting Up Logging in Platform SDK • Additional Logging Features • Log4j2 Configuration with the Application Template Application Block Platform SDK Developer's Guide 6 Introductory Topics Introducing the Platform SDK Introducing the Platform SDK The Platform SDK exposes the protocols of Genesys servers as an API. This means you can write .NET and Java applications that communicate with these servers in their native protocols. You can use the Platform SDK to do two main things: • Establish and maintain a connection to each Genesys server used by your application • Send and receive messages to and from each of these Genesys servers In addition to enabling these two basic functions, the Platform SDK ships with application blocks, which have been built on top of the Platform SDK in order to provide simple yet high-performance ways to do things like configuring warm standby settings for your connections and working with configuration objects. The following image shows the relationship between the Platform SDK protocol objects and the servers each of them connects with. Each protocol object subclasses ClientChannel, which in turn subclasses DuplexChannel and implements the Protocol interface. This means they all share a common interface to the Genesys servers. The protocol objects communicate with the corresponding Genesys servers over a TCP connection, with each one using the native protocol of the server it connects with. For example, the TServerProtocol object communicates over TCP with a T-Server, using the TLIB protocol that is native to the T-Server. As mentioned above, the Platform SDK also includes reusable production-quality application blocks that can be dropped into your code to provide simple yet high-performance ways to carry out important functions that are commonly needed by applications that communicate with Genesys servers. As shown below, there are two main types of application blocks: generic and specific. Platform SDK Developer's Guide 7 Introductory Topics Introducing the Platform SDK Generic application blocks provide functionality that is useful for a broad range of applications, such as configuring connection and warm standby settings. These application blocks are recommended for use in most development. Specific application blocks are only beneficial for certain types of applications. For example, the Configuration Object Model application block makes it easy to work with objects in the Genesys Configuration Layer and is only required when you are writing an application that requires this functionality. Finally, the Platform SDK includes additional components designed to make development of custom applications easier. These components offer support for useful features such as customized logging or switch abstraction. The Protocols The Platform SDK is divided into separate “protocols.” Each component works with one or more of Genesys servers. The following table shows the servers each of the Platform SDK protocols connects with, and gives the names of the native protocols that are used to communicate with each server. Platform SDK Protocol Name Genesys Servers Native Protocols Configuration Platform SDK Configuration Server CFGLIB Contacts Platform SDK Universal Contact Server UCS Protocol • Message Server • GMESSAGELIB Management Platform SDK • Solution Control Server • SCSLIB • Local Control Agent • LCALIB Platform SDK Developer's Guide 8 Introductory Topics Introducing the Platform SDK Platform SDK Protocol Name Genesys Servers Native Protocols Open Media Platform SDK Interaction Server ITX, ESP • CMLIB Outbound Contact Platform SDK Outbound Contact Server • OCS-Desktop Protocol • Custom Server • Custom Server Protocol Routing Platform SDK • Universal Routing Server • Routing Server Protocol Statistics Platform SDK Stat Server STATLIB • TLIB Voice Platform SDK T-Servers • Preview Interaction Protocol • MCR Chat Lib • Chat Server • MCR E-Mail Lib Web Media Platform SDK • E-Mail Server Java • MCR Callback Lib • Callback Server • ESP E-Mail Lib Configuration Platform SDK The Configuration Platform SDK enables you to build applications that use the services of the Genesys Configuration Server. This allows these applications to either query on objects in the Configuration Layer of your Genesys environment or to add, modify, and delete information about those objects, while taking advantage of an environment in which Configuration Server carries out several important administrative functions. Contacts Platform SDK The Contacts Platform SDK allows you to build applications that view, or interact with, the contact information for your contact center. This SDK accesses information directly from Universal Contact Server, allowing you to design applications that access contact information when dealing with multimedia interactions such as chat or email, for example. Management Platform SDK The Management Platform SDK enables you to write applications that interact with Message Server, Solution Control Server, and Local Control Agents. Open Media Platform SDK With the Open Media Platform