Cisco Unified JTAPI Developers Guide for Cisco Unified Communications Manager Release 7.0(1)
New and Changed Information
Downloads: This chapterpdf (PDF - 642.0KB) The complete bookPDF (PDF - 7.6MB) | Feedback

New and Changed Information

Table Of Contents

New and Changed Information

Cisco Unified Communications Manager Release 7.0(1)

Join Across Lines with Conference Enhancements

Locale Infrastructure Development

Do Not Disturb-Reject

Calling Party Normalization

Click to Conference

Extension Mobility Username Login

Java Socket Connect Timeout

selectRoute() with Calling Search Space and Feature Priority

Call Pickup

Cisco Unified Communications Manager Release 6.1

Certificate Download API Enhancement

Join Across Lines

Intercom Support for Extension Mobility

Cisco Unified Communications Manager Release 6.0

Recording and Silent Monitoring

Intercom

Arabic and Hebrew Language Support

Do Not Disturb

Secure Conferencing

Cisco Unified IP 7931G Phone Interaction

Version Format Change

Calling Party IP Address

Multilevel Precedence and Preemption Support

Non-Controller Adding of Parties to Conferences

Conference Chaining

Forwarding on No Bandwidth & Unregistered DN

Directed Call Park

Voice MailBox Support

Privacy On Hold

CiscoRTPHandle Interface on Cisco RTP Events

Hold Reversion

Translation Pattern Support

Calling Party IP Address

Cisco Unified Communications Manager Release 5.1

Join Across Lines

New Error Code in CiscoTermRegistrationFailedEv

Star (*) 50 Update

Call Forward Override

Cisco Unified Communications Manager Release 5.0

Partition Support

Hairpin Support

QoS Support

Transport Layer Security (TLS)

SIP Phone Support

SIP Phone Support

Secure Real-Time Protocol Key Material

SIP REFER/REPLACE

SIP 3XX Redirection

Terminal and Address Restrictions

Unicode Support

Linux, Windows, and Solaris Installation

Silent Install

Command Line Invocation

JTAPI Client Installer

JRE 1.2 and JRE 1.3 Support Removal

Superprovider and Change Notification

Alternate Script Support

Half-Duplex Media Support

Network Alerting

Auto Updater for Linux

Call Select Status

JTAPI Version Information

Backward Compatibility


New and Changed Information


This chapter describes new and changed JTAPI information for Cisco Unified Communications Manager Administration.It contains the following sections:

Cisco Unified Communications Manager Release 7.0(1)

Cisco Unified Communications Manager Release 6.1

Cisco Unified Communications Manager Release 6.0

Cisco Unified Communications Manager Release 5.1

Cisco Unified Communications Manager Release 5.0

Backward Compatibility

For more information, go to the Programming Guides website at http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_list.html.

Cisco Unified Communications Manager Release 7.0(1)

This section describes the new and changed features in Cisco Unified Communications Manager from Release 6.1 to Release 7.0(1) and Cisco Unified JTAPI enhancements. It has the following:

Join Across Lines with Conference Enhancements

Locale Infrastructure Development

Do Not Disturb-Reject

Calling Party Normalization

Click to Conference

Extension Mobility Username Login

Java Socket Connect Timeout

selectRoute() with Calling Search Space and Feature Priority

Call Pickup


Note The following IPv6 related methods are not supported in Cisco Unified Communications Manager Release 7.0(1):

canSupportIPv6()
setProviderOpenRetryAttempts (int retryAttempts)
getProviderOpenRetryAttempts()
getIPAddressingMode() (available on CiscoMediaTerminal and CiscoRouteTerminal interfaces)
register(java.net.InetAddress address, int port, CiscoMediaCapability [] capabilities, int[] algorithmIDs, java.net.InetAddress address_v6, int activeAddressingMode)
register(CiscoMediaCapability [] capabilities, int[] int registration Type, int[] algorithmIDs, int activeAddressingMode)
getTerminals() (available on new interface CiscoProviderTermCapabilityChangedEv)
getAddressingModeForMedia()
getCallingPartyIpAddr_v6() (available on CiscoCallCtlConnOfferedEv and CiscoRouteEvent interfaces)
CTIERR_IPADDRMODEMISMATCH
CTIERR_DYNREG_IPADDRMODE_MISMATCH
hasIPv6CapabilityChanged()
CiscoTerminal.IP_ADDRESSING_MODE_IPv4
CiscoTerminal.IP_ADDRESSING_MODE_IPv6
CiscoTerminal.IP_ADDRESSING_MODE_IPv4_v6
CiscoTerminal.IP_ADDRESSING_MODE_Unknown
CiscoTermRegistrationFailedEv.IP_ADDRESSING_MODE_MISMATCH


Join Across Lines with Conference Enhancements

The Join Across Lines with Conference enhancements are:

Conference chaining across lines; for example, applications can conference two conference calls in which each conference is on a different address but on the same terminal.

Applications can conference two calls on different addresses of the same terminal.

Add participants to a conference using a non-controller.


Note Join Across Lines can be disabled by turning off the Join Across Lines Policy service parameter, while Conference Chaining and the feature that allows Non-Controller adding participant to conference can be disabled by disabling the Advanced Ad Hoc Conference Enabled and Non-linear Ad Hoc Conference Linking Enabled service parameters.


The following is the behavior when an application issues a conference request but selected and active calls are not part of the conference request. It also applies for user selected calls which are not part of the conference request, but become part of the resulting conference:

The Active Call on a Terminal is always added to the resulting conference when conference is invoked on a call on any address on that terminal. Consider that B1 and B2 addresses are on the same terminal. Then:

A --> B1- GC1

C --> B1- GC2

D --> B2- GC3 (active call)

The application invokes GC1.conference (GC2) and results in A-B1-C-D in a conference with GC1, although the call with D was not part of the conference request.

An active conference call on a terminal is added to the resulting conference when conference is invoked on a call on any line on that terminal. In this case, the active conference call becomes the surviving final call (provided the application specified primary call is not a conference call).

In this example, the application specified primary call is cleared after the conference operation. It is possible that the application specified primary call may not join the resulting conference and in that case the call is not cleared after the conference is complete.

Consider that the B1 and B2 addresses on the same terminal and conf1 is a conference call with A-B1-C in conference with B1 as the controller. Then:

B1 --> D - GC1 (on hold)

conf1 - GC2 (active call)

B2 --> E - GC3 (on hold)

Application invokes GC1.conference(GC2, GC3). This will result in A-B1-C-D-E in conference with GC2 as the surviving call. Although application had specified GC1 to be the primary call, GC1 does not survive after the conference.

The behavior also applies to regular conferencing with a common controller. Consider A, B, C, and D are lines on different terminals. Then:

A --> B - GC1

C --> - GC2

D --> - GC3 (active call)

The application requests GC1.conference (GC2). This results in A-B-C-D in conference with GC1. Although a direct call with D was not part of the conference request, D joins the conference.

Interface Changes

There are no interface changes. You can use the current interfaces to conference calls on different addresses on the same terminal.

Message Sequences

Join Across Lines with Enhancements

Backward Compatibility

This feature is backward compatible.

Locale Infrastructure Development

This feature removes currently supported languages for JTAPI client install. JTAPI client install is only supported in English. It also adds the capability to dynamically update the locale in JTAPI Preference application from the Cisco Unified Communications Manager server. JTAPI Preference application will continue to support all the languages that are supported in prior releases. Support for adding new languages and updating locale files is also added.

Prior to this release, the JTAPI client install and JTAPI Preferences application were localized during builds and did not add support for new languages or update locales for existing languages. The JTAPI client locale updates were performed in Cisco Unified Communications Manager maintenance releases. This feature is adding capability to dynamically update locale file for JTAPI Preferences application. And JTAPI Client install will be only installable in English languages.

The JTAPI Client install needs the Cisco Unified Communications Manager TFTP server IPaddress. The TFTP IP address is used for downloading locale files for the preferences application. If the TFTP IP address is not entered or an incorrect IP address is entered, the preference application displays only in English language. Further on whenever new locale updates are available, JTAPI Preferences application will notify user about available updates and update locale files.

Interface Changes

There are no interface changes.

Message Sequences

Locale Infrastructure Development Scenarios

Backward Compatibility

This feature is backward compatible from the JTAPI Application perspective, but from the JTAPI Client install perspective, currently supported languages have been removed. In this regard, it is not backward compatible.

Do Not Disturb-Reject

Do Not Disturb-Reject (DND-R) is an enhancement to the existing DND feature. Cisco Unified Communications Manager and JTAPI previously supported only the Ringer off DND. The user can reject calls with DND-Reject. DND-R can be set from the phone configuration page or the phone profile configuration page in Cisco Unified Communications Manager Administration.

When DND-R is enabled, the call is not presented to the terminal that has Call Reject enabled. There is no audible or visual indication of incoming calls on that end point. To enable DND-R, set the DND Status as true and the DND option to Call Reject.

FeaturePriority overrides DND. It can have any of the following values:

1: Normal

2: Urgent

3: Emergency

FeaturePriority in connect() API on CiscoCall is introduced in this release. FeaturePriority in selectRoute() and redirect() API is already supported in prior releases. When feature priority as EMERGENCY is specified in connect() API, and the destination terminal has DND-R enabled, the call still rings at the destination terminal and overrides the DND-R settings.

When a terminal has DND-R enabled and receives an intercom call, DND-R settings are overridden and call presents. This is because feature priority is always 2 (URGENT) for intercom calls.

In non- shared line scenario where A calls B and Terminal B has DND-R enabled, CallCtlConnFailedEv with cause USER_BUSY is delivered on A. User would see the same behavior if we have DND-R enabled on all the terminals which have shared DNs

In the case of shared lines when at least one of the terminal does not have DND-R enabled and a call is placed to the shared line, then JTAPI delivers TermConnPassiveEv and CallCtlTermConnInUseEv for the terminals which have DND-R enabled (assuming the call was made with NORMAL feature priority). TermConnPassiveEv and CallCtlTermConnBridgedEv is delivered if DND-R is disabled on the terminal during a call.

A new event CiscoTermDNDOptionChangedEv will be sent to the terminal observer whenever the DND option changes on the phone page or Common Phone Profile page in Cisco Unified Communications Manager Administration.

Default DND option is Ringer-off and Route points do not support DND.

Interface Changes

CiscoTermDNDOptionChangedEv; CiscoCall; CiscoTermEvFilter

Message Sequences

DND-R

Backward Compatibility

This feature is backward compatible. Application will see new events if this feature is configured. The new events are filterable through TerminalEventFilter interface (CiscoTermEvFilter). By default filter is disabled and the new events are not delivered.

Calling Party Normalization

Calling Party Normalization (CPN) is an enhancement. This feature provides the option to transform or normalize the incoming call number and convert into the E.164 format, which includes the (country code, state code, and number type). The number type field identifies the subscriber, national, international, or unknown. The number type is not supported in conference scenarios.

Interface Changes

This feature introduces a new method in CiscoCall that is getGlobalizedCallingParty() and a new method in CiscoPartyInfo that is getNumberType(). See CiscoCall and CiscoPartyInfo for more information.

Message Sequences

Calling Party Normalization

Backward Compatibility

This feature is backward compatible.

Click to Conference

Click to conference feature provides interfaces on SIP trunk for applications such as Instant Messenger (IM) to add parties to a conference. Users can add other parties to a conference or remove parties using such applications. When click to conference is used to add a party to conference, a call is offered to the target address. Only one connection for target address is created on this initial call. This call is then added to conference resulting in a new callID for the call on the target address and connections for other addresses in the call are created on the new call.

This section describes the interface changes done in Cisco JTAPI to handle the interactions when an address is added to a conference using click to conference feature. When click to conference feature is used there is no consult call and JTAPI applications would not receive CiscoConferenceStartEv or CiscoConferenceEndEv.

The feature can be disabled by turning off the "ENABLE CLICK TO CONFERENCE" CallManager service parameter.

Interface Changes

CiscoFeatureReason

Message Sequences

Click to Conference

Backward Compatibility

This feature is backward compatible. No change in JTAPI applications when this feature is not configured or used.

Extension Mobility Username Login

The Extension Mobility Login Username enables applications to get the Extension Mobility login username from the API provided on CiscoTerminal.

Interface Changes

CiscoTerminal

Message Sequences

Extension Mobility Login Username

Java Socket Connect Timeout

The Java Socket Connect Timeout enhancement enables the configuration of a timeout in seconds using the Cisco Unified JTAPI specification and prevents connection delays to the CTIManager when the primary CTI Manager. The default is 15 seconds.

If the default of 15 seconds is unacceptable to the application, the default JAVA API of zero (0) sets the behavior to the normal JAVA Socket Connect API.

The range of values are 5 through 180 seconds. Zero defaults to Java behavior of the socket connet without any time out for connection.

Interface Changes

CiscoJtapiProperties

Message Sequences

CiscoJtapiProperties

Backward Compatibility

This features is backward compatible.

selectRoute() with Calling Search Space and Feature Priority

The selectRoute() has feature priority and calling search space parameters as an array. This API provides the flexibility of different feature priorities and calling search spaces for each route selected.

Interface Changes

CiscoRouteSession

Message Sequences

selectRoute() with Calling Search Space and Feature Priority

Backward Compatibility

This feature is backward compatible. The selectRoute() API remains functional and interoperates with the overloaded selectRoute() API.

Call Pickup

Call Pickup enables devices within a Call Pickup Group to be alerted that another phone in the group is ringing and to pick up the call—taking it from the original ringing device.

With this enhancement, Cisco Unified Communications Manager JTAPI supports observing terminals and addresses at which call pickup events are happening, however, it does not provide API to invoke call pickup operations from the application. This is a small change in the way the API handles Call Pickup events when the Auto Call Pickup service parameter is enabled. If this parameter is disabled, when a user presses their Pickup softkey, their phone begins to ring, and they have all the normal actions available to them. If "Auto Call Pickup" is enabled, pressing the softkey immediately picks up the call without ringing.

Interface Changes

There are no interface changes.

Message Sequences

Call Pickup

Backward Compatibility

This feature is backward compatibility.

Cisco Unified Communications Manager Release 6.1

This section describes the new and changed features in Cisco Unified Communications Manager from Release 6.0 to Release 6.1 and Cisco Unified JTAPI enhancements. It has the following:

Certificate Download API Enhancement

Join Across Lines

Intercom Support for Extension Mobility

Certificate Download API Enhancement

Currently JTAPI certificate download API has some security issues, to solve the problem new certificate download APIs are provided. New APIs will require applications to specify a certificate pass phrase and the certificate pass phrase will be used for encrypting Java key store where client/server certificates are stored.

Old certificate download APIs are deprecated, however it will still be around for some time to avoid backward compatibility issue for applications. However it is highly recommended for application to migrate to new APIs.

JTAPI will also provide new API deleteCertificate() and deleteSecurityPropertyForInstance() which can be used by application to delete certificate which are already installed. If application want to change pass phrase for certificate java key store, it need to delete old certificate using this API and upload new certificate.

JTAPIPreferences UI security tab is enhanced to provide two new buttons one for DeleteCertificate and another for Update Certificate. DeleteCertificate button will allow users to delete certificate for required username/instanceID. Update Certificate button will allow users to upload certificate from CAPF server. If certificate update is successful, certificate update box will be updated to show Updated, authorization string and certificate pass phrase will be cleared. If certificate update operation fails, certificate box will continue to show status Not Updated status unless certificate was previously updated. User/Applications need to provide certificate pass phrase every time they try to update certificate, JTAPI will not save certificate pass phrase for security reason in any circumstances, it would be applications responsibility to secure the pass phrase and provide through API when needed.

Backward Compatibility

This feature should be backward compatible.

Join Across Lines

In this version this feature will allow applications to conference 2 calls which are on different addresses of the same terminal. It will also let applications add participants to a conference using a non-controller. Join across lines is supported on CTI-supported SIP phones.

Join across lines feature can be disabled by turning off "Join Across Lines Policy" service parameter, while Conference Chaining and feature to allow Non-Controller adding participant to conference can be disabled by disabling the "Advanced Ad Hoc Conference Enabled" and "Non-linear Ad Hoc Conference Linking Enabled" service parameters.


Note Join Across Lines is supported only on SCCP phones.


Interface Changes

There are no interface changes for this feature. Applications can use the current conference interfaces to conference calls on different addresses on the same terminal.

Backward Compatibility

This feature should be backward compatible.

Intercom Support for Extension Mobility

In 6.0(1) Cisco Unified Communication Manager, we added support for intercom feature. Intercom feature requires destination to be auto-answered with one-way audio, therefore, no shared addresses can be configured for intercom. However when user login using Extension Mobility (EM) profile, it is possible to end up with shared address for intercom, hence currently Extension Mobility is not supported with intercom. Due to the wide use of Extension Mobility, this CIA is addressing the need to support intercom for Extension Mobility while still maintaining the single destination non-sharable nature of intercom addresses.

This feature requires intercom addresses to be configured with default terminal, and allows configuring of intercom address on EM profile. When user EM login to a terminal with EM profile that is configured with an intercom address, intercom address will only be available if default terminal of intercom address is same as terminal where user has logged in. If an intercom address is configured on terminal but default terminal for intercom address is not that terminal, intercom address will not appear on terminal. If this terminal is configured in the control list of JTAPI application, JTAPI will not create intercom address in the provider domain. From JTAPI point of view, there is no new interface or changes needed to support this feature. However this feature introduces some transitional scenarios where intercom functionality may not work on intercom addresses. Please see the used cases.

Backward Compatibility

This feature should be backward compatible.

Cisco Unified Communications Manager Release 6.0

This section describes the new and changed features in Cisco Unified Communications Manager, Release 6.0 and Cisco Unified JTAPI enhancements. It has the following:

Recording and Silent Monitoring

Intercom

Arabic and Hebrew Language Support

Do Not Disturb

Secure Conferencing

Cisco Unified IP 7931G Phone Interaction

Version Format Change

Multilevel Precedence and Preemption Support

Non-Controller Adding of Parties to Conferences

Conference Chaining

Forwarding on No Bandwidth & Unregistered DN

Directed Call Park

Voice MailBox Support

Privacy On Hold

CiscoRTPHandle Interface on Cisco RTP Events

Hold Reversion

Translation Pattern Support

Calling Party IP Address

Recording and Silent Monitoring

This feature lets applications record and silently monitor calls. The caller represents the end point, which calls or receives a call from the monitor target or the recording initiator. The monitor target is the party to monitor (the agent), and the monitoring party is the monitor initiator (the supervisor).

The recording feature lets applications record conversations on any observed address. There are three recording configurations available:

No recording

Automatic recording

The system initiates a recording session, and streams media to the configured recording device whenever a call goes to a connected state.

Application-controlled recording

If application-controlled recording is configured on an address, the application can start and stop recording. The call must exist in the connected state before the application can start recording.

The administrator can set up any one of these recording configurations on a line.

On the successful setup of a recording session that is triggered by either auto recording or an application request, the system sends two audio streams to the recording device: the audio from the recording initiator and the audio from the caller.

The silent monitoring feature lets applications listen to a live conversation between two other parties. The monitor initiator cannot talk to either the monitor target or the caller.

Only an application request can initiate monitoring. The application must send a monitor request for each call that it wants to monitor. The system can only monitor calls that are in a connected state. On the successful completion of a monitor request, the audio stream between the monitor target and the caller streams to the monitor initiator. The monitor target will receive a tone

If the monitor target is configured to receive a tone

If the application requests a tone when it starts the monitor

The recording and silent monitoring features do not support secured calls. Ensure security is disabled on devices that are monitor targets or recording initiators.

Two user groups in Cisco Unified Communications Manager Administration support the recording and silent monitoring feature. Applications can record and monitor calls if they belong to the Standard CTI Allow Call Recording and Standard CTI Allow Call Monitor user groups respectively. The system delivers recording- and monitoring-related events to all call observers. Application see these events if they do not belong to the two special groups.

"Monitor" and "Recording" are reserved words that should not be configured as display names for any lines in the system. Other reserved words are "Conference," "Park Number," "Barge," and "CBarge."

When a monitoring session is established, the terminal observer on the monitoring initiator receives Cisco RTP events. Although the media for a silent monitoring call flows only in one direction, getMediaConnectionMode() would return CiscoMediaConnectionMode.TRANSMIT_AND_RECEIVE instead of CiscoMediaConnectionMode.RECEIVE_ONLY. Applications should expect to see the same behavior in CiscoMediaOpenLogicalChannelEv if a CTIPort is used as the monitor initiator.

When a monitoring call (the call used by the monitor initiator) is conferenced, the final call does not have any connection to the monitor target. When the monitor initiator conferences another party into a monitoring call, both parties can hear the audio between the monitor target and the caller.

The following interfaces extend TermConnEv and are delivered to callobserver. For shared lines, the system delivers these events to call observers on the address or terminal of the talking terminal connections. Applications see no events if they only the terminal whose connection is in the INUSE or BRIDGED state.

CiscoTermConnRecordingStartedEv

CiscoTermConnRecordingStartedEv
 
   

Indicates the start of recording and is delivered to the call observer of the recording initiator. Auto recording configuration or by an application request can trigger recording.

CiscoTermConnRecordingEndEv

CiscoTermConnRecordingEndEv
 
   

Indicates the end of recording and is delivered to the recording initiator.

CiscoTermConnMonitoringStartEv

CiscoTermConnMonitoringStartEv
 
   

Indicates the start of monitoring and is delivered to the call observer on the monitor target. Using getMonitorType() on this event will return the monitor type.

CiscoTermConnMonitoringEndEv

CiscoTermConnMonitoringEndEv
 
   

Indicates the end of monitoring and is delivered to the call observer on the monitor target.

CiscoTermConnMonitorInitiatorInfoEv

Exposes monitor initiator information and is delivered to the call observer of the monitor target. This interface has one method:

CiscoMonitorInitiatorInfo getCiscoMonitorInitiatorInfo ()

Returns a CiscoMonitorInitiatorInfo that exposes the terminal name and address of the monitor initiator.

CiscoTermConnMonitorTargetInfoEv

Exposes monitor target information and is delivered to the call observer of monitor target. This interface has one method:

CiscoMonitorInitiatorInfo getCiscoMonitorTargetInfo()

Returns a CiscoMonitorInitiatorInfo that exposes the terminal name and address of the monitor target.

Two new error codes notify applications about monitoring failures:

CTIERR_PRIMARY_CALL_INVALID would be returned by CiscoException.getErrorCode() for exceptions that occurred when a monitoring request fails due to the call going idle or getting transferred.

CTIERR_PRIMARY_CALL_STATE_INVALID would be returned when the monitoring request fails due to the call transitioning to a different state where monitoring cannot be invoked.

This release introduces a new AddressType, MONITORING_TARGET. JTAPI creates a connection on an address of this type for a monitoring target address, CiscoAddress.getType() returns this value.

Backward Compatibility

This feature is backward compatible. Applications will not see any new events unless this feature is configured and used on one of the application-controlled addresses. The administrator can enable this feature by adding JTAPI application users to the Standard CTI Allow Call Recording and Standard CTI Allow Call Monitor user groups.

For detailed information about these interface changes, see the following topics:

CiscoJtapiException

CiscoAddress

CiscoCall

CiscoMediaTerminalConnection

CiscoMediaTerminalConnectionCapabilities

CiscoMonitorTargetInfo

CiscoMonitorInitiatorInfo

CiscoProvider

CiscoProviderCapabilities

CiscoProviderCapabilityChangedEv

CiscoProviderObserver

CiscoRecorderInfo

CiscoTerminalConnection

CiscoTermConnMonitorInitiatorInfoEv

CiscoTermConnMonitorTargetInfoEv

CiscoTermConnRecordingTargetInfoEv

Intercom

The Intercom feature allows one user to call another user and have the call answered automatically with one-way media from the caller to the called party, regardless of whether the called party is busy or idle. The called user can press the talk back softkey (unmarked key) on their phone display, or the called user can invoke the join() JTAPI API, that is provided on TerminalConnection, to start talking to the caller. Only a specially-configured intercom address on the phone can initiate an intercom call. JTAPI creates a new type of address object named CiscoIntercomAddress for intercom addresses that are configured on the phone. The application can get all of the CiscoIntercomAddress that are present in the provider domain by calling the interface getIntercomAddresses () on CiscoProvider.

An intercom call can be initiated from the JTAPI interface by calling the CiscoIntercomAddress.ConnectIntercom () interface. The application provides an intercom target DN for this interface. If the intercom target DN is preconfigured or preset by the application, the application can get the target DN by calling the CiscoIntercomAddress.getTargetDN() interface; otherwise, the application must provide a valid intercom target for the call to be successful.

An intercom call is autoanswered at the intercom target; JTAPI will move TerminalConnection/CallCtlTerminalConnection at the intercom target to the Passive/Bridged state. The application can invoke a join () interface on the TerminalConnection of the intercom target to initiate talk back. If join () is successful, the TerminalConnection/CallCtlTerminalConnection of the intercom target will move to an Active/Talking state. For an intercom call, JTAPI only supports the following interfaces:

Call.drop ()

Connection.disconnect ()

CallCtlTerminalConnection.join ()

The application cannot perform any feature operations on an intercom call. JTAPI will throw an exception if the application invokes redirect, consult, transfer, conference, or park for a Connection on a CiscoIntercomAddress. The application will also receive an exception if it tries to invoke setForwarding (), getForwarding (), cancelForwarding (), unPark (), setRingerStatus (), setMessageWaiting (), getMessageWaiting (), setAutoAcceptStatus (), or getAutoAcceptStatus () on CiscoIntercomAddress.

Applications can get the value of a configured intercom target DN and the label on a CiscoIntercomAddress from the provided API. JTAPI provides two types of APIs: one to return the default and another to return the current value set for the intercom target. The default value is the intercom target DN and label that are preconfigured through Cisco Unified Communications Manager Administration. The current value is the interim target DN and label that are set by the application. If the application has not set the any value, the current value will be same as the default value. Applications can invoke the API setIntercomTarget () on CiscoIntercomAddress to set the intercom target DN, label, and unicode label. Only one application is allowed to set the intercom target, label, and unicode label for an intercom address. If two applications try to set the value, the first succeeds, and the second receives an exception. When a intercom target DN and label changes, JTAPI provides a CiscoAddressIntercomInfoChangedEv to the AddressObserver that is added to CiscoIntercomAddress. If the application has set an intercom target DN and label, and a JTAPI or CTI failover or failback occurs, JTAPI or CTI will restore the previously set value of the intercom target DN, label, and unicode label. If the JTAPI or CTI cannot restore the intercom target DN, label, or unicode label, JTAPI provides a CiscoAddrIntercomInfoRestorationFailedEv to the AddressObserver on CiscoIntercomAddress. In the case of an application failure, or if for any reason the application goes down, the target DN, label, and unicode label will reset to the default. JTAPI provides the interface resetIntercomTarget () on the CiscoIntercomAddress to reset the intercom target.

Auto-answer always stays enabled for CiscoIntercomAddress. The application can invoke the method getAutoAnswerEnabled () on CiscoAddress to get the auto-answer capability of an address.

For an intercom target that is connected with one-way media to the Intercom initiator, the device state would be set to CiscoTermDeviceStateWhisper. This is a new device state for the Terminal object. In this state, the Terminal can initiate a new call or receive a new incoming call. If the application enables a filter to receive this device state, the application receives CiscoTermDeviceStateWhisperEv. The application can enable a filter by calling setDeviceStateWhisperEvFilter() on CiscoTermEvFilter. The DeviceStates DEVICESTATE_ACTIVE, DEVICESTATE_HELD, DEVICESTATE_ALERTING all override DEVICESTATE_WHISPER; if one call exists in either the active, held, or alerting state, and another in whisper, the DeviceState will be DEVICESTATE_ACTIVE, DEVICESTATE_HELD, or DEVICESTATE_ALERTING, respectively.


Note The Cisco JTAPI implements the javax.telephony.TerminalConnection interface join() to let the intercom target talk back to the initiator. The system implements this interface for CiscoIntercomAddresses only. If applications invoke this interface for regular shared lines in a passive or bridged state, JTAPI throws a MethodNotImplimented exception.



Tip This feature is backward compatible if the application-controlled devices (Terminals) do not have intercom lines configured on them. Applications can disable the intercom feature by not having an intercom line configured on the application-controlled devices (terminals).


For detailed information about these interface changes, see the following topics:

CiscoIntercomAddress

CiscoAddrIntercomInfoRestorationFailedEv

CiscoAddress

CiscoCall

CiscoProvider

CiscoTermEvFilter

CiscoTerminal

CiscoTerminalConnection

CiscoTermDeviceStateWhisperEv

Arabic and Hebrew Language Support

This version of the Cisco JTAPI supports the Arabic and Hebrew languages, which users may select during installation and in the Cisco JTAPI Preferences user interface.

Backward Compatibility

This feature is backward compatible.

Do Not Disturb

Do-Not-Disturb (DND) gives phone users the ability to go into the DND state on the phone when they are away from their phones or do not want to answer the incoming calls. The DND softkey enables and disables this feature.

From the user pages, users can configure the following settings for DND:

DND Option-Ringer off

DND Incoming Call Alert-beep only/flash only/disable

DND Timer-value between 0-120 minutes. It specifies a "period in minutes to remind the user that DND is active".

DND status-on/off


Note The Application can only enable or disable the DND status.


The Application can set the DND status by invoking a new interface on CiscoTerminal.

JTAPI will also query the application about any change in the DND status when DND status is set by phone, Cisco Unified Communications Manager Administration, or application.

The application must enable the filter in CiscoTermEvFilter to receive the preceding notification.

The application can also query for the DND status through a new interface on CiscoTerminal.

The application can also query for the DND option through a new interface on CiscoTerminal.


Note This feature applies to phones and CTI ports. It does not apply to Route points.


In the case of emergency calls (made by a CER application) landing on an application that has DND enabled, the system overrides the DND settings and presents the call to the application. A new parameter, FeaturePriority, in the redirect() and selectRoute() APIs on CiscoCall, CiscoConnection, and CiscoRouteSession, respectively, makes this possible. The CER application that initiates the emergency call sets FeaturePriority as FeaturePriority_Emergency. The application will set the feature priority only for emergency calls. In the case of normal calls, applications will either not set the feature priority at all or set it to FeaturePriority_Normal. Applications will not set FeaturePriority_Emergency in case of normal calls. When initiating feature calls such as Intercom, applications need to specify FEATUREPRIORITY_URGENT.


Note The connect() API on CiscoCall does not support the FeaturePriority parameter.


The application will receive an exception if it tries to perform a getDNDStatus(), setDNDStatus() or getDNDOption() before the device is in service.

A Post condition has been added to DND to handle a DB update failure or device out-of-service situations if they occur after the setDNDStatus() request is sent. If a DB update failure or device out-of-service condition occurs after the setDNDStatus() request is sent, setDNDStatus() delivers a CiscoTermDNDStatusChangedEv to the application. If this event is not received, a post-condition time-out occurs, and the following exception is thrown: could not meet post conditions of setDNDStatus().

Backward Compatibility

This feature is backward compatible. Applications will see new events if this feature is configured. You can filter the new events through the TerminalEventFilter interface (CiscoTermEvFilter). By default this filter is disabled and the system does not deliver the new events.

For additional information, see the following topics:

CiscoTerminal

CiscoTermDNDStatusChangedEv

CiscoTermEvFilter

CiscoCall

CiscoConnection

CiscoRouteSession

CiscoTermInServiceEv

Secure Conferencing

This feature informs applications whether a call is secure, allowing for secure conference calls. When the overall security status of the call changes, secure conferencing provides applications with a notification in the form of an event on the call. Applications receive the overall call security status of the call in the CiscoCallSecurityStatusChangedEv when the overall call security status changes. When a terminal goes to the talking state, JTAPI provides the call security status information to the applications. Applications can query the security status of the call by using a new interface on CiscoCall. The system makes the security status information available to applications when the applications start monitoring an existing call.

In shared address scenarios, the system also reports CiscoCallSecurityStatusChangedEv to the RIU parties. The OverallCallSecurityStatus matches the status reported on the active terminals. For example, in a three-party conference with A (Encrypted), B (Encrypted), C (Authenticated), and C' (Authenticated), the system reports CiscoCallSecurityStatusChangedEv with OverallCallSecurityStatus = Authenticated to C and C'. The system delivers this event on a per-call basis.

SRTP key information will continue to be sent for encrypted parties whether or not the OverallCallSecurityStatus is Encrypted. For example, in a three-party conference with A (Encrypted), B (Encrypted), and C (non-secure), the OverallCallSecurityStatus of the conference call is NotAuthenticated. However, the media connecting A, B, and the conference bridge will continue to be Encrypted because they are encrypted parties. Thus, A and B will receive SRTP keys despite the OverallCallSecurityStatus.


Tip


Backward Compatibility

This feature is backward compatible. The new parameter "EnableSecurityStatusChangedEv" in the jtapi.ini file controls the new event CiscoCallSecurityStatusChangedEv generated by the secure conferencing feature. Applications can turn on this parameter by adding the line "EnableSecurityStatusChangedEv=1" to the jtapi.ini file to receive this new event. By default, this parameter does not appear in the jtapi.ini file, so event notification is disabled. The setCallSecurityStatusChangedEv() interface on com.cisco.jtapi.extensions.CiscoJtapiProperties lets applications set this ini parameter programmatically.

For additional information, see CiscoCallSecurityStatusChangedEv.

Cisco Unified IP 7931G Phone Interaction

You can configure Cisco Unified IP 7931G phones in two modes:

NoRollOver

RollOver (across the same DN or across different DNs).

When Cisco Unified IP 7931G phones are configured in NoRollOver mode, they operate like regular SCCP phones, and in this mode transfers or conferences cannot be made across the different addresses. JTAPI will support controlling and monitoring of a 7931G phone when it is configured in NoRollOver mode.

In RollOver mode, Cisco Unified IP 7931G phones support transfer or conference across different addresses. In this mode, JTAPI does not allow controlling and monitoring of a Cisco Unified IP 7931G phone. Applications see such terminal/addresses as restricted. If a Cisco Unified IP 7931G phone is in the control list of an application user and the phone configuration changes from NoRollOver to RollOver mode, JTAPI sends a CiscoAddrRestrictedEv event for addresses on the Cisco Unified IP 7931G phone and sends a CiscoTermRestrictedEv for terminals, with cause CiscoRestrictedEv.CAUSE_UNSUPPORTED_DEVICE_CONFIGURATION.

However, if the phone configuration changes from RollOver to NoRollOver mode, JTAPI sends a CiscoAddrActivatedEv event for addresses on the Cisco Unified IP 7931G phone and sends a CiscoTermActivatedEv for terminals.

If a Cisco Unified IP 7931G phone that is configured in RollOver mode transfers or conferences to JTAPI-controlled addresses, JTAPI applications will not see a common controller in the final and the consult call. This would provide different behavior to the JTAPI application. Depending on how the JTAPI application is processing information that is provided in events, applications may require changes to handle JTAPI events for this transfer or conference scenario.

You can disable transfers and conferences across the line by configuring the Cisco Unified IP 7931G phone to NoRollOver mode through the phone configuration window of Cisco Unified Communications Manager Administration.

There are two new cause codes for the CiscoRestrictedEv interface. When the terminal or address is restricted because a Cisco Unified IP 7931G phone is configured in RollOverMode, JTAPI sends CiscoAddrRestrictedEv with cause CiscoRestrictedEv.UNSUPPORTED_DEVICE_CONFIGURATION. This release also introduces a default cause code CAUSE_UNKNOWN, which applications should handle.

Backward Compatibility

This feature is backward compatible. You can disable this feature by configuring all Cisco Unified IP 7931G phones in a cluster in NoRollOver mode or by not having any Cisco Unified IP 7931G phones in a Cisco Unified Communications Manager cluster. If any phone in a Cisco Unified Communications Manager cluster is configured with RollOver mode, it may cause changes to the behavior of JTAPI-controlled addresses and terminals.

For more information, see CiscoRestrictedEv.

Version Format Change

In release 6.0, the Cisco JTAPI version changes from a 4-digit format to a 5-digit format similar to the format used by Cisco Unified Communications Manager. The JTAPI version will remain similar to the Cisco Unified Communications Manager version. New interfaces let applications get the extended version number. See CiscoJtapiVersion.

Backward Compatibility

This feature is backward compatible.

Calling Party IP Address

Extensions to CallCtlConnOfferedEv and RouteEvent provide a method for retrieving the IP address of the calling party. This feature provides the calling party IP address to the destination side of basic calls, consultation calls for transfer and conference, and basic redirect and forwarding. The system does not support other scenarios and feature interactions, including those where the calling party changes. This feature only supports IP phones as calling party devices, although IP address of other calling devices may also be provided. See CiscoCallCtlConnOfferedEv and CiscoRouteEvent.

Backward Compatibility

This feature is backward compatible.

Multilevel Precedence and Preemption Support

Cisco Unified Communications Manager enables the use of supplementary services by phones that are configured for Multilevel Precedence and Preemption (MLPP). Cisco Unified Communications Manager does this by maintaining the precedence level for calls.


Note JTAPI does not provide the precedence level of applications.


Non-Controller Adding of Parties to Conferences

Any party in a conference can now add participants into the conference. In previous releases, only the conference controller could add participants.

CiscoConferenceStartEv contains an identifier for the requestor party.

The method getConferenceControllerAddress returns the terminal connection of the requestor.

The new method getOriginalConferenceControllerAddress() for CiscoConferenceStartEv returns the terminal connection of the original controller.

Conference Chaining

The conference chaining feature lets applications join two separate conference calls together. JTAPI applications see chained conference calls represented as two separate calls. When conference calls are chained, JTAPI creates a new connection for the conference chain and provides the CiscoConferenceChainAddedEv event on CallCtlCallObserver. When the conference chain is removed from the call, JTAPI disconnects the conference chain connection and provides the CiscoConferenceChainRemovedEv event on CallCtlCallObserver. From CiscoConferenceChainAdded/RemovedEv, applications can obtain CiscoConferenceChain, which provides a link for all the conference chain connections.

Figure 2-1 shows parties A, B, and C in conference call GC1 and parties C, D, and E in conference call GC2.

Figure 2-1 Calls Prior to Chaining

After the conference chain is created, the calls will look like Figure 2-2:

Figure 2-2 Calls After Chaining

Applications may get all of the participants of a chained conference from the CiscoChainedConference object, which provides conference chain connections from all the conference calls that are chained together. By browsing through the connections list, applications can get a list of all the chained conference calls; however, applications need to have at least one participant of each conference observed.


Note For any conference scenario that involves chaining conferences or adding parties to a chained conference call, JTAPI will not provide ConferenceStarted/Ended event.


For more information, see the following topics:

CiscoCall (for the new getConferenceChain() interface)

CiscoConferenceChain

CiscoConferenceChainAddedEv

CiscoConferenceChainRemovedEv

Forwarding on No Bandwidth & Unregistered DN

This feature enhances the forwarding logic to handle the No Bandwidth & Unregistered DN cases:

No Bandwidth: When a call cannot be delivered to a remote destination due to no bandwidth, the system reroutes the call to the AAR Destination Mask or Voice Mail. The user makes these configuration changes from the directory number window of the Cisco Unified Communications Manager GUI.

Unregistered DN: When a call is placed to an unregistered DN, the system delivers the call to a DN that is configured for Call Forward on No Answer (CFNA), as in releases prior to release 6.0.

When a call is forwarded due to Call Forward No Bandwidth (CFNB) to another cluster destination over a trunk/gateway using QSIG then call history might get lost. For example, if Phone A calls Phone B, which is in a low bandwidth location, with CFNB set to forward calls to Phone C, which is in a different cluster, and the QSIG protocol is used for this intercluster forwarding, then the original called party and the last redirecting party might not get passed to the destination party.

Directed Call Park

This feature allows the user to park a call by transferring the call to a user-selected park code.

Examples

A calls B; B transfers the call to a parked DN. On completion of the transfer, the A to B call is parked at the specified parked DN. A will receive MOH (if configured). When C unparks the call (by dialing the prefix code and park code), A and C connect.

If A calls the parked DN directly, A connects to the parked DN and the system marks this parked DN as busy. A stays connected to this parked DN until park reversion.

If C does not unpark the call at the parked DN, the call park reverses back to the DN that parked the call (B), and A and B connect again. B can again try to d-Park to another parked DN. When park reversion occurs, Cisco Unified Communications Manager JTAPI passes a new reason code to the application.

CTI sends the parked number to Cisco Unified Communications Manager JTAPI in the form "Park Number: (<Prefix Code>)<DPark DN>". Cisco Unified Communications Manager JTAPI parses this and exposes both "Prefix Code" and "DPark DN" to applications.

When a call is unparked, the parked party and unparking party both receive a CPIC event with the reason given by CTI, and the parked party connects to the unparking party.

When party A calls a dPark DN and party B also calls the same dPark DN, the system can connect either A or B to the dPark DN, and the other party will be disconnected.

Cisco Unified Communications Manager JTAPI Support

Cisco Unified Communications Manager JTAPI supports this feature. When the system transfers a call to a directed call park DN (dparked), the application sees a connection created for directed call park DN, and the call control connection state is CallControlConnection.QUEUED. The system delivers CiscoTransferstart and end events. An application can use the new interface on CiscoConnection to get the prefix code needed to unpark the call.

Performance and Scalability

This feature provides the same performance impact as the existing transfer feature.

Voice MailBox Support

This feature exposes voice mailbox numbers, which let Cisco Unified Communications Manager JTAPI applications forward calls from a directory number to the correct voice mailbox.

The Cisco Unified Communications Manager Administrator can associate a voicemail profile for each directory number. When the voicemail option is enabled for any forward setting, and if the corresponding forward is enabled, the call rolls down to the voicemail pilot number that is associated with the voicemail profile.

The voicemail profile contains voicemail pilot number and voicemail box mask fields. Voicemail box mask specifies the mask that is used to format the voicemail box number for auto-registered phones. When forwarding a call to a voice messaging system from a directory line on an auto-registered phone, Cisco Unified Communications Manager applies this mask to the number that is configured in the Voice Mail Box field for that directory line.

For example, if you specify a mask of 972813XXXX, the voice mailbox number for directory number 7253 becomes 9728137253. If you do not enter a mask, the voice mailbox number matches the directory number (7253 in this example).

Cisco Unified Communications Manager JTAPI Support

To support this feature, Cisco Unified Communications Manager JTAPI exposes voicemail box numbers for called party, lastRedirected party and originalCalled party. These voicemailbox fields are exposed on CiscoPartyInfo, which is exposed on CiscoCall object. If voicemail is not configured for a party, then Cisco Unified Communications Manager JTAPI will return empty Strings for voicemailbox fields.

In prior releases Cisco Unified Communications Manager JTAPI did not expose voicemailbox fields to applications, so Cisco Unified Communications Manager JTAPI voicemailbox applications could not determine whether a voicemail box mask was configured for a voicemail profile, which could result in a voicemail box number that is different from the directory number.

The new interfaces for CiscoCall are:

getCalledPartyInfo()

getCurrentCalledPartyInfo()

getLastRedirectedPartyInfo()

The new interface for CiscoPartyInfo is getVoiceMailbox().

Performance and Scalability

This feature does not increase the traffic from the Cisco Unified Communications Manager JTAPI layer to the application layer. However, there could be small performance impact because of additional fields passed over the network.

Privacy On Hold

This feature enhances the privacy of private held calls. When privacy is enabled, only the phone that placed a call on hold can retrieve that call, and the calling name and number are not displayed.

The feature provides a shared address the ability to determine whether other shared addresses may barge into a call. When privacy is enabled, other shared address cannot barge into the call. Privacy is a terminals property. On IP phones there is a Privacy feature button to enable and disable the privacy feature. Privacy can be dynamically enabled and disabled for the active calls on the terminal. When Privacy is on for a call, the TerminalConnection state available to other shared addresses is set to "In Use." If Privacy status is changed during the CallProgress, CiscoTermConnPrivacyChangedEvent is delivered to the application.

In prior releases, if Privacy is enabled and the call is put on hold, then all TerminalConnections will be in TermConnHeld state and any other shared Address terminalConnection can unhold the call. In Cisco Unified Communications Manager 4.2, if the "Enforce Privacy on Held Calls" service parameter is enabled, and if Privacy is enabled for a call, then putting the call on hold does not change the terminalConnections of other shared addresses and they remain in the "In Use" state.

Performance and Scalability

There is no performance impact with this feature because there is no additional traffic generated between Cisco Unified JTAPI, applications, and Cisco Unified Communications Manager.

CiscoRTPHandle Interface on Cisco RTP Events

The following interfaces are enhanced to allow applications to get a CiscoRTPHandle from the events:

CiscoRTPInputStartedEv

CiscoRTPInputStoppedEv

CiscoRTPOutputStartedEv

CiscoRTPOutputStoppedEv

CiscoRTPHandle represents the callID of the call in Cisco Unified Communications Manager and stays the same as long as the call is active on the terminal. At any particular terminal/address, although the call and the associated GCID can change, CiscoRTPHandle will remain constant.

Hold Reversion

The Hold Reversion feature provides applications with a notification, when Cisco Unified Communications Manager notifies an address about the presence of a held call, when the call has been ONHOLD for a certain amount of time. Applications receive this notification as the CiscoCallCtlTermConnHeldReversionEv call control terminal connection event on their call observers on the particular address which has put the call ONHOLD. This notification is provided only once for the applications for the held call.

The event is sent only to the terminal connection of the terminal where the call was put on hold. If the address represents a shared line address, other terminal connections of the shared line address will not receive the event.

To receive this event, applications must add a call observer to the address. The cause for this event will be CAUSE_NORMAL. If the call observer is added after the hold reversion timer has expired and the notification has already been sent to the phone, applications will receive CiscoCallCtlTermConnHeldReversionEv with cause CAUSE_SNAPSHOT.

For more information, see CiscoCallCtlTermConnHeldReversionEv.

Translation Pattern Support

If a calling party transformation mask is configured for a translation pattern that is applied to a JTAPI application-controlled Address, the application may see extra connections created and disconnected when both the calling and called party are observed. A Connection is created for a transformed calling party instead of the actual calling party and CiscoCall.getCurrentCallingParty() would return the transformed calling party, when only the called party is observed. In general, JTAPI might not be able to create the appropriate Connection in the Call, and might not be able to provide correct information for currentCalling, currentCalled, calling, called, and lastRedirecting parties.

For example, consider a translation pattern X that is configured with a calling party transformation mask Y and called party transformation mask B. If A calls X, the call goes to B. In this scenario:

If the application is observing only B, JTAPI creates a Connection for Y and B, and CiscoCall.getCurrentCallingParty() would return Address Y.

If the application is observing both A and B, a Connection for A and B gets created, a Connection for Y gets temporarily created and dropped, and CiscoCall.getCurrentCallingParty() would return Address Y.

There could be other inconsistencies in the calling information if further features get performed on a basic call. Cisco recommends that you not configure a calling party transformation mast for a translation pattern that might get applied to JTAPI application-controlled addresses.

Calling Party IP Address

The Calling Party IP Address enhancement provides the calling party IP address to the destination side of basic calls, consultation calls for transfer and conference, and basic redirect and forwarding. Only calling party IP phones are supported, although IP address of other calling devices may also be provided.


Note Other feature interactions are not supported including those during which the calling party changes.


New Cisco extensions to the CallCtlConnOfferedEv and RouteEvent classes are created and expose a method to obtain the calling party IP address . The new extensions are CiscoCallCtlConnOfferedEv and CiscoRouteEvent. An empty value returned indicates that the calling party IP address is not available.

Basic Call Scenario

JTAPI application monitors party B

Party A is an IP phone

A calls B

IP Address of A Available to JTAPI Application Monitoring B Consultation Transfer Scenario

JTAPI application monitors party C

Party B is an IP phone

A talking B

B intiates a consultation transfer call to C

IP Address of B is available to JTAPI application monitoring party C

Consultation Conference Scenario

JTAPI application monitors party C

Party B is an IP phone

A talking B

B intiates a consultation conference call to C

IP Address of B is available to JTAPI application monitoring party C

Redirect Scenario

JTAPI application monitors party B and party C

Party A is an IP phone

A calls B

IP Address of A is available to JTAPI application monitoring party B

Party A redirects B to party C

Calling IP address is not available to JTAPI application monitoring party B

Calling IP address of B is provided to JTAPI application monitoring party C

Backward Compatibility

This feature is backward compatible. Application must invoke a new API to query IP address of a call.

Cisco Unified Communications Manager Release 5.1

This section describes the new and changed features in Cisco Unified Communications Manager, from Release 5.0 to Release 5.1 and Cisco Unified JTAPI enhancements. It has the following:

Join Across Lines

New Error Code in CiscoTermRegistrationFailedEv

Star (*) 50 Update

Call Forward Override

Join Across Lines

The Join Across Lines feature allows support for conference across lines. It allows two or more calls on different addresses of the same terminal to be joined though the join softkey on the phone or conference() API provided by JTAPI. The behavior to JTAPI applications will change, as applications will not see a common controller in final and consult calls.

There is no change in the API and same events are delivered whether calls are conferenced on the same address (regular conference) or across addresses (Join across lines). When join across lines feature is performed CiscoConferenceStartEv/EndEv will be provided to all addresses on the controller terminal that have consult or final calls which are being joined together into one conference.

In CiscoConferenceStartEv the conferenceControllerAddress will always be the primary controller address. As is now, application can set the controller via the setConferenceController() API. If application does not specify this, then JTAPI itself would find a suitable controller for the conference. However it is recommended for applications to set the controller address when Join Across Lines feature is invoked.

If observer is not added on the controller address, then applications may see null values for either the talking or held terminal connection values in the CiscoConferenceStartEv. Before this release, when application tries to do a conference across lines, the request will fail at the JTAPI layer itself. With this release, the conference() API implementation has been enhanced to all the request to pass through after finding suitable terminal connections of the final and consult calls. JTAPI relies on the common terminal of the addresses involved in the call to find suitable terminal connections. Multiple conference across address is also supported when more than two calls need to be joined. This feature is not supported by SIP devices in 5.1.2 release. JTAPI will throw exception (ILLEGAL_HANDLE) if this feature is requested on a SIP device.

There are no interface changes for this feature. There will be change in behavior with respect to events provided to applications.

Backward Compatibility

This feature is backward compatible, as there are no changes in the behavior of conference when this feature is not enabled. This feature can be enabled/disabled on a per device basis. If the "Join Across Lines" setting on the device is set to Default, then the system-wide CallManager service parameter "Join Across Lines Policy" setting will be used. If this feature is enabled and application does a join across lines, application will see difference in behavior as stated above.

JTAPI applications written for 5.1 should be backward compatible with JTAPI released with 5.1.2. A JTAPI client upgrade is required only if new features are used.

New Error Code in CiscoTermRegistrationFailedEv

This event is send to application when TerminalRegistration fails for some reason. The return value of getErrorCode() interface indicates the type of failure. On getting this event application should try to re-register the Terminal. In this version a new return value is added to this interface. CiscoTermRegistraionFailedEv.UNKNOWN is introduced in this version to handle unknown failures.

Backward Compatibility

This feature is backward compatible.

Star (*) 50 Update

The Star(*)50 feature enables the user to divert a call to original called party (value returned by CiscoCall.getCalledAddress() method) and the called party (value returned by CiscoCall.getCurrentCalledAddress() method) from phone UI. After pressing the iDivert softkey, a menu displays identifying the names of the original called party and the called party.

The user selects one of the two names and the call is redirected to the Voice Mailbox of the selected party. With the legacy iDivert, the call is diverted to original called party Voice Mailbox by just pressing iDivert softkey. Cisco Unified Communications Manager Administration has introduced following Service parameters to configure this feature:

iDivert Legacy Behavior—Determines whether the phone uses the legacy iDivert behavior when a user presses the iDivert softkey, or the enhanced *50 iDivert behavior. If the iDivert legacy service parameter is set to true, the iDivert legacy behavior is adopted and vice versa.

Allow QSIG during iDivert-Determines whether iDivert legacy is allowed in deployments that have voice messaging integration over QSIG trunks and is only used when the Use Legacy iDivert service parameter is set to true.

iDivert User Response timer-Determines the number of seconds that Cisco Unified Communications Manager Administration waits for a response from the user before the iDivert screen is removed. If no user action occurs by the time this timer expires, the screen is removed from the phone. If the Use Legacy iDivert service parameter is set to true, Cisco Unified Communications Manager Administration ignores this parameter.

There is no interface change at JTAPI layer for this feature. The behavior changes from JTAPI application point of view is that Calls could either go to voicemail of OrigicalCalled Party or Called

Backward Compatibility

This feature is backward compatible.

Call Forward Override

This feature provides a mechanism to override the call forward all feature. If a user (CFA Initiator) sets CFA to another user (CFA target), the CFA should be ignored if the CFA target calls the CFA initiator. This would allow the CFA Target to reach the CFA Initiator for important calls.

The behavior of this CallManager feature is configurable via service parameter - CFADestinationOverride.

Example: Alice has a phone with DN 1000 * Bob has a phone with DN 2000 * Daniel has a phone with DN 4000 * Alice does a CFA to 2000

CFA behavior * Bob calls Alice. Call goes to Alice and does not follow CFA back to himself. * Daniel calls Alice. Call follows CFA to Bob. * Bob answers and transfers the call to Alice. Bob can do this because Alice has her phone forwarded to Bob. There is no interface change to JTAPI layer with this feature. However JTAPI applications could see a difference in behavior when CiscoAddress.setForward() API is invoked. In scenario where CFA target calls the CFA initiator like described in above example, call will not be forwarded if feature is enabled.

Backward Compatibility

JTAPI applications written for 5.0 should be backward compatible with JTAPI released with 5.1.release. JTAPI Client Upgrade Application doesn't require JTAPI Client upgrade to run or be backward compatible. JTAPI Client upgrade is required only if new features are used.

Cisco Unified Communications Manager Release 5.0

This section describes the new and changed features in Cisco Unified Communications Manager, from Release 4.x to Release 5.0 and Cisco Unified JTAPI enhancements. It has the following:

Partition Support

Hairpin Support

QoS Support

Transport Layer Security (TLS)

SIP Phone Support

Secure Real-Time Protocol Key Material

SIP REFER/REPLACE

SIP 3XX Redirection

Terminal and Address Restrictions

Unicode Support

Linux, Windows, and Solaris Installation

Silent Install

Command Line Invocation

JTAPI Client Installer

JRE 1.2 and JRE 1.3 Support Removal

Superprovider and Change Notification

Alternate Script Support

Half-Duplex Media Support

Network Alerting

Auto Updater for Linux

Call Select Status

JTAPI Version Information

Partition Support

Prior to Cisco Unified Communications Manager Release 5.0, JTAPI did not support partitions. JTAPI considered addresses with the same DN, but different partitions, as same address. It created only one Address object for such cases because addresses are identified only by their DN and not by their partition information.

Beginning with Release 5.0, JTAPI supports addresses that have the same DN but belong to different partitions and treats them as different addresses. Partition information of the addresses is exposed to applications through the methods specified below. Applications that want to make use of this partition support feature must use the API provided to them through JTAPI interfaces and use the address objects accordingly.

This feature is backward compatible. JTAPI supports the current APIs that are used to open and access address objects.

In Cisco Unified Communications Manager Release 5.0, JTAPI is partition aware and the following configurations are supported.

Addresses with the same DN, in the same partition, and in different devices get treated as shared lines.

Addresses with the same DN, in the same partition, and in the same device are not allowed.

Addresses with the same DN, in different partitions, and in the same device get treated as different addresses. Two address objects get created for this scenario, and the application can distinguish between the two by calling the getPartition() API on the address objects.

Addresses with the same DN, in different partitions, and in different devices get treated as different addresses. Two address objects get created for this scenario and the application can distinguish between the two by calling the getPartition() API on the address objects.

Partition support changes in JTAPI are confined to the address objects and do not affect any other functions or classes of JTAPI. The following sections specify the interface changes.

CiscoAddress Interface

A new method is provided in this class with the following signature.

string getPartition ()

Returns the partition string of the address object. Applications need to use this method to get the partition information. JTAPI will use this partition information to distinguish between addresses that have the same DN but belong to different partitions and sends the partition information to open the specific addresses.

For example, a provider open returns two addresses, A(1000, P1) and B (1000, P2), where A and B denote the address objects, 1000 denotes the DN of the address objects, and P1,P2 indicate the partitions to which the addresses belong.

Figure 2-3 Provider Open Returns Two Addresses

When the user invokes A.getPartition (), P1 gets returned while B.getPartition () returns P2.

The provider.getAddresses() method returns multiple addresses in which the Address objects have the same DN but different partition information. An Application can use this method to distinguish between two Address objects that have the same DN but belong to different partitions.

CiscoProvider Interface

The CiscoProvider interface provides the following methods:

Address[]

getAddress(String number)
 
        

Returns an array of Address objects that corresponds to the number and different partitions.

Address

getAddress(String number, String partition)
 
        

Returns the Address object that has the same DN as the "number" parameter and belongs to the same partition as specified by the "partition" parameter.


If two addresses A(1000, P1) and B(1000,P2) exist, where A and B denote the address objects, 1000 denotes the DN of the address objects, and P1,P2 indicate the partitions to which the addresses belong, when an application calls provider.getAddress("1000"), it gets two address objects, A and B.

Figure 2-4 provider.GetAddress() Returns Two Address Objects

When the application calls A.getPartition(), it returns P1, B.getPartition() returns P2, and so on. An Application can distinguish between the two address objects that are using the getPartition method.

Consider the case where the application calls provider.getAddress(1000, P1). In this case, the application specifically looks for the address object whose DN is 1000 and partition is P1. In this case, "A" gets returned by the provider object.

Figure 2-5 Provider Calls a Specific Address and Partition

CiscoProvCallParkEv Event

CiscoProvCallParkEv provides the following methods in this interface.

string   getParkingPartyPartition()

Returns the partition string of the parking party.

string   getParkedPartyPartition()

Returns the partition string of the parked party.

string   getParkPartyPartition()

Returns the partition string of the park DN.

For details on the interface changes, see Chapter 5 "Cisco Unified JTAPI Implementation." To view the message sequences for partitions support, see "Message Sequence Charts."

Hairpin Support

A hairpin call happens when the call leaves one cluster to some other device across the gateway, then comes back to a device in the same cluster. The GCID for the call coming back into the cluster would be different than the GCID that originally initiated the call, even though both are in the same cluster. In previous releases, if both parties were controlled by JTAPI, then there were two connections: one for CiscoAddress.Internal and the other for CiscoAddress.External.

JTAPI supports hairpin calls when an application monitors both ends of the hairpin call. Previously only one end of the hairpin call could be monitored because the address was represented only as a DN.

In the current release, if there are two addresses with the same DN but one is within the same cluster and the other is across the gateway, then JTAPI creates a separate address object for the external DN and only one connection is returned for an address, based on its type. This process avoids hairpin issues, as in previous releases when the address was represented only as a DN and when an application retrieved connections for the address it used to get two connections.

Since fixing these issues could have caused compatibility issues with previous releases, a generic solution for these issues was developed in this release. Calls involving an external party with the same DN as the monitored local party are now properly supported; however, no new interface is added for this feature.

Backward Compatibility

This feature is not backward compatible.

QoS Support

QoS support is enhanced in this release to enable QoS (DSCP marking) in both directions of the application ´ CTIManager connectivity. In previous releases it was enabled in only one direction: CTIManager Æ application.

The DSCP (QoS) values for both directions of the link are set by the "DSCP IP CTIManager to Application" value in the CTIManager service parameters. The default value is CS3(precedence 3) DSCP (011000).

The "DSCP value for Audio calls" service parameter is the recommended QoS value for audio calls. This value is exposed to JTAPI applications.

The following setup procedures must be performed on the client machine for JTAPI QoS to work on Windows platforms.

If you are running Windows 2000, follow these steps:


Step 1 Start the Registry Editor (Regedt32.exe).

Step 2 Go to key: HKEY_LOCAL_ MACHINE on
Local Machine\System\CurrentControlSet\Services\Tcpip\Parameters\

Step 3 On the Edit menu, click Add Value.

Step 4 In the Value name box, enter DisableUserTOSSetting.

Step 5 In the Data Type list, click REG_DWORD and then click OK.

Step 6 In the Data box, enter a value of 0 (zero) and then click OK.

Step 7 Quit Registry Editor and then restart the computer.


If you are running Windows XP or Windows Server 2003, follow these steps:


Step 1 Start Registry Editor (Regedt32.exe).

Step 2 Go to key: HKEY_LOCAL_ MACHINE on
Local Machine\System\CurrentControlSet\Services\Tcpip\Parameters\

Step 3 On the Edit menu, point to New, and then click DWORD Value.

Step 4 Enter DisableUserTOSSetting as the entry name, and then press ENTER.

When you add this entry, the value gets set to 0 (zero). Do not change the value.

Step 5 Quit Registry Editor and then restart the computer.


For more information on using the Registry Editor to set the Internet Protocol Type of Service bits, see the topic "Setsockopt is unable to mark the Internet Protocol type of service bits in Internet Protocol packet header" on the Microsoft technical support web site.

These JTAPI interfaces support QoS:

Provider Interface

int

getAppDSCPValue()
 
        

Returns the "DSCP IP for CTI applications" service parameter. This value specifies the DSCP value that JTAPI sets on its link to CTI. Applications can get this value by querying the provider object by using this API every time that they get a ProviderInServiceEvent.

private int

precedenceValue = 0x00
 
        

To store the DSCP value that CTI provides.


For details on these interfaces, see Chapter 5 "Cisco Unified JTAPI Implementation." To view the message flow for QoS, see "Message Sequence Charts."

Transport Layer Security (TLS)

This feature lets JTAPI applications communicate with CTIManager through a secure connection. CTIManager runs a TLS listener socket to accept connections from JTAPI. A client certificate, which the server uses to authenticate the client, and a server certificate, which the client uses to authenticate the server, are both required for establishing a TLS connection.

In the Cisco Unified Communications Manager environment, the server certificate exists in the form of CTL on the TFTP server, and JTAPI downloads this certificate. The initial download of CTL is trusted and occurs without verification, so Cisco strongly recommends performing this download in a secure environment. One of the two System Administrator Security Tokens (SAST) that are present in the CTL file signs the CTL; subsequent CTL downloads get verified with the SAST from the old CTL file.

JTAPI connects to CAPF by using the CAPF protocol to get the client certificate (LSC). These certificates can be authenticated with the issuer's certificate present in CTL.

CTI tracks the number of provider connections created per client certificate. Applications can create only one provider by using a client certificate. If more than one instance of a provider is created, both providers get disconnected from CTI and go out of service. JTAPI will retry the connection to CTI to bring the original provider in service; however, if both instances of provider continue to exist, after a certain number of retries provider will get permanently shut down, and the client certificate will be marked as compromised. Any further attempt to create a provider by using this client certificate will fail. Applications must contact the administrator to configure a new instanceId and download a new client certificate to resume operation.


Note Each client certificate is associated with a unique instanceId configured in the Cisco Unified Communications Manager database. Applications can provide an instanceId in providerString as an optional parameter to use a unique certificate while creating a CiscoProvider.


To run multiple instances of applications with TLS, the application user should be configured in the Cisco Unified Communications Manager database with multiple instanceIDs. Applications use these unique instanceIDs to get unique client certificates for each instance.

The JTAPI preferences application provides a graphic user interface to configure the Security parameters and update server/client certificates. Application users need to configure the TFTPServer IP address, CAPFServer IP address, Username, InstanceID, and AuthorizationString parameters through the JTAPI preferences to download/install certificates on the application server.

New interfaces are provided for JTAPI client applications on the client layer object. For example, a JTAPI client interface is provided on the CTIClientProperties class.

This feature is backward compatible with previous releases as JTAPI Applications can still connect to CTIManager on non-secure socket connections. However, this option will be available only for a limited number of releases and could be removed in future releases. It is recommended that Applications move to secure connections.

The following sections describe the interface changes for TLS support in JTAPI.

CiscoJtapiPeer.getProvider()

public javax.telephony.Provider getProvider(java.lang.String providerString) 
throws  
javax.telephony.ProviderUnavailableException
 
   

This interface is modified to take a new optional parameter InstanceID. It returns an instance of a Provider object given a string argument that contains the desired service name.

Optional arguments may also be provided in this string, with the following format:

< service name > ; arg1 = val1; arg2 = val2; ... 
 
   

Where < service name > is not optional, and each optional argument=value pair that follows is separated by a semicolon. The keys for these arguments are implementation-specific, except for two standard-defined keys:

login—Provides the login user name to the Provider.

passwd—Provides a password to the Provider.

A new optional argument would be expected by CiscoJtapiPeer in providerString:

InstanceID—Provides InstanceID for Application Instance.

InstanceID is needed when two or more instances of an application want to connect to Provider (CTIManager) through a TLS connection from the same client machine. Each instance of an application requires its own unique X.509 certificate to establish a TLS connection. If JTAPI attempts to open more that one connection with same username/instanceID, CTIManager rejects the TLS connection. If instanceID is not provided, JTAPI randomly picks one of the instances of USER and, in that case, the connection may fail if a connection for the selected Instance already exists.

If the argument is null, this method returns some default provider as determined by the JtapiPeer object. The returned provider is in the Provider.OUT_OF_SERVICE state.

Post-conditions:

this.getProvider().getState() = Provider.OUT_OF_SERVICE
 
   

Specified bygetProvider in interface javax.telephony.JtapiPeer

ParametersproviderStringThe name of the desired service plus an optional argument.

Returns—An instance of the Provider object.

Throwsjavax.telephony.ProviderUnavailableExceptionIndicates that a provider corresponding to the given string is unavailable.

CiscoJtapiProperties

JTAPI provides an interface on CiscoJtapiProperties to enable or disable the security option and install the client/server certificates that are required to establish a secure TLS socket connection.

com.cisco.jtapi.extensions  
Interface CiscoJtapiProperties

getSecurityPropertyForInstance

public java.util.Hashtable getSecurityPropertyForInstance()
 
   

This interface returns a Hash table with all the parameters set for User/InstanceID. The Hash table gets set with the following "key-value" pairs:

Table 2-1

KEY
VALUE

          "user"

userName

string "instanceID"

InstanceID

string "AuthCode"

authCode

string "CAPF"

capfServer IP-Address

string "CAPFPort"

capfServer IP-Address port

string "TFTP"

tftpServer IP-Address

string "TFTPPort"

tftpServer IP-Address port

string "CertPath"

certificate Path

string "securityOption"

Boolean security option(true for enable/ false for disabled)

string "certificateStatus"

Boolean certificate status(true for updated/ false for not updated)


ReturnsHash table in the format described previously for the first user and instance.


getSecurityPropertyForInstance

public java.util.Hashtable getSecurityPropertyForInstance 
(java.lang.String user, java.lang.String instanceID)
 
   

This interface returns a Hash table with all the parameters set for User/InstanceID. The Hash table is set with the following "key-value" pairs:

Table 2-2

KEY
VALUE

          "user"

userName

string "instanceID"

InstanceID

string "AuthCode"

authCode

string "CAPF"

capfServer IP-Address

string "CAPFPort"

capfServer IP-Address port

string "TFTP"

tftpServer IP-Address

string "TFTPPort"

tftpServer IP-Address port

string "CertPath"

certificate Path

string "securityOption"

Boolean security option(true for enable/ false for disabled)

string "certificateStatus"

Boolean certificate status(true for updated/ false for not updated)


Parameters:

user - UserName for which you want security parameters

instanceID - InstanceID for which you want security parameters

ReturnsHash table in above described format.


setSecurityPropertyForInstance

public void setSecurityPropertyForInstance(java.lang.String user,
                      java.lang.String instanceID,
                      java.lang.String authCode,
                      java.lang.String tftp,
                      java.lang.String tftpPort,
                      java.lang.String capf,
                      java.lang.String capfPort,
                      java.lang.String certPath,
                      boolean securityOption)

You can use this interface to set security properties for the following parameters:

Parameters:

user—UserName for which the security parameter is being updated

instanceID—InstanceID for which the security parameter is being updated

authCode—Authorization string

capf—IP-Address of CAPF server

capfPort—IP-Address port number on which the CAPF server is running, as defined in a CallManager Service parameter. If the value is null, the default value is 3804.

tftp—IP-Address of TFTP server

tftpPort—IP-Address port number on which the TFTP server is running. The Cisco Unified Communications Manager TFTP server usually runs on port 69. If the value is null, the default value is 69.

certPath—Path where certificate needs to be installed


updateCertificate

public void updateCertificate(java.lang.String user,
               java.lang.String instanceID,
               java.lang.String authcode,
               java.lang.String ccmTFTPAddress,
               java.lang.String ccmTFTPPort,
               java.lang.String ccmCAPFAddress,
               java.lang.String ccmCAPFPort,
               java.lang.String certificatePath)
 
   

This interface installs an X.509 client certificate for the USER instance in the certificate store by connecting to the Cisco Unified Communications Manager Certificate Authority Proxy Function (CAPF) server. It also downloads the Certificate Trust List (CTL) from the Cisco Unified Communications Manager TFTP server.

If the user credentials are not valid, this method throws a PrivilegeViolationException. If the TFTP server or CAPF server address is not correct, this method throws an InvalidArgumentException. Every instance of an application requires a unique client certificate. If a multiple instanceID is configured in the Cisco Unified Communications Manager database, applications can call this interface multiple times to install a client certificate for every instance.

Pre-conditionsWhen calling this interface, an application should have network connectivity with the Cisco Unified Communications Manager CAPF and TFTP servers.

Post-conditionsThis process installs client and server certificates on the JTAPI application machine.

Parameters:

user—Name of the CTI application user that is configured in the Cisco Unified Communications Manager database

instanceID—Application instance ID that is configured in the Cisco Unified Communications Manager database. Every instance of an application requires a unique ID.

authCode—Authorization string that is configured in the Cisco Unified Communications Manager database. The authCode can be used only once for getting certificates.

ccmTFTPAddress—IP-Address of the Cisco Unified Communications Manager TFTP server.

ccmTFTPPort—IP-Address port number on which the Cisco Unified Communications Manager TFTP server is running. The Cisco Unified Communications Manager TFTP server usually runs on port 69. If null, the default value is 69.

ccmCAPFAddress—IP address of the Cisco Unified Communications Manager CAPF server.

ccmCAPFPort—Port number on which the Cisco Unified Communications Manager CAPF server is running, as defined in the Cisco Unified Communications Manager Service parameters. If the value is  null, the default value is 3804.

certificatePath—Directory path where the certificate needs to be installed

Throws:

InvalidArgumentException—This exception gets thrown for an invalid TFTP server or CAPF server address.

PrivilegeViolationException—This exception gets thrown for an invalid user, instanceID, or authCode.


IsCertificateUpdated

public boolean IsCertificateUpdated 
	(java.lang.String user, java.lang.String instanceID)
 
   

This interface provides information about whether client and server certificates are updated for a given user/instanceID.

Parameters:

user—UserName as defined in the Cisco Unified Communications Manager Administration.

instanceID—InstanceID for the specified UserName.

Returns—True if certificates are already updated; false if certificates are not updated.


updateServerCertificate

public void updateServerCertificate(java.lang.String ccmTFTPAddress,
                  java.lang.String ccmTFTPPort,
                  java.lang.String ccmCAPFAddress,
                  java.lang.String ccmCAPFPort,
                  java.lang.String certificatePath)
 
   

This interface installs an X.509 server certificate that is given the certificate path. If the TFTP server address is not correct, this method throws an InvalidArgumentException. Auto update applications should use this interface to update the server certificate before invoking an HTTPS connection with Cisco Unified Communications Manager.

Pre-conditionsWhen calling this interface, applications should have network connectivity with the TFTP server.

Post-conditionsThis interface installs the server certificate on the JTAPI application machine.

Parameters:

ccmTFTPAddress—IP address of the Cisco CallManager TFTP server.

ccmTFTPPortPort number on which the Cisco Unified Communications Manager TFTP server is running.
If null, the default value is 69.

certificatePath—Directory path for installing the certificate.

ccmCAPFAddress—IP address of the Cisco Unified Communications Manager CAPF server.

ccmCAPFPort—Port number on which the Cisco Unified Communications Manager CAPF server is running.
If the value is null, the default value is 3804.

Throws:

InvalidArgumentException—If the TFTP server address is invalid.


Interface that is Provided on JTAPI Preferences

The JTAPI Preferences dialog box includes a Security tab to let application users configure the username, instanceId, authCode, TFTP IP address, TFTP port, CAPF IP server address, CAPF server port, and certificate path, and enable secure connection.

"CAPF server port" number defaults to 3804.

This value is configurable in the Cisco Unified Communications Manager Administration service parameters page. The CAPF server port value entered through JTAPI Preferences should be same as that configured in Cisco Unified Communications Manager Administration.

"TFTP server port" number defaults to 69.

This value should not be changed unless you are advised to do so by the System Administrator.

"Certificate Path" is where the application wants the sever and client certificates to be installed.

If this field is left blank, the certificates get installed in the ClassPath of JTAPI.jar.

"Certificate update Status" provides information on whether a certificate has been updated or not.

You must select "Enable Secure Connection" to enable a secure TLS connection to Cisco Unified Communications Manager.

If "Enable Security Connection" is not selected, JTAPI makes a non-secure connection to CTI even if the certificate is updated/installed.

The "Enable Security Tracing" check box lets you enable or disable tracing for the certificate installation operation.

If tracing is enabled, you can select three different levels, "Error," "Debug," or "Detailed," from the drop-down menu.

The JTAPI Preference UI can be used to configure a security profile for one or more than one userName/instanceID pair. When application users revisit this page, and have previously configured security profile for a userName/instanceID pair, the security profile automatically gets populated when the user enters a username/instanceID and clicks on any other edit box.

One change in the JTAPI Preferences UI is that the "Trace Levels" tab is renamed "JTAPI Tracing." This is to highlight the fact that the "JTAPI Tracing" tab only lets you change trace setting for the JTAPI layer. Tracing for the installation of Security certificates must be enabled on the Security tab.

SIP Phone Support

This release of Cisco Unified Communications Manager allows SIP phones to register and interoperate with SCCP phones. The following sections describe the new interfaces introduced to support SIP phones along with the limitations and differences in behavior with respect to SCCP phones. Though not all existing features are supported on SIP phones, the general behavior in terms of JTAPI events and interfaces for SIP phones are similar to that of a SCCP phone.

JTAPI applications can only control TNP-based SIP phones, which includes Cisco Unified IP 7970 phones. Applications should not include Cisco Unified IP 7960, 7940, and other phones that are running the SIP protocol in their control list. JTAPI applications cannot control third-party SIP phones, so third-party SIP phones should not be included in the control list.

SIP Phone Support

In prior released, JTAPI supported an initial feature set on SIP phones. In this release support is added for the following functionality on SIP phones:

Park for SIP Phones

Unpark for SIP Phones


Tip The order of events for consult calls is different for SIP and SCCP phones. Consider the following scenario:


a. Terminal A initiates a call to the shared line B/B'.

b. The shared line initiates a consult call to Terminal C.

If the shared line is a SIP device, the call events are:

B (active) receives: OnHold -> Select -> NewCall

B' (remote-in-use) receives: Select -> NewCall -> OnHold

However, if the shared line is a SCCP device, the call events are Select -> OnHold -> NewCall on both terminals.

If the application is only monitoring, call.getConsultingTerminalConnection() may return null.

JTAPI supports the following features for SIP phones:

Call.connect; offhook

answer; disconnect; drop; hold, unhold

consult; transfer; conference; redirect

playdtmf, deviceData

JTAPI supports the following events for SIP Phones:

CiscoTermDeviceStateEv, RTP events, inService, and OutOfService

MediaTermConnDtmfEv (only out of band is supported), transfer start and end events, conference start and end events, CiscoToneChangedEv, and CiscoTermConnPrivacyChangedEv

SIP phone behavior differs from that of SCCP phones in the following ways:

Call Rejection—When a call is made to a SIP phone, the phone can choose to reject the call. In this case, applications will see CallActive, ConnCreatedEv followed by ConnDisconnectedEv for the address on the SIP terminal. This is similar to RP rejecting the call.

Consult without media calls involving SIP phones should be transferred within 1.5 seconds after the call is connected.

For SIP phones, enbloc dialing is always used even if the user first goes off hook before dialing digits. The phone will wait until all the digits are collected before sending the digits to the Cisco Unified Communications Manager. This means that CallCtlConnDialingEv will get delivered only after enough digits are pressed on the phone to match one of the configured dialing patterns.

Applications should configure "out of band DTMF" on all devices to receive MediaTermConnDtmfEv.

Events for CTI ports, route points, and SCCP phones are not changed.

When a SIP TNP phone using UDP as transport fails connectivity with Cisco Unified Communications Manager, JTAPI applications receive the events CiscoTermOutOfServiceEv and CiscoAddrOutOfServiceEv for the terminal and address defined for the phone. Because of the inherent delay in UDP in detecting the connectivity loss, the TNP-based SIP phone may visually show as registered after applications already have been notified with the out-of-service events.

If Cisco Unified IP Phones 7960,7940, and non-TNP phones running SIP, are included in the control list, exceptions will be thrown when observers (both observer and call observers) are added to the address or terminal and CiscoTermRestrictedEv is delivered to a provider observer. The cause for these events would be CiscoRestrictedEv.CAUSE_UNSUPPORTED_PROTOCOL.

CiscoTerminal exposes new interface getProtocol() to indicate whether terminal is an SCCP phone or a SIP phone. CiscoTerminalProtocol defines the values that are returned by getProtocol().

The following new interfaces defined on CiscoCall let applications get URL information for external SIP entities.

Public interface CiscoCall

CiscoPartyInfo

getLastRedirectingPartyInfo()

CiscoPartyInfo

getCurrentCallingPartyInfo()

CiscoPartyInfo

getCurrentCalledPartyInfo()

CiscoPartyInfo

getCalledPartyInfo()

Public interface CiscoPartyInfo

CiscoUrlInfo

getUrlInfo()

Address

getAddress()

string

getDisplayName()

string

getUnicodeDisplayName()

boolean

getAddressPI()

boolean

getDisplayNamePI()

boolean

getlocale()

Public interface CiscoUrlInfo

 
      

int

getUrlType() 
Final int URL_TYPE_TEL
Final int URL_TYPE_SIP
Final int URL_TYPE_UNKNOWN

string

getHost()

string

getUser()

int

getPort()

int

getTransportType()
Final int TRANSPORT_TYPE_UDP
Final int TRANSPORT_TYPE_TCP

Public interface CiscoTerminal

 
      

int

getProtocol ()

CiscoTerminalProtocol

 
      

static int

PROTOCOL_NONE

Indicates an unrecognized or unknown protocol type

static int

PROTOCOL_SCCP

Indicates the device is using SCCP protocol to communicate to Cisco Unified Communications Manager

static int

PROTOCOL_SIP

Indicates the device is using SIP protocol to communicate to Cisco Unified Communications Manager


Secure Real-Time Protocol Key Material

This feature provides the mechanism that is needed to deliver Secure Real-Time Protocol (SRTP) key material of an encrypted media session between authenticated end points within Cisco Unified Communications Manager based Enterprise systems. To receive this key material, the administrator must configure the TLS Enabled and SRTP Enabled flags in the Cisco Unified Communications Manager Administrator pages and a TLS link must be established between JTAPI and the CTIManager.

Key materials get exposed in CiscoRTPInputKeyEv and CiscoRTPOutputKeyEv. To get these events, applications must enable rtpKeyEvenabled in CiscoTermEvFilter. By default, filters are disabled to maintain backward compatibility. If filters are enabled, application always get CiscoRTPInputKeyEv and CiscoRTPOutputKeyEv. A security indicator in these events indicates whether the media is encrypted and whether keys are available.

CiscoRTPInputKeyEv contains key material of the input stream and CiscoRTPOutputKeyEv contains key material of the output stream. Applications can use this key material to decrypt the packets and start monitoring or recording the media. Applications must not store this key material in a way that leaves the material vulnerable to tampering, and applications must zero out or clear the entry for these keys when they go out-of-scope.

This key material contains

Key Length

Master Key

Salt Length

Master Salt

AlgorithmID

isMKIPresent

Key Derivation Rate

This enhancement also supports a secure media termination for CTIPorts and RoutePoints. To do this, the application passes in supported encrypted algorithms in CTIPort and route point register requests. The application gets an error if no TLS link and no SRTP Enabled flags exist. Whether media are encrypted or not depends on whether the other end is interested in secure media and whether the algorithm is negotiated successfully.

For mid-call monitoring, if the application comes up after a call is established between two end points, the application must query Terminal.createSnapshot() and snapshot event CiscoTermSnapshotEv. CiscoTermSnapshotCompletedEv gets sent, which indicates whether the current media between end points is secure or not. Applications can query CiscoMediaCallSecurityIndicator to get a security indicator for a call; however, this does not contain any key material in the event. If no calls exist on any of the lines on the terminal, applications only get CiscoTermSnapshotCompletedEv. To maintain backward compatibility, these events get generated only when an application enables the snapShotRTPEnabled filter in CiscoTermEvFilter.

CiscoRTPHandle gets added in all RTP events so that applications can correlate RTP events related to a single call. For backward compatibility, no new events are generated when there is no secure media.

For more information on SRTP, see the Secure RTP Library API Documentation by David McGrew on SourceForge.net.

The following sections describe the interface changes for SRTP key material.

Public Interface CiscoMediaEncryptionKeyInfo

int

getAlgorithmID()
 
        

This method returns the media encryption algorithm for the current stream.

int

getIsMKIPresent()
 
        

An MKI indicator that indicates whether MKI is present. Key management defines, signals, and uses the MKI.

int

getKeyLength ()
 
        

This method returns the master key length.

byte[]

getKey() 
 
        

This method returns the master key for the stream.

int

getSaltLength ()
 
        

This method returns the salt length.

byte[]

getSalt()
 
        

This method returns the salt key for the stream.

int

keyDerivationRate()
 
        

Indicates the SRTP key derivation rate for this session.


CiscoMediaSecurityIndicator

static int

MEDIA_ENCRYPTED_KEYS_AVAILABLE
 
        

Indicates that media terminated is secured and keys are available.

static int

MEDIA_ENCRYPTED_KEYS_UNAVAILABLE
 
        

Indicates that media is terminated in secured mode, but keys are not available because SRTP is not enabled in Cisco Unified Communications Manager Administration User windows. This could be because either no TLS exists or no IPSec is configured for this application.

static int

MEDIA_ENCRYPTED_USER_NOT_AUTHORIZED
 
        

Indicates that media is terminated in secured mode, but keys are not available because user is not authorized to get the keys.

static int

MEDIA_NOT_ENCRYPTED
 
        

Indicates that media is not encrypted for this call.


CiscoRTPInputKeyEv

CiscoMedia
EncryptionKeyInfo

getCiscoMediaEncryptionKeyInfo ()
 
        

Returns CiscoMediaEncryptionKeyInfo only if the provider is opened with TLS link and if SRTP enabled option is set for the application in Cisco Unified Communications Manager User Administration; otherwise, it returns null.

int

getCiscoMediaSecurityIndicator()
 
        

Returns media security indicator, which is one of the following constants from the CiscoMediaSecurityIndicator:

MEDIA_ENCRYPTED_KEYS_AVAILABLE 
MEDIA_ENCRYPT_USER_NOT_AUTHORIZED 
MEDIA_ENCRYPTED_KEYS_UNAVAILABLE 
MEDIA_NOT_ENCRYPTED

CiscoCallID

getCallID ()
 
        

Returns CiscoCallID object if CiscoCall is present when this event is sent. If no CiscoCall is present, this method returns null.

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns CiscoRTPHandle object. Applications can get a call reference by using CiscoProvider.getCall( CiscoRTPHandle ). If no call observer exists, or if there was no call observer when this event is delivered,  CiscoProvider.getCall( CiscoRTPHandle ) may return null.


CiscoRTPOutputKeyEv

CiscoMedia
EncryptionKeyInfo

getCiscoMediaEncryptionKeyInfo ()
 
        

Returns CiscoMediaEncryptionKeyInfo only if the provider is opened with TLS link and if the SRTP enabled option is set for the application in Cisco Unified Communications Manager User Administration. Otherwise, it returns null.

int

getCiscoMediaSecurityIndicator() 
 
        

Returns media security indicator, which is one of the following constants from CiscoMediaSecurityIndicator:

MEDIA_ENCRYPTED_KEYS_AVAILABLE 
MEDIA_ENCRYPT_USER_NOT_AUTHORIZED 
MEDIA_ENCRYPTED_KEYS_UNAVAILABLE 
MEDIA_NOT_ENCRYPTED

CiscoCallID

getCallID ()
 
        

Returns CiscoCallID object if CiscoCall is present when this event is sent. If  no CiscoCall is present, this method returns null.

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns CiscoRTPHandle object. Applications can get a call reference by using CiscoProvider.getCall(CiscoRTPHandle). If no call observer exists, or if there was no call observer when this event is delivered,  CiscoProvider.getCall( CiscoRTPHandle ) may return null.


CiscoTermSnapshotEv

CiscoMediaCall
MediaSecurity
Indicator[]

getMediaCallSecurityIndicator ()
 
        

Returns media security status for each active call on this device.


CiscoTermSnapshotCompletedEv

This event has no methods.

CiscoMediaCallSecurityIndicator

int

getCiscoMediaSecurityIndicator()
 
        

Returns media security indicator, one of the following constants from CiscoMediaSecurityIndicator:

MEDIA_ENCRYPTED_KEYS_AVAILABLE 
MEDIA_ENCRYPT_USER_NOT_AUTHORIZED 
MEDIA_ENCRYPTED_KEYS_UNAVAILABLE 
MEDIA_NOT_ENCRYPTED

CiscoCallID

getCallID ()
 
        

Returns a CiscoCallID object if a CiscoCall is present when this event is sent. If no CiscoCall is present, this method returns null.

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns a CiscoRTPHandle object. Applications can get a call reference by using CiscoProvider.getCall( CiscoRTPHandle ). If no callobserver exists or if there was no callobserver when this event is delivered, CiscoProvider.getCall( CiscoRTPHandle ) may return null.


CiscoRTPInputStartedEv

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns a CiscoRTPHandle object. Applications can get a call reference by using CiscoProvider.getCall(CiscoRTPHandle). If no call observer exists, or if there was no call observer when this event is delivered, CiscoProvider.getCall(CiscoRTPHandle) may return null.


CiscoRTPInputStoppedEv

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns a CiscoRTPHandle object. Applications can get call reference by using CiscoProvider.getCall(CiscoRTPHandle). If no call observer exists, or if there was no call observer when this event is delivered, CiscoProvider.getCall(CiscoRTPHandle) may return null.


CiscoRTPOutputStartedEv

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns a CiscoRTPHandle object. Applications can get a call reference by using CiscoProvider.getCall(CiscoRTPHandle). If no call observer exists, or if there was no call observer when this event is delivered, CiscoProvider.getCall(CiscoRTPHandle) may return null.


CiscoRTPOutputStoppedEv

CiscoRTPHandle

getCiscoRTPHandle ()
 
        

Returns CiscoRTPHandle object. Applications can get call reference using CiscoProvider.getCall(CiscoRTPHandle). If there is no call observer, or if there was no call observer when this event is delivered, then CiscoProvider.getCall(CiscoRTPHandle) may return null.


CiscoTermEvFilter

boolean

getSnapshotEnabled ()
 
        

Returns the enable/status of CiscoTermSnapshotEv and CiscoTermSnapshotCompletedEv for the terminal.

void

setSnapshotEnabled (boolean enabled)
 
        

Sets enable/disable status of CiscoTermSnapshotEv. If disabled, CiscoTermSnapshotEv and CiscoTermSnapshotCompletedEv
are not sent to applications.

boolean

getRTPKeyEvEnabled ()
 
        

Returns the enable/disable status of CiscoRTPInputKeyEv and CiscoRTPOutputKeyEv.

void

setRTPKeyEvEnabled (boolean enabled)
 
        

Sets enable/disable status for CiscoRTPInputKeyEv and CiscoRTPOutputKeyEv.


CiscoTerminal

void

createSnapshot () throws InvalidStateException
 
        

This method generates CiscoTermSnapshotEv, which contains security status of current active call on the terminal. To access this method, the terminal must be in CiscoTerminal.IN_SERVICE state, and CiscoTermEvFilter.setSnapshotEnabled () must be set to True.


CiscoMediaTerminal

void

register(CiscoMediaCapability[] capabilities, 
int[] supportedAlgorithms)
 
        

The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED state and its provider must be in the Provider.IN_SERVICE state. This interface provides dynamic registration with secure media. If applications do not invoke this method, the media gets terminated in non-secure mode.

void

register(java.net.InetAddress address, int port, 
CiscoMediaCapability[] capabilities, int[] algorithmIDs)
 
        

The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED state, and its provider must be in the Provider.IN_SERVICE state. This interface provides static registration with secure media. If applications do not register this interface, the media remains non-secured. AlgorithmIDs indicate SRTP algorithms that this CTIPort supports. AlgorithmIDs maybe only one of CiscoSupportedAlgorithms.


CiscoRouteTerminal

void

register(CiscoMediaCapability[] capabilities, int registrationType, int[] 
algorithmIDs
 
        

The CiscoRouteTerminal must be in the CiscoTerminal.UNREGISTERED state, and its provider must be in the Provider.IN_SERVICE state. By default, media gets terminated in non-secure mode. AlgorithmIDs indicate SRTP algorithms that this CTIPort supports. AlgorithmIDs may be only one of CiscoSupportedAlgorithms.


CiscoSupportedAlgorithm Constants

AES_128_COUNTER

SIP REFER/REPLACE

REFER is a SIP method that is defined by RFC 3515. The REFER method indicates that the recipient (referee, identified by the Request-URI) should contact a third party (referred to as the "target") by using the contact information that is provided in the request. This REFER method allows the party who is sending the REFER (referrer) to be notified of the outcome of the referenced request.

Cisco Unified Communications Manager, being a Back-To-Back User Agent (B2BUA), processes both inside and outside dialog inbound REFER on behalf of the Referee. As result of REFER, Cisco Unified Communications Manager creates a call between the Referee and the Refer-to-Target. If there is a previously existing call between the Referrer and the Referee, the call at the Referrer gets dropped after REFER completes.

The REPLACES feature is the replacement of an existing SIP dialog with a new dialog. A SIP dialog is a call between two SIP user agents; a Cisco Unified Communications Manager dialog is a half call (callleg). The REPLACES feature is triggered either by REFER or by an INVITE. Cisco Unified Communications Manager handles a REPLACES request on behalf of the recipient of the REPLACES header. The request is associated with a new dialog and the requesting party is the party that wants to replace another party in the existing dialog (call) identified in the REPLACES header. Cisco Unified Communications Manager disconnects the dialog (call) identified in the REPLACES header and connects the requesting party.

JTAPI is enhanced to model Call events caused by the Cisco Unified Communications Manager REFER and REPLACE features in the JTAPI call model. JTAPI provides applications with the capability to handle call events caused by REFER and REPLACE features. JTAPI does not provide any interface for applications to initiate REFER or REFER/INVITE with REPLACES requests; however, JTAPI can handle the call events properly.

These two features are backward compatible. JTAPI provides events that are caused by REFER/REPLACE with CAUSE_NORMAL. Applications can get feature-specific reasons from the new interface CiscoCallEv.getCiscoFeatureReason().


Note This interface provides feature-specific reasons for current and new features, but this method will not remain backward compatible in future releases. Applications using this interface must implement default handling to avoid future backward-compatibility issues.


The following sections describe the interface changes for SIP REFER/REPLACE.

CAUSE provided for REFER/REPLACE

JTAPI provides CAUSE_NORMAL for events that caused by REFER/REPLACES. Applications should use CiscoCallEv.getCiscoFeatureReason() to get the feature-specific reason.

Interface provided on CiscoCallEv

This interface provides CiscoFeatureReason in the JTAPI call event. Older features, such as transfer, continue to receive the old CiscoCause that is provided by the previous interface, CiscoCallEv.getCiscoCause(). This new interface provides REASON_TRANSFER for transfer.

com.cisco.jtapi.extensions
Interface CiscoCallEv

int

getCiscoFeatureReason()
 
        

This interface returns Cisco Unified Communications Manager Feature Reason.


Interface CiscoFeatureReason

JTAPI provides CiscoFeatureReason in Call events caused by features. CiscoFeatureReason is provided for existing as well as new Cisco Unified Communications Manager features. For REFER and REPLACES features, the reason would be REASON_REFER and REASON_REPLACES. This interface will provide new reasons for any new features that may be introduced in the future, and is not backward compatible.

Applications using CiscoFeatureReason should expect to receive new reasons in later releases and must implement default behavior to maintain the Application's backward compatibility.

Applications that use CiscoFeatureReason should expect to receive new reasons in later releases and must implement default behavior to maintain backward-compatibility.

Public interface CiscoFeatureReason

static int

REASON_REFER
 
        

Reason returned for events that are sent for REFER by Cisco Unified Communications Manager.

static int

REASON_REPLACE
 
        

Reason returned for events that are sent for REPLACE by Cisco Unified Communications Manager.


SIP 3XX Redirection

The SIP Redirect server receives SIP requests and responds with 3xx(redirection) responses, which direct the client to contact an alternate set of SIP addresses. This enhancement supports the Cisco Unified Communications Manager Redirection (3xx) Call Control primitive in compliance with RFC 3261. The Cisco Unified Communications Manager Redirection primitive processes SIP 3xx responses and does sequential hunting to each contact address from the 3xx response. Cisco Unified Communications Manager Redirection primitive also handles feature interactions that result from performing this operation. Cisco Unified JTAPI exposes new reason codes in all CallEvs, which indicate when connection and terminalConnection are created and destroyed as a result of this primitive.

LastRedirectAddress may change if feature interactions like JTAPI Redirect or CallForwardNoAnswer occur when the Redirection primitive is hunting for a target. If the target does not answer and Cisco Unified Communications Manager Redirect takes control of the call to send it to next target, lastRedirectAddress is set to the party who originally sent the SIP 3xx response.

If a diversion header is present in the SIP 3xx response, the 3xx primitive uses the first value of the diversion header for lastRedirectParty, and JTAPI applications will see the diversion header element as lastRedirectAddress.

To maintain backward compatibility, JTAPI exposes the new API CiscoCallEv.getCiscoFeatureReason() in the CiscoCallEv interface, which contains the reason as CM_REDIRECTION.


Note Applications should be aware that new feature-specific reason codes could be returned from this API, and applications should provide default behavior for unrecognized reason codes.


The following sections describe the interface changes for SIP 3XX Redirection.

Public interface CiscoFeatureReason

static int

REASON_CM_REDIRECTION 
 
        

This reason indicates that event is a result of 3xx response from the CM_REDIRECTION primitive in Cisco Unified Communications Manager.


CiscoCallEv

int

getCiscoFeatureReason()
 
        

A feature specific reason for this event. Applications should make sure to handle unrecognized reasons and provide default behavior as this interface may not be backward compatible as new reasons might be added in the future.


Terminal and Address Restrictions

This enhancement restricts applications from controlling and monitoring a certain set of terminals and addresses when the administrator configures them as restricted in Cisco Unified Communications Manager Administration.

The administrator can configure a particular line on a device (address on a particular terminal) as restricted. If a terminal is added into the restricted list in Cisco Unified Communications Manager Administration, all addresses on that terminal are also marked as restricted in JTAPI. If an application comes up after the configuration is completed, it can know whether a particular terminal or address is restricted from checking the interface CiscoTerminal.isRestricted() and CiscoAddress.isRestricted(Terminal). For shared lines, applications can query the interface CiscoAddress.getRestrictedAddrTerminals(), which indicates whether an address is restricted on any terminals.

If a line (address on a terminal) is added into the restricted list after an application comes up, the applications will see CiscoAddrRestrictedEv. If the address has any observers, applications will see CiscoAddrOutOfService. When a line is removed from the restricted list, applications will see CiscoAddrActivatedEv. If an address has any observers, applications see CiscoAddrInServiceEv. If an application tries to add observers on an address after it is restricted, a PlatformException gets thrown. However, if any observers are added before the address is restricted, they will remain as is, but applications cannot get any events on these observers unless the address is removed from the restricted list. Applications can also choose to remove observers from an address.

If a device (terminal) is added to the restricted list after an application comes up, the application will see CiscoTermRestrictedEv. If the terminal has any observers, the application will see CiscoTermOutOfService. If a terminal is added to the restricted list, JTAPI also restricts all addresses that belong to that terminal and applications will see CiscoAddrRestrictedEv. If a terminal is removed from the restricted list, applications will see CiscoTermActivatedEv and CiscoAddrActivatedEv for the corresponding addresses. If an application tries to add observers on a terminal after it is added to the restricted list, a PlatformException is thrown. However, if any observers are added before the terminal is restricted, they will remain as is, but applications cannot get any events on these observers unless the terminal is removed from the restricted list

If a shared line is added to the restricted list after an application comes up, the application will see CiscoAddrRestrictedOnTerminalEv. If any address observers exist on the address, the application will see CiscoAddrOutOfServiceEv for that terminal. If all shared lines are added to the restricted list, when the last one is added, applications will see CiscoAddrRestrictedEv. If a shared line is removed from the restricted list after the application comes up, applications will see CiscoAddrActivatedOnTerminalEv. If  any observers exist on the address, the application will see CiscoAddrInServiceEv for that terminal. If all shared lines in the control list are removed from the restricted list, applications will see CiscoAddrActivatedEv when the last one is removed, and all addresses on terminals will receive InService events.

If all shared lines in the control list are marked as restricted, and an application tries to add observers, a platform exception is thrown. If a few shared lines are in the restricted list, while others are not, when an application adds an observer on the address. only non-restricted lines will go in service.

If any active calls are present when an address or terminal is added to the restricted list and reset, applications will see connection and TerminalConnections get disconnected.

If no addresses or terminals are added to the restricted list, this feature is backward compatible with earlier versions of JTAPI: no new events are delivered to applications.

The following sections describe the interface changes for address and terminal restrictions.

CiscoTerminal

boolean

isRestricted() 
 
        

Indicates whether a terminal is restricted. If the terminal is restricted, all associated addresses on this terminal are also restricted. Returns true if the terminal is restricted; returns false if it is not restricted.


CiscoAddress

javax.telephony.
Terminal[]

getRestrictedAddrTerminals()
 
        

Returns an array of terminals on which this address is restricted. If none are restricted, this method returns null.

In shared lines, a few lines on terminals may be restricted. This method returns all the terminals on which this particular address is restricted. Applications cannot see any call events for restricted lines. If a restricted line is involved in a call with any other control device, an external connection gets created for the restricted line.

boolean

isRestricted(javax.telephony.Terminal terminal)
 
        

Returns true if any address on this terminal is restricted.
Returns false if no addresses on this terminal are restricted.


public interface CiscoRestrictedEv extends CiscoProvEv { 
	public static final int ID = com.cisco.jtapi.CiscoEventID.CiscoRestrictedEv;
 
   
	/**
	 * The following define the cause codes for restricted events
	 */
	
	public final static int CAUSE_USER_RESTRICTED = 1;
	
	public final static int CAUSE_UNSUPPORTED_PROTOCOL = 2;
	
	}
 
   

This is the base class for restricted events and defines the cause codes for all restricted events. CAUSE_USER_RESTRICTED indicates the terminal or address is marked as restricted. CAUSE_UNSUPPORTED_PROTOCOL indicates that the device in the control list is using a protocol that is not supported by Cisco Unified JTAPI. Existing Cisco Unified IP 7960 and 7940 phones that are running SIP fall in this category.

CiscoAddrRestrictedEv

Public interface CiscoAddrRestrictedEv extends CiscoRestrictedEv. Applications will see this event when a line or an associated device is designated as restricted from Cisco Unified Communications Manager Administration. For restricted lines, the address will go out of service and will not come back in service until it is activated again. If an address is restricted, addCallObserver and addObserver will throw an exception. For shared lines, if a few shared lines are restricted, and others are not, no exception is thrown, but restricted shared lines will not receive any events. If all shared lines are restricted, an exception is thrown when adding observers. If an address is restricted after adding observers, applications will see CiscoAddrOutOfServiceEv, and when the address is activated, the address will go in service.

CiscoAddrActivatedEv

Public interface CiscoAddrActivatedEv extends CiscoProvEv. Applications will see this event whenever a line or an associated device is in the control list and is removed from the restricted list in the Cisco Unified Communications Manager Administration. If any observers exist on the address, applications will see CiscoAddrInServiceEv. If no observers exist, applications can try to add observers, and the address will go in service.

CiscoAddrRestrictedOnTerminalEv

Public interface CiscoAddrRestrictedOnTerminalEv extends CiscoRestrictedEv. If a user has a shared address in the control list, and if one of the lines is added into the restricted list, this event will be sent. Interface getTerminal() returns the terminal on which the address is restricted. Interface getAddress() returns the address that is restricted.

javax.telephony.Address

getAddress() 

javax.telephony.Terminal

getTerminal() 

CiscoAddrActivatedOnTerminal

Public interface CiscoAddrActivatedOnTerminalEv extends CiscoProvEv. When a shared line or a device that has a shared line is removed from the restricted list, this event will be sent. The interface getTerminal() returns the terminal that is being added to the address. The interface getAddress() returns the address on which the new terminal is added.

 
      

javax.telephony.Address

getAddress() 

javax.telephony.Terminal

getTerminal() 

CiscoTermRestrictedEv

Public interface CiscoTermRestrictedEv extends CiscoRestrictedEv. Applications will see this event when a device is added into restricted list from Cisco Unified Communications Manager Administration after the application launches. Applications will not be able to see events for restricted terminals or addresses on those terminals. If a terminal is restricted when it is in InService state, applications will get this event and terminal and corresponding addresses will move to the out-of-service state.

CiscoTermActivatedEv

Public interface CiscoTermActivatedEv extends CiscoRestrictedEv.

 
      

javax.telephony.Terminal

getTerminal()
 
        

Returns the terminal that is activated and is removed from the restricted list.


CiscoOutOfServiceEv

static int

CAUSE_DEVICE_RESTRICTED
 
        

Indicates whether an event is sent because a device is restricted.

static int

CAUSE_LINE_RESTRICTED
 
        

Indicates whether an event is sent because a line is restricted.


CiscoCallEv

static int

CAUSE_DEVICE_RESTRICTED
 
        

Indicates whether an event is sent because a device is restricted.

static int

CAUSE_LINE_RESTRICTED 
 
        

Indicates whether an event is sent because a line is restricted.


Unicode Support

Cisco Unified Communications Manager release 5.0 supports unicode display names on unicode-enabled IP phones. You can configure ASCII names and unicode names for display names. JTAPI receives all names in unicode and ASCII formats and provides two new interfaces, getCurrentCalledPartyUnicodeDisplayName and getCurrentCallingPartyUnicodeDisplayName, to allow applications to get display names in unicode. It also provides the ability to get unicode display names during call progress.

JTAPI receives the encoding capability of application controlled IP phones in device registered and device in service events from CTI, locale and language group information in device info response, and provides interfaces to applications to get the locale, alternate script, and unicode capability of IP phones. CiscoTerminal and CiscoTermInServiceEv interfaces are enhanced to provide this information for phones that are in the application control list when the CiscoTerminal is in the inservice state.

JTAPI receives the alternate script information of all parties in the call and provides interfaces to applications to get the language group of the current calling and current called party. Two interfaces, getCurrentCallingPartyLanguageGroup and getCurrentCalledPartyLanguageGroup, are available on CiscoCall to get this information. Applications also receive both ASCII and UCS-2 encoded unicode display names for the current calling and called addresses.

Unicode support for JTAPI also includes:

CiscoCall interface changes

CiscoLocales interface changes

CiscoTerminal / CiscoTerminalInServiceEv interface changes

Applications might need to reconfigure their username/password after upgrading to Release 5.0.

The following sections describe the interface changes for unicode support.

Interface CiscoCall changes

The following new methods on CiscoCall let applications get the unicode display names and the corresponding locales.

/**
	 * This interface returns the unicode display name of the current called party 
	 * in the call.
	 */
	public String getCurrentCalledPartyUnicodeDisplayName();
 
   
	/**
	 * This interface returns the locale of the current called party unicode
	 * display name. CiscoLocales interface lists the supported locales.
	 */
	public int getCurrentCalledPartyUnicodeDisplayNamelocale();
 
   
	/**
	 * This interface returns the unicode display name of the current calling party
	 * in the call.
	 */
	public String getCurrentCallingPartyUnicodeDisplayName ();
 
   
	/**
	 * This interface returns the locale of the current called party
	 * unicode display name
	 */
	public int getCurrentCallingPartyUnicodeDisplayNamelocale();
 
   

CiscoLocales

The CiscoLocales interface lists all the locales that Cisco Unified JTAPI supports.


Note For a list of all supported locales in the most recent release, see the "man" page for CiscoLocales.


public interface CiscoLocales
{
	public static final int LOCALE_ENGLISH_UNITED_STATES;
	public static final int LOCALE_FRENCH_FRANCE; 
	public static final int LOCALE_GERMAN_GERMANY;
	public static final int LOCALE_RUSSIAN_RUSSIA ;
	public static final int LOCALE_SPANISH_SPAIN ;
  	public static final int LOCALE_ITALIAN_ITALY ;
  	public static final int LOCALE_DUTCH_NETHERLAND ;
  	public static final int LOCALE_NORWEGIAN_NORWAY ;
  	public static final int LOCALE_PORTUGUESE_PORTUGAL; 
	public static final int LOCALE_SWEDISH_SWEDEN ;
  	public static final int LOCALE_DANISH_DENMARK 
	public static final int LOCALE_JAPANESE_JAPAN; 
	public static final int LOCALE_HUNGARIAN_HUNGARY ;
  	public static final int LOCALE_POLISH_POLAND ;
  	public static final int LOCALE_GREEK_GREECE ;
  	public static final int LOCALE_TRADITIONAL_CHINESE_CHINA;
  	public static final int LOCALE_SIMPLIFIED_CHINESE_CHINA;
  	public static final int LOCALE_KOREAN_KOREA;
}

CiscoTerminalInServiceEv Interface

int

getLocale() 
 
        

This method returns the current locale information for this terminal.

int

getSupportedEncoding () 
 
        

This method returns true if this terminal supports unicode.


CiscoTerminal Interface

int

getLocale()
 
        

This method returns the current locale information for this terminal. The CiscoTerminal must be in the CiscoTerminal.IN_SERVICE state to access this method.

int

getSupportedEncoding ()
 
        

This method returns the unicode capability of this Terminal. The CiscoTerminal must be in the CiscoTerminal.IN_SERVICE state to access this method.


The getSupportedEncoding () returns one of the following results that are defined in CiscoTerminal.

/** 
  * Indicates the <Code>CiscoTerminal.getSupportedEncoding ()</CODE>
  * for this Terminal is UNKNOWN
*/ 
 public final static int UNKNOWN_ENCODING = 0;
 
   
/** 
  * Indicates the <Code>CiscoTerminal.getSupportedEncoding ()</CODE>
  * for this is NOT_APPLICABLE.
  * This is valid for only CiscoMediaTerminals and RoutePoints
*/ 
 public final static int NOT_APPLICABLE = 1;
 
   
/** 
  * Indicates the <Code>CiscoTerminal.getSupportedEncoding ()</CODE> for this
  * Terminal is ASCII and this terminal supports only ASCII_ENCODING
*/ 
 public final static int ASCII_ENCODING = 2;
 
   
/** 
  * Indicates the <Code>CiscoTerminal.getSupportedEncoding ()</CODE>
  * for this Terminal is UCS2UNICODE_ENCODING 
 */ 
 public final static int UCS2UNICODE_ENCODING = 3;

Linux, Windows, and Solaris Installation

This feature provides a uniform install and uninstall procedure for the Cisco Unified JTAPI Client on Windows, Linux, and Solaris Platforms. In previous releases the Cisco Unified JTAPI Client installer was provided only for the Windows platform and Application users had to follow manual steps to install it on Linux and Solaris machines.

Cisco Unified JTAPI Install has been developed with InstalledShieldMultiPlatform (ISMP). The Linux and Solaris versions of the installer are provided as a binary file (.bin) and for Windows it is an executable (.exe) file. All three installers are available on the Cisco Unified Communications Manager plug-in page.

The following changes in upgrades and downgrades to and from this release are present in the JTAPI Client on the Windows platform:

The new installer does not support downgrades to previous releases. Application users must manually uninstall JTAPI prior to re-installing any previous version of the JTAPI client.

When you are upgrading from a previous release, the new installer prompts you to uninstall the current version and continues installation only after the previous version of the JTAPI client has been uninstalled.

Applications can bundle the JTAPI Installer with their installation by using a silent install invocation. Applications that want to run the installer in silent mode can use one of the following commands:

Windows: CiscoJTAPIClient.exe -silent

Linux: CiscoJTAPIClient-linux.bin -silent

Solaris(Sparc): CiscoJTAPIClient-solarisSparc.bin -silent

Solaris(X86): CiscoJTAPIClient-solarisX86.bin -silent

Applications that want to use the JTAPIInstaller from the command line can use one of the following commands from the command prompt:

Windows: CiscoJTAPIClient.exe -console

Linux: CiscoJTAPIClient-linux.bin -console

Solaris (Sparc): CiscoJTAPIClient-solarisSparc.bin -console

Solaris (X86): CiscoJTAPIClient-solarisX86.bin -console

A character-input-based menu guides the installation procedure. The same options are available as in the GUI based installation. This type of installation is best suited to non-GUI platforms like Linux.

When a fresh install or an upgrade/downgrade is performed on a Linux platform, the JTAPIInstaller automatically detects the destination folders and does a silent install. However, if a previous version is present on the system, the installer does not know the applications path and installs the applications in a predetermined location by forcibly creating the folder.

Linux Install

When a fresh install or an upgrade and downgrade is being done, the installer will automatically detect the destination folders and do the silent install. However, if a previous version is present in the system, the installer would not know the application path and hence will install the application in a predetermined location, by creating the folder.

Backward Compatibility

This feature is not backward compatible. Application using command line or silent install feature of CiscoJtapiClient install need to make changes to command invocation of the install. Please see details for more info.

Silent Install

Applications can bundle JTAPIInstaller along with their Installation by doing silent install invocation on JTAPIInstaller. The way in which silent install is invoked is described in section (5.1.2.14.1). When a pre-SD version is present in the system and a upgrade to SD version happens, the new installer will automatically invoke the pre-SD uninstaller. Applications that need to uninstall the pre-SD version of JTAPI in silent-mode, need to invoke the installer from command line in the following manner: CiscoJtapiClient.exe -W newversion.silent=1. This method is applicable only for Windows platform. Applications which want to find out the version of the JTAPI even before the installation of the new SD installer, before executing it, need to use the following command to do so.

CiscoJtapiClient.exe silent -W newversion.check=1 goto showversion Once this command is run from the command line, the installer will create a file called jtapiversion.txt in the current directory. This will have the JTAPI version of the installer in a.b(c.d) format. This command is applicable for all client platforms (Linux/ Solaris/ Windows).

Command Line Invocation

This mode will be helpful for installing JTAPI in systems that do not have GUI support (for ex. a Linux account). The entire installation procedure will be guided by a character input based menu, where the user will be asked to provide a series of inputs, based on the install time conditions. This mode also provides all the other options provided by the GUI based installer. The way in which command line install is invoked is described in the given section (5.1.2.14.2).

JTAPI Client Installer

If during installation using ISMP Installer, a prior release of the JTAPI Client Installer is present in the system, the ISMP installer will detect this from the registry and thereby invoke the uninstaller of the prior release. The user should ensure that the uninstall operation of the prior release completes without errors, following which the ISMP installer proceeds. If there are some errors during the uninstallation of the prior release of JTAPI, the ISMP installer cannot detect it and hence will continue to proceed with installation.

Although ISMP installer provides the above method of uninstalling the prior JTAPI Client Installer in the system before proceeding with the actual install, it is recommended that the user follows the procedure below.

Procedure


Step 1 Go to Add/Remove programs.

Step 2 Run the uninstaller of the prior release.

This is recommended so that the user does not directly invoke the current release installer.The installer invokes the uninstaller of the prior release. When the uninstall completes, the user is prompted to restart the system now or later. If the user chooses restart now, then the server is rebooted while the installer is trying to install the new version. This issue occurs because the uninstaller of the prior release and installer of the current release are written using different types of IS/ISMP and are not linked.


ISMP installer also does not support the downgrade operation to a prior release.

Backward Compatibility

This feature is not backward compatible.

JRE 1.2 and JRE 1.3 Support Removal

This release of the CiscoJTAPIClient supports only JRE 1.4. There are no interface changes; however, the JRE 1.2 and 1.3 versions are no longer supported. This change is to support QoS, which is available only in the JDK1.4 version (and above). In addition, jtapi.jar contains Cisco encryption files that depend on the JRE 1.3 version (and above). This provides a stronger password encryption algorithm when it is sent over TCP to CTIManager. As part of this feature, JTAPI invokes the API provided by IMS (Identity Management System, a Cisco Unified Communications Manager component) to encrypt a password before sending it.

JRE 1.4 also enables Cisco Unified JTAPI to use additional JDK 1.4 APIs. Applications that use previous versions of JRE must install JDK 1.4 to use Cisco Unified JTAPI.


Note There are no interface changes to JTAPI Applications, however JTAPI.jar contains RSA jsafe.jar (3.3) and Apache log4j-1.2.8.jar files. If Applications are using any jar files that are not compatible with these versions of jsafe.jar (Version 3.3) and log4j-1.2.8.jar, then JTAPI or the Application may not work, depending on which one is in the classpath first


As part of this migration, JTAPIPreferences and sample applications dependency on MS-JVM was also removed. Two new configuration parameters were provided on the Advanced tab in the JTAPI Preferences dialog box:

JTAPI Post Condition Timeout

Use Progress As Disconnected

Backward Compatibility

This feature is not backward compatible.

Superprovider and Change Notification

Superprovider enhancements for JTAPI in this release consist primarily of the following changes.

When the "Superprovider privilege" gets disabled from Cisco Unified Communications Manager Administration after a provider opens, JTAPI gets notified through a CTI Change Notification Event and cleans up all the devices that it has opened that are not in its control list.

JTAPI informs applications about the change using the "CiscoProviderCapabilityChangedEvent." This new event gets issued when the flag changes and indicates whether the flag has been enabled or disabled. When a device that is not in the control list is opened in the Superprovider mode, then moved to the control list, JTAPI moves the device into its control list.

When a normal application receives a "CiscoProviderCapabilityChangedEvent" with the flag set, it means the Superprovider privilege has been granted to it, and it can start acquiring devices not in its control list.

When a Superprovider application receives a "CiscoProviderCapabilityChangedEvent" with the Superprovider flag not set, it means that the Superprovider privilege has been removed for it. The following sequence of events then occurs:

Applications receive a Provider OOS event and all devices acquired/opened by it are closed.

Applications receive a CiscoTermRemovedEv for all devices not in the control list that have been acquired or opened.

Applications receive a Provider inService event when JTAPI succeeds in reconnecting to CTI as a normal user.

Applications receive device and line information.

Applications receive CiscoTermCreatedEv for all controlled devices that were open before the provider went OOS.

JTAPI notifies applications by using the "CiscoProviderCapabilityChangedEvent" when the "park DN monitoring" flag is changed from Cisco Unified Communications Manager Administration.

When an application receives this event with the flag set, it does a register feature for the controlling park DN.

When an application receives this event with the flag not set, JTAPI again informs applications by using a "CiscoProviderCapabilityChangedEvent" and closes all the park DN addresses.

JTAPI notifies applications by using the CiscoProviderCapabilityChangedEvent" when the "change calling party number" flag is changed from Cisco Unified Communications Manager Administration.

When an application receives this event with the flag set, it can change the calling party number.

When an application receives this event with the flag not set, it cannot change the calling party number.

Applications should not change the calling party number when this flag is disabled.

When a device that is not in the control list is opened or acquired by Superprovider, and is then deleted from Cisco Unified Communications Manager Administration, JTAPI closes the terminal object and sends a CiscoTermRemovedEvent to the application for that device.

Interface Changes

As a part of the Superprovider and change notification enhancements, JTAPI exposes the following API to applications. The JTAPI implementation for Superprovider and the handling of certain Provider capabilities has changed as a result. Superprovider enhancements for JTAPI in this release consist of the JTAPI QBE interface, changes in JTAPI behavior, and the new API which is exposed to applications.

JTAPI delivers CiscoProviderCapabilityChangedEv to the applications, with the following format. Applications should be able to receive and process this new event from JTAPI.

public interface CiscoProviderCapabilityChangedEv {
	public CiscoProviderCapabilities getCapability ();
}
 
   

CiscoProviderCapabilities have the following new methods for setting calling party modify privilege for the provider:

	public boolean canModifyCallingParty();
  	public void setCanModifyCallingParty(boolean value);
 
   

CiscoProviderCapabilityChangedEv is delivered to the applications with the appropriate flag values.

After this, the following sequence of events occurs:

JTAPI sends provider OOS events to the application and device/line OOS to devices and lines in the control list that are open.

JTAPI then tries to reconnect to CTI.

If reconnect succeeds, JTAPI sends a provider inService event and reopens all the devices in the control list that were previously open.

If reconnect does not succeed, JTAPI shuts down the provider and sends a ProviderClosedEvent.

If Superprovider privilege is added, JTAPI sends a CiscoProviderCapabilityChangedEv to the applications with the appropriate flag values.

If the MonitorParkDN flag is enabled, JTAPI sends a CiscoProviderCapabilityChangedEv with the monitor park DN flag set to true.

If the MonitorParkDN flag is disabled, JTAPI sends a CiscoProviderCapabilityChangedEv with the monitor park DN flag set to false.

JTAPI also closes all the park DN addresses and delivers a CiscoAddrRemovedEv to applications.

When the ModifyCgPn flag is changed, JTAPI sets a flag in the provider object that is checked during redirect scenarios, and applications are accordingly allowed or denied permission to change the calling party.

JTAPI also delivers a CiscoProviderCapabilityChangedEv with the flag set to modify CgPn.

CiscoProvider Interface

boolean

hasSuperproviderChanged()
 
        

Tells the application whether the Superprovider privilege changed.

boolean

hasModifyCallingPartyChanged()
 
        

Tells the application whether the ModifyCgPn privilege changed.

boolean

hasMonitorParkDNChanged()
 
        

Tells the application whether the Park DN monitoring privilege changed.


Backward Compatibility

This feature is not backward compatible.

Alternate Script Support

Certain IP phone types support an alternate language script other than the default script that corresponds to the phone-configurable locale. For example, the Japanese phone locale has two written scripts. Some phone types support only the default Katakana script, while other phones types support both the default script and the alternate Kanji script. Because applications can send text information to the phone for display purposes, they need to know what alternate script a phone supports, if any.

The new getAltScript() method provides alternate script information for an observed device. Currently there is only one known alternate script: Kanji for the Japanese locale.

JTAPI provides a new method for CiscoTerminal to provide alternate script information.

java.lang.String

getAltScript()
 
        

Only one alternate script, Kanji for the Japanese locale, is currently supported. An empty string return value indicates there is no alternate script configured or the terminal does not support an alternate script.


Backward Compatibility

The alternate script feature does not impact JTAPI backward compatibility.

Half-Duplex Media Support

Currently JTAPI media events CiscoRTPInputStarted, CiscoRTPOutputStarted, CiscoRTPInputStopped and CiscoRTPOutputStopped do not indicate whether media is half duplex (receive only / transmit only) or full duplex (both receive and transmit).

This enhancement adds the capability to provide this information in a JTAPI media event. JTAPI provides an interface on the above media events to query whether media is half duplex or full duplex.

The half duplex media support feature does not impact JTAPI backward compatibility.

A new interface getMediaConnectionMode() is added to Cisco Unified JTAPI RTP events. This interface will return the following values depending on the media:

CiscoMediaConnectionMode.NONE

CiscoMediaConnectionMode.RECEIVE_ONLY

CiscoMediaConnectionMode.TRANSMIT_ONLY

CiscoMediConnectionMode.TRANSMIT_AND_RECEIVE.

CiscoRTPInputStarted/StoppedEv should only return RECEIVE_ONLY and TRANSMIT_AND_RECEIVE. The interface should not return NONE or TRANSMIT_ONLY. If that happens, applications should ignore the event or log an error.

CiscoRTPOutputStarted/StoppedEv should only return TRANSMIT_ONLY and TRANSMIT_AND_RECEIVE. The interface should not return values NONE or RECEIVE_ONLY. If that happens, applications should ignore the event or log an error.

CiscoMediaOpenLogicalChannedEv should only return RECEIVE_ONLY and TRANSMIT_AND_RECEIVE. The interface should not return values NONE or TRANSMIT_ONLY. If that happens, applications should ignore the event or log an error.

public interface CiscoRTPInputStartedEv

int

getMediaConnectionMode() 
 
        

Returns CiscoMediaConnectionMode


public interface CiscoRTPOutputStartedEv

int

getMediaConnectionMode()
 
        

Returns CiscoMediaConnectionMode


public interface CiscoRTPInputStoppedEv

int

getMediaConnectionMode()
 
        

Returns CiscoMediaConnectionMode


public interface CiscoRTPOutputStoppedEv

int

getMediaConnectionMode()
 
        

Returns CiscoMediaConnectionMode


Network Alerting

In earlier releases of CiscoJTAPI (CiscoJTAPI versions 1.4(x.y)), when a call was made to an address outside of the cluster, CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv events were delivered to the far end address.

In later versions of Cisco Unified Communications Manager (4.0 and above) and Cisco Unified JTAPI (2.0), these events were not delivered. In these versions CallCtlConnection for the far end address went to the ESTABLISHED state from the OFFERED state. The previous versions of Cisco Unified JTAPI delivered CallCtlConnOfferedEv, CallCtlConnEstablishedEv for the far end address when a call was made across a gateway with "overlap sending" turned off. CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv events were not delivered to the application.

In Cisco Unified Communications Manager 4.0 and 4.1, the "Allow overlap sending" flag on the route pattern configured for the gateway or the "AllowNetworkEventsAfterOffered" parameter in jtapi.ini needed to be turned on to receive network events.

In Cisco Unified Communications Manager Release 5.0, if the "Allow overlap sending" flag is enabled, an application sees ConnCreatedEv, CallCtlConnNetworkReachedEv, CallCtlConnNetworkAlertingEv, and CallCtlConnEstablishedEv for the far end address for calls across a gateway.

If the "Allow overlap sending" flag is not enabled, an application sees ConnCreatedEv, CallCtlConnOfferedEv, CallCtlConnNetworkReachedEv, CallCtlConnNetworkAlertingEv, and CallCtlConnEstablishedEv for the far end address for calls across a gateway.


Note AllowNetworkEventsAfterOffered is not available in Cisco Unified Communications Manager Release 5.0. The above events are delivered regardless of the jtapi.ini parameter setting.


Backward Compatibility

This feature is not backward compatible.

Auto Updater for Linux

In order to support this feature for Linux based JTAPI client machines, auto updater feature has the following changes in its interface. The interface required that applications provide component name, provider IP address, user name and password. Applications do not need to specify an URL for downloading the component. This is done to avoid the issue with updater application in case URL changes between various releases of Cisco Unified Communications Manager Administration.

A new API called "Replace()" is part of the component interface. This facilitates replacing of old component with a newly downloaded component. The following section defines the operation of updater after the new interface changes. The new updater will:

Use the same API signature as the old one.

Create a file newjtapi.jar in the current folder of application ñ which is the new version of the jar file.

Copy the current jtapi.jar to a file by name component.temp in the classpath specified.

Replace the current jar file with the new jar file. At the end of this operation, the current jar file becomes the component.temp and new jar file becomes jtapi.jar. Applications can still use old component interface which take URL either by specifying the URL themselves or by querying the URL through the new interface provided on CiscoProvider. The API required to get the URL information is present in the Interface summary for this feature. This operation is supported for both Unix and Windows.

Backward Compatibility

This feature is not backward compatible.

Call Select Status

Cisco JTAPI sends CiscoTermConnSelectChangedEv event whenever the call is selected either by feature or by manually. Once application receives the event, application can use TerminalConnection.getSelectStatus() to get proper call select status. There are three possible statuses by calling TerminalConnection.getSelectStatus() as follows:

CiscoTerminalConnection. CISCO_SELECTEDNONE: The select status means that the call is not selected

CiscoTerminalConnection. CISCO_ SELECTEDLOCAL: The select status means that the call is selected on the terminal connection

CiscoTerminalConnection. CISCO_ SELECTEDREMOTE: Passive TerminalConnection will get this select status if the call is selected by it's shared line

Backward Compatibility

This feature is not backward compatible.

JTAPI Version Information

In order to connect to Release 5.0 of Cisco Unified Communications Manager Administration, JTAPI clients have to upgrade to the new version of JTAPI bundled with the Cisco Unified Communications Manager Administration Release 5.0. JTAPI version is in the form of 3.0(X.Y), where X and Y depend on the sub-release. Applications cannot connect with prior release of JTAPI.

Backward Compatibility

This release of JTAPI is backward compatible with applications written for Cisco Unified Communications Manager Release 6.0. CiscoJtapiClient upgrade is not mandatory.

Cisco JtapiClient upgrade is not mandatory. Applications are required to upgrade to Cisco Unified Communications Manager Release 6.1, CiscoJTAPIClient only if using any of the new features developed in Cisco Unified Communications Manager Release 6.1.

When a user upgrades from Cisco Unified Communications Manager 4.x (Windows) to Cisco Unified Communications Manager 7.0(1) (Windows/Linux), the plugin URL to download the jtapi.jar is different. In Cisco Unified Communications Manager Release 7.0(1), the plugin URL from 6.x releases is maintained.

The applications should comply with the following rules:

The order of Cisco JTAPI events, beyond that which is required for JTAPI protocol operation, may change. Application developers should not depend upon the order of events, beyond that which is required for JTAPI protocol operation. Applications should be able to recover from out of order events, even when the order is required for (API Name) protocol operation.

Applications should avoid using deprecated methods.

Application should expect to see new behavior and/or event order with new phones.

Application should gracefully ignore events it does not handle. For example: CiscoCallChangedEv can be ignored if applications chooses to use CiscoTransferStart and End events.

Application should have a default behavior for reasons that it is not aware of.

Applications should have a default behavior for undefined error codes.

Any behavior not defined in JTAPI 1.2 specification and not described in Cisco Unified JTAPI Developers Guide should not be considered as a feature.

For Cisco Unified Communications Manager Administration Release 4.x (Windows), the URL is http://<servername or ip address>/CCMPluginsServer/jtapi.jar.

For Cisco Unified Communications Manager Administration Release 6.x and 7.0(1) (Linux), the URLis http://<server name or ip address>/plugins/jtapi.jar.

For Cisco Unified Communications Manager Administration Release 7.0(1) (Windows), the URL is http://<server name or ip address>/plugins/jtapi.jar.

The backward compatibility with regard to the plugin URL is not maintained between Cisco Unified Communications Manager Release 4.x and Cisco Unified Communications Manager Release 7.0(1).