See: Description
Package | Description |
---|---|
com.avaya.ccs.api | |
com.avaya.ccs.api.enums | |
com.avaya.ccs.api.exceptions |
The Contact Control Service (CCS) is a component on the Contact Center server which provides Agent and Contact control services for third parties applications. Third party applications can communicate with the Contact Control Service by developing against the Contact Control Service Application Programming Interface (CCS API). The Application Programming Interface (API) communicates with the Contact Control Service through WebSockets. Requests are transmitted from the API to the Contact Control Service over a proprietary HTTP-like protocol. Events are transmitted from the Contact Control Service to the API over a proprietary JSON-like protocol.
Below is a high level architecture diagram of the solution describing where the components are deployed and how they communicate.
The com.avaya.ccs.api package contains the set of interfaces defined for communication with the Contact Control Service. The com.avaya.ccs.api.enums package contains the enumerations that are utilized by the interfaces defined in the com.avaya.ccs.api package. The com.avaya.ccs.api.exceptions package contains the exceptions that can be thrown by the API interfaces. The com.avaya.ccs.core package is private and contains the API implmentation. Application developers do not require this package and therefore this package should not be imported in the application source.
ClientI
interface object. Once an instance of this interface is obtained, the API methods defined on this interface can be used to access the Contact Control Service. The next sections will describe the defined interfaces and the eventing structure of the API.
The ClientI
represents the CCS API's connection to the Contact Control Service. Each ClientI
object will have a WebSocket open to the Contact Control Service. For High Availability solutions, there are Contact Control Service instances on each of the High Availability Contact Center servers. For Mission Critical High Availability campus solutions the client will have a WebSocket open to each of the High Availability Contact Center servers (one WebSocket to the Active Contact Center and one WebSocket to the Standby Contact Center). Please see the ClientI
interface and the ClientI.create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)
javadocs for detailed information.
The SessionI
interface represents an authenticated session with the Contact Control Service. A ClientI
object will have a single SessionI
object at any one time which is obtained on successful ClientI.signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
. A successful signin and authentication is required to gain access to the Contact Control Service. Please see the ClientI.signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
javadocs for detailed information.
The UserI
interface represents a Contact Center User (Agent or Supervisor) in the Contact Control Service. A UserI
object allows the application to control the Contact Center User. A UserI
object is associated with a SessionI
and there can be multiple users per session depending on the configuration. The UserI
objects in a session can be accessed by invoking SessionI.openUsers(com.avaya.ccs.api.UserListenerI)
once a new session has been created. Please see UserI
javadocs for detailed information.
The ResourceI
interface represents a Contact Center Users device or endpoint. A ResourceI
object allows the application to control the Contact Center Users device. A ResourceI
object is associated with a SessionI
and there can be multiple resources per session depending on the configuration. The ResourceI
objects in a session can be accessed by invoking SessionI.openResources(com.avaya.ccs.api.ResourceListenerI)
once a new session has been created. Please see ResourceI
javadocs for detailed information.
The InteractionI
interface represents a Contact Center User's (Agent or Supervisor) interaction with a Contact in the Contact Center. An InteractionI
object allows the application to control the Contact Center Users participation in the Contact as well as access the details of the Contact. There can be multiple interactions in a SessionI
at any given time. The InteractionI
objects in a session can be accessed by invoking SessionI.openInteractions(com.avaya.ccs.api.InteractionListenerI)
once a new session has been created. Please see InteractionI
javadocs for detailed information.
The MonitoredUserI
interface represents a monitored Contact Center User from the point of view of their Supervisor in the Contact Control Service. A MonitoredUserI
object allows the application to invoke supervisor operations on a user in the Contact Control Service. The MonitoredUserI
objects are associated with the Supervisors UserI
object and there can be multiple monitored users on a Supervisor user. The MonitoredUserI
objects can be accessed by invoking UserI.monitorUsers(com.avaya.ccs.api.MonitoredUserListenerI)
on the Supervisors user. Please see UserI
and MonitoredUserI
javadocs for detailed information.
The MonitoredInteractionI
interface represents an InteractionI
object at a UserI
object from the point of view their Supervisor in the Contact Control Service. A MonitoredInteractionI
object allows the application to invoke supervisor operations on an interaction in the Contact Control Service. There can be multiple monitored interactions on a Supervisor user. The MonitoredInteractionI
objects can be accessed by invoking MonitoredUserI.monitorInteractions(com.avaya.ccs.api.MonitoredInteractionListenerI)
. Please see InteractionI
and MonitoredInteractionI
javadocs for detailed information.
The API has a thread pool which is used to execute requests received from the application, process events received over the Web Socket from the Contact Center server and notify the application of these events. CCS API interface methods (requests) that have a return type of void are non blocking and will return immediately to the executing application thread. The CCS API threading implementation guarantees synchronous processing of requests within the same ClientI object. These interface methods will send a request over the Web Socket to the Contact Center server. If the request is not successful and an error occurs, the application is notified via the appropriate API event listener (see the 'API Event Handling' section of this Overview and the interface javadocs for detailed information). CCS API interface methods that have a return type other than void will block the executing application thread. These interface methods perform a cached data lookup within the CCS API and will return the requested data to the application. The executing application thread will only be blocked for a short duration as the requested data is always locally cached in the CCS API. These methods will not cause a request to be sent over the Web Socket to the Contact Center server.
Each interface listed above has a corresponding listener interface. For example ClientI
has ClientListenerI
. Each listener interface has an onEvent method defined, for example ClientListenerI
has an onClientEvent method which carries a NotificationEventI
object as an argument. Events on API interface objects are delivered to the application through these listener interface methods. The application must provide an implementation of each of these listener interfaces. The implementations of these listener interfaces are supplied to the CCS API as mandatory arguments to methods that are defined on the API interface objects. When the application is notified of an event through the event listener methods, the application must immediately move processing of the event off the CCS API processing threads. Please see the listener interfaces javadocs and the NotificationEventI
for detailed information on API eventing.
Secure WebSockets are mandatory for the CCS API's communication with the Contact Control Service. Secure WebSockets require certificates as do any secure protocol. The CCS API is the initiator of the WebSocket and hence is the client in the WebSocket handshake. The Contact Control Service is the receiver of the WebSocket and hence is the server in the WebSocket handshake. The server generally will provide a signed certificate in the secure handshake. At the time the ClientI
object is created, the application can provide a keystore object to the API which will be used to validate received signed certificates from the server. The keystore if supplied therefore must contain the CA certificate of the Certificate Authority that signed the servers certificate. The application can also choose not supply a keystore. The result will be that all received signed certificates are trusted by the API. In this case the data sent will still be encrypted however the identity of the server will not be validated. It is recommended that a keystore is provided to the API to ensure fully secure communications. For more information on API security implementation please see the ClientI
javadocs.
The API requires Log4j2 to output log statements. A default log4j2.xml configuration is located in the api directory of the packaged SDK. This configuration file contains the logging configuration details for the API. The application must configure log4j2 to ensure that the API outputs log statements for debugging purposes. If the application is already using log4j2, the logging configuration for the API (specified in the default log4j2.xml) can simply be added to the applications existing log4j2 configuration file. If the application is not using log4j2, then the developer must place the API's default log4j2.xml file on the classpath of the application. The API uses log4j2 asynchronous loggers. This is essential when running a server application under load (see API Application Types). For asynchronous logging in log4j2, the third party disruptor library is required. A log4j2.component.properties file is located in the api directory and is also required to be placed on the applications classpath.
The CCS API can be used to build client or server applications to communicate with the Contact Control Service on the Contact Center server. It is important to note that the client or server application cannot be hosted on the Contact Center server.
ClientI
object to control the Contact Center User that is accessing the application. There is a single UserI
object within a single ClientI
and SessionI
object. An example of this type of application would be a desktop client application for Contact Center Users.
ClientI
objects, each representing and controlling a single Contact Center User (Agent or Supervisor). Each client object will have a single SessionI
object and a single UserI
object (one User per Client/Session). The application signs in each client individually using the credentials of the Contact Center User that the client is representing. As mentioned previously, each ClientI
object will open a WebSocket to the Contact Center server (the application will have a Web Socket per Contact Center User).
ClientI
object to represent and control multiple Contact Center Users (Agents or Supervisors). In this approach, an administrator creates a mapping of multiple Contact Center Users (Agents or Supervisors) to a CCT User account in the Contact Center. The application signs into the client using the credentials of the CCT User account. The ClientI
object will have a single SessionI
object but will have multiple UserI
objects, one for each Contact Center User that is mapped to the CCT User account (multiple Users per Client/Session). In this approach there can be one or more ClientI objects, each ClientI object will open a WebSocket to the Contact Center server. For high capacity applications using this approach, load should be split across multiple Client objects and therefore multiple WebSockets (see below for details). Important Note: Agents with ContactType.Voice
only can be supported using this approach. Agents with Multimedia contact types such as ContactType.POM_Outbound
cannot be supported using this approach.
For Multiple Users per Client applications, the server application must create the ClientI
object with the Profile.Server
profile. The server application can create multiple client objects if it wishes to split the load of the Contact Center Users across multiple client objects (therefore splitting the load across multiple web sockets). To accomplish this the administrator would split the mapping of the Contact Center Users across multiple CCT User accounts. Taking an example; two CCT User accounts could be created with 100 Contact Center Users mapped to each account. Controlling the maximum supported Contact Center Users (Agents and Supervisors) is supported through a single client object or multiple client objects.
For Single User per Client applications, the server application must create each ClientI
object with the Profile.AgentDesktop
profile. Controlling the maximum supported Contact Center Users (Agents and Supervisors) is supported with this configuration.
When designing and developing a server application, performance under load must be taken into consideration.
There is one Contact Control Service instance created on the Contact Center server per ClientI
object and therefore one Contact Control Service instance per WebSocket. Request processing within the Contact Control Service instance is blocking. Request processing within the CCS API is non-blocking and does not block the executing application threads (see the 'API Threading' section of this Overview for more details).
For client applications or server applications developed using the Single User per Client approach, requests are processed synchronously per Contact Control Service instance (per WebSocket) and therefore per Contact Center User. For server applications developed using the Multiple Users per Client approach, even though there are multiple Contact Center Users controlled by a ClientI
object, requests will be processed synchronously per Contact Center User rather than per WebSocket. This is to improve performance but also to guarantee the processing order of requests per Contact Center User.
Multiple requests of the same type (for example two answer requests) or multiple requests of different types (for example answer & hold) will take different durations to complete end to end through the solution. The service provider platforms in the solution (such as the call server) will have their own limits around concurrent requests and request durations. Other factors such as network round trip time durations between all components in the solution will also affect request times. Due to these factors it is not possible to provide a figure with respect to the supported API request throughput. In general, the recommendation would be that requests into the Contact Control Service API be throttled by the server application. Taking an example, if the server application is signing in Contact Center Users in bulk, invocations of ClientI.signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
request must be throttled. Throttling of requests is critical for applications that have high capacity requirements.
The table below provides information on application use cases, the appropriate design approach for the use case and the limits that each design approach is bound by.
Application Use Case | Profile | Number of supported ClientI objects | Number of supported UserI objects per ClientI | Details |
---|---|---|---|---|
Client application (Desktop application for a Contact Center User) | Profile.AgentDesktop |
1 | 1 - 10 | A client application can only have a single ClientI object. The application can have up to 10 Users mapped to the Contact Center User that is signed into the ClientI. For the majority of client applications, the ClientI object will control one UserI |
Server application (Single User per Client) | Profile.AgentDesktop |
1 - 3000 | 1 | A server application using this profile can have up to 3000 ClientI objects. The application can have only one UserI per ClientI object |
Server application (Multiple Users per Client) | Profile.Server |
1 - 10 | 1 - 3000 | A server application using this profile can create up to 10 ClientI objects. The total number of Contact Center Users that are controlled by the application should be split evenly across the client objects. The application can control up to a maximum of 3000 Users, this is regardless of the number of Client objects created. For high capacity server applications using this profile, utilizing the maximum number of supported ClientI objects is recommended. Taking an example of an application requiring control of 1000 Contact Center Users; The application could create 10 ClientI objects with each ClientI controlling 100 Contact Center Users. Alternatively the application could create a single ClientI object controlling 1000 Contact Center Users. |
Applications developed against the Contact Control Service API's should not exceed a total of 3000 concurrent ClientI objects. Applications should also not exceed a total of 10 concurrent Profile.Server
ClientI objects. Please note these figures are total instances across all applications connected to the Contact Control Service on a Contact Center server and therefore are solution limits.