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:

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.

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:

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.

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
		

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:

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

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.

The following list describes the basic steps that are common to virtually all JTAPI applications.

• Obtain a JtapiPeer object using the JtapiPeerFactory class. For example:
  The TsapiPeer class, com.avaya.jtapi.tsapi.TsapiPeer, represents the Avaya JTAPI implementation.
  jtapiPeer = JtapiPeerFactory.getJtapiPeer("com.avaya.jtapi.tsapi.TsapiPeer")
• Obtain a list of available tlinks by using the getServices() method of the JtapiPeer class. For example:
  String[ ] tlinks = jtapiPeer.getServices();
• Obtain a Provider object using the getProvider() method of the TsapiPeer class. Specify the aeserver tlink name and aeserver login and password, for example:
  provider = tsapiPeer.getProvider("avaya#cstaserv#csta#aeserver;" + "login=user1;" + "passwd=user1pass;")
  where
  
  • avaya#cstaserv#csta#aeserver is the tlink name
  • aeserver is the name of the AE Services server (AE Server) that is running the JTAPI Service.
  • login and passwd refer to the authentication login and password.

Provider Object

The Provider object is an abstraction of telephony service-provider software. A Provider hides the service-specific aspects of the telephony subsystem and enables Java applications and applets to interact with the telephony subsystem in a device-independent manner.

Call Object

The Call object represents a telephone call, the information flowing between the service provider and the call participants.

Address Object

The Address object represents a telephone number. It is an abstraction for the logical endpoint of a telephone call.

Connection Object

A Connection object models the communication link between a Call object and an Address object.

Terminal Object

The Terminal object represents a physical device such as a telephone and its associated properties.

TerminalConnection Object

TerminalConnection objects model the relationship between a Connection and the physical endpoint of a Call, which is represented by the Terminal object.

This may be because the JTAPI application has some classes that are not part of a "package" and thus have no path in an archive file such as a JAR, ZIP, or CAB file. The DefaultJtapiPeer class must exist in the ECSJTAPI archive files outside of the Avaya package. (This is forced by the JTAPI design specification). Some instances virtual machines cannot recognize classes without a package when multiple archive files are involved. This winds up being DefaultJtapiPeer and can cause this exception.

Prior to JTAPI release 1.3, the Java observer/observable model was the pattern that JTAPI applications could follow to receive events from a JTAPI implementation using the JTAPI API.

With JTAPI releases 1.3 (packages Core, Media, Mobile) and 1.4 (packages Callcontrol, Callcenter, Phone, Private), applications could transition to using an event delivery scheme based in spirit on the Java 1.1 delegation-based event model (or "Listener model"). JTAPI releases 1.3 and 1.4 also include the Observer methods and events, but deprecate them.

CSTA Error 41 relates to 'SUBSCRIBED RESOURCE AVAILABILITY'. CTI login that is used for the login may not have the necessary privileges. Check on AE Server, in the CTI Users -> List All Users' page; check that application login credential has right privileges.

AgentTerminal.addAgent() should only be used when the agent is not logged in. Calling addAgent() when the agent is already logged in should fail and do nothing to the agents state. Developers should use setState() if the agent is already logged on and wish to change the agent's state.

Agent state changes are not observed on an AgentTerminal object. To get these, the observer should be placed on the ACDaddress object. The only state changes reported are log-on and log-off.

public void routeEvent(RouteEvent event) {
LucentCallInfo xyz : (LucentCallInfo)event.getRouteSession();
UserEnteredCode d = xyz.getUserEnteredCode() ;
System.out.println('Entered Digits ['+d.getDigits()+']');
}

public void routeEvent(RouteEvent event) {
LucentRouteSession xyz : (LucentRouteSession)event.getRouteSession();
UserToUserInfo d = new UserToUserInfo(?MY user to user data?);
xyz.selectRoute(routeSelected, false, d);
}

LucentCall call = (LucentCall) ((CallEv) event).getCall();
ACDAddress acdAddress = call.getDeliveringACDAddress();
String trunk = ((LucentCallInfo) call).getTrunk();

Provider provider = jtapiPeer.getProvider( providerString );

If(provider instanceOf LucentProvider) {
TrunkGroupInfo tgi = ((LucentProvider)provider).getTrunkGroupInfo(trunkAccessCode);
System.out.println("Number of Idle trunks ["+ tgi.idleTrunks +"] Number of in-use Trunks ["+tgi.usedTrunks+"]");
}

Avaya's JTAPI implementation doesn't support "setApplicationData" and "getApplicationData" methods of "CallCenterCall". One way of achieving this is to pass a key in the "UserToUserInfo" and perform a database query to get the necessary data.

First ensure that security database is enabled on AES simulator and the ACD/ hunt group is added as an ACD device in the device list.

To monitor a hunt-group or ACD, associated hunt-group need to be modified. Use 'change hunt-group' command, and set or select the check box for ACD.

Once you have completed the first task, follow these steps to query status on queue.

• Call function CallProvider.getAddress(string) where an ACD extension is passed as an input.
• Check that the returned Address object is an instance of ACDAddress.
• Call ACDAddress.getNumberQueued();

You may need to create new CTI User login. Follow these steps to add the user:

• Start the AES OA&M Web page and login with the 'avaya' user.
• Then select
  User Management --> User Management --> Add User.
• Set the User Id, Common Name, Surname, User Password and Confirm Password fields. Set CT User to "yes".
• Submit the form.

Now restart the applicatioon and retry your query.

Yes. The 'CallCtlTermConnHeldEv' interface indicates that the connection is in the 'HELD' state. The call observer class must implement the interface 'CallControlCallObserver' in order to receive this and any other Call Control events.

Avaya has not implemented 'transfer(String)' method in 'CallControlCall', So, the exception 'com.avaya.jtapi.tsapi.TsapiMethodNotSupportedException: unsupported by implementation' is raised. Use the method 'transfer(Call otherCall)' to achieve a transfer operation. This method moves all participants from one call to another, with the exception of a selected common participant.

Currently, tests are conducted with over 625 simultaneous monitors/observers, where 400 monitors are generated using JTAPI. Full capacity testing is currently done with TSAPI monitors and not with JTAPI.

Avaya's implementation of JTAPI does not provide access to the state of the physical endpoint (i.e. Terminal) for 'off switch' parties. Therefore, it is not possible to expose the capabilities that allow the application to query the state of the dynamic device or manipulate it. The 'getTerminalConnection()' API method will return 'null', as there is no 'Terminal' object or 'TerminalConnection' object for 'off switch' parties.

Yes, Java Telephony API (JTAPI) provides the required functionality to accomplish this. The JTAPI interface 'javax.telephony.callcenter.Agent' implements this service. The DMCC Java SDK also provides call control capabilities in release 4.1.

The Avaya JTAPI implementation supports the following requests related to agent queue information:

1. getNumberQueued (returns the number of calls queued at an ACDAddress)
2. getLoggedOnAgents (returns the Agents logged into the ACDAddress)

For more details, please refer to the AE Services 4.1 JTAPI Programmer's Reference, available on DevConnect. You can find the programmer's reference by performing a devconnect search on "JTAPI Reference".

When an agent is added to a terminal (Agent Terminal), the application can specify the initial state for the agent. If this is selected as 'Agent.LOG_IN', then the agent will be logged in after adding to the terminal.

On the phone's terminal, call the LucentTerminal.addAgent() method.

Following are the required parameters:

• AgentAddress - specifies the Address on this Terminal that this request is for, where the Terminal may support several addresses.
• AcdAddress - specifies the address of the ACD that the Terminal is requested to be logged in to (may be null).
• InitialState - specifies the initial state of the agent. Valid states are Agent.READY, Agent.NOT_READY and Agent.LOG_IN.
• WorkMode - specifies the work mode this Agent should be set to. Valid values are LucentAgent.MODE_AUTO_IN and LucentAgent.MODE_MANUAL_IN.
• AgentID - is the Agent's ID.
• Password - is the Agent's password.

This error occurs because of an overflowing queue in AE Services. One explanation could be a network outage that prevents AE Services from sending messages to the application. In the absence of a network issue, this failure may occur because the application reads from the queue at a rate slower than the rate at which messages are being written into it, i.e., the application is unable to retrieve messages from the client queue fast enough resulting in queue overflow. AE Services is forced to drop the connection because of excessive time taken by the application for reading consecutive messages from the queue. Some common application behaviors which trigger this issue are that the application uses the thread that receives messages from the library to do some amount of internal processing or that the thread has entered a sleep mode. It is recommended that the application have a dedicated thread which is only involved in shifting messages from the client queue to an internal application queue/dispatcher thread in the application's queue management portion.

Here are the steps to un-hold a specific call on a device:

• Obtain the Connection list: Connection list can be obtained from an address as well as from a call object. The getConnections method returns all the connections associated with the supplied address or call object, on which the method is invoked. If getConnections is invoked on a call object, the connections associated with the desired address can be obtained as below:
  

  
  Connection connection[] = call.getConnections();
  	String desiredAddressName = "46001";
  	  for ( int i = 0; i < connection.length; i++ )
  	  {
  	   Connection conn = connection[ i ];
  	   if ( conn.getAddress().getName().equals(desiredAddressName) )
  	   {
  		Connection localConn = conn;
  	   }
  	  }
  							

• Get the TerminalConnection list: From the connection obtain the Terminal connections:
  

  TerminalConnection[]terminalConns = 	localConn.getTerminalConnections();
  			

• Putting the call on hold/unhold for specific TerminalConnection object: Select the appropriate terminal connection and invoke method hold or un-hold:

  for ( int i=0; i < terminalConns.length; i++ )
  	 {
  	   TerminalConnection termConn = terminalConns[ i ];
  	   if ( termConn instanceof CallControlTerminalConnection  )
  {
  		String name = termConn.getTerminal().getName().
  		if(name.equals(desiredAddressName)
  		{
  		   // To hold the call
  	  ((CallControlTerminalConnection)termConn).hold();
  	   // To unhold the call
  	   ((CallControlTerminalConnection) termConn).unhold();
    }
   }
  							

Refer to the JTAPI documentation available with JTAPI SDK 4.2 for more details.

The procedure to get the agent ID from the call event information is described below:

1. Every call event is associated with a call object. Get the connections on the call using call.getConnections(). getConnections method will return an array of connections associated with this call. Ideally, there should be at least two connections, one referring to the calling party and the other referring to the agent to which the call is redirected.
2. On each of the returned connections, use the connection.getTerminalConnection() method, which will return an array of TerminalConnection objects associated with this Terminal.
3. Now check the type of the terminal returned. In case of a terminal connections referring to agent, type will be AgentTerminal.
4. Using AgentTerminal.getAgent() on the terminal matched by the above step, get a list of agents (Agent Objects) logged into this terminal. Note that in the case of a call involving more than one agent, multiple terminals will return a type of AgentTerminal.
5. On this Agent Object, invoke AgentTerminal.getAgentID() method, which returns the agent's identification.

A sample code snippet for the above scenario is provided below:

/* The function callChangedEvent handles the various call events 
 * that are received at the extension on which call observer is added.
 */


public void callChangedEvent(CallEv[] eventList) 
{
    for ( int eventIndex = 0; eventIndex < eventList.length; eventIndex++ )
    {
        CallEv e = eventList[eventIndex ];
        /* Retrieve the call object from the call event.*/
        Call call = e.getCall();

     	 /* Get the connection array. 
         * getConnections returns an array of   
         * Connections associated with this call
         */

        Connection[] connectionArray = call.getConnections(); 

        if (connectionArray == null)  /* Check Connections*/  
	 {                                                  
	     System.out.println("No active connections present");  
	     return;
	 }
        for ( int connIndex = 0; connIndex < connectionArray.length; 
              connIndex++ )
        {
	    Connection conn = connectionArray[connIndex ];
	    /* get the terminal connections */
	    TerminalConnection[] terminalConns = conn.getTerminalConnections;        
	    if (terminalConns == null)
	    {
		   System.out.println("No valid TerminalConnection found.");
		   return;
	    }

	    for ( int termIndex=0; termIndex < terminalConns.length; termIndex++ )
	    {
		   if (terminalConns[termIndex] instanceof AgentTerminal)
		   {
			   /*get the agent array*/
			   Agent[] agents = terminalConns[termIndex].getAgents();  
			   for (int agentIndex = 0; agentIndex < agents.length; 
                            agentIndex++ )
			   {
				  /* get the agentID*/
				  String agentID = agents[agentIndex].getAgentID();
				  System.out.println("Agent ID :"+agentID);
			   }
		   }
	    }
       }
    }
		

The information from the TSAPI.pro file is read when the library is loaded. There is no provision to force the TSAPI.pro file to be reloaded. Hence, it is not possible to access the updated TSAPI.pro file without closing the JTAPI application which is running. You must shutdown and restart, or launch a second instance of the application driver level and have the driver level applications communicate with a top level process.

Invoke the RouteAddress interface for the address.addCallObserver() method to monitor a VDN on its address.

When a resource is unavailable to complete an operation, JTAPI throws the ResourceUnavailableException exception. If the number of already existing observers reaches the limit, the exception is set with the Error field set to OBSERVER_LIMIT_EXCEEDED. In some cases, the number of allowed observers is zero.

The OBSERVER_LIMIT_EXCEEDED error is encountered when the addCallObserver() method is used on an AgentTerminal in cases where the AgentTerminal object is obtained using an Agent ID. If the agent's login ID is passed as an extension (to obtain an AgentTerminal object), the addCallObserver() method (when invoked on this AgentTerminal object), will throw this error. If the AgentTerminal is obtained by using the station extension where the agent logs in (using the getAgentTerminal() method), a Call Observer can be put on the returned AgentTerminal object.

For more details, please refer to the document Avaya Java Telephony API (JTAPI) javadoc, version 4.2, available on the Avaya DevConnect website at http://www.avaya.com/devconnect.

Yes, Avaya JTAPI supports SST starting from the AE Services server Release 4.1 onwards.

SST feature in JTAPI is accessed by using CallControlCall.transfer() method. This method transfers the participant(s) currently in a call to another address. This method takes address string as an argument indicating where the call is to be transferred and returns a new connection associated with the destination address.

Before performing SST, a Transfer Controller needs to be set up for the call. The Transfer Controller represents a TerminalConnection that is getting transferred. The application can set the transfer controller using the CallControlCall.setTransferController() method. The terminal connection set as the Transfer Controller must be in the CallControlTerminalConnection.TALKING state for the transfer to complete. The other terminal connection(s) in the call can be in the TALKING or HELD state.

The code snippet below illustrates how to perform SST.

// <summary>
// Perform's single step transfer.
// </summary>
// @param call - an existing call on which SST is to be performed.
// @param transferController - terminal connection object of the
// terminal from which the call is to be transferred.
// @param transferTo - address to which the call is to be transferred.
// @return - returns a new connection associated with the transferTo address.

public Connection singleStepTransfer(Call call, 
	TerminalConnection transferController, String transferTo) {

	Connection newConn = null;

	try {
		// Type cast Call object to CallControlCall object
		// to access transfer() & setTransferController() methods.
		CallControlCall callCtlCall = (CallControlCall) call;

		// Set transfer controller
		callCtlCall.setTransferController(transferController);

		// perform SST
		newConn = callCtlCall.transfer(transferTo);

	} // End of try block
	catch (Exception e) {
		System.out.println("Error :" + e.getMessage());
		// handle exception here.
	}// End of catch block
return newConn;
	}// End of method.
						

JTAPI does not provide an API method to access longest call waiting time. An application can calculate the longest call waiting time interval by calculating the difference in timestamp values saved on arrival of the CallCtlConnQueuedEv and the CallCtlConnEstablishedEv events for each call.

For example, if calls are routed through a VDN prior to delivery to a hunt group that the application wants to measure queue interval times for, then the application must set a call observer on the VDN address object:

String vdn_extension = "12345";
....
Address vdn = provider.getAddress(vdn_extension);
vdn.addCallObserver(timestampsCollectingCallObserver);
....
						

Then the application will begin receiving the events mentioned above (along with others), and can populate a data structure with Call object reference as well as the arrival time in queue, and when the call is answered use that information to calculate longest call waiting, average call distribution, and expected wait times. Note that a CallCtlConnQueuedEv is only provided if the call enters the hunt group's queue. If the call is delivered directly to an agent, there is no CallCtlConnQueuedEv event.

JTAPI uses TASPI service in Application Enablement Server. It does not require special licensing requirements other than TSAPI license requirements. Please see TSAPI licensing requirements in TSAPI FAQ.

In JTAPI, the monitorCallsViaDevice method on a VDN consumes no licenses. A license is consumed when the application does something to a call it has discovered exists (through its monitor on the VDN).

A monitor on a station (typically an Agent), takes a TSAPI Basic User license as long as the monitor is active. Usually, one station monitor requires one TSAPI Basic User license. If an application performs call control on a station that is NOT already monitored, then an additional license would be needed during the call control operation.

The TSAPI Basic User license is often referred to as either an "agent-based license" or a "station based license. It is intended for applications that want to monitor a call or a station

The CallCenterProvider.getACDAddresses()method returns an array of ACD Addresses associated with the Provider and within the Provider's domain. This list is static; i.e., it does not change after the Provider is first created. If the CTI user used in the JtapiPeer.getProvider() method has unrestricted access, then the CallCenterProvider.getACDAddresses()method throws the above mentioned exception. If the user has restricted access and no ACD Addresses are associated with this Provider, then the method returns null. In order to avoid the exception, enable restricted CTI access for the CTI user that is being used in the JtapiPeer.getProvider()method. Using a web browser, navigate to the AE Service's Home OA&M page (http://<IP-Address-of-AE-Services>), click on AE Server Administration, login with CTI username and password and select CTI OAM Administration. From that page, navigate to Administration -> Security Database -> CTI Users -> List All Users. Select the radio button for the CTI user that the application utilizes and click Edit. Click on the Unrestricted Access "Disable" button to enable "Restricted Access" for the CTI user. The following screenshots show this sequence.

For more information, refer to the section titled Security Database objects in Chapter 6 of Avaya MultiVantage® Application Enablement Services Administration and Maintenance Guide, Release 4.2, 02-300357, Issue 10, May 2008, available on http://www.avaya.com/devconnect.

While invoking the Call.Connect() method, it is necessary to provide the originating Terminal object, the corresponding Address associated with the originating Terminal object and a valid destination telephone number. The originating Address must be associated with the originating Terminal (i.e. Address.getTerminals()should include originating Terminal) and the originating Terminal must be associated with the originating Address (i.e. Terminal.getAddress()should include the originating Address). If the originating Terminal is not associated with the originating Address, then the JTAPI service throws an InvalidArgumentException containing the above error message. In Avaya's implementation, there can be only one Address associated with a Terminal. In other words, there is a 1:1 relationship between Address and Terminal in Avaya's JTAPI implementation.