Table Of Contents
Cisco Unified JTAPI Installation
Introduction
Determining the Current JTAPI Version
Installing the Cisco Unified JTAPI Software
Silent Install Invocation
Command Line Invocation
End User Installation
Installation Procedures
Linux and Solaris Platforms
Verifying Linux and Solaris Installation
Windows Platforms
Verifying Windows Installation
Configuring Cisco Unified JTAPI Preferences
JTAPI Tracing Tab
Log Destination Tab
Cisco Unified CallManagers Tab
Advanced Tab
Security Tab
Language Tab
Administering User Information for JTAPI Applications
Fields in the jtapi.ini File
Sample jtapi.ini file with default values
Cisco Unified JTAPI Installation
This chapter describes how to install and configure the Cisco Unified Java Telephony API (JTAPI) client software for Cisco Unified CallManager 5.0 and later releases.
This chapter contains the following topics:
•
Introduction
•Installing the Cisco Unified JTAPI Software
•Verifying Windows Installation
•Configuring Cisco Unified JTAPI Preferences
•Administering User Information for JTAPI Applications
Introduction
The Cisco Java Telephony API (JTAPI) implementation comprises Java classes that reside on all client machines that run JTAPI applications. Installation of the Cisco Unified JTAPI implementation must take place before these applications can function correctly. Make sure that the Cisco Unified JTAPI classes are installed wherever JTAPI applications run, whether on Cisco Unified CallManager, a separate machine, or both.
Previously, the system supported installation of the JTAPI client only on Windows platforms. With this release, the JTAPIInstaller provides a unified installation/uninstallation process for the JTAPI client for Linux, Windows, and Solaris, as listed in Table 2-1. For Linux and Solaris versions, the InstallShield MultiPlatform (ISMP) installer generates a binary file (.bin), and for the Windows version, it generates an executable file (.exe), after the set of files that need to be installed is obtained.
Table 2-1 Supported JVM Versions for Cisco Unified CallManager
Platform
|
OS Release(s)
|
Release 5.0
|
Linux
|
AS 3.0
|
SunJVM 1.5.0.4
|
| |
|
SunJVM 1.4.2
|
| |
|
IBM 1.4.2
|
| |
Red Hat 7.3
|
SunJVM 1.5.0.4
|
| |
|
SunJVM 1.4.2
|
| |
|
IBM 1.4.2
|
Solaris
|
6.2 on SPARC
|
SunJVM 1.5.0.4
|
| |
|
SunJVM 1.4.2
|
| |
|
IBM 1.4.2
|
Windows
|
9X
|
SunJVM 1.4.2
|
| |
|
IBM 1.4.2
|
| |
2000
|
SunJVM 1.5.0.4
|
| |
NT 4.0+
|
SunJVM 1.4.2
|
| |
XP (32 bit)
|
IBM 1.4.2
|
Note If you have upgraded to Cisco Unified CallManager 5.0, 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 as described in the Installing the Cisco Unified JTAPI Software section.
Upgraded JTAPI client software does not work with previous releases of Cisco Unified CallManager.
Determining the Current JTAPI Version
To know the version number of JTAPI from the installer, the following command needs to be used.
•CiscoJtapiVersion.exe - silent -W newversion.check="1" -goto showversion
•CiscoJtapiClient-linux.bin -silent -W newversion.check="1" -goto showversion
•CiscoJtapiClient-solarisSparc.bin -silent -W newversion.check="1" -goto showversion
•CiscoJtapiClient-solarisX86.bin -silent -W newversion.check="1" -goto showversion
A file called "jtapiversion.txt" is created in the same folder from where the command is executed and it will have the JTAPI version in the format A.B(C.D).
When a previous JTAPI version is present in the system and an upgrade is made to the current version of JTAPI, the installer invokes the uninstaller of the previous release. If you want to invoke the previous uninstaller in silent mode, then use the command:
CiscoJtapiClient.exe -silent -W newversion.silent="1"
Note This command is applicable only to Windows environments.
If it is installed, you can also use the JTAPI Preferences user interface utility tool to verify the installed JTAPI version.
Step 1 Choose Start > Programs > CiscoJTAPI > JTAPI Preferences. The following menu is displayed:
Step 2 Select the "ReadMe" file. This file designates the version of Cisco Unified JTAPI currently installed.
Installing the Cisco Unified JTAPI Software
You can install the Cisco Unified JTAPI software in either of two modes:
•Silent Install Invocation
•Command Line Invocation
•End User Installation
For the ISMP installer to run, the installer temporarily installs a Java Runtime Environment (JRE) version and uses it for its operation. The JRE is removed during uninstall operation.
Note Distribution of the JRE with the Cisco Unified JTAPIInstaller occurs in accordance with an agreement between Sun Microsystems, Inc., and Cisco Systems, Inc.
Silent Install Invocation
Applications can bundle the JTAPIInstaller along with their installation by using a silent install invocation of the JTAPIInstaller.
Applications that run the JTAPIInstaller in silent mode can use of the following commands:
•Linux platforms—CiscoJTAPIClient-linux -silent
•Solaris (Sparc) platforms—CiscoJTAPIClient-solarisSparc.bin -silent
•Solaris (X86) platforms—CiscoJTAPIClient-solarisX86.bin -silent
•Windows (Win9X, Win ME, Win2K, or WinXP) platforms—CiscoJTAPIClient.exe -silent
When performing a fresh install or an upgrade/downgrade, the JTAPIInstaller automatically detects the destination folders and does the silent install. The installer places the JTAPI Sample Applications and the JAR Files in the appropriate folders that the user specifies during installation or to the default folders in case of a silent install. However, if a previous version is present, the JTAPIInstaller does not know the apps path, so it creates the default folders, Lib and JTAPITools, and installs the apps in those folders.
For Windows clients, the JTAPIInstaller also updates the registry with the new install information. For Linux versions, it creates a file named jtapiver.ini in the user's home directory.
Command Line Invocation
To run the JTAPIInstaller interactively from the command line, enter one of the following commands from the command prompt:
•Linux platforms—CiscoJTAPIClient-linux.bin -console
•Solaris (Sparc) platforms—CiscoJTAPIClient-solarisSparc.bin -console
•Solaris (X86) platforms—CiscoJTAPIClient-solarisX86.bin -console
•Windows (Win9X, WinME, Win2K, or WinXP) platforms—CiscoJTAPIClient.exe -console
The command line mode is helpful for installing JTAPI in systems that do not have GUI support, such as Linux systems. A character-based menu, where the user is asked to provide a series of inputs based on the install time conditions, guides the entire installation procedure. This mode also provides all the other options that the GUI-based installer provides.
End User Installation
The JTAPI Installer uses a Java Foundation Classes (JFC) swing interface for the end user interface. The install procedure asks the user to provide a series of information and checks.
The uninstallers are created and installed in the target system, under the folder "_uninst." This folder is placed within the JTAPI application's path, which is normally C:\Program Files\JTAPITools for Windows and $HOME/.jtapi/bin for Linux). The user can invoke the uninstaller by using this path.
A log file named ismpInstall.txt (or ismpUninstall.txt) in the folder from which the installer/uninstaller is executed stores all details about the installation procedure. You can also use this file to check for any errors that may occur because it contains the entire list of traces of the various events that occur during product installation.
Installation Procedures
The following sections describe the installation procedures for the Linux, Solaris, and Windows platforms.
Linux and Solaris Platforms
Cisco Unified JTAPI supports multiple languages for the installation and JTAPI Preferences user interface.
The Cisco Unified JTAPIInstaller installs the following items on the local disk drive:
•JTAPI java classes in $HOME/.jtapi/lib
•JTAPI Preferences in $HOME/.jtapi/bin
•JTAPI sample applications (makecall, jtrace) in $HOME/.jtapi/bin
•JTAPI documentation in $HOME/.jtapi/bin/doc
Perform the following steps to install the Cisco Unified JTAPI software on a Linux/Solaris platform:
Step 1 Log in to the computer where you want to install the Cisco Unified JTAPI client software.
Step 2 Locate the appropriate ISMP installer and launch it.
•CiscoJTAPIClient-linux.bin - for Linux OS
•CiscoJTAPIClient-solarisSparc.bin - for Solaris Sparc OS
•CiscoJTAPIClient-solarisX86.bin - for Solaris X86 OS
Step 3 Follow the instructions that the Cisco Unified JTAPI Installer presents.
Note The installation software installs the Cisco Unified JTAPI software on the default drive.
In Linux, for example, the default directory is $HOME/.jtapi/lib
Verifying Linux and Solaris Installation
To ensure that the JTAPI installation has been done properly, perform the following steps:
Step 1 .jtapiver.ini file should be created in the $HOME directory
Step 2 JTAPI Program files and documentation should be present under the folder $HOME/.jtapi/bin.
This would include the makecall, jtrace, Locale_files, and doc folders.
Step 3 JTAPI Library should be present under the folder $HOME/.jtapi/lib.
This would include the jtapi.jar, jtracing.jar, and updater.jar files.
Step 4 After ensuring that jtapi.jar is present in the classpath, run the following command from the command line prompt of $HOME/.jtapi/bin ./_jvm/bin/java:
com.cisco.services.jtprefs.jtprefsFrame
This should bring up the JTPrefs GUI.
Note In the absence of the JTPrefs application, the jtapi.ini file can be generated by typing:
< jview | java > CiscoJtapiVersion -parms
A jtapi.ini file will be generated to the current directory.
During installation, users can choose a different folder than $HOME to install JTAPI. In this case, a folder called .jtapi will be created within the user selected folder and the bin and lib folders will be created within this folder for copying the corresponding files. For example, if the user chooses the folder name /home/jtapiuser/ the folder structure would be:
/home/jtapiuser/.jtapi/bin — which contains the makecall, jtrace, Locale_files, and doc folders.
/home/jtapiuser/.jtapi/lib — which contains the jtapi.jar, jtracing.jar, and updater.jar files
In this case, the command at Step 4 should be invoked from the /home/jtapiuser/.jtapi/bin folder.
Windows Platforms
Cisco Unified JTAPI supports multiple languages for the installation and JTAPI Preferences user interface. The Cisco Unified JTAPIInstaller installs the following items on the local disk drive:
•JTAPI java classes in %SystemRoot%\java\lib
•JTAPI Preferences in Program Files\JTAPITools
•JTAPI sample applications (makecall, jtrace) in Program Files\JTAPITools
•JTAPI documentation in Program Files\JTAPITools\doc
To install the Cisco Unified JTAPI software on a Windows platform perform the following steps:
Step 1 Log in to the computer where you want to install the Cisco Unified JTAPI client software.
Step 2 Close all Windows programs.
Step 3 Locate the ISMP installer (CiscoJTAPIClient.exe) and launch it.
Step 4 Follow the instructions presented by the Cisco Unified JTAPIInstaller.
Note The installation software installs the Cisco Unified JTAPI software on the default drive.
When Windows NT is installed, for example, the default directory is C:\WINNT\Java\lib.
Verifying Windows Installation
To verify the JTAPI Windows installation, you can use the makecall application that allows you to place a call via JTAPI. Perform the following steps to use the makecall application.
Step 1 From the Windows NT command line, navigate to the directory where you installed Cisco Unified JTAPI Tools. By default, this directory is C:\Program Files\JTAPITools.
Step 2 Execute the following command:
java CiscoJtapiVersion
Step 3 Execute the following command:
java makecall <server name> <login> <password> 1000 <phone1> <phone2>
where:
server name specifies the hostname or IP address of the Cisco Unified 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. Refer to the Cisco Unified CallManager Administration Guide for details.
For login and password, use the user ID and password that you configured in the Cisco Unified CallManager User Configuration window.
Configuring Cisco Unified JTAPI Preferences
Use the Cisco Unified JTAPI Preferences application (JTPREFS) to configure trace levels and trace destinations as well as several other system parameters. Installation of the Cisco Unified JTAPI Preferences into the Program Files\JTAPITools directory utility takes place by default. To open the Cisco Unified JTAPI Preferences utility, choose Start > Programs > Cisco Unified JTAPI > JTAPI Preferences.
This section, which describes how to use the Cisco Unified JTAPI Preferences application, includes the following:
•JTAPI Tracing Tab
•Log Destination Tab
•Cisco Unified CallManagers Tab
•Advanced Tab
•Security Tab
•Language Tab
JTAPI Tracing Tab
One change in the JTAPI Preferences user interface renames the former "Trace Levels" tab "JTAPI Tracing." This change highlights the fact that the JTAPI Tracing tab allows you to change trace settings only for the JTAPI layer. Security install tracing levels are enabled on the new Security Tab.
Figure 2-1 illustrates the JTAPI Tracing tab of the Cisco Unified JTAPI Preferences application. The window title shows the JTAPI version number.
Figure 2-1 JTAPI Tracing Tab
The JTAPI Tracing tab allows you to enable or disable JTAPI trace levels as listed in Table 2-2.
Table 2-2 JTAPI Trace Levels
SN
|
Jtapi.ini fields
|
Default
|
Min
|
Max
|
Description
|
1
|
Traces=INFORMATIONAL; DEBUG; WARNING
|
None
|
N/A
|
N/A
|
Trace levels. For individual levels, see the descriptions below.
|
2
|
INFORMATIONAL
|
None
|
N/A
|
N/A
|
Status events
|
3
|
DEBUG
|
None
|
N/A
|
N/A
|
Highest level debugging events
|
4
|
WARNING
|
None
|
N/A
|
N/A
|
Low-level warning events
|
You can enable or disable additional debugging levels in the Debug Levels window, as described in the following list:
|
5
|
JTAPI_DEBUGGING
|
None
|
N/A
|
N/A
|
JTAPI methods and events trace
|
6
|
JTAPIIMPL_DEBUGGING
|
None
|
N/A
|
N/A
|
Internal JTAPI implementation trace
|
7
|
CTI_DEBUGGING
|
None
|
N/A
|
N/A
|
Trace Cisco Unified CallManager events sent to JTAPI
|
8
|
CTIIMPL_DEBUGGING
|
None
|
N/A
|
N/A
|
Internal CTICLIENT implementation trace
|
9
|
PROTOCOL_DEBUGGING
|
None
|
N/A
|
N/A
|
Full CTI protocol decoding
|
10
|
MISC_DEBUGGING
|
None
|
N/A
|
N/A
|
Miscellaneous low-level debug trace
|
Log Destination Tab
The Log Destination tab allows you to configure how JTAPI creates traces and how they are stored.
Figure 2-2 illustrates the Log Destination tab of the Cisco Unified JTAPI preferences application. Table 2-3 contains descriptions of the log destination fields.
Figure 2-2 Log Destination Tab
Table 2-3 Log Destination Fields
SN
|
Jtapi.ini fields
|
Default
|
Min
|
Max
|
Description
|
16
|
UseAlarmService
|
0
|
NA
|
NA
|
When this option is enabled, JTAPI alarms go to an alarm service that is running on the specified machine. You must specify the host name and port number when enabling this option.
|
34
|
UseSyslog
|
FALSE
|
NA
|
NA
|
When this option is enabled, traces go to a UDP port as specified in the Collector and Port Number fields. Syslog collector service collects traces and directs them to the CiscoWorks2000 server.
|
14
|
Use Rotating Log Files
(SyslogCollector)
|
FALSE
|
NA
|
NA
|
Allows you to direct traces to a specific path and folder. No fewer than two log files and no more than 99 files can exist. Cisco Unified 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.
|
31`
|
Use Java Console
(UseSystemDotOut)
|
FALSE
|
NA
|
NA
|
When this option is enabled, tracing goes to the standard output or console (command) window.
|
Log File Settings
|
This section provides the following parameters and options:
|
33
|
Maximum Number of Log Files
(NumTraceFiles)
|
10
|
2
|
1000
|
Allows you to specify the maximum number of log files to be written.
|
15
|
Maximum Size of Log Files
(TraceFileSize)
|
1048576
|
1048576
|
NP
|
Allows you to specify the maximum size of log files to be written.
|
32
|
Use the Same Directory
(UseSameDirectory)
|
1
|
NA
|
NA
|
Allows you to specify whether the same folder name should be used for each instance of an application.
When this 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 this option is disabled, each instance of the application, whether successive or simultaneous, will cause trace files to be placed in a new folder sequential to the last folder that was written. Cisco Unified JTAPI detects the last folder present in the trace path and automatically increments the numeric index.
|
12
|
Trace Path
(TracePath)
|
.
|
NA
|
NA
|
Allows you to specify the path name to which trace files are written. When the path is not specified, JTAPI defaults to the application path.
|
41
|
Directory Name Base
(Directory)
|
.
|
NA
|
NA
|
Allows you to specify a folder name where the trace files will be contained.
|
26
|
File Name Base
(FileNameBase)
|
Cisco
Jtapi
|
NA
|
NA
|
Use this value to create the trace file name.
|
13
|
File Name Extension
(FileNameExtension)
|
log
|
NA
|
NA
|
A numerical index appended to the file base name indicates the order in which trace files are created.
If you enter "jtapiTrace" in the File Name Base field and "log" in the File Name Extension field, the trace files will be named jtapiTrace01.log, jtapiTrace02.log, and so on. If the File Name Base and File Name Extension fields are left blank, JTAPI picks the trace files names as CiscoJtapi01.log, CiscoJtapi02.log, and so on.
|
Cisco Unified CallManagers Tab
This tab allows you to define a list of Cisco Unified CallManagers that a JTAPI application can present to the user for optional Cisco Unified CallManager connectivity.
Figure 2-3 illustrates the Cisco Unified CallManagers tab of the preferences application.
Figure 2-3 Cisco Unified CallManagers Tab
Advanced Tab
You can configure the parameters in Table 2-4 through the Advanced tab in the JTPrefs application. You may need these low-level parameters for troubleshooting and debugging purposes only.
Figure 2-4 illustrates the Advanced tab of the preferences application.
Figure 2-4 Advanced Tab
Note Cisco strongly recommends that you not modify the parameters in Table 2-4 unless the Cisco Technical Assistance Center (TAC) instructs you to do so.
Table 2-4 Advanced Configuration Fields
SN
|
Jtapi.ini fields
|
Default
|
Min
|
Max
|
Description
|
27
|
Enable Periodic Wakeup
(PeriodicWakeupEnabled)
|
FALSE
(disabled)
|
NA
|
NA
|
Enables (or disables) a heartbeat in the internal message queue that JTAPI uses. If JTAPI has not received a message in the time defined in PeriodicWakeupInterval, it causes the thread to wake up and creates a log event.
|
29
|
Periodic Wakeup Interval
(PeriodicWakeupInterval)
|
50
|
NP
|
NP
|
Allows you to define a period of inactivity in the JTAPI internal message thread (in seconds). If JTAPI has not received a message during this time, the thread wakes up and logs an event.
|
25
|
Enable Queue Stats
(QueueStatsEnabled)
|
FALSE
(disabled)
|
NA
|
NA
|
Causes JTAPI to log the max queue depth over the specified number of messages that are queued to JTAPI main event thread.
For every x messages processed, JTAPI logs a DEBUGGING level trace that reports the maximum queue depth over that interval, where x is the number of messages specified in Queue Size Threshold.
|
30
|
Queue Size Threshold
(QueueSizeThreshold)
|
25
|
10
|
NP
|
Specifies the number of messages that define the interval over which JTAPI will report the maximum queue depth.
|
??
|
CTI Request Timeout
(CtiRequestTimeout)
|
15
|
10
|
NP
|
Specifies the number of seconds that JTAPI will wait for a response from a CTI request.
|
17
|
Provider Open Request Timeout
(ProviderOpenRequestTimeout)
|
200
|
10
|
NP
|
Specifies the number of seconds that JTAPI will wait for a response to a Provider Open Request.
|
24
|
Provider Retry Interval
(ProviderRetryInterval)
|
30
|
5
|
NP
|
Specifies the number of seconds that JTAPI will retry opening connection to a Cisco Unified CallManager cluster in case of system failure.
|
11
|
Server Heartbeat Interval
(DesiredServerHeartbeatInterval)
|
30
|
>0
|
NP
|
Specifies the interval at which the connection between JTAPI and the Cisco Unified CallManager cluster will be verified (in seconds).
If JTAPI fails to receive heartbeats, it will establish a connection via the second CTIManager that is specified in the provider open request.
|
23
|
Route Select Timeout
(RouteSelectTimeout)
|
5000
|
0
|
NP
|
Specifies the interval in milliseconds that JTAPI will wait for the application to respond to the Route event. If the application does not respond in this time, JTAPI ends the route and sends the corresponding RouteEnd event.
|
Security Tab
Figure 2-5 illustrates the new Security tab of the preferences application.
Figure 2-5 Security Tab
Application users need to configure the User Name, InstanceID, Authorization Code, TFTPServer IP-Address, and CAPFServer IP-Address parameters through the JTAPI Preferences application before invoking the JTAPI API or JTAPI Preferences to download/install certificates on the Application server.
You can use JTAPI Preferences to configure security profiles for one or more userName/instanceID pair. If an Application user has previously configured a security profile for a userName/instanceID pair, the security profile automatically populates when the user enters the username/instanceID and clicks any of the other edit boxes.
Apart from the GUI provided through JTAPI Preferences, an Application can also install a client certificate by calling the interface that is provided at CiscoJtapiProperties. When Interface UpdateCertificate() is called, the JTAPI client connects to the TFTP server to download the CTL file and extract certificates to the given certificate path, then connects to the CAPF server to download the client certificate and installs it into the given certificate path.
jtapi.ini files in comma separated value (CSV) format store users security records. Semicolons separate individual records. An example of a users security record follows:
SecurityProperty=user,123,12345,172.19.242.37,3804,172.19.242.37,69,.\\,true,false;<next record>; ...
You can configure the following parameters on the Security tab:
Table 2-5 JTAPI Security Configuration Fields
SN
|
Jtapi.ini fields
|
Default
|
Min
|
Max
|
Description
|
20
|
Enable Security Tracing
(SecurityTraceEnabled)
|
FALSE
|
NA
|
NA
|
You can enable (or disable) tracing for certificate install operations by checking this check box and choosing the desired trace level.
|
35
|
Select Trace Level
(SecurityTraceLevel)
|
0
|
0
|
2
|
You can choose one of three different trace levels:
•Error=0 — Logs error events
•Debug=1 — Logs debugging events
•Detailed=2 — Logs all events
|
42*
|
User Name
(Username)
|
NA
|
NA
|
NA
|
If Application users have previously configured a security profile for a userName/instanceID pair, that security profile automatically polulates when the user enters the username/instanceID and clicks any of the other edit boxes.
|
42*
|
Instance ID
(instanceID)
|
NA
|
NA
|
NA
|
Application instance identifier. If an application is connecting to CTIManager with the same user, then it needs to define an instanceID for each instance of the application to download the certificate Authorization String.
|
42*
|
Authorization String
(authcode)
|
NA
|
NA
|
NA
|
One time string used to download certificate.
|
42*
|
TFTP Server IP Address
|
NA
|
NA
|
NA
|
IP address of the TFTP server (normally the Cisco Unified CallManager IP Address).
|
42*
|
TFTP Server Port
|
69
|
NP
|
NP
|
The TFTP Server Port is defaulted to 69. Do not change this value unless the System Administrator advises you to do so.
|
42*
|
CAPF Server IP Address
|
NA
|
NA
|
NA
|
IP address of the CAPF server in dotted decimal.
|
42*
|
CAPF Server Port
|
3804
|
NP
|
NP
|
The CAPF Server Port number defaults to 3804; however, you can also configure this number in the Cisco Unified CallManager Administration. Ensure that the value that is entered through the JTAPI Preferences is the same as is configured in Cisco Unified CallManager Administration.
|
42*
|
Certificate Path
|
JTAPI.jar
location
|
NA
|
NA
|
The path where the Application wants server and client certificates installed. If blank, certificates are installed in the ClassPath of JTAPI.jar.
|
| |
Enable Secure Connection
|
FALSE
|
NA
|
NA
|
Check this option to enable a secure TLS connection to Cisco Unified CallManager. If this option is not checked, JTAPI cannot make a non-secure connection to CTI even if the certificate is updated/installed.
|
| |
Certificate Update Status
|
|
|
|
This field provides information on whether the certificate has been updated.
|
Language Tab
Figure 2-6 illustrates the Language tab of the preferences application.
Figure 2-6 Language Tab
The Language tab allows you to select one of the installed languages to view the configuration settings in that language. You can select the following languages:
Danish German Greek English
Spanish Finnish French Hungarian
Italian Japanese Dutch Norwegian
Polish Brazilian Portuguese Portuguese Russian
Swedish
Select a language, and the tabs will display with text in that language.
Administering User Information for JTAPI Applications
The JTAPI application requires that users be given the 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 the JTAPI application. The list of devices that are assigned to the user represents the phones that the user needs to control from the application (for example, make calls and answer calls).
Fields in the jtapi.ini File
Applications which run in non-GUI based platforms, where JTPrefs cannot be invoked, can write their own jtapi.ini file and place it along with jtapi.jar based on the values provided here. JTAPI will make use of these values to configure itself.
Applications should ensure that they provide valid data as described in Table 2-6. Applications are responsible for errors caused in JTAPI behavior due to improper jtapi.ini file values.
NA: Not Applicable
NP: Not Present
Table 2-6 Fields in jtapi.ini File
SN
|
Jtapi.ini fields
|
Default
|
Min
|
Max
|
Description
|
1
|
Traces=INFORMATIONAL; WARNING;DEBUG
|
None
|
NA
|
NA
|
Trace levels. For individual levels, please see the description below.
|
2
|
INFORMATIONAL
|
0
|
NA
|
NA
|
Status events
|
3
|
DEBUG
|
0
|
NA
|
NA
|
Highest level debugging events
|
4
|
WARNING
|
0
|
NA
|
NA
|
Low-level warning events
|
5
|
JTAPI_DEBUGGING
|
0
|
NA
|
NA
|
JTAPI methods and events trace
|
6
|
JTAPIIMPL_DEBUGGING
|
0
|
NA
|
NA
|
Internal JTAPI implementation trace
|
7
|
CTI_DEBUGGING
|
0
|
NA
|
NA
|
Trace Cisco Unified CallManager events that are sent to the JTAPI implementation
|
8
|
CTIIMPL_DEBUGGING
|
0
|
NA
|
NA
|
Internal CTICLIENT implementation trace
|
9
|
PROTOCOL_DEBUGGING
|
0
|
NA
|
NA
|
Full CTI protocol decoding
|
10
|
MISC_DEBUGGING
|
0
|
NA
|
NA
|
Miscellaneous low-level debug trace
|
11
|
DesiredServerHeartbeatInterval
|
30
|
>0
|
NP
|
Specifies how often, in seconds, the connection between JTAPI and the Cisco Unified CallManager cluster will be verified. If JTAPI fails to receive heartbeats, it will establish a connection via the second CTIManager that is specified in the provider open request.
|
12
|
TracePath
|
.
|
NA
|
NA
|
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.
|
13
|
FileNameExtension
|
log
|
NA
|
NA
|
A numerical index that is 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 Unified JTAPI picks the trace files names as CiscoJtapi01.log, CiscoJtapi02.log, and so on.
|
14
|
SyslogCollector
|
FALSE
|
NA
|
NA
|
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 Unified 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.
|
15
|
TraceFileSize
|
1048576
|
1048576
|
NP
|
Allows you to specify the maximum size of log files to be written.
|
16
|
UseAlarmService
|
0
|
NA
|
NA
|
When this option is enabled, JTAPI alarms go to an alarm service that is running on the specified machine. You must specify the host name and port number when enabling this option.
|
17
|
ProviderOpenRequestTimeout
|
200
|
10
|
NP
|
Specifies the time in seconds that JTAPI will wait for a response for the Provider Open Request. The default is 10 seconds.
|
18
|
JtapiPostConditionTimeout
|
15
|
10
|
20
|
JTAPI has post conditions for events and if the post condition is not met before a timeout, JTAPI will throw exceptions. This field is for setting the timeout value of such conditions.
|
19
|
ApplicationPriority
|
2
|
NA
|
NA
|
This field is used for prioritizing multiple provider open requests. Currently, JTAPI only sends a default value.
|
20
|
SecurityTraceEnabled
|
FALSE
|
NA
|
NA
|
Enables tracing for security related messages.
You can enable (or disable) tracing for certificate install operations by checking this box and selecting the desired trace level.
|
21
|
AlarmServicePort
|
1444
|
NP
|
NP
|
This field is used for sending alarms to a different server. Users can select the alarm server host name and port on which the service is running and JTAPI will send the alarms to the specified server and port.
|
22
|
AlarmServiceHostname
|
null
|
NA
|
NA
|
The alarm server host name.
|
23
|
RouteSelectTimeout
|
5000
|
0
|
NP
|
Specifies the time in milliseconds that JTAPI waits for the application to respond to the Route event. If the application does not respond in this time, JTAPI ends the route and sends the corresponding RouteEnd event.
|
24
|
ProviderRetryInterval
|
30
|
5
|
NP
|
Specifies the time in seconds that JTAPI will retry opening a connection to the Cisco Unified CallManager cluster in case of system failure.
|
25
|
QueueStatsEnabled
|
FALSE
|
NA
|
NA
|
Causes JTAPI to log the max queue depth over the specified number of messages that are queued to JTAPI main event thread. In other words, for every x messages processed, JTAPI logs a DEBUGGING level trace that reports the maximum queue depth over that interval, where x is the number of messages that are specified in Queue Size Threshold.
|
26
|
FileNameBase
|
CiscoJtapi
|
NA
|
NA
|
Use this value to create the trace file name.
|
27
|
PeriodicWakeupEnabled
|
FALSE
|
NA
|
NA
|
Enables (or disables) a heartbeat in the internal message queue that JTAPI uses. If JTAPI has not received a message in the time defined in PeriodicWakeupInterval, it causes the thread to wake up and creates a log event.
|
28
|
JTAPINotificationPort
|
2789
|
1
|
NP
|
Port through which JTAPI paramter changes are communicated to JTAPI applications during runtime.
|
29
|
PeriodicWakeupInterval
|
50
|
NP
|
NP
|
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.
|
30
|
QueueSizeThreshold
|
25
|
10
|
NP
|
Allows you to specify the number of messages that define the time over which JTAPI will report the maximum queue depth.
|
31
|
UseSystemDotOut
|
FALSE
|
NA
|
NA
|
This field is used to display traces on the console.
|
32
|
UseSameDirectory
|
1
|
NA
|
NA
|
Allows you to specify whether the same folder name should be used for each instance of an application.
When this 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 this option is disabled, each instance of the application, whether successive or simultaneous, will cause the trace files to be placed in a new folder sequential to the last folder written. Cisco Unified JTAPI detects the last folder in the trace path and automatically increments the numeric index.
|
33
|
NumTraceFiles
|
10
|
2
|
1000
|
Allows you to specify the maximum number of log files to be written.
|
34
|
UseSyslog
|
FALSE
|
NA
|
NA
|
When this option is enabled, traces go to a UDP port as specified in the Collector and Port Number fields. Syslog collector service collects traces and directs them to the CiscoWorks2000 server.
|
35
|
SecurityTraceLevel
|
0
|
0
|
2
|
Trace level for security messages
0 = Error, 1 = debug, 2 = detailed
|
36
|
|
|
|
|
|
37
|
UseTraceFile
|
TRUE
|
NA
|
NA
|
Enables the writing of logs to logFile Trace Writer.
|
38
|
CMAssignedAppID
|
0
|
NA
|
NA
|
Feature ID assigned to the application - this ID is preassigned by Cisco Unified CallManager.
|
39
|
|
|
|
|
|
40
|
CtiManagers
|
null
|
NA
|
NA
|
List of CTI Managers for which tracing needs to be collected.
|
41
|
Directory
|
.
|
NA
|
NA
|
Allows you to specify a folder name where the trace files will be contained.
|
42
|
Security Property
SecurityProperty=username, instanceId, authcode,
tftp ip address, tftp port,
capf ip address, capf port, certificate path, security option, certificate status
|
NA
|
NA
|
NA
|
Users security record (username, instanceId, authcode, tftp ip address, tftp port, capf ip address, capf port, certificate path, security option, certificate status), will be stored in jtapi.ini files in a comma separated string. Records are separated by a semicolon.
SecurityProperty=user,123,12345,172.19.242.37, 3804,172.19.242.37,69,.\\,true,false;<next record>;...
|
SECURITY PROPERTY DESCRIPTION
(This section should not to be added in jtapi.ini - it is only for description of the Security Property fileds.)
|
1
|
Username
|
NA
|
NA
|
NA
|
When Application users have previously configured a security profile for a userName/instanceID pair, that security profile is automatically polulated when the user types in username/instanceID and clicks any of the other edit boxes.
|
2
|
instanceId
|
NA
|
NA
|
NA
|
Application instance identifier. If an application is connecting to CTIManager with the same user, then it needs to define an instanceID for each instance of the application to download the certificate Authorization String.
|
3
|
authcode
|
NA
|
NA
|
NA
|
Authorization string configured in the Cisco Unified CallManager database; can be used only once for getting certificate.
|
4
|
CallManager TFTP IP address
|
NA
|
NA
|
NA
|
TFTP Address of Cisco Unified CallManager (normally the Cisco Unified CallManager IP Address)
|
5
|
CallManger TFTP port
|
69
|
NP
|
NP
|
Default value of 69 should not be changed unless advised to do so by the System Administrator.
|
6
|
CallManager CAPF IP server address
|
NA
|
NA
|
NA
|
CAPF Server IP Address
|
7
|
CallManager CAPF server port
|
3804
|
NP
|
NP
|
Default value is 3804; however, this is configurable in the Cisco Unified CallManager Admin service parameters page; value entered through this interface should be the same as that configured on Cisco Unified CallManager Admin page.
|
8
|
Certificate path
|
JTAPI.jar
location
|
NA
|
NA
|
Location where Application wants sever and client certificates to be installed. If this field is left blank, certificates will be installed in ClassPath of JTAPI.jar
|
9
|
Enable secure connection
|
TRUE
|
NA
|
NA
|
If this field is not set to TRUE, JTAPI will make a non-secure connection to CTI even if certificates are updated/installed.
|
10
|
Certificate Update Status
|
NA
|
NA
|
NA
|
JTPreference GUI can be used to configure security profile for one or more userName/instanceID pairs.
|
Sample jtapi.ini file with default values
#Cisco Unified JTAPI version 3.0(0.156) Release ini parameters
#Wed Sep 14 16:55:30 PDT 2005
DesiredServerHeartbeatInterval=30
ProviderOpenRequestTimeout=200
JtapiPostConditionTimeout=15
JTAPINotificationPort=2789
Traces=WARNING;INFORMATIONAL;DEBUG
PeriodicWakeupInterval=50
Debugging=JTAPI_DEBUGGING;JTAPIIMPL_DEBUGGING;CTI_DEBUGGING;CTIIMPL_DEBUGGING;
PROTOCOL_DEBUGGING;MISC_DEBUGGING
UseProgressAsDisconnectedDuringErrorEnabled=0
SyslogCollectorUDPPort=514
SecurityProperty=cisco,123,12345,A.B.C.D,3804,A.B.C.D,69,/C\:/Program
Files/JTAPITools/./,false,false;
