General
JTAPI is an object oriented API that is meant for developing computer telephony applications in the JAVA programming language to run on JAVA supporting operating systems or web browsers.
The core JTAPI interfaces and classes are contained in the package: javax.telephony. The "core" API provides the basic call model and rudimentary telephony features, such as placing telephone calls and answering telephone calls.
Avaya MultiVantage Application Enablement Services (AE Services) JTAPI Release 3.1.0, supports the JTAPI 1.4 specification. The Avaya Implementation of JTAPI supports the JTAPI 1.4 specification with Observers only, not Listeners. The JTAPI 1.4 specification is a superset of the JTAPI 1.2 specification, and the Avaya implementation of JTAPI 1.4 includes the Observer (1.2) methods. Package com.avaya.jtapi.tsapi is the Avaya implementation of JTAPI.
No, the Java Telephony API (JTAPI) Client Programmers Guide contains a section called "Support for JTAPI" which outlines the portions of the specification that have been implemented by Avaya. This document is available on this DevConnect web Portal.
The latest version of the JTAPI Client can be located by navigating to the JTAPI release page.
Both JTAPI and TSAPI sample codes are available on this DevConnect Web Portal at http://devconnect.avaya.com. The sample codes can be tested against Avaya Remote Lab. More details on the Remote Lab are available on the DevConnect Training page, a link for which can be found on the left hand navigation bar of this page.
AE Services server configuration details like the AE Services server name, IP address and port are configured in the 'TSAPI.pro' file. If the 'TSAPI.pro' file contains correct information and if it is not shown in the JTAPI Exerciser, the directory which contains the 'TSAPI.pro' file is not in the Java CLASSPATH. Include the appropriate directory name in the Java CLASSPATH (e.g. C:\TEMP) and then run the JTAPI Exerciser test tool.
Locate the Ecsjtapia.jar file in the directory structure on the machine the application is running on (the default Windows install location is C:\Program Files\Avaya\AE Services\JTAPI Client\JTAPI). Change your working directory to that location, and run the following java command from a operating system command prompt: "java -cp Ecsjtapia.jar ECSJtapiVersion"
For example:
C: > cd C:\Program Files\Avaya\AE Services\JTAPI Client\JTAPI
C:\Program Files\Avaya\AE Services\JTAPI Client\JTAPI > java -cp Ecsjtapia.jar
ECSJtapiVersion
Version of Avaya's implementation of Jtapi is 3.1.0 build 69
JTAPI client from AE Services is compatible with Avaya CT 1.3. There is a possibility of incorrect behavior depending upon how the private data message is implemented by the application. When there is a release difference between the AE Services server and the TSAPI/JTAPI client, the client must properly encode messages using the private data version returned by the server during the open stream process. Failure to do so by the client may result in messages not being handled properly by the AE Services server. If the application, confirms to the private data level returned by the AE Services server, then there should be no compatibility issues.
A JTAPI application can use jtapiPeer.getServices() method to get an array of all the Tlinks provisioned in the specified AE Services server(s). When Tlinks are not displayed or returned by the jtapiPeer.getServices(), there is usually some problem with the Java CLASSPATH or the configuration specified in TSAPI.pro file. The JTAPI implementation needs to be able to locate the TSAPI.pro file. The JTAPI API locates the file using the CLASSPATH. Once the TSAPI.pro file is located, the JTAPI library expects to find a correct IP address and port for AE Services server in the TSAPI.pro file. If any one of these is not set correctly, then the error: 'TSAPIPlatformException: Server not found' is encountered.
The jtapiPeer.getServices() method will also not return any Tlinks, when the AE Services server specified in the TSAPI.pro file doesn't have any provisioned Tlinks.
In the tsapi.pro file an altTraceFile can be configured to collect tsapi tracing associated with the client libraries such as JTAPI and CTIConnector. There is not a default location or name for the trace file, an explicit path must be specified.
You should use the forward slash in the path name for all operating systems:
altTraceFile=C:/temp/tsapi_trace.txt
For more information on JTAPI tracing reference the JTAPI programmer's guide under the Configuring your JTAPI client library and JTAPI properties sections.
Yes, to develop software applications using JTAPI, the JTAPI Client version and the JTAPI SDK version must be the same. For example, JTAPI SDK 4.1 should be used with JTAPI Client 4.1.
Release 4.1.0 of the AE Services JTAPI Client used with AE Services Server 4.1.x.) provides following new features:
- Support for secure client connections using Transport Layer Security (TLS): The JTAPI client can establish a secure session with an AE Services Release 4.1.0 server where the TSAPI Link (Tlink) has been administered as encrypted.
- Earlier detection of network connectivity problems: By monitoring "heartbeat" events sent by the AE Services Release 4.1.0 server at regular intervals, the JTAPI client is able to detect and report network outages to the application.
- Alternate TSAPI Link (Tlink) Selection: Up to four alternate TSAPI links may be specified for a given TSAPI link. In the event that JTAPI client is unable to connect to the preferred TSAPI link, it will attempt a connection to an alternate TSAPI link. For more information about specifying Alternate Tlinks in the tsapi.pro file, see "Specifying Alternate Tlinks for the JTAPI client" in "Avaya MultiVantage® Application Enablement Services TSAPI, JTAPI, and CVLAN Client and SDK Installation Guide, 02-300543".
- A addPredictiveCallObserver() call, which is exposed through the new LucentV7ACDManagerAddress interface. For more information on JTAPI LucentV7ACDManagerAddress, refer to the following link http://support.avaya.com/elmodocs2/AES/4.1/jtapi/com/avaya/jtapi/tsapi/LucentV7ACDManagerAddress.html
- getCSTACause(), which is exposed through the new ITsapiCallEvent interface. Applications can use this method to retrieve the CSTA cause value provided in the TSAPI call event that was the source of the associated JTAPI event or events.
- JTAPI fastConnect() API call, which is particularly useful to applications that use Feature Access Codes (FACs) and applications that use Vector Directory Numbers (VDNs). For more information on JTAPI fastConnect, refer to the following link http://support.avaya.com/elmodocs2/AES/4.1/jtapi/com/avaya/jtapi/tsapi/package-summary.html#JTAPI%20fastConnect
Refer to the section 'Setting up your computer to run JTAPI applets' in Chapter 3 of Avaya MultiVantage® Application Enablement Services TSAPI, JTAPI, and CVLAN Client and SDK Installation Guide document ID 02-300543 Release 4.1 Issue 4 dated December 2007. This document is available on the DevConnect portal (http://www.avaya.com/devconnect)
It is ok to ignore the warning about the expired Avaya certificate and
allow the application to run. This is a known issue in all the versions of the JTAPI library
up through release 4.1. The issue is being addressed and will be fixed in the next JTAPI
release.
The procedure to extract the UCID information from the RouteEvent in JTAPI is explained in detail as below:
- First get the LucentRouteSession by invoking the RouteEvent.getRoutingSession() method.
- Extract the routed call (LucentV5Call or LucentCall) from the session using LucentRouteSession.getCall() method.
- Then extract the UCID from the call using getUcid() method on the call object.
If a JTAPI application is observing a large number of objects (more than 1200), Avaya recommends disabling the Security Data Base (SDB). This is because, during application initialization, there can be performance issues due to JTAPI pulling a large amount of information from the AE Services server's SDB, since JTAPI obtains all information from TSAPI. For more information on performance, please refer to the Application Enablement Services capacities section of the Avaya MultiVantage® Application Enablement Services Overview, 02-300360, Release 4.1, December 2007, Issue 4 document.
An InvalidStateException exception occurs when the current state of an object involved in the method invocation does not meet the acceptable pre-conditions for invoking the method.
If the CallControlCall.transfer() method is used to perform the call transfer, a pre-requisite is that the transfer controller must be present on each of the two Calls and share a common Terminal and the two Calls must be in either of the CallControlTerminalConnection.TALKING or CallControlTerminalConnection.HELD.
The CallControlTerminalConnection.TALKING state indicates that the terminal is actively a part of a call (typically 'off-hook'), and the party is communicating on the call.
The CallControlTerminalConnection.HELD state indicates that a terminal is a part of a call, but is on hold.
If this condition is not met, the InvalidStateException exception is thrown while transferring the call.
For more details on call transfer, refer to the JTAPI Javadoc and the InvalidStateException.html document defined under the javax.telephony package.
The user may also refer to Avaya MultiVantage® Application Enablement Services TSAPI for Avaya Communication Manager Programmer's Reference, 02-300544, Release 4.1, December 2007, Issue 3.
There was an issue with the JTAPI client where the call observer was not being released by the client back to the AE Services server. This behavior is fixed in the AE Services server 4.2 JTAPI SDK. Developers are recommended to upgrade to the AES JTAPI SDK version 4.2. Alternatively, the user can shutdown the application and close the socket that is used with the AE Services server to free the license(s).
If a JTAPI application is observing a large number of objects (more than 1200), Avaya recommends disabling the Security Data Base (SDB). This is because, during application initialization, there can be performance issues due to JTAPI pulling a large amount of information from the AE Services server's SDB, since JTAPI obtains all information from TSAPI. For more information on performance, please refer to the Application Enablement Services capacities section of the Avaya MultiVantage® Application Enablement Services Overview, 02-300360, Release 4.1, December 2007, Issue 4 document.
It is possible to monitor non-speakerphone equipped phones but call control operations on these phones may fail.
Two types of operations can be performed on a phone. The first of these is a monitor operation, where an application only monitors the specified JTAPI object. This includes adding an observer and extracting event information. Such operations can be performed on any device, including non-speaker phones without any failures.
The second type of operation is a call control operation such as originating and answering a call. These tasks typically include changing the state of the hook switch. Since a non-speakerphone cannot be put off-hook programmatically, operations such as these will fail on a non-speakerphone equipped phone.
For getting UEC (UserEnteredCode) in the call events, two VDNs need to be set up. The first VDN collects the digits that represent the User Entered Code (UEC) from the caller and should not be monitored. The first vector then needs to route the call to a second VDN. If the second VDN is monitored, then the monitoring application will get the UEC in the call events. A call observer on a station receives only the UEC that is received by the VDN that redirects the call to the station, provided that the VDN is observed.
For more details refer to the UserEnteredCode class in the package
com.avaya.jtapi.tsapi.UserEnteredCode in the JTAPI Javadoc.
The user may also refer section "How to Collect userEnteredCode (UEC)" from document Avaya
MultiVantage®Application Enablement Services TSAPI for Avaya Communication Manager
Programmer's Reference 02-300544 Release 4.1 December 2007 Issue 3.
The alternate T-Link selection is an AE Services 4.1 feature, which only occurs at the time when the JTAPI application attempts to create a Provider. If the preferred T-Link is unavailable at that time, the alternate T-Link selection will select one of the alternatives (if they are available). The duration that JTAPI waits for the response from the AE services while opening a connection is determined by TCP timeout value.
Note: An alternate T-Link selection does not switch a running JTAPI application over to a different T-Link if there is a problem accessing the preferred T-Link once communication has been established over a T-Link.
The TCP timeout described for JTAPI configured in the TSAPI.PRO file. The setting is:
MaxWaitForSocket= 20
This setting controls the number of seconds JTAPI will wait for a socket to open (i.e., to open a T-Link connection). The default value is 20 seconds.
It is not possible to modify the agent's state forcibly by invoking the LucentAgent.setState() method when the agent is busy on a call. If an application is trying to do so forcibly, the application will encounter an InvalidStateException exception. For more details, please refer the setState() method defined under Lucent Agent described in the JTAPI javadocs.
It is not possible to receive call events for calls coming to Hunt Group by adding a call observer to Hunt Group's Address using addCallObserver() method. Avaya's implementation of JTAPI provides support for adding a call observer to a VDN Address but not to a Hunt Group Address (or ACDAddress). Typically in a call center, a call is first handled by a VDN and after the call is classified using the vector logic, the call is routed to an appropriate Hunt Group. A call observer can be added to a VDN Address using the addCallObserver() method. A VDN call observer provides adequate notification of calls that are being handled by hunt groups. An application can add AddressObserver to ACDAddress or Hunt Group's Address for receiving agent login & logout events.
In a consultation call, the agent puts the customer's call (which is the first call) on hold and initiates an internal second call for consultation with the consulting party. Communication Manager tracks the agent's state with respect to the first call which is an ACD call. When the customer disconnects/drops from the call, the first call is completed. The agent's state can then be set to 'ACW' from 'Busy', since the agent is available to answer a subsequent ACD call.
However, in case of a conference, both the calls are merged and treated as a single ACD call and agent states are tracked with respect to this call. When the customer disconnects from the call, the ACD call is not viewed as terminated (the PBX does not track closely enough which party(ies) made the call an ACD call to make this decision possible). Agent is still viewed as busy or active in ACD call. Hence, the application is unable to set the agent's state to 'ACW'.
Using either the LucentV6Agent.setState() or LucentV7Agent.setState() method available in JTAPI and selecting the Enable Pending Flag option, the application can set the agent's state to 'ACW'. When the flag is set to true, the request to change the agent state is deferred till the ACD call is cleared. After the call, Communication Manager then changes the state to 'ACW'.
Avaya CT is no longer supported. The same functionality can be achieved by using AE Services JTAPI Client. JTAPI Client interfaces with an appropriate Server (CT- Server or AE Services Server) using the Ecstapi.jar file. This jar file is installed when the JTAPI Client is installed on the Client Machine.
The latest version of AE Services JTAPI Client can be downloaded from the DevConnect portal (http://www.avaya.com/devconnect) using the following procedure:
Browse to Products and SDK -> Application Enablement Services -> AE Services: JTAPI SDK -> Technical Resource -> AE Services Release 4.2 content: JTAPI Downloads and then download the appropriate SDK as per the requirements.
Notes:
- The Ecstapi.jar file is almost fully compatible with the Avaya CT 1.3 client interface.
- Features which are incompatible with CT-Server can be listed from the package.html document included with the JTAPI javadoc, installed with the JTAPI SDK.
There are three types of transfer scenarios, as described below:
- Consultation Transfer: In this type of transfer, the transfer takes place after a new call has been answered.
- Blind Transfer: In this type of transfer, a transfer is done before answering the new call, i.e., when the call is in the alerting state.
- Single Step Transfer: In this type of transfer, a transfer is done without putting the existing call on hold.
A sample code snippet to perform the transfer operation is shown below:
CallControlCall activeCall; // activeCall specifies the CallControlCall // object which sets the transfer controller // terminal connection object. CallControlCall heldCall; // heldCall specifies the call which is put // on hold while invoking the transfer. Connection connection[] = activeCall.getConnections(); for (int conn_index = 0; conn_index < connection.length; conn_index++) { // Iterate through the connection array TerminalConnection[] terminalConns = connection[conn_index].getTerminalConnections(); for (int termConn_index = 0; termConn_index < terminalConns.length; termConn_index++) { // Iterate through the terminal connection array try { // The CallControlTerminalConnection.TALKING state // indicates that a Terminal is actively part of a Call, // typically "off-hook", and the party is communicating on // the telephone call. TerminalConnection.ACTIVE state // indicates that a Terminal is actively part of a // telephone call. This usually implies that the party // speaking on that Terminal is party of the telephone // call. if(terminalConns[termConn_index].getState() == CallControlTerminalConnection.TALKING || terminalConns[termConn_index].getState() == TerminalConnection.ACTIVE) { // set the TransferController to be the first // Active or Talking connection that is located. In // practice this is typically the party that is // initiating the transfer request. activecall.setTransferController (terminalConns[termConn_index]); } activeCall.transfer(heldCall); // Transfer is invoked by // activeCall object // placing first call on // hold. } catch (Exception e) { System.out.println("Exception occurred during Transfer Call"+e.getMessage()); } return; }// End of inner for }//End of outer for
Avaya MultiVantage® Application Enablement Services (AE Services) JTAPI Release 4.2.0 supports the JTAPI 1.4 specification. The Avaya implementation of JTAPI, however, supports the JTAPI 1.4 specification only with Observers and not with Listeners. The JTAPI 1.4 specification is a superset of the JTAPI 1.2 specification, and the Avaya implementation of JTAPI 1.4 includes the Observer (JTAPI 1.2) methods. A method call to add a Listener (for example, myAddress.addAddressListener(myACDListener)) to JTAPI objects will result in the javax.telephony.MethodNotSupportedException exception. The solution is to change the code to add an Observer instead of a Listener. The package com.avaya.jtapi.tsapi is the Avaya implementation of JTAPI.
No, a restart of JTAPI application is not needed for configuration setting changes in the TSAPI.PRO file to take effect. The JTAPI Client library reads the TSAPI.PRO file every 100 seconds. This allows the JTAPI application to use the updated information from the TSAPI.PRO file.
For example, if the setting for the location of the JTAPI application trace log is changed in TSAPI.PRO file while the application is running, the JTAPI application trace logs will start getting stored at the updated location within 100 seconds.
Note: Add/Update of AE Services server IP Address (or FQDN), Alternate Tlink, or location of CA certificate(s) does not impact the existing ACS session. The application will need to establish a new ACS session to use the modified configuration settings.
The JTAPI Exerciser is a part of the JTAPI SDK which can be found on the DevConnect web site
http://www.avaya.com/devconnect by following steps below:
- Login
- Click on "Advanced Search" in the top right part of the Welcome page.
- On the DevConnect Search page enter "JTAPI SDK" into the Keywords field.
- Check "SDKs/APIs" checkbox below the Keywords field and click on the Submit button.
- Download the appropriate operating system versions of the JTAPI SDK.
- Repeat steps 2 through 5 to acquire the "JTAPI Client"
- Enter "JTAPI SDK Installation Guide" into the Keywords field.
- Check "Product Documentation" checkbox below the Keywords field and click on the Submit button.
- Download the appropriate version and follow the instructions in the Installation guide to install the full JTAPI client and JTAPI SDK.
Start > Programs > Avaya AE Services > SDKs > JTAPI
The operating system (OS) independent version of the JTAPI SDK contains the JTAPI Exerciser in the TOOLS/Jtapiex folder. Once the content of the JTAPI SDK archive is extracted the JTAPI Exerciser can be started from command line.
For example, on a Linux platform the JTAPI Exerciser can be started by using the following commands:
cd <jtapi_client_location> java -cp .:./ecsjtapia.jar:%lt;jtapi_sdk_location%gt;/TOOLS/Jtapiex/jtapiex.jar jtapiex.Jtapiex
Note that the JTAPI exerciser depends on the JTAPI client library and appropriate configuration information in the TSAPI.PRO file. For JTAPI Client installation and configuration of the TSAPI.PRO file please refer to Chapter 3 "Installing the JTAPI Client and JTAPI SDK" of the "Avaya MultiVantage Application Enablement Services TSAPI, JTAPI, and CVLAN Client and SDK Installation Guide".
To get the UCID of the call, cast the RouteSession
object to
LucentRouteSession
, then use the getCall()
method to get the call
object:
Call call = ((LucentRouteSession)event.getRouteSession()).getCall();
String ucid = ((LucentV5CallInfo)call).getUCID());
Yes, the JTAPI SDK can be used for developing Web-based applications. The JTAPI JAR file (as of AE Services Release 6.2 , called "ecsjtapia.jar") made available with the SDK distribution can be used for developing applications that run in a Web-container (e.g. Apache Tomcat in conjunction with JSPs and Servlets).
The design of the web application must not interfere with prompt processing of inbound requests. For example,
- The Heartbeat Request from AE Services must be responded to by the SDK in a timely fashion or AE Services will terminate the stream (connection) with the application.
- Once the application receives an event, it should release the event thread immediately and continue with event processing on a different thread. This is because the JTAPI application will not be notified of other events until the previous event's callback method is complete.
Yes. Selective Listen Hold (SLH) – also referred to as Selective Listen Disconnect prevents the flow of voice and DTMF signals coming from a specified party from being received by another party in the call. In many cases blocking that pathway is valuable functionality. One use of this functionality is with a PCI-DSS application to prevent a contact center agent from hearing personal information supplied by a party in the call. However, if a recording device that is using DMCC Multiple Registrations, is receiving the agent’s audio stream, when SLH is invoked to reconfigure the audio the agent is receiving, the recording application is also blocked from receiving the voice and DTMF information sent by the far end party. This may or may not be expected by the call recording application. Another case could be that the Multiple Registrations application is doing analytics on the audio stream; when SLH is invoked, the analytics application may be prevented from receiving audio or DTMF events unexpectedly and undesirably. Since multiple applications may be involved at a customer site (one using Multiple Registrations and the other invoking SLH), but both operating on the same party in the call, the MR application may be unaware that the interaction is occurring. If being in full control of the receipt of all of the audio and DTMF information occurring in a call is required by the application, then the guidance in the DevConnect White Paper Recommended Guidance for DMCC Applications Utilizing Call Media should be reviewed for further information about how to properly design for this interaction.