public interface ClientI
ClientI
interface represents the starting point for gaining access to the Contact Control Service.
To access the Contact Control Service, the application must create an instance of the ClientI
object via the
static factory method create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)
. Following creation of a ClientI
instance, there is no
connection established with the server. In order to connect and establish an authenticated session with the server,
the application must invoke signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
. Each ClientI
instance can be associated with only one
SessionI
instance.
The ClientI
object will transition through different ClientState
values to notify the application of
state changes on the communication link between the client and server;
ClientState.DISCONNECTED
to ClientState.CONNECTING
ClientState.CONNECTING
to ClientState.CONNECTED
ClientState.CONNECTED
to ClientState.AUTHENTICATED
These state transitions are sent to the application in NotificationType.UPDATE
notifications for the
ClientI
object through the ClientListenerI
implementation supplied as an argument to the signin
method.
Connection Resiliency
If getAutoReconnect()
returns true
, the client will attempt to automatically recover the
connection to the Contact Control Service if the connection is lost. On loss of the connection, the ClientI
object will transition from ClientState.AUTHENTICATED
to ClientState.CONNECTING
. The SessionI
object representing the previously authenticated session will be deleted and a NotificationType.DELETE
notification will be sent to the SessionListenerI
implementation provided by the application to the signin
method. For further information on session lifecycle, please see SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)
. The
ClientI
is the only object that survives after a loss of connection to the Contact Control Service.
On successful reconnection to the Contact Control Service, the API will automatically signin the client to the
Contact Control Service. The application will receive a new authenticated session as described in the signin method.
The client will transition through the following states;
Reconnect delay parameters
There are several client reconnection delay parameters. Reconnection delays are configurable; and defaults are defined
in Client.java.
channel.reconnect.short_outage_delay
- the initial timeout delay. If disconnected, the channel will
reconnect after this duration. Default is 2 secondschannel.reconnect.long_delay_retries_threshold
- after this many attempts, if the channel has not transitioned
to ClientState.AUTHENTICATED
, then the retry timeout will switch to channel.reconnect.long_outage_delay If {@link ClientI#getAutoReconnect} returns {@code false}, the client will not attempt to automatically recover the connection to the Contact Center server. On loss of the connection the {@code ClientI} object will transition from {@link ClientState#AUTHENTICATED} to {@link ClientState#DISCONNECTED}. The application is notified of this state change through a {@link NotificationType#ERROR} notification for the {@code ClientI} object. To connect to the Contact Control Service again, the application must invoke {@link ClientI#signin}.
High Availability
The following High Availability solutions are supported by the API;
Solutions can have Campus High Availability and/or Geographic High Availability. For Geographic HA, a Remote Geographic Node (RGN) is provisioned. The RGN is for disaster recovery scenarios where the Campus (main site) has a complete outage. A switchover to the RGN is manually triggered by administrators when a sufficient outage is detected.
In a Campus switchover, if an outage occurs on the Active Contact Center server, the solution will automatically switchover to the Standby Contact Center server. On detection of this outage, the {@code ClientI} will automatically switchover to the Standby Contact Center server. This automatic switchover of the {@code ClientI} is managed internally by the API.
In a Geographic switchover, if the entire Campus has an outage, the application will have to manually connect to the fully qualified hostname of the RGN Contact Center server. Access to the RGN fully qualified hostname will not be provided to the application by the API. The RGN fully qualified hostname must be made available to the application by other means.
Please see Contact Center solution documentation for information on Business Continuity and Mission Critical High Availability solutions as well as switchover behaviors for all solutions. Expected switchover times vary depending on the solution.
Contact Center Mission Critical High Availability (MCHA) Campus
When connecting to a Contact Center Mission Critical High Availability campus pair, the application must provide the
fully qualified managed hostname of the Contact Center MCHA pair as the server argument to {@link ClientI#create}.
The {@link ClientI#isHa} method defines whether the Contact Center is configured for MCHA. The
{@link ClientI#isHaOperational} method defines whether MCHA is fully operational. This is determined by the client
object being connected and authenticated to both the Active and Standby Contact Center servers. The application is
notified of a change to {@link ClientI#isHaOperational} through a {@link NotificationType#UPDATE} notification for
the {@code ClientI} object. The Contact Center that is currently Active can be retrieved by
{@link ClientI#getConnectedServer}.
If the Active Contact Center server has an outage, a switchover will occur and the Standby Contact Center server will take over the Active role. On switchover, a manual signin to the newly Active Contact Center server is not required by the application. The client will automatically signin to the newly Active Contact Center server (previous Standby server). A {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change may occur depending on the type of outage that occurred on the Active Contact Center server. If this state transition occurs the client will quickly transition back to {@link ClientState#AUTHENTICATED} once the Standby Contact Center server has taken over the Active role. A {@link NotificationType#DELETE} notification will be sent to the application for the {@code SessionI} object associated with the previously Active Contact Center server. A {@link NotificationType#NEW} notification will be sent to the application for the new {@code SessionI} object associated with the newly Active Contact Center server (previously the Standby server).
Contact Center Business Continuity (BC) Campus
When connecting to a Contact Center Business Continuity campus pair, the application must provide the fully qualified
managed hostname of the Contact Center BC pair as the server argument to {@link ClientI#create}. The
{@link ClientI#isHa} and the {@link ClientI#isHaOperational} methods will return {@code false}.
If the Active Contact Center server has an outage, a switchover will occur and the Standby Contact Center server will take over the Active role. On switchover, a manual signin to the newly Active Contact Center server is not required by the application. The client will automatically signin to the newly Active Contact Center server (previous Standby server). A {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change will occur on an outage to the Active Contact Center server. The client will transition to {@link ClientState#AUTHENTICATED} once the Standby Contact Center server has taken over the Active role. A {@link NotificationType#DELETE} notification will be sent to the application for the {@code SessionI} object associated with the previously Active Contact Center server. A {@link NotificationType#NEW} notification will be sent to the application for the new {@code SessionI} object associated with the newly Active Contact Center server (previously the Standby server).
Contact Center Remote Geographic Node (RGN)
For both High Availability solutions, a Remote Geographic Node server can be provisioned. If a Campus outage occurs,
a {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change will occur. If it is identified
that the Campus has had a complete outage (entire Campus is down), a decision will be made to manually switchover to
the RGN. Once this decision has been made and the RGN has taken over, the application must now connect to the RGN.
The application must invoke {@link ClientI#disconnect} to notify the client to cease attempting to connect to the
Campus. On successful disconnect, the client will transition to {@link ClientState#DISCONNECTED}. The application
should then invoke {@link ClientI#setServer} providing the fully qualified hostname of the RGN. The application
should then execute {@link ClientI#signin} to connect and signin to the RGN.
Security
Secure communication between the application and the Contact Center server is mandatory and is implemented by the use of
Secure Web Sockets. A {@link SecurityContextI} object containing a keystore can be supplied by the application to
{@link ClientI#create}. Please see the CCS API overview and {@link ClientI#create} for further information on
security.
Modifier and Type | Method and Description |
---|---|
static ClientI |
create(java.lang.String server,
Profile profile,
java.lang.String applicationName,
SecurityContextI securityContext)
A static factory method which creates and returns a
ClientI object. |
void |
disconnect()
Requests that the
ClientI object be disconnected. |
boolean |
getAutoReconnect() |
java.lang.String |
getClientId()
returns the Client ID.
|
java.lang.String |
getConnectedServer()
Identifies the fully qualified hostname of the Contact Center server that the client is currently connected and
authenticated with.
|
java.lang.String |
getServer() |
SessionI |
getSession() |
ClientState |
getState()
The current state of the
ClientI object can be retrieved by this method. |
java.lang.String |
getVersion() |
boolean |
isConnected()
Provides an indication of whether or not the
ClientI is currently connected to the server. |
boolean |
isHa()
Specifies whether the server that this client is connected to is provisioned for Mission Critical High
Availability (MCHA).
|
boolean |
isHaOperational()
Identifies whether Mission Critical High Availability (MCHA) is fully connected and operational at this time.
|
boolean |
isSecure()
Specifies whether communication to the server is fully secure.
|
void |
setAutoReconnect(boolean autoReconnect)
Sets whether the
ClientI object should automatically attempt to reconnect to the server on a web socket
close. |
void |
setServer(java.lang.String server)
Allows the application to change the fully qualified hostname of the server that the client will connect at
signin time.
|
void |
signin(java.lang.String userId,
java.lang.String password,
SessionListenerI sessionListener,
ClientListenerI clientListener)
Request that the
ClientI object connect and authenticate with the Contact Center server to use the
Contact Control Service. |
void signin(java.lang.String userId, java.lang.String password, SessionListenerI sessionListener, ClientListenerI clientListener) throws InvalidArgumentException, InvalidStateException
ClientI
object connect and authenticate with the Contact Center server to use the
Contact Control Service.
The application must supply implementations of the listener interfaces ClientListenerI
and
SessionListenerI
as arguments to the signin method. The ClientListenerI
notifies the application
of client level events via the ClientListenerI.onClientEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.ClientI>)
method. The SessionListenerI
notifies the application of session level events via the SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)
method.
Signin is a two stage process within the SDK, the connection process and the authentication process . A web socket must first be established with the server (connection process) and then the user must be authenticated for use of the Contact Control Service (authentication process).
If the connection process is successful, a web socket will be established with the server. During the
connection process, two NotificationType.UPDATE
notifications will be sent to the application for the
ClientI
object indicating the transition to ClientState.CONNECTING
and then to
ClientState.CONNECTED
. At this point isConnected()
will return true
. These notifications
will be sent to the application via the ClientListenerI
argument supplied by the application.
If the authentication process is successful, a NotificationType.UPDATE
notification will be sent
to the application for the ClientI
object indicating the transition to ClientState.AUTHENTICATED
.
This notification will be sent to the application via the ClientListenerI
argument supplied by the
application. A SessionI
object will also be created representing the authenticated session with the
server. A NotificationType.NEW
notification will be sent to the application for the SessionI
object. This object will provide the application access to the Contact Control Service. This notification will be
sent to the application via the SessionListenerI
argument supplied by the application. The
getSession()
method will return the reference to the new SessionI
object.
Note that the connection and authentication occur sequentially and therefore the client could transition from
ClientState.CONNECTING
to ClientState.CONNECTED
to ClientState.AUTHENTICATED
very
quickly.
If the connection process fails;
getAutoReconnect()
returns true
, a NotificationType.UPDATE
notification will
be sent to the application for the ClientI
object indicating the transition to
ClientState.CONNECTING
. The isConnected()
method will return false
getAutoReconnect()
returns false
, a NotificationType.ERROR
notification will
be sent to the application for the ClientI
object indicating the transition to
ClientState.DISCONNECTED
. The isConnected()
method will return false
getAutoReconnect()
value, if a NotificationType.ERROR
notification is
sent to the application and ErrorI.getErrorCode()
returns ErrorCode.SecureCommunicationFailure
,
ErrorCode.UnresolvedHost
or ErrorCode.IllegalUri
, the client will not automatically reconnect.
These communication errors are deem not automatically recoverable and require a configuration change to resolve
If the authentication process fails;
SessionI
object was not created. A NotificationType.ERROR
notification will be sent to the
application via the SessionListenerI
argument supplied by the application, indicating the reason for the
failure. The SessionI
reference in this NotificationEventI
will be null
and
getSession()
will return null
NotificationType.ERROR
notification will be sent to the application via the ClientListenerI
argument supplied by the
application. The ClientI
object will transition to ClientState.DISCONNECTED
Possible errors for this method are listed below. If the meaning of the error code in the context of this method differs significantly from the generic description given for that error code, then a context-specific meaning is given.
Error Codes | Context Specific Meaning / Notes |
---|---|
ErrorCode.ApplicationNotEnabled |
|
ErrorCode.AuthenticationFailure |
|
ErrorCode.CommServerOutOfResources |
|
ErrorCode.InvalidCredentials |
|
ErrorCode.WorkspacesLicenseLimitExceeded |
Workspaces license limit exceeded. |
ErrorCode.WorkspacesLicenseNotGranted |
Workspaces license not granted. |
ErrorCode.InvalidParameter |
The supplied user ID is invalid (not in domain\\user format). |
ErrorCode.SecureCommunicationFailure |
Secure communication with the server has failed. One cause of this can be an SSL handshake failure which can occur if the correct CA certificate is not present in the supplied keystore. |
ErrorCode.UnresolvedHost |
The hostname that was supplied by the application to create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI) could not be resolved. |
ErrorCode.IllegalUri |
The hostname that was supplied by the application to create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI) contained characters that are
illegal URI characters and therefore the websocket to the server could not be opened. |
ErrorCode.ServiceUnreachable |
The service on the server is either unreachable, shut down, or could not obtain a license. |
ErrorCode.Unauthorized |
userId
- the user id as administered in the Contact Centerpassword
- the password to authenticate the usersessionListener
- listener object that will notify the application of session level eventsclientListener
- listener object that will notify the application of client level eventsInvalidArgumentException
- if the ClientListenerI
is null
, if the SessionListenerI
is null
, if
the user argument is null
or empty, if the password argument is null
or emptyInvalidStateException
- if the client is not in the correct state to signinvoid disconnect()
ClientI
object be disconnected.
If successful, the established web socket to the server is closed. If the client had an authenticated
SessionI
with the server, the session will be deleted. A NotificationType.DELETE
notification
will be sent to the application for the SessionI
object via the SessionListenerI
implementation
that is supplied as an argument to signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
. For further information on the session lifecycle,
please see SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)
.
A NotificationType.ERROR
notification will be sent to the application via the ClientListenerI
implementation that is supplied as an argument to signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
. This indicates that the client is no
longer connected to the server, getState()
will return ClientState.DISCONNECTED
and
isConnected()
will return false
. After disconnect, if required the ClientI
object
can be used again to sign in to the Contact Control Service by invoking signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
.
boolean isConnected()
ClientI
is currently connected to the server. Returning
true
does not necessarily mean that it is possible to perform actions on the server. The
getState()
property must be ClientState.AUTHENTICATED
for actions to be carried out on the
server.true
if the web socket to the server is established, false
if it is notjava.lang.String getServer()
void setServer(java.lang.String server)
server
- the fully qualified hostname for the client to use for the next signin to the serverjava.lang.String getVersion()
ClientState getState()
ClientI
object can be retrieved by this method. If the client transitions state,
a NotificationType.UPDATE
notification will be sent to the application containing the updated
ClientI
object. These notifications are sent to the ClientListenerI
implementation that is
supplied by the application as an argument to the signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)
method.ClientI
object.void setAutoReconnect(boolean autoReconnect)
ClientI
object should automatically attempt to reconnect to the server on a web socket
close.
The default value for this is true
. The client will not auto reconnect if the web socket was closed due
to invocation of disconnect()
. If High Availability is provisioned, the client will automatically
reconnect regardless of this setting.
autoReconnect
- true
if the connection should be automatically reconnected on loss of connection,
false
if the connection should not be automatically reconnectedboolean getAutoReconnect()
true
if the ClientI
will automatically reconnect, false
if the Clienti
will not automatically reconnectboolean isHa()
This property is only accurate once the client has been connected to the server. This is identified by a
transition of the ClientI
object to ClientState.AUTHENTICATED
.
true
if the currently or previously connected server is provisioned for MCHA, false
otherwiseboolean isSecure()
true
if the clients communication with the server is fully secure (with certificate validation),
false
if it is not (trust all)java.lang.String getClientId()
boolean isHaOperational()
Mission Critical High Availability is deemed operational when the ClientI
object is connected to and has
an authenticated session with both the Active and the Standby Contact Center servers.
true
if the client deems MCHA operational, false
if the client does not or if
isHa()
returns false
(not provisioned)java.lang.String getConnectedServer()
For High Availability campus configurations, this will be the fully qualified hostname of the Contact Center
server that is currently Active. This will most likely be different from the server property returned by
getServer()
. The getServer()
API will return the server argument that was supplied to
either the create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)
or to the setServer(java.lang.String)
API's and for HA campus solutions this
should always be the fully qualified managed name of the Contact Center HA pair.
null
if the client is currently not connected to any Active Contact Centerstatic ClientI create(java.lang.String server, Profile profile, java.lang.String applicationName, SecurityContextI securityContext)
ClientI
object.
For communication with a standalone Contact Center server, the fully qualified hostname of the Contact Center server should be provided as the server argument. For communication with a High Availability campus pair (Business Continuity or Mission Critical), the fully qualified managed hostname of the Contact Centers should be provided as the server argument.
The profile argument is mandatory. For client applications controlling a single UserI
object through a
single ClientI
object, the application should create the ClientI
object with
Profile.AgentDesktop
. For server applications controlling multiple UserI
objects through a
ClientI
object (multiple Users per Client), the application should create the ClientI
object with
Profile.Server
. If the server application is controlling multiple UserI
objects through multiple
ClientI
objects (one User per Client), the application should create the ClientI
with
Profile.AgentDesktop
. See the CCS API Overview for further information.
The application name argument is mandatory and should be populated with a string that clearly identifies the application that has been developed against the API. This is logged on the Contact Center server and is used in debugging issues. If multiple applications or different version of the same application are developed against the CCS API then each should have a different name.
An optional SecurityContextI
object can be provided by the application as an argument. The
SecurityContextI
object can be created using the static factory method SecurityContextI.create(java.security.KeyStore)
.
The ssl context for the web socket will be created based on the keystore that is supplied in the
SecurityContextI
object. The signed certificate that is received from the server will be validated
against the CA certificate in the keystore. This will validate the identity of the server. It is therefore
imperative that the keystore contain the CA certificate from the Certificate Authority that signed the servers
certificate.
If a SecurityContextI
object is not provided by the application, the web socket implementation will trust
all received server certificates. The communication between the application (Web Socket client) and Contact Center
server (Web Socket server) will still be over secure web sockets and the data sent will be encrypted however the
identity of the server will not be validated.
It is highly recommended that a SecurityContextI
object is provided containing a valid keystore to ensure
that the communication with the server is fully secure.
server
- fully qualified hostname of the server that the ClientI
is to connect to (mandatory argument)profile
- the type of application that is creating this client (mandatory argument)applicationName
- the name of the application that has been developed against the API (mandatory argument)securityContext
- an optional SecurityContextI
object containing the keystore to use for secure communications
or null
if no security context is to be specifiedClientI
object instance