Open Interfaces CCT SDK_img_0

CCT Open Interfaces SDK

Quick Start

1.            What is the Avaya Open Interfaces Communication Control ToolKit (CCT) SDK?. 2

2.            What is in the Open Interfaces?. 4

Advantages of SOA. 4

SDK contents. 5

Reference Client 5

SDK support 6

Related Documents. 6

Contacting Support 6

3.            What are the different Services?. 7

Which API to use?. 7

Full API features. 7

Lite API features. 9

4.            Programming with the CCT Open Interfaces. 10

Prerequisites. 10

Basic Outline of an Application. 11

CCT Login. 11

Method Call 12

Asynchronous Events. 12

Notification Producer. 12

Notification Consumer. 13

SOA CCT WebServices and HA. 13

High Availability configured AACC. 13

SOA CCT WebServices and Session Event Handling. 13

5.            FAQ.. 14

Frequently Asked Questions. 14

6.            Constraints on Agent Count and Contact Rate per Hour. 14

Constraints on Agent Count and Contact Rate per Hour. 14

7.            Tutorials. 15

SOA CXF Tutorial 15

SOA CCT Web Services Subscriptions. 15

SOA Registering For Specific Agent Events. 16

SOA Create a Contact, Hold, UnHold and Answer. 16

SOA Detect Incoming Calls and Retrieve calledAddress and callingAddress from the Contact Service  16

SOA Register for Session Termination Events. 17

 

 

 

1.            What is the Avaya Open Interfaces Communication Control ToolKit (CCT) SDK?

A series of SOAP (I) based Open Interfaces are provided to 3rd parties to enable communication of their applications based on the SOA (II) architecture. These web services are SOAP based allowing applications and customers to discover the functionality offered by each web service (III) using the WSDL (IV) provided. Customers are able to use these services to create agent tools or combine these services with additional 3rd party services (Google, Amazon, Microsoft...) to create the next generation of Web 2.0 applications.

 

These web services are hosted on the CCT server and require that the CCT SOA settings be configured and enabled on the CCT server.

 

These web services can be optionally configured to use TLS. If this functionality is enabled the customer is required to provide the necessary certificates. Please refer to the Avaya Aura™ Contact Center Commissioning see Related Documents for details on how to configure Open Interfaces on the CCT server.

 

When SOA is configured and enabled on CCT a list of services can be obtained through the splash screen at the following location, where the <CCT HostName> is the host name of the CCT server and 9090 is the port used by the splash screen.

 

http:// <CCT HostName>:9090

 

Each service is defined by a WSDL. This WSDL (Web Service Definition Language) is a machine readable description of the functionality being offered by this web service. Various technologies use this WSDL to interrogate the web service and create the relevant proxies to send and receive SOAP messages with the web service.

 

In general the associated WSDLs for all services can be obtained at the following location where the <Service Name> represents the name of the requested services i.e. SessionService and the <OI Configured Port> represents the SOA OI web services open port number. The <OI Configured Port> is configurable using the AACC Communication Control Toolkit - CCT Console. The default is port 9080.

 

http:// <CCT HostName>:<OI Configured Port>/SOAOICCT/services/<Service Name>?wsdl

 

        I.            SOAP is an industry-accepted W3C specification used to describe messages (XML documents and their attachments) so that they can be sent across a network.

      II.            A SOA is a collection of services. A service is a function that is well-defined, self-contained, and does not depend on the context or state of other services. These services communicate with each other.

    III.            A web service is an application that accepts XML-formatted requests from other systems across a network (Internet or intranet) using lightweight, vendor-neutral communications protocols.

    IV.            WSDL is the Web Services Description Language. WSDL provides a grammar for describing services as a set of endpoints that exchange messages. A WSDL document serves as a language and platform-agnostic (XML) description of one or more services. It describes the services, how to access them, and what type of response (if any) to expect. A WSDL document can be either privately exchanged or posted to a UDDI registry (either public or private) to allow broader access.

 

 

2.            What is in the Open Interfaces?

The Open Interfaces are installed on your Avaya Communication Control Toolkit server but require the associated Open Interfaces license before they can be enabled, see Avaya_Contact_Center_Commissioning in Related Documents for configuring services.

 

These services supplement your existing tools to simplify communication control development.

 

This documentation is for the CCT Open Interfaces which are related to the following version of the Avaya Aura Contact Center ©.

 

Version

Avaya Aura Contact Center © 7.0.2

 

The specific version of each service can be found by going to the splash and then locating the service. The version is detailed in the header of each table Service Method List.

 

For example, if you want to find:

·          The version of the Address Service

·          The list of methods associated with the Address Service

Both can be found here. Please refer to the Developer Program web site for the latest version of all documentation.

 

http://<SERVER_IP_ADDRESS>:< OI Configured Port>/Services.jsp?servicename=AddressService

 

 

Advantages of SOA

SOA is an architectural style whose goal is to achieve a loose coupling among interacting software agents.

 

This means that applications existing on different Operating Systems written in different programming languages can communicate and exchange data with each other.

 

The Open Interfaces provides a number of basic features that make it easier to deploy a variety of applications. These features include:

Zero Deployment – SOA has a loose coupling of services with operating systems, programming languages and other technologies and hence does not place additional requirements on the client to download Avaya libraries

Technology Agnostic – SOA is not associated with a specific OS, programming language or technology and hence leaves the clients free to develop in their language(s) of choice.

Common Integration Point – SOA is becoming a common integration technology between different technologies and applications.

 

 

SDK contents

The SDK contains the following elements:

Application programming interface documentation

Installed reference client

Source code for reference client implementations

Tutorial for creating a client using flex technology

 

Reference Client

The CCT Open Interfaces contains a reference client that can be used to test the web services. This reference client is similar in design to the .Net CCT reference client and allows users to exercise the majority of the call control functionality available through the web services.

 

The reference client can be found at:

·          OI_RefClient

 

This reference client can be launched using the RefClient.bat. Once launched, the reference client can be configured to point to the CCT server, by accessing the Preferences file menu and entering the CCT server name the configured port name and whether this service has been configured to use TLS.

 

Once the OI reference client has been configured to point to the CCT server hosting the Open Interfaces the user will need to log in using the correct CCT login in credentials

 

Parameter

Description

Username

A windows user that has been imported into CCT

Password

Password associated with the windows user

Domain

The name of the server or domain on which the user has been registered.

 

A more detailed description and tutorial of how to use and configure the OI Ref Client can be found at

·          OI Ref Client

 

 

SDK support

Support for the SDK APIs is supplied by the Developer Partner Program. For more information about contacting support personnel, see Contacting support.

 

 

Related Documents

The following table lists documents that contain more information about the Open Interfaces and Communication Control Toolkit:

 

 

 

Contacting Support

If you are a DevConnect member, contact the Avaya Dev Connect personnel through the following e-mail address:

devconnect@avaya.com

 

For details about becoming a DevConnect Member, see

http://www.avaya.com/gcm/master-usa/en-us/corporate/alliances/devconnect/index.htm

 

 

3.            What are the different Services?

There are two types of APIs included in the Communication Control Toolkit OI SDK:

High functionality client application using the Full API

Simple client application using the Lite API

 

Each of the above APIs has its own client reference implementation. These API client reference implementations include source code, enabling you to write your own CCT Clients.

 

Which API to use?

The following is a summary of the different features included in each API. Essentially the API can be broken into two groupings, the full API which exposes all the functionality of the full call model and the lite API which offers a simpler call mode. Both these API’s reduce the complexity over traditional APIs

 

Both these API’s closely match the features offered by the existing .Net CCT SDK and should be familiar to users who have experience using this SDK.

 

Full API features

The full API offers a complete feature set that exposes the full call model to the client. This type of functionality is often required when creating a complex client of complex CCT server base application.

Main points of the API are;

complete feature set

suitable for both complex client or complex CCT server based solutions

 

The following is a list of services that comprise of the Full API:

 

Service Name

Description

Address

This service models an Address in the system It provides methods to read and set the attributes of the address.

Agent

This service models an Agent in the system It provides agent related functionality such as login/logout as well as methods for querying or manipulating data related to a given agent.

 

AgentTerminal

This service provides access to agent terminal connection related functionality.

 

AgentTerminalConnection

This service models an agent terminal in the system It provides methods to read and set the attributes of the terminal.

 

Connection

This service models a Connection in the system It provides methods to read and set the attributes of the connection.

 

Contact

This service models a Contact in the System and as such provides functionality for querying and manipulating a given contact.

Metrics

This service provides access to system metrics such as terminals, addresses, active sessions etc.

 

RoutePointAddress

This service provides functionality to query control status of RoutePointAddresses as well as take and release control etc.

 

RoutePointConnection

This service provides functionality associated with RoutePointConnections such as querying capabilities, routing and applying media treatment etc.

 

TerminalConnection

This service is used to provide functionality associated with TerminalConnections such as answer/hold, conferencing, transferring, retrieving associated contacts and connections etc.

 

Terminal

This service provides functionality associated with Terminals such as querying and setting associated states, retrieving associated Address and TerminalConnection objects etc.

This service models a User in the system It provides methods to read attributes of the user such as Address(s), Terminal(s) etc.

 

User

This service models a User in the system It provides methods to read attributes of the user such as Address(s), Terminal(s) etc.

 

NotificationProducer

This service offers clients the ability to subscribe for contact center notifications.

 

NotificationConsumer

A Notification Consumer represents the endpoint to which the Notification Producer sends events.

 

 

 

Lite API features

The Lite API offered by the Session Service offers a subset of functionality from the Full API that is typically used in rapid client or simple server based solutions. The SessionService abstracts the client from the full call model allowing them to work with the more familiar concept of Agent’s, Addresses and Terminal without requiring an in-depth knowledge of Connections and Terminals Connections

 

Main points of the API are;

• Rapid client or simple server based solutions

• Easy to use, ideal for form or non-form based integrations

• Reduced feature set of Full API

 

The following is a list of services that comprise of the Lite API:

 

Service Name

Description

Session

This is a summary service and represents a subset of all the other services exposed and as such can be used in place of them in many cases. SessionService exposes a higher level API thus making it easier to use.

 

NotificationProducer

This service offers clients the ability to subscribe for contact center notifications.

 

NotificationConsumer

A Notification Consumer represents the endpoint to which the Notification Producer sends events.

 

4.            Programming with the CCT Open Interfaces

There are many different applications and technologies that can be used to create applications that use the CCT Open Interfaces. Although the actual implementation may differ from technology to technology the basic steps followed would be similar.

 

Clients can communicate with the Web Services directly through SOAP messaging or through a proxy layer. As each technology has a different approach to interfacing to the web services it is left to specific tutorials located in the SDK or online to detail how to import the services into a client application.

 

Prerequisites

The following assumptions are made.

1.         That the CCT and the CCT Open Interfaces are configured an running. Please refer to the Avaya Contact Center Commissioning guide on how to configure the web services.

2.         That the developers are both familiar with their choice of technology and how that technology integrates with web services.

 

 

Basic Outline of an Application

Before a 3rd Party Application is able to access the call control functionality of the Open interfaces, it will typically follow these steps;

 

Import the web services into their development environment or applications. This involves a proxy layer being generated from which application method calls are converted to SOAP request. Alternatively an application may create the SOAP messages directly.

 

The application will need to login into CCT to receive a valid Single Sign On (SSO) Token.

 

Once the application has obtained a valid SSO token it will use it in all subsequent calls to the Open Interfaces. This SSO token is used to validate an applications session.

 

The application can then register an endpoint to receive asynchronous messaging from the CCT Open Interfaces for this session.

 

 

CCT Login

Before the service can be used the developer must first receive a Single Sign On (SSO) token that is used for all subsequent calls to the service. To receive this token the developer must supply the required authentication details;

 

Username – The user will need to have imported either a windows or domain user into the CCT system

Password – a password associated with the supplied windows username.

Domain – the domain of the windows user that was imported. (or server name if user is created locally on CCT server)

 

When the user logs in successfully they receive an sso token that associates a session with the user. This session is used to validate subsequent method calls with a specific session and associate any registered notifications with a specific 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 CCT OI configuration screen. Each time the service is accessed this timeout is reset. Best practice is that OI clients use a short session timeout (5-10 minutes) and an accompanying heartbeat keep-alive mechanism. OI is based on Service Oriented Architecture, so it’s each OI Client’s responsibility to ensure that sessions are initiated and terminated correctly.  For further information please refer to the Session Handling chapter. 

Method Call

Third party applications wishing to access the call control functionality of the CCT Open Interfaces will issue SOAP messages directly or through a proxy layer to the services.

 

Asynchronous Events

Historically with web-services in a client server environment where a client wants to be kept up to date with status on the server, this was realized through polling. i.e. the client would periodically poll the server for its current status. For example, if a soft phone application wants to know when there was a change in state of the phone conversation, the following steps would occur for a polling approach;

The client asks server if any changes in call

The server responds indicating no changes

The client asks server if any changes in call

The server responds indicating no changes

This continues until at some point after the call changes state, the server responds indicating a change in state and the client can then act on this change

 

This approach isn’t very efficient. If the time between polls is small then CPU usage and network traffic increases. If there is more than one client/consumer, the server/producer can get saturated process client requests.

 

The solution to this problem is web services notifications. Instead of periodically asking the producer if there are any changes, we make an initial call asking the producer to notify the consumer whenever a certain event occurs.

 

The CCT Open Interfaces relies on the WS-Notification standard to deliver asynchronous notifications to registered clients. There are two principle parts to this solution the Notification Producer and the Notification Consumer. Basically, notification producers have to expose a subscribe operation that notification consumers can use to request a subscription. Consumers, in turn, have to expose a notify operation that producers can use to deliver the notification.

 

Notification Producer

A Notification Producer is capable of producing a set of Notification messages. A NotificationProducer accepts incoming Subscribe requests. Each Subscribe request contains a reference to a NotificationConsumer and identifies the subset of the Notifications the NotificationProducer should produce. This subset can be described by identifying one or more boolean filters, including filtering by Topic, as discussed in [WS-Topics]. Topics are used to represent the set of “items of interest for subscription”. The NotificationProducer agrees to produce Notification Messages as requested in the Subscribe request, or returns a fault if the subscription cannot be handled. The user as the choice of registering for all events or a specific list of events, for performance reasons it is recommended that the user registers only for events they are interested in.

 

Notification Consumer

A Notification Consumer represents the endpoint to which the Notification Producer sends events. The client application implements the Notification Consumer web service based on the Notification Consumer WSDL. The client application then subscribes for events i.e. contact state changes, with the Notification Producer. When an event occurs the producer creates the appropriate notification message and determines what consumers have registered interest in that event from its list of subscriptions. Finally, the producer invokes the notify operation of the consumer passing the notification message as parameter. Please note that the Notification service requires ports being established between the Server and the Client machines, this may require firewall configuration changes.

 

SOA CCT WebServices and HA

High Availability configured AACC

On a High Availability configured AACC, the client code that connects to the web services may need to have a process in place in case a server goes down and a switch happens. For code examples on how to deal with a server switch please refer here:

·         WebServices and HA

 

 

SOA CCT WebServices and Session Event Handling

For details of in build session timeout handling mechanisms please refer here:

·         Web Services, Session Event and Heartbeat Handling

 

 

 

 

5.            FAQ

Frequently Asked Questions

For a list of frequently asked questions please click the link below:

·          FAQ

 

 

6.            Constraints on Agent Count and Contact Rate per Hour

Constraints on Agent Count and Contact Rate per Hour

The CCT SOA Open Interface SDK provides a mechanism for CTI using SOAP/XML based Web Services.

 

There are differences in the underlying architecture between the CCT OI and the alternative AACC .Net CTI SDK which lead to limits on:

  1. The supported number of concurrent logged in agents
  2. The contact-rate (measured in contacts per hour) that the CCT OI SDK can support.

 

 

The limits are given below for (i) SIP-based and (ii) CS1K-based AACC deployments.

 

SIP-Based

  • Maximum count of logged in Agents:            1000
  • Maximum contact rate:                                   10,000 contacts per hour

 

CS1K-Based

  • Maximum count of logged in Agents:            1500
  • Maximum contact rate:                                   15,000 contacts per hour

 

Where a CTI application interacting with the AACC is being developed with requirements that exceed either, (1) the supported agent count or (2) the contact rate, then the CCT OI SDK is not a suitable choice.

 

This is also true if the requirements come within a minimum of 20% of these limits and the CTI application is expected to scale up to greater numbers in the near future.

 

In either of the cases above, it is recommended that the CTI application should be designed to use the CCT.Net SDK which supports the full AACC capacity for agents and contact rate per hour.

 

 

7.            Tutorials

SOA CXF Tutorial

This tutorial describes how to validate a user against the CCT Open Interfaces, create a new contact, create a screen-pop application, and change the state of an agent.

 

The project can be obtained from the following directory

 

Tutorial

Location

SOA CXF Tutorial

Tutorial 1

 

 

SOA CCT Web Services Subscriptions

This tutorial describes how to subscribe for SOA CCT Web Service Notifications via two different means.

 

The first utilises the UserService to subscribe for notifications in the simplest manor. This notification will subscribe for all event types. The second utilises the NotificationProducer to subscribe for specific notifications. In the case of this tutorial it will just subscribe for Agent Property LOGIN_STATUS notifications.

 

The project can be obtained from the following directory

 

Tutorial

Location

SOA CCT Web Services Subscriptions

Tutorial 2

 

 

SOA Registering For Specific Agent Events

This tutorial describes how to subscribe for specific SOA CCT Web Service Notifications.

 

It will also examine some of the TCP packages that get sent from the client to the server and vice versa

 

The project can be obtained from the following directory

 

Tutorial

Location

Registering For Specific Agent Events

Tutorial 3 A

 

 

SOA Create a Contact, Hold, UnHold and Answer

This tutorial describes how to create a contact using different services. It will guide you how to hold, unhold and answer that contact.

It will examine the TCP packages that get sent from the client to the server and vice versa

 

The project can be obtained from the following directory

 

Tutorial

Location

Tutorial 3 B - Create Contact Answer Hold Unhold

Tutorial 3 B

 

 

SOA Detect Incoming Calls and Retrieve calledAddress and callingAddress from the Contact Service

This tutorial describes how to utilise the features provided by the SOA CCT Web Services. It demonstrates how to subscribe for TerminalConnection RINGING events and to retrieve the calledAddress and callingAddress from the Connection Service. We will also use a tool to capture TCP/IP packets and display what some of the specific XML packages look like

 

It will examine the TCP packages that get sent from the client to the server and vice versa

 

The project can be obtained from the following directory

 

Tutorial

Location

Tutorial 3 C - Detect Incoming Calls and Retrieve Information

Tutorial 3 C

 

SOA Register for Session Termination Events

This tutorial describes how to subscribe for SOA Session Termination and Session Termination Imminent notifications, and gives a simple example of using the User Service session heartbeat mechanism.

 

The project can be obtained from the following directory

Tutorial

Location

Tutorial 4- Registering For Session Termination Events

Tutorial 4