Open Interfaces CCT SDK_img_0

CCT Open Interfaces SDK

Reference

1.       Communication Control Toolkit Open Interfaces Object Model 2

2.       The SSO object. 3

3.       The Address object. 3

4.       The Terminal object. 5

5.       The Contact object. 6

6.       The Connection object. 8

7.       The TerminalConnection object. 9

8.       Object specialisations. 11

Agent Terminals. 11

Route Point Addresses. 11

9.       State transition diagrams. 12

10.        FAQs. 15

11.        Call Attached Data Limitations. 15

12.        Intrinsics Limitations. 15

13.        Security. 16

User Validation & Authentication. 16

Encryption. 16

14.        Open Interfaces SDK Reference. 17

15.        Tutorial 18

Open Interfaces Reference Client Eclipse Project 18

 

 

 

1.            SOA Open Interfaces Object Model

This section will provide an overview of the main object types used when programming with the SOA Open Interface SDK, namely:

         SSO object

         Address object

         Terminal object

         Contact object

         Connection object

         TerminalConnection object

Note: The SOA Open Interface web services are hosted on the Communication Control Toolkit server. The objects described here are from the Communication Control Toolkit Full API.

 

 

2.            The SSO object

The SSO object represents a client connection to the Open Interfaces and is the starting point for gaining access to Open Interfaces SDK functionality.

The client application:

1.      Creates an authenticationLevel object

2.      Sets properties to indicate the address of the server and which user credentials to use when connecting

3.      Calls the logInToCCTServer on the SessionService (or UserService) to establish a connection to the Open Interfaces server

A SSO object is the result of a successful connection to the server.

The SSO object is required for all subsequent calls to the Open Interfaces. The SSO is used to verify that the user has been authenticated and to associate the user with their current session.

If there is no activity related to this SSO token for 2 hours (see configuration) the session will timeout and subsequent calls using this session will fail. If the user has registered for events then a SessionTermination imminent event will notify that the session is about to expire and must be refreshed. If the Open Interfaces service is interrupted (planned or unplanned) the session will be invalidated and an exception will be thrown the next time this session is used.

For more information, see Address, Session service

 

 

3.            The Address object

The Address object represents a logical communications endpoint. Examples of addresses are a telephone number, an e-mail address, and a SIP URL. Address objects are remote objects that reside on the Communication Control Toolkit server that can be accessed by the Address. Other specializations of an address may exist and can be accessed through their respective services (i.e. RoutePointAddress)

As described above, each client is granted access to a set of addresses that is directly controlled by the Communication Control Toolkit server. In addition, as contacts are created within the Communication Control Toolkit server, the client application may gain visibility to additional addresses that are associated with these contact objects; however, unless the address has been specifically assigned to the client, the client will not be able to exercise any control over the address (the IsControlled property can be queried to determine this).

An Address object provides the following types of interfaces that are used by the client application to manipulate the object, and thereby control the underlying communications infrastructure:

         Object properties that are queried and/or set by the application (for example, the "do not disturb" status of the address)

         Methods that are invoked by the client to perform some function (for example, originate a call from this address)

         Events for which the application can register handlers to be notified of changes related to the address or other objects related to it (for example, a change in value of one of the address properties, or a change in state of one of the connections to this address)

Like many of the object interfaces defined by the Open Interfaces, the Address object contains a special GetCapabilities method. This method returns an object that is used to determine what properties and/or methods the object currently supports. For example, in the case of an Address, the Capabilities object is defined by the Address Capabilities complex type.

The Capabilities object contains a set of Boolean flags that map to specific properties and/or methods found on the parent object. These flags indicate whether the corresponding property or method is used by the application. Some of the flags defined by the Capabilities object are static in nature (for example, the address never supports Do Not Disturb functionality), or they are dynamically updated by the Communication Control Toolkit server in response to changes in the state of the object. The Capabilities object is used by the application to adjust the user interface to match the set of capabilities provided by the Address object.

The Address object defines a rich set of events so that the client application can listen for changes in the Communication Control Toolkit server that are related to the address. The following events are available on the Address object:

         Address property changed event — indicates a change in one of the properties of the address object.

         Connection state changed and remote connection state changed events — Separate events are provided for local and remote connections. Local connections are those connections that are directly related to the address, whereas remote connections are those that are related to the address through an existing contact and thereby represent the remote leg of a call. More discussion regarding connection objects will follow in a later section.

         Connection property changed event — this event signals a change in a property of one of the local connections currently associated with the address.

         Contact property changed event — this event signals a change in a property of a contact object associated with the address.

Based on the client application, not all of the events need to have event handlers registered against them; however, Avaya recommends that you register a connection state changed event handler. Avaya also recommends that you register an address state changed event handler on the session service. This enables addresses to be taken out of service or entirely removed from the configuration.

For more information, see Address, Session

 

 

4.            The Terminal object

A Terminal object represents a physical communications endpoint (including software applications). Some examples of terminals are:

         Telephone set

         SIP softphone

         E-mail client

         IVR line.

Like Address objects, Terminal objects are remote objects that reside on the Communication Control Toolkit server. The objects can be accessed through the Terminal. This base TerminalService defines a terminal that models a common business set (also known as a Knowledge Worker set).

The capabilities supported by a particular terminal are obtained through the Terminal Capabilities complex type, returned by calling the terminal service GetCapabilities method.

The Communication Control Toolkit Open Interface also defines a specialization of the Terminal object used to model a contact center agent set. The AgentTerminal derives from the base Terminal service to provide the expanded functionality of the contact center agent set. Since the AgentTerminal expands the set of properties and methods available to the client, the Capabilities property for an agent terminal returns an AgentTerminal Capabilites complex type, rather than the Termina Capabilites complex type that is returned for a normal terminal.

Regardless of the particular type of terminal being modeled, all terminals require an address to be associated with them to be useful. The Terminal object provides a RelatedAddresses property that returns the set of addresses defined to be related to the terminal. This information is used by the client application to provide an intelligent interface. This intelligent interface allows you to select the primary terminal and address combination used to initiate outbound contacts.

Like the Address object, the Terminal object also defines a set of events on which the client application registers event handlers, although the set is somewhat smaller. The following events are available on the Terminal object:

         Terminal property changed event — indicates a change in one of the properties of the Terminal object.

         Terminal connection state changed event — indicates a change in the state of one of the terminal connections associated with the terminal. To find out more about Terminal Connection objects, see TerminalConnectionState.

Traditional voice Terminal objects (i.e. those that represent a physical phone set) are statically configured on the Communication Control Toolkit server and are assigned to the CCT user via the administration console. Other Terminal objects that represent multimedia terminals or SIP-based telephony clients are dynamically created when a Contact Center agent logs in (refer to the Agent service for more information). Thus, in this environment it is required that a Open Interfaces client application register for Terminal state change event in order to become aware of these dynamically created Terminal objects. Similarly, the Address objects assigned to these Terminals are also dynamically created and require an event handler installed on the Session.AddressStateChanged event.

Note: Because of their dependence on the Avaya Contact Center functionality, these multimedia Terminal objects will never be available in a Knowledge Worker (non Contact Center) environment.

For more information, see Terminal

 

 

5.            The Contact object

A Contact object models a communications session. Some examples of contacts are:

         A telephone call

         An instant message session

         A video call

 

Client applications become aware of the existence of a contact through various methods:

         A notification received by a registered endpoint on the "contact entering scope" event of the application’s Session object

         A notification received by a registered endpoint on the "connection state changed" event of one of the application’s Address objects

         A notification received by a registered endpoint on the "terminal connection state changed" event of one of the application’s Terminal objects

         The return value of a method called on one of the remote objects associated with the session (for example, the Originate method on an Address object)

A Contact object is a remote object residing on the server, which is accessible through the Contact. The Contact object implements a GetCapabilities method, which returns a Contact Capabilites complex type. The Capabilities complex type allows the client application to determine what functions the Contact object supports.

Unlike the Address and Terminal objects, Contact objects do not directly provide any events to the client. Instead, changes to the properties of a Contact object are received by the application through a "contact property changed" event handler registered on one of the client’s Address objects. This approach allows the client to install the event handler prior to actually receiving the contact, thereby eliminating the possibility of missing contact-related events in the time period between when the client first learns of the existence of the contact and when it has an event handler registered on it.

The most notable property of the Contact object is the ability to associate arbitrary data with the contact. This data can be accessed through the Data property on the Contactas an array of key/value pairs. or optionally as Strings or Binary data,, and it remains associated with the contact for the life of the contact. The contact data can be accessed and/or modified by any client that has access to the contact. If a contact is transferred from one address to another, the contact-related data moves with the contact. Client applications can use this contact data to record such things as caller account information with the contact so that when it is moved from department to department, the caller does not need to repeat or reenter it.

For more information, see Contact.

 

 

6.            The Connection object

A connection represents an association between a contact and an address. Typically, a contact has two or more connections. For example, in a phone call between two parties A and B (where A and B are addresses), there is

         Address object A

         Address object B

         Contact object C, representing the call

         Connection object CA, representing the relationship between address A and contact C

         Connection object CB, representing the relationship between address B and contact C

The following diagram shows the Connection object relationships:

section6

The Connection object is a remote object residing on the Communication Control Toolkit server that can be accessed through the Connection. The Connection object, coupled with the TerminalConnection, provides the majority of the state information and control capabilities found in the Communication Control Toolkit Open Interfaces.

The client application learns about new connections through the event handlers that the client has registered on the connection state changed events of the session’s Address objects. If the client receives a state change event for a connection it has never seen before, it can assume that the connection represents a new contact on the associated Address object. No one connection state can be expected to signal a new connection on an address. The client application can also query the address object directly for an array of current connections on that address. This is useful following connection to the Communication Control Toolkit server for determining the current state of affairs for the addresses assigned to the client’s session.

As events occur in the Communication Control Toolkit server affecting the state of the connection, state change events are relayed to the client. The client, upon receiving these events, can perform whatever processing is necessary, such as updating a display, enabling buttons, and so on. One important state change that the client must watch for is a transition to the Disconnected state. This state transition signals the client that the associated connection object is no longer valid and all references to it should be discarded. If the client application is monitoring remote connection objects associated with its addresses, it is important to note that the client is not guaranteed to receive a Disconnected event for any remote connections, since local connections from the contact to the address may be torn down before the remote connection. In this case, the removal of the local connection should cause the client to discard any references to associated remote Connection objects.

The capabilities associated with the Connection object, defined by the Connection Capabilities complex type, are highly state dependent. Capabilities that are enabled while the connection is in one state may become disabled in another state, and vice versa. Due to this state dependence, the client application should use the connection capabilities object provided with each state change event to determine what capabilities are currently enabled.

For more information, see Connection.

 

 

7.            The TerminalConnection object

A terminal connection represents the relationship between a terminal and a connection. For example, A calls B. B has a desk phone (Bd) and a mobile phone (Bm) (both of which are configured with B’s address). B answers the call on his desk phone (Bd). The relationship between the terminal (Bd) and the connection is represented by a terminal connection.

The following diagram expands the diagram shown in the previous section to include the following terminal connection-related objects:

         Terminal object T1

         Terminal object T2

         TerminalConnection object TCCA-T1, representing the relationship between Connection object CA and Terminal object T1

         TerminalConnection object TCCB-T2, representing the relationship between Connection object CB and Terminal object T2

The following diagram depicts the TerminalConnection object relationships:

section7

The TerminalConnection object is modeled in the Communication Control Toolit Open Interface as a remote object that implements the TerminalConnection interface. Like most Communication Control Toolkit objects, it has a GetCapabilities method that returns an object that implements the most Communication Control Toolkit objects; it has a GetCapabilities method that returns an object that implements the most Communication Control Toolkit objects.

Unlike connections, terminal connections for remote legs of a contact are not visible to the client session. Thus, a client session having access to address A and terminal T1 has a view of the Communication Control Toolkit objects that is a subset of those shown in the above diagram.

Remote terminal connections are not modeled in the Communication Control Toolkit. This is because real-world systems typically do not have visibility all the way back to the physical set used for the far end of the call. In the case where a client session is granted access to both terminals and addresses involved in a contact, the session is able to see both ends of the call, but it has this visibility due to its access to both terminals involved in the call only.

State change event handling for TerminalConnection objects is very similar to that for Connection objects with the exception that there are no event notifications for remote terminal connections. To receive terminal connection state changed events, the client application must register an event handler on the terminal’s terminal connection state changed event. Changes in the state of a terminal connection usually cause a change in the enabled capabilities for the terminal connection. For this reason, the client application should use the terminal connection capabilities provided with each state transition event to update itself with the current set of capabilities for the terminal connection. A transition to the Dropped state is the signal to the client application to discard all references to the terminal connection.

For more information, see TerminalConnection.

 

 

8.            Object Specialisations

The Communication Control Toolkit SDK interfaces object generally model the most common or basic form of the object. There are some specializations of the base interfaces defined in the Communication Control Toolkit SDK API for terminals and addresses that extend or modify the base functionality.

 

Agent Terminals

The base Terminal service models a standard physical terminal. An extension of this service is defined specifically for modeling a terminal used by an agent in a contact center.

The AgentTerminal extends the Terminal service to provide the additional functionality available on a contact center agent terminal.

In support of the AgentTerminal, additional service extensions include

         AgentTerminalCapabilities — Extends TerminalCapabilities to include additional capabilities properties to cover the additional functionality found in the AgentTerminal.

         AgentTerminalConnection — Extends TerminalConnection to model the association between a Connection object and an agent terminal. The AgentTerminalConnection interface provides additional functionality for controlling terminal connections to an agent terminal.

 

Route Point Addresses

A route point address is a special address type used in contact center environments for routing incoming contacts. Route point addresses do not have any terminal relationships and cannot directly originate outbound contacts. Contacts received at a route point address are given various treatments (for example, ringing, silence, music) while the contact center locates an available agent to handle the contact, at which point the contact can be routed to the agent.

The Communication Control Toolkit Open Interfaces defines an extension of the Address service, named RoutePointAddress, for modeling a route point address.

In support of the RoutePointAddress service, additional interface extensions include:

         RoutePointConnection — Extends Connection to model the association between a Contact object and a route point address. The RoutePointConnection service provides additional functionality for controlling connections to a route point address.

To determine what type of object it is dealing with, a client application uses standard run-time type checking of the received object.

 

 

9.            State Transition Diagrams

Connection and TerminalConnection objects change state based on state computer logic in the Communication Control Toolkit server. This section provides the state transition diagrams to illustrate the legal state transitions for connections and terminal connections.

See the Communication Control Toolkit Full API Reference section for detailed descriptions of the various states.

The following diagram depicts the Connection state transitions:

The following diagram depicts the Terminal Connection state transitions:

Refer to the ConnectionState enumeration in the table below for descriptions of the various Connection states:

ALTERING

ANCHORED

CONTROLLED

DIALING

DISCONNECTED

ESTABLISHED

FAILED

IDLE

INITIATED

NETWORK_ALERTING

NETWORK_REACHED

OFFERED

PARKED

RETRIEVING

ROUTING

QUEUED

UNKNOWN

 

Refer to the TerminalConnectionState enumeration in the table below for descriptions of the various TerminalConnection states.

IDLE

RINGING

ACTIVE

HELD

AUTOHELD

INUSE

BRIDGED

DROPPED

UNKNOWN

 

10.    FAQs

For a complete and up to date list of Frequently Asked Questions please visit the developer partner site.

 

 

11.    Call Attached Data Limitations

There is maximum limit of 45k5 of data to be attached to a contact, please refer to the CCT documentation for further information.

5 This value can vary from Service Provider Implementation i.e. CS1K, CS2k and SIP OCS, please refer to manual for specific limit.

 

 

12.    Intrinsics Limitations

It is not recommended that intrinsics should be used to store large quantities of data as it may impact overall performance in the Contact Centre.

If these intrinsics are to be accessed using the scripting engine contained in Contact Centre then there are additional limitations to the size and amount of intrinsics that can be associated with a contact, please refer to the scripting documentation for further details.

 

 

13.    Security

There are two levels of security for the CCT Open Interfaces. Firstly the web services authenticate whether the user is know and configured and secondly all communication between client and server can be optionally encrypted.

 

User Validation & Authentication

Before the service can be used the developer must first receive a Single Sign On (SSO) token that will be used for all subsequent calls to the service. To receive this token the developer must supply the server details (IP address/CCT server name and port) & the required authentication details;

         Username – Upon registration with the Developer Partner Program (DPP) a developer will receive a user name to allow access to the service.

         Password – a password associated with the supplied username.

         Domain – the domain on which the web service is hosted.

When the user submits their username and password to the service it is validated to determine if it is a valid windows user. Depending on the initial configuration of the service this user can be a local windows user on the CCT Server or a windows user on the domain.

Once the service has verified that the user is a valid windows user it then checks to see if the user is configured in the CCT console. Once both of these criteria are met the user receives an SSO token representing their current session.

Each session has a time out associated with it. The default for a Session timeout is 2 hours but can be configured using the OI configuration screen. Each time the service is accessed this timeout is reset.

For further information on how to configure the user store and CCT users please consult the section Avaya Contact Center Commissioning.

 

Encryption

The client communicates with the server through the use of SOAP messages. These SOAP messages are essentially XML data made up of header and a body. The Open Interfaces CCT can be configured to encrypt these SOAP messages at the transport layer using TLS configuration.

To configure TLS an administrator will need to generate a certificate signing request (CSR). The administrator will need to present this CSR to their chosen Certificate Authority (CA) to receive a corresponding certificate.

For further information on how to configure TLS please consult the document Avaya Contact Center Commissioning.

 

 

14.    Open Interfaces SDK Reference

The following contains a link to the Java Docs associated with the implementation of the web service. Note Port Number is the default port number used , but is configurable.

These services can also be accessed using through the splash screen located at;

http://<CCT HostName> :9090

Service Name

Location

JavaDoc Location

SOAOICCT_AddressService

http:// <CCT HostName>:9080/SOAOICCT/services/AddressService?wsdl

Javadocs

SOAOICCT_AgentService

http:// <CCT HostName>:9080/SOAOICCT/services/AgentService?wsdl

Javadocs

SOAOICCT_AgentTerminalConnectionService

http:// <CCT HostName>:9080/SOAOICCT/services/AgentTerminalConnectionService?wsdl

Javadocs

SOAOICCT_AgentTerminalService

http:// <CCT HostName>:9080/SOAOICCT/services/AgentTerminalService?wsdl

Javadocs

SOAOICCT_ConnectionService

http:// <CCT HostName>:9080/SOAOICCT/services/ConnectionService?wsdl

Javadocs

SOAOICCT_ ContactManagerService

http:// <CCT HostName>:9080/SOAOICCT/services/ ContactManagerService?wsdl

Javadocs

SOAOICCT_ContactService

http:// <CCT HostName>:9080/SOAOICCT/services/ContactService?wsdl

Javadocs

SOAOICCT_MetricsService

http:// <CCT HostName>:9080/SOAOICCT/services/MetricsService?wsdl

Javadocs

SOAOICCT_RoutePointAddressService

http:// <CCT HostName>:9080/SOAOICCT/services/RoutePointAddressService?wsdl

Javadocs

SOAOICCT_RoutePointConnectionService

http:// <CCT HostName>:9080/SOAOICCT/services/RoutePointConnectionService?wsdl

Javadocs

SOAOICCT_SessionService

http:// <CCT HostName>:9080/SOAOICCT/services/SessionService?wsdl

Javadocs

SOAOICCT_TerminalConnectionService

http:// <CCT HostName>:9080/SOAOICCT/services/TerminalConnectionService?wsdl

Javadocs

SOAOICCT_TerminalService

http:// <CCT HostName>:9080/SOAOICCT/services/TerminalService?wsdl

Javadocs

SOAOICCT_UserService

http:// <CCT HostName>:9080/SOAOICCT/services/UserService?wsdl

Javadocs

SOAOICCT_NotificationProducer

http:// <CCT HostName>:9080/SOAOICCT/services/NotificationProducer?wsdl

SOAOICCT_NotificationConsumer

http:// <CCT HostName>:9090/NotificationConsumerInterface.wsdl

 

 

 

15.    Tutorial

Open Interfaces Reference Client Eclipse Project

This SDK contains a reference implementation of the Open Interfaces Reference Client. This reference implementation shows how the CCT Open Interfaces can be called from a java client.

This project contains the class SOARefClient.java that is used to launch the Reference Client. This client is similar to the reference client available in the CCT .Net SDK and hence should be familiar to existing CCT users.

To launch this project select the class SOARefClient.java select Run As\Java Application and enter the following program arguments;

-Djava.util.logging.config.file=config.soa.client/logging.properties

-Djavax.net.ssl.trustStorePassword=123123

-Djavax.net.ssl.trustStore=./config.soa.client/trustedCA.keystore

-Dcxf.config.file=SecureClient.cxf

The project can be obtained from the following directory:

Tutorial

Location

OI Reference Client

OI_RefClient