Guest

Cisco Unified Communications Manager (CallManager)

Cisco JTAPI Installation Guide for Cisco CallManager 3.3

Hierarchical Navigation

Downloads

 Feedback

Table Of Contents

Cisco JTAPI Installation Guide for Cisco CallManager 3.3

Contents

Introduction

Installing the Cisco JTAPI Software

Verifying the Installation

Configuring Cisco JTAPI Tracing

Trace Levels

Log Destination

Cisco CallManager

Advanced

Language

JTAPI Preferences on non-Microsoft environments

Administering User Information for JTAPI Applications

Obtaining Documentation

World Wide Web

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco.com

Technical Assistance Center

Cisco TAC Web Site

Cisco TAC Escalation Center


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.

Contents

This document contains the following topics:

•Introduction

•Installing the Cisco JTAPI Software

•Verifying the Installation

•Configuring Cisco JTAPI Tracing

•JTAPI Preferences on non-Microsoft environments

•Administering User Information for JTAPI Applications

•Obtaining Documentation

•Obtaining Technical Assistance

Introduction

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.

Procedure

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:

http://Name/CCMAdmin/main.asp

where:

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.

Procedure

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>

where:

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:

•Trace Levels

•Log Destination

•Cisco CallManager

•Advanced

•Language

Trace Levels

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

•INFORMATIONAL—Status 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

Log Destination

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.

Table 1 Log Destination Configuration Fields 

Field
Description

Enable Alarm Service

When this option is enabled, JTAPI alarms go to an alarm service running on the specified machine. You must specify the host name and port number when enabling this option.

Use Java Console

When this option is enabled, tracing goes to the standard output or console (command) window.

Use Syslog

When this option is enabled, traces go to a UDP port as specified in the Syslog Collector and Port Number fields. Syslog collector service collects traces and directs them to the CiscoWorks2000 server.

Use Rotating Log Files

This option allows you to direct the traces to a specific path and folder in the system. No fewer than two log files and no more than 99 files can exist. Cisco JTAPI rotates through the log files in numerical order, returning to the first log file after filling the last. Log files increase in size in 1-megabyte increments.

Use the Same Directory

This option allows you to specify whether the same folder name should be used for each instance of an application.

When the option is enabled, JTAPI traces the log files to the same directory. In this case, successive instances of a JTAPI application will restart the log files starting at index 01.

When the option is disabled, each application instance, whether successive or simultaneous, will cause the trace files to be placed in a new folder sequential to the last folder written. Cisco JTAPI detects the last folder present in the trace path and automatically increments the numeric index.

Path

This field allows you to specify the path name to which the trace files are written. When the path is not specified, JTAPI makes the default the application path.

Directory Name Base

This field allows you to specify a folder name where the trace files will be contained.

File Name Base and File Name Extension

Use these values to create the trace file names with a numerical index appended to the file base name to indicate the order in which the files are created.

For example, if you enter jtapiTrace in the File Name Base field and log in the File Name Extension field, the trace files would rotate between jtapiTrace01.log, jtapiTrace02.log and jtapiTrace10.log. If the File Name Base and File Name Extension fields are left blank, Cisco JTAPI picks the trace files names as CiscoJtapi01.log, CiscoJtapi02.log, and so on.


Cisco CallManager

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.

Advanced

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

Table 2 Advanced Configuration Fields 

Field
Description

Enable Periodic Wakeup

This setting enables a heartbeat in the internal message queue that JTAPI uses. It causes the thread to wake up if it has not received a message in the time defined in the PeriodicWakeupInterval and creates log an event. The default setting is disabled.

Periodic Wakeup Interval (sec)

This setting allows you to define a time of inactivity in the JTAPI internal message thread. If JTAPI has not received a message during this time, the thread wakes up and logs an event. The default is 50 seconds.

Enable Queue Stats

This setting causes JTAPI to log the max queue depth over the specified number of messages queued to JTAPI main event thread. In other words, for every x messages processed, JTAPI logs a DEBUGGING level trace reporting the maximum queue depth over that interval, where x is the number of messages specified in Queue Size Threshold. The default setting is disabled.

Queue Size Threshold

This setting allows you to specify the number of messages that define the time over which JTAPI will report the maximum queue depth. The default is 25 messages.

CTI Request Timeout (sec)

This setting specifies the time in seconds that JTAPI will wait for a response from a CTI request. The default is 15 seconds.

Provider Open Request Timeout (sec)

This setting specifies the time in seconds that JTAPI will wait for a response for the Provider Open Request. The default is 30 seconds.

Provider Retry Interval (sec)

This setting specifies the time in seconds that JTAPI will retry opening a connection to the CallManager cluster in case of system failure. The default is 30 seconds.

Server Heartbeat Interval (sec)

This setting specifies how often in seconds that the connection between JTAPI and the Cisco CallManager cluster will be verified to be alive. If JTAPI fails to receive heartbeats, it will establish a connection via the second CTIManager specified in the provider open request.

Route Select Timeout (ms)

This setting specifies the time in milliseconds that JTAPI will wait for the application to respond to the Route event. If the application does not respond within this time, JTAPI will end the route and send the corresponding RouteEnd event.


Language

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 2002

PROTOCOL_DEBUGGING=0

UseSameDirectory=1

JTAPIIMPL_DEBUGGING=0

UseSystemDotOut=0

QueueStatsEnabled=0

PeriodicWakeupInterval=50

RouteSelectTimeout=5000

UseTraceFile=1

ProviderOpenRequestTimeout=200

CtiManagers=cm-server1,cm-server2;cm-server3

Directory=Traces

DEBUG=0

DesiredServerHeartbeatInterval=30

AlarmServicePort=1444

CTI_DEBUGGING=0

SyslogCollector=

JTAPI_DEBUGGING=0

PeriodicWakeupEnabled=0

NumTraceFiles=10

AlarmServiceHostname=

MISC_DEBUGGING=0

TracePath=.

UseAlarmService=0

CTIIMPL_DEBUGGING=0

WARNING=0

Traces=WARNING;INFORMATIONAL;DEBUG

INFORMATIONAL=0

UseSyslog=0

JtapiPostConditionTimeout=15

JTAPINotificationPort=789

FileNameBase=seaview

CtiRequestTimeout=30

TraceFileSize=2097152

Debugging=JTAPI_DEBUGGING;JTAPIIMPL_DEBUGGING;CTI_DEBUGGING;CTIIMPL_DEBUGGING;PROTOCOL_DEB
UGGING;MIS

C_DEBUGGING

FileNameExtension=log

QueueSizeThreshold=25

ProviderRetryInterval=30

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

Obtaining Documentation

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:

http://www.cisco.com

Translated documentation is available at this URL:

http://www.cisco.com/public/countries_languages.shtml

Documentation CD-ROM

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.

Ordering Documentation

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:

http://www.cisco.com/en/US/partner/ordering/index.shtml

•Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:

http://www.cisco.com/go/subscription

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

Documentation Feedback

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 bug-doc@cisco.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:

Cisco Systems
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

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:

http://www.cisco.com

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:

http://www.cisco.com/tac

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:

http://www.cisco.com/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:

http://www.cisco.com/tac/caseopen

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:

http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml

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.