Sign in using DevConnect ID

Forgot password?

Trouble logging in?

Submit a ticket for Registration Support.

I have an SSO ID

?
sign in

Don't have a DevConnect or SSO ID ?

Create a DevConnect account or join the program.

register now
^

FAQ: Application Enablement Services

See All Content
X

FAQ: JTAPI

General

What is JTAPI?

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.

What is the core JTAPI Package?

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.

What is Avaya implementation of JTAPI?

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.

Does the Avaya JTAPI implementation cover the full JTAPI specification?

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.

What is the latest version of JTAPI Client?

The latest version of the JTAPI Client can be located by navigating to the JTAPI release page.

Is JTAPI sample code available?

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.

How does one provide a 'service name' value for the JTAPI Exerciser?

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.

How can I find the version of JTAPI that my application is using?

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

Are there any restrictions concerning the use of JTAPI client 4.1 in combination with Avaya Computer Telephony (CT) 1.3 and G3r R12 running on Communication Manager (CM) 2.XX?

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.

Why would jtapiPeer.getServices() method not return any Tlinks?

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.

How can the JTAPI libraries be configured to log the trace output from a JTAPI client application to a file (tsapi.pro, JTAPI, CTIConnector)?

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.

In order to develop software applications using Java Telephony API (JTAPI), is it necessary to have the same version for the JTAPI SDK and the JTAPI Client?

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.

What is new in JTAPI Client Release 4.1.0?

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

Where can I find tips to setup my desktop to launch JTAPI applets?

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)

Why am I receiving an expired certificate warning when I launch a JTAPI sample application applet on my desktop?


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.

What is the procedure to extract the UCID information from the RouteEvent in JTAPI?

The procedure to extract the UCID information from the RouteEvent in JTAPI is explained in detail as below:

  1. First get the LucentRouteSession by invoking the RouteEvent.getRoutingSession() method.
  2. Extract the routed call (LucentV5Call or LucentCall) from the session using LucentRouteSession.getCall() method.
  3. Then extract the UCID from the call using getUcid() method on the call object.

Does Avaya recommend any special AE Services configurations to support JTAPI applications that observe a large number of objects?

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.

Why does my JTAPI application encounter an InvalidStateException exception when invoking transfer?

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.

Why is it that even after invoking the Terminal.removeCallObserver() method and the call being disconnected, the number of user licenses for TSAPI (VALUE_TSAPI_USERS) acquired by the AE Services' server does not get decremented?

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).

Does Avaya recommend any special AE Services configurations to support JTAPI applications that observe a large number of objects?

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.

Is it possible to control non-speakerphone equipped phones such as phone models 4601 and 9610 remotely using JTAPI?

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.

What is the reason for not getting UEC (UserEnteredCode) for all call events?

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.

Is there a way to set the duration for which JTAPI waits before selecting an alternate T-link?

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.

Is it possible to modify an agent's state forcibly when it is busy on a call by invoking the LucentAgent.setState() method?

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.

Is it possible to use the addCallObserver() method to observe a Hunt Group for call events?

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.

Why is it that the agent's state can be set to 'After Call Work (ACW)' in a consultation call but not in a conference call using JTAPI?

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'.

Where can an Avaya CT 1.3 compatible JTAPI client side interface be downloaded?

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:

  1. The Ecstapi.jar file is almost fully compatible with the Avaya CT 1.3 client interface.
  2. 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.

What is Blind Transfer and how can a Blind Transfer operation be performed using JTAPI?

There are three types of transfer scenarios, as described below:

  1. Consultation Transfer: In this type of transfer, the transfer takes place after a new call has been answered.
  2. 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.
  3. Single Step Transfer: In this type of transfer, a transfer is done without putting the existing call on hold.
In a Blind Transfer, the controller puts one party on hold, initiates a new call and performs the transfer without waiting for the new call to be answered. This transfer is implemented using the CallControlCall.Transfer() method. In this type of transfer, the transfer controller does not wait for the call to be answered - it performs the transfer when the call is in the alerting state.

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
		

Why does a Java exception occur in a call to add a Listener to a JTAPI Object?

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.

Does a JTAPI application require a restart for the configuration settings changes in the TSAPI.PRO file to take effect?

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.

How can I access the JTAPI Exerciser?

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:

  1. Login
  2. Click on "Advanced Search" in the top right part of the Welcome page.
  3. On the DevConnect Search page enter "JTAPI SDK" into the Keywords field.
  4. Check "SDKs/APIs" checkbox below the Keywords field and click on the Submit button.
  5. Download the appropriate operating system versions of the JTAPI SDK.
  6. Repeat steps 2 through 5 to acquire the "JTAPI Client"
  7. Enter "JTAPI SDK Installation Guide" into the Keywords field.
  8. Check "Product Documentation" checkbox below the Keywords field and click on the Submit button.
  9. Download the appropriate version and follow the instructions in the Installation guide to install the full JTAPI client and JTAPI SDK.
On a Microsoft Windows platform, the JTAPI Exerciser is an optional part of JTAPI SDK installation. Once the installation of the SDK and exerciser is complete, "JTAPI Exerciser" and "Exerciser Help" file can be found by following the start menu path below:

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".

How can I get the UCID from the Route Session when using Adjunct routing?

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());

Can the JTAPI SDK be used for developing Web-based applications?

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.