Table Of Contents
Cisco JTAPI Installation Guide for Cisco CallManager 3.3
This document describes how to install and configure the Cisco Java Telephony API (JTAPI) client software for Cisco CallManager 3.3.
This document contains the following topics:
Cisco Java Telephony API (JTAPI) implementation comprises of java classes that reside on all client machines running JTAPI applications. Installation of the Cisco JTAPI implementation must take place before applications will function correctly. Make sure the Cisco JTAPI classes are installed wherever JTAPI applications will run, whether on Cisco CallManager, on a separate machine, or on both. Installation requires 5 MB of local disk space.
Note If you have upgraded to Cisco CallManager 3.3, you must upgrade the JTAPI client software on any application server or client workstation on which JTAPI applications are installed. If you do not upgrade the JTAPI client, your application will fail to initialize. If you need to upgrade, download the appropriate client from the Cisco CallManager Administration as described in "Installing the Cisco JTAPI Software".
The upgraded JTAPI client software does not work with older releases of Cisco CallManager.
Installing the Cisco JTAPI Software
The Cisco JTAPI installation utility installs the following items on the local disk drive:
•JTAPI java jar files in %SystemRoot%\java\lib
•JTAPI Preferences (jtprefs.exe) in Program Files\JTAPITools
•JTAPI sample applications (makecall, jtrace) in Program Files\JTAPITools
•JTAPI documentation in Program Files\JTAPITools\doc
•JTAPI language related files in Program Files\JTAPITools\Locale_files,\Program File\JTAPITools\LanguageName.properties
•JTAPILocaleProperties.ini in %SystemRoot%\java\lib
Note To run JTAPI applications, you need a Java 1.1-compatible environment such as the Sun JDK 1.1.x, JDK 1.2, or Microsoft Virtual Machine (bundled with Internet Explorer 4.0 and higher). Cisco JTAPI will also run on Sun JDK1.2 and Sun JDK 1.3.
To use JTPREFS with Cisco JTAPI, however, requires Microsoft Java Virtual Machine 5.00.3190 or later. For information on JTPrefs, see "Configuring Cisco JTAPI Tracing".
Cisco JTAPI installation is supported on Windows 2000 and Windows NT platforms.
Perform the following steps to install the Cisco JTAPI software.
Step 1 Log in to the computer where you want to install the Cisco JTAPI client software.
Step 2 Close all Windows programs.
Step 3 Open a web browser.
Step 4 Go to the Cisco CallManager administration windows:
Name specifies the name or IP address of the Cisco CallManager
Step 5 Choose Application > Install Plugins.
Step 6 Choose the Cisco JTAPI link.
When the JTAPI installation program launches, you are prompted to select a language for the installation. The installation continues in the selected language.
Step 7 Follow the instructions in the popup windows.
Note Install Cisco JTAPI software on the default drive as directed by the installation software. When Windows NT is installed in C:\WINNT, the default directory, for example, is C:\WINNT\Java\lib.
Verifying the Installation
To verify the JTAPI installation, you can use the makecall application that allows you to place a call via JTAPI. Perform the following procedure to use the makecall application.
Step 1 From the Windows NT command line, navigate to the directory where you installed Cisco JTAPI Tools. By default, this directory is C:\Program Files\JTAPITools.
Step 2 Execute the following command:
Jview makecall <server name> <login> <password> 1000 <phone1> <phone2>
server name specifies the hostname or IP address of the Cisco CallManager (for example, CTISERVER).
phone1 and phone2 designate directory numbers of IP phones or virtual phones that the user controls according to the user configuration. See the Cisco CallManager Administration Guide for details.
For login and password, use the user ID and password that you configured in the Cisco CallManager User Configuration window.
Configuring Cisco JTAPI Tracing
Use the Cisco JTAPI tracing preferences application (JTPREFS.EXE) to configure trace levels and trace destinations. Installation of the Cisco JTAPI Preferences into the Program Files\JTAPITools directory utility takes place by default. To open the Cisco JTAPI Preferences utility, choose Start > Programs > Cisco JTAPI > JTAPI Preferences.
This section, which describes how to use the Cisco JTAPI preferences application, discusses the following topics:
Figure 1 illustrates the Trace Levels tab of the Cisco JTAPI preferences application. The window title shows the JTAPI version number.
Figure 1 Trace Levels Tab
The Trace Level tab allows you to enable or disable the following JTAPI trace levels:
•WARNING—Low-level warning events
•DEBUG—Highest level debugging events
You may enable or disable additional debugging levels in the Debug Levels window, as described in the following list:
•JTAPI_DEBUGGING—JTAPI methods and events trace
•JTAPI_IMPLDEBUGGING—Internal JTAPI implementation trace
•CTI_DEBUGGING—Trace Cisco CallManager events that are sent to the JTAPI implementation
•CTIIMPL_DEBUGGING—Internal CTICLIENT implementation trace
•PROTOCOL_DEBUGGING—Full CTI protocol decoding
•MISC_DEBUGGING—Miscellaneous low-level debug trace
Figure 2 illustrates the Log Destination tab of the Cisco JTAPI preferences application.
Figure 2 Log Destination Tab
The Log Destination tab allows you to configure how JTAPI creates traces and how they are stored. Table 1 contains descriptions of the log destination fields.
Figure 3 illustrates the Cisco CallManager tab of the Cisco JTAPI preferences application.
Figure 3 CallManager Tab
This tab allows you to define a list of Cisco CallManagers that a JTAPI application can present to the user for optional Cisco CallManager connectivity.
Figure 4 illustrates the Advanced tab of the Cisco JTAPI preferences application.
Figure 4 Advanced Tab
You can configure the parameters in Table 2 through the Advanced tab in the JTPrefs application. You may need these low-level parameters for troubleshooting and debugging purposes only.
Note Cisco recommends that you not modify the parameters in Table 2 unless instructed to do so by Cisco Technical Assistance Center (TAC).
Figure 5 illustrates the Language tab of the Cisco JTAPI preferences application. From the Language Tab, you can select the supported language of your choice from the pull-down menu. Currently, only English, French, and German are supported.
Figure 5 Language Tab
JTAPI Preferences on non-Microsoft environments
For non-Microsoft environments, you must create a jtapi.ini file manually and place it in the CLASSPATH. The following list provides the parameter names with sample values:
Note Note: The jtapi.ini file can be generated by typing jview CiscoJtapiVersion -parms OR java CiscoJtapiVersion -parms. This displays the .ini parameters for the current CiscoJTAPI version and can be copied to a jtapi.ini file. (A file is not automatically generated to avoid multiple jtapi.ini files interfering with the normal running of the application
#Cisco Jtapi version 1.4(2) Release ini parameters#Wed Nov 20 16:28:15 PST 2002PROTOCOL_DEBUGGING=0UseSameDirectory=1JTAPIIMPL_DEBUGGING=0UseSystemDotOut=0QueueStatsEnabled=0PeriodicWakeupInterval=50RouteSelectTimeout=5000UseTraceFile=1ProviderOpenRequestTimeout=200CtiManagers=cm-server1,cm-server2;cm-server3Directory=TracesDEBUG=0DesiredServerHeartbeatInterval=30AlarmServicePort=1444CTI_DEBUGGING=0SyslogCollector=JTAPI_DEBUGGING=0PeriodicWakeupEnabled=0NumTraceFiles=10AlarmServiceHostname=MISC_DEBUGGING=0TracePath=.UseAlarmService=0CTIIMPL_DEBUGGING=0WARNING=0Traces=WARNING;INFORMATIONAL;DEBUGINFORMATIONAL=0UseSyslog=0JtapiPostConditionTimeout=15JTAPINotificationPort=789FileNameBase=seaviewCtiRequestTimeout=30TraceFileSize=2097152Debugging=JTAPI_DEBUGGING;JTAPIIMPL_DEBUGGING;CTI_DEBUGGING;CTIIMPL_DEBUGGING;PROTOCOL_DEB UGGING;MISC_DEBUGGINGFileNameExtension=logQueueSizeThreshold=25ProviderRetryInterval=30SyslogCollectorUDPPort=514
Administering User Information for JTAPI Applications
JTAPI applications require that users be administered in the directory and be given privilege to control one or more devices. Follow the procedures for adding a user and assigning devices to a user in the "Adding a New User" section before using a JTAPI application. The list of devices assigned to the user represents the phones that the user needs to control from the application (for example, make calls and answer calls).
These sections explain how to obtain documentation from Cisco Systems.
World Wide Web
You can access the most current Cisco documentation on the World Wide Web at this URL:
Translated documentation is available at this URL:
Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which is shipped with your product. The Documentation CD-ROM is updated monthly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual subscription.
You can order Cisco documentation in these ways:
•Registered Cisco.com users (Cisco direct customers) can order Cisco product documentation from the Networking Products MarketPlace:
•Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:
•Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco Systems Corporate Headquarters (California, U.S.A.) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).
You can submit comments electronically on Cisco.com. In the Cisco Documentation home page, click the Fax or Email option in the "Leave Feedback" section at the bottom of the page.
You can e-mail your comments to email@example.com.
You can submit your comments by mail by using the response card behind the front cover of your document or by writing to the following address:
Attn: Document Resource Connection
170 West Tasman Drive
San Jose, CA 95134-9883
We appreciate your comments.
Obtaining Technical Assistance
Cisco provides Cisco.com as a starting point for all technical assistance. Customers and partners can obtain online documentation, troubleshooting tips, and sample configurations from online tools by using the Cisco Technical Assistance Center (TAC) Web Site. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC Web Site.
Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.
Cisco.com is a highly integrated Internet application and a powerful, easy-to-use tool that provides a broad range of features and services to help you with these tasks:
•Streamline business processes and improve productivity
•Resolve technical issues with online support
•Download and test software packages
•Order Cisco learning materials and merchandise
•Register for online skill assessment, training, and certification programs
If you want to obtain customized information and service, you can self-register on Cisco.com. To access Cisco.com, go to this URL:
Technical Assistance Center
The Cisco Technical Assistance Center (TAC) is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two levels of support are available: the Cisco TAC Web Site and the Cisco TAC Escalation Center.
Cisco TAC inquiries are categorized according to the urgency of the issue:
•Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration.
•Priority level 3 (P3)—Your network performance is degraded. Network functionality is noticeably impaired, but most business operations continue.
•Priority level 2 (P2)—Your production network is severely degraded, affecting significant aspects of business operations. No workaround is available.
•Priority level 1 (P1)—Your production network is down, and a critical impact to business operations will occur if service is not restored quickly. No workaround is available.
The Cisco TAC resource that you choose is based on the priority of the problem and the conditions of service contracts, when applicable.
Cisco TAC Web Site
You can use the Cisco TAC Web Site to resolve P3 and P4 issues yourself, saving both cost and time. The site provides around-the-clock access to online tools, knowledge bases, and software. To access the Cisco TAC Web Site, go to this URL:
All customers, partners, and resellers who have a valid Cisco service contract have complete access to the technical support resources on the Cisco TAC Web Site. The Cisco TAC Web Site requires a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to this URL to register:
If you are a Cisco.com registered user, and you cannot resolve your technical issues by using the Cisco TAC Web Site, you can open a case online by using the TAC Case Open tool at this URL:
If you have Internet access, we recommend that you open P3 and P4 cases through the Cisco TAC Web Site.
Cisco TAC Escalation Center
The Cisco TAC Escalation Center addresses priority level 1 or priority level 2 issues. These classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer automatically opens a case.
To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to this URL:
Before calling, please check with your network operations center to determine the level of Cisco support services to which your company is entitled: for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). When you call the center, please have available your service agreement number and your product serial number.
CCIP, the Cisco Arrow logo, the Cisco Powered Network mark, the Cisco Systems Verified logo, Cisco Unity, Follow Me Browsing, FormShare, iQ Breakthrough, iQ Expertise, iQ FastTrack, the iQ Logo, iQ Net Readiness Scorecard, Networking Academy, ScriptShare, SMARTnet, TransPath, and Voice LAN are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, Discover All That's Possible, The Fastest Way to Increase Your Internet Quotient, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, the Cisco IOS logo, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherSwitch, Fast Step, GigaStack, Internet Quotient, IOS, IP/TV, LightStream, MGX, MICA, the Networkers logo, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, RateMUX, Registrar, SlideCast, StrataView Plus, Stratm, SwitchProbe, TeleRouter, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries.
All other trademarks mentioned in this document or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0208R)
Copyright © 2002, Cisco Systems, Inc.
All rights reserved.