See: Description

ccs api packages
Package | Description
--- | ---
com.avaya.ccs.api |
com.avaya.ccs.api.enums |
com.avaya.ccs.api.exceptions |

## Contact Control Service

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.

## Contact Control Service Software Development Kit

The Contact Control Service Software Development Kit (CCS SDK) is the packaged resources that are required to develop an application that is compliant with the Contact Control Service. The CCS SDK packaged zip contains;

- Contact Control Service Application Programming Interface (CCS API)
- Contact Control Service Reference Client
- Relevant documentation

The CCS API is located in the api directory of the packaged SDK. The CCS Reference Client is located in the reference-client directory of the packaged SDK. The documentation is located in the documentation directory of the packaged SDK.

## Contact Control Service Application Programming Interface

The Contact Control Service Application Programming Interface (CCS API) defines the set of interfaces to provide Java developers with access to the Contact Control Service.

### Libraries

The API requires the following third party libraries;

- Jetty for the WebSockets implementation.
- Jackson for JSON processing.
- Log4j2 and Disruptor libraries for outputting log statements from within the API source code.

The third party libraries are located in the api/lib directory of the packaged SDK. The ccs-api.jar file contains the compiled CCS API which is located in the api directory of the packaged SDK. All third party library jar files as well as the ccs-api.jar file must be placed on the classpath when developing an application against the CCS API.

### API Structure

The API is structured into four packages;

- com.avaya.ccs.api
- com.avaya.ccs.api.enums
- com.avaya.ccs.api.exceptions
- com.avaya.ccs.core

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.

### Developing a CCS API Application

The starting point when developing a CCS API compliant application is the creation of a `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.

#### API Interfaces

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.

#### API Threading

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.

#### API Event Handling

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.

#### API Security

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.

#### API Logging

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.

#### API Application Types

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.

#### Client Application

A client application controls a single Contact Center User (Agent or Supervisor). The application creates a single `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.

#### Server Application

A server application controls multiple Contact Center Users (Agents or Supervisors) from a single application. To accomplish this, there are two approaches that can be taken in the design of the application;

1. Single User per Client: The application can create multiple `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).
2. Multiple Users per Client: The application can create a `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.

#### API Performance Considerations

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.

#### API Limitations

The CCS API has the following limitation;

The same Contact Center agent cannot be logged in to CCS SDK Client and Avaya Aura Agent Desktop sumultainiously. If CCS detects that the same Agent was logged in to other application then CCS SDK Client will receive `NotificationType.NEW` with state `UserState.UsedByOtherClient` by `UserListenerI`. After that CCS Session for CCS SDK Client will be cleared. It means that CCS SDK Client will stop receiving any notifications from CCS.