Cisco Unified JTAPI Developers Guide for Cisco Unified Communications Manager Release 7.0(1)
Features Supported by Cisco Unified JTAPI
Downloads: This chapterpdf (PDF - 570.0KB) The complete bookPDF (PDF - 7.6MB) | Feedback

Features Supported by Cisco Unified JTAPI

Table Of Contents

Features Supported by Cisco Unified JTAPI

Call Forward

Call Park

Park Retrieval

Park Reminder

Park DN Monitor

CiscoJtapiExceptions

Cisco Unified JTAPI Install Internationalization

Clear Calls

Device Recovery

Device Recovery for Phones

CTI RoutePoints

CTI Ports

Directory Change Notification

Enable or Disable Ringer

Transfer and Conference Extensions

Transfer

CiscoTransferStartEv

CiscoTransferEndEv

Transfer Scenarios

Conference

Cisco Extensions

Conference Scenarios

Conference Events

Transfer and Conference Enhancement

Consult Without Media

Media Termination Extensions

Cisco Unified Communications Manager Media Endpoint Model

Payload and Parameter Negotiation

Initialization

Payload Selection

Receive Channel Allocation

Starting Transmission and Reception

Stopping Transmission and Reception

Cisco MediaTerminal

Provisioning

Registration

Adding Observers

Accepting Calls

Receiving and Responding to Media Flow Events

Inbound Call Media Flow Event Diagram

Cisco Unified Communications Solutions RTP Implementation

Redirect

Routing

Cisco Route Session Implementation

Select Route Timer

Forwarding Timer

Route Session Extension

Caller Options Summary

Fault Tolerance When Using Route Points

Redundancy

Cluster Abstraction

Cisco Unified Communications Manager Server Failure

Redundancy in CTI Managers

Invoking CTIManager Redundancy

CTIManager Failure

Heartbeats

Calling Party Display Name

Set MessageWaiting

Quiet Clear

GetCallInfo

DeleteCall

GetGlobalCallID

GetCallID in RTP Events

XSI Object Pass Through

CiscoTerminal Method

Authentication and Mechanism

Cisco VG248 and ATA 186 Analog Phone Gateways

Multiple Calls Per DN

Shared Line Support

Transfer and DirectTransfer

Conference and Join

Barge and Privacy Event Notification

CallSelect and UnSelect Event Notification

Dynamic CTI Port Registration

Media Termination at Route Point

Redirect Set Original Called ID

Single Step Transfer

Autoupdate of API

Changes in DeviceType Name Handling

CiscoTerminal Filter and ButtonPressedEvents

Modifying Calling Number

AutoAccept Support for CTI Ports and Route Points

CiscoTermRegistrationFailed Event

SelectRoute Interface Enhancement

Presentation Indicator for Calls

Progress State Converted to Disconnect State

Device State Server

Forced Authorization and Client Matter Codes

Supported Interfaces

Call.Connect() and Call.Consult()

Call.transfer(String) and Connection.redirect()

RouteSession.selectRoute()

Super Provider (Disable Device Validation)

Q.Signaling (QSIG) Path Replacement

Network Events


Features Supported by Cisco Unified JTAPI


This chapter describes features that are supported by the Cisco Unified JTAPI specification and contains the following:

Call Forward

Call Park

Park Retrieval

Park Reminder

Park DN Monitor

CiscoJtapiExceptions

Cisco Unified JTAPI Install Internationalization

Clear Calls

Device Recovery

Device Recovery for Phones

CTI RoutePoints

CTI Ports

Directory Change Notification

Enable or Disable Ringer

Transfer and Conference Extensions

Transfer

Conference

Consult Without Media

Media Termination Extensions

Cisco Unified Communications Manager Media Endpoint Model

Cisco MediaTerminal

Receiving and Responding to Media Flow Events

Redirect

Routing

Redundancy

Cluster Abstraction

Cisco Unified Communications Manager Server Failure

Redundancy in CTI Managers

Calling Party Display Name

Set MessageWaiting

Quiet Clear

GetCallInfo

DeleteCall

GetGlobalCallID

GetCallID in RTP Events

XSI Object Pass Through

Cisco VG248 and ATA 186 Analog Phone Gateways

Multiple Calls Per DN

Shared Line Support

Transfer and DirectTransfer

Conference and Join

Barge and Privacy Event Notification

CallSelect and UnSelect Event Notification

Dynamic CTI Port Registration

Media Termination at Route Point

Redirect Set Original Called ID

Call Forward

Cisco Unified JTAPI supports setting the Call Forward feature according to the JTAPI Specification. Cisco Unified JTAPI implementation does not support all the forwarding characteristics but supports only the FORWARD_ALL attribute for the Address. Applications can invoke setForwarding, getForwarding, and cancelForwarding methods on a CallControlAddress object, but the CallControlForwarding instruction can only be of type FORWARD_ALL.

Call Park

Cisco Unified JTAPI supports user interactions with Call Park and reports the appropriate events to the applications. When a call is parked from an IP phone, the connection that belongs to the parking address moves into Disconnected state, and the associated TerminalConnection moves into Dropped state. A new connection in queued state for the park number gets created.

If an application is monitoring only the address that parked the call, all existing connections get Disconnected, TerminalConnections get Dropped, and the call moves to Invalid state.

Park Retrieval

When a call is parked from an IP phone, the park number displays on the phone. Any terminal can unpark the call by dialing the park number. When a call is unparked, a new call gets created with connections to unparked address. The CallControlConnection for the park number in the original call, which is in the Queued state, moves to the Disconnected state.

Park Reminder

When a parked call is not retrieved for a specified time, a reminder call returns to the address that parked the call, and Park Number connection moves to the Disconnected state. The call reconnects and moves to the Established state. A terminal connection in Talking state gets created for the address that parked the call.

Park DN Monitor

Cisco Unified JTAPI applications can register to receive events when calls are parked and unparked. CiscoProvCallParkEv events will be delivered to provider observer when the application registers for this feature. To successfully register for this feature, ensure that the "call park retrieval allowed" flag for the user is turned on. You can access this flag with the user configuration on Cisco Unified Communications Manager Administration. After registering for this feature, the application will receive CiscoProvCallParkEv events whenever a call is parked or unparked from any device in the cluster.

The following new interfaces allow applications to register and unregister for this feature:

public interface CiscoProvider {
public void registerFeature ( int featureID ) throws  
	InvalidStateException, PrivilegeViolationException;
public void unregisterFeature ( int featureID ) throws  
	InvalidStateException;
}

The featureID is CiscoProvFeatureID.MONITOR_CALLPARK_DN.

CiscoJtapiExceptions

Cisco Unified JTAPI notifies the application of CTI-generated error codes. These codes return when an exception or error occurs in the CTIManager. The CTI returned error code propagates to the application separately. The application can extract the error code by invoking getErrorCode() method on the exception object, can get CTI error code name by invoking getErrorName() method, and can get error description by invoking method getErrorDescription().

The methods getErrorName(int errorCode) and getErrorDescription (int errorCode) deprecate and get removed in future releases. Cisco recommends that application users do not use these methods.

Cisco Unified JTAPI Install Internationalization

Cisco Unified JTAPI supports multiple languages for the JTAPI installation and user preference UI. When JTAPI launches, you receive options for choosing languages for the installation. After choosing a language, further installation instructions display in the chosen language. The first option always specifies English. If certain phrases are missing in the locale language, the instructions default to English. See Chapter 4, "Cisco Unified JTAPI Installation" for more information.

Clear Calls

Cisco Unified JTAPI applications can clear phantom calls without dropping active calls. The CiscoAddress provides a clearCallConnections message to allow applications to clear the calls when no active calls exist on the Cisco Unified Communications Manager (formerly Cisco Unified CallManager).

Device Recovery

Cisco Unified JTAPI supports automatic device recovery.

Device Recovery for Phones

For devices such as the Cisco Unified IP Phone 7960, the re-homing feature represents part of the device firmware. On a primary Cisco Unified Communications Manager failure, the phone attempts to connect to the backup Cisco Unified Communications Manager when it is no longer on a call. This transition gets communicated to applications in the form of out-of-service and in-service events that the CTIManager Failure section describes.

For virtual devices with no firmware such as CTI Ports and CTI RoutePoints, the CTIManager or Cisco Unified JTAPI performs the failover.

CTI RoutePoints

On a Cisco Unified Communications Manager server failure, the CTIManager recovers the device from the Cisco Unified Communications Manager server group as defined in the device pool administration for the CTI RoutePoint. When the primary Cisco Unified Communications Manager server recovers, the CTIManager attempts to recover the device on its primary Cisco Unified Communications Manager. This re-homing happens when no more calls exist on the device (similar to physical devices).

On a CTIManager failure, Cisco Unified JTAPI recovers the device on the backup CTIManager. The application receives notification of the availability of a device with the CiscoAddrOutOfServiceEv and CiscoAddrInServiceEv events.

CTI Ports

CTI Ports that are registered by an application include a mechanism similar to phone devices. When the Cisco Unified Communications Manager that is handling signaling for a CTIPort fails, the CTIManager recovers its services according to the device pool administration for this device. On a CTIManager failure, Cisco Unified JTAPI reregisters the CTI Port after it connects to the backup CTIManager. The CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv events and the corresponding in-service events get sent after recovery of the CTI Port.

The application controls media streaming for these devices, and streaming continues even when the port is out of service. The application has responsibility to ensure that new calls do not get presented to the device until it is ready to accept them.

Directory Change Notification

Applications require notification asynchronously of device additions or deletions from the user control list and device deletions from the Cisco Unified Communications Manager database. Applications also receive notification about line changes to a device. This notification gets sent to Cisco Unified JTAPI, propagates to applications with CiscoAddrCreatedEv, CiscoAddrRemovedEv, CiscoTermCreatedEv, and CiscoTermRemovedEv on the AddressObserver and TerminalObservers, respectively.


Note Ensure that the device is registered for CTIPorts and CTIRoutePoints to receive the line change notification.


Enable or Disable Ringer

The CiscoAddress extension allows applications to set the status of the ringer for all lines on a device. No events generate when the ringer setting gets changed from the administration pages or anywhere else.

Transfer and Conference Extensions

You may find that transfer and Conference events are difficult to understand in JTAPI. This happens because, when the participants are moved from one call to the other, JTAPI represents this action by deleting the parties from one call and adding them to the other call. It may confuse you for an application to receive an indication that a party dropped from the call when, in reality, it is in the process of being moved. The Cisco Unified JTAPI implementation defines some extra events that make it easier for applications to deal with these functions.

Transfer

The transfer feature moves the participants of one call, the transferred call, to another call, the final call. Moving participants in a call results in their associated Connections transitioning to the DISCONNECTED state in the transferred call and new Connections for these participants being created in the final call. Similarly, any associated TerminalConnections transition into the DROPPED state in the transferred call and get created in the final call. Cisco extensions by definition mark the start and the end of the events that relate to transfer.

You can correlate the newly created connection objects with the old connection objects by use of the CiscoConnection.getConnectionID() method to obtain the CiscoConnectionID for the old and new connections. Matching connections possess identical CiscoConnectionID objects when compared by using the CiscoConnectionID.equals() method.

CiscoTransferStartEv

This event indicates that the transfer operation started, and the events that follow relate to this operation. Specifically, Connections and TerminalConnections get both removed and added as a result of the transfer.

Applications may obtain the two calls that are involved in transfer-transferred call and final call and the transfer controller information from this event. If the JTAPI application is not observing the transfer controller, the transfer controller information does not get made available in this event.

CiscoTransferEndEv

This event indicates that the transfer operation ended. After this event is received, the application can assume that all involved parties transferred, and all Connections and TerminalConnections moved to the final call.

Transfer Scenarios

In the following scenarios, A, B, and C represent three parties that are involved in the transfer.

Consult Transfer; B is the Transfer Controller

In a consult transfer, applications can redirect calls to a different address, and the transferrer can "consult" with the transfer destination before redirecting.

A calls B on call Call1.

B answers and consults to C on call Call2.

B transfers call Call2 to call Call1.

To do this type of transfer, use the following JTAPI methods:

Call2.setTransferEnable(true) (This optional method means transfer is enabled in the call object by default.)

Call2.consult(TermConnB, C)

Call1.transfer(Call2)


Note During consult transfer, Call1.transfer(Call2) will transfer the call but not Call2.transfer(Call1).


Table 3-1 lists the core events that observers of A and B receive between the CiscoTransferStartEv and the CiscoTransferEndEv:

Table 3-1 Core Events for Observers of A and B 

Meta Event Cause
Call
Event
Fields

META_UNKNOWN

Call1

CiscoTransferStartEv

transferredCall=Call2
finalCall=Call
transferController=
TermConnB

META_CALL_TRANSFERRING

Call1

TermConnDroppedEv B
CallCtlTermConnDroppedEv B
ConnDisconnectedEv B
CallCtlConnDisconnectedEv B

 

META_CALL_TRANSFERRING

Call1

ConnCreatedEv C
ConnConnectedEv C
CallCtlConnEstablishedEv C
TermConnCreatedEv C
TermConnActiveEv C
CallCtlTermConnTalkingEv C

 

META_CALL_TRANSFERRING

Call2

TermConnDroppedEv B
CallCtlTermConnDroppedEv B
ConnDisconnectedEv B
CallCtlConnDisconnectedEv B

 

META_CALL_TRANSFERRING

Call2

TermConnDroppedEv C
CallCtlTermConnDroppedEv C
ConnDisconnectedEv C
CallCtlConnDisconnectedEv C
CallInvalidEv C

 

META_UNKNOWN

Call2

CallObservationEndedEv

 

META_UNKNOWN

Call1

CiscoTransferEndEv

transferredCall=Call2
FinalCall=Call1
transferController=
TermConnB


Arbitrary Transfer; A is the Transfer Controller

In an arbitrary transfer, one call can get transferred to another call, irrespective of how either call was created. Unlike consult transfer, no need exists to first create one of the calls by using the consult method.

A calls B on call Call1.

A puts Call1 on hold.

A calls C on call Call2.

A transfers Call1 to Call2.

To do this type of transfer, use the following JTAPI methods:

Call2.transfer(Call1) to transfer call Call1 to final call Call2, or

Call1.transfer(Call2) to transfer call Call2 to final call Call1

Assuming Call1.transfer(Call2) was called, Table 3-2 lists the core events that observers on A and C receive between CiscoTransferStartEv and CiscoTransferEndEv:

Table 3-2 Core Events for Observers of A and C 

Meta Event Cause
Call
Event
Fields

META_UNKNOWN

Call1

CiscoTransferStartEv

transferredCall=Call2
finalCall=Call1
transferController=
TermConnB

META_CALL_TRANSFERRING

Call1

TermConnDroppedEv B
CallCtlTermConnDroppedEv B
ConnDisconnectedEv B
CallCtlConnDisconnectedEv B

 

META_CALL_TRANSFERRING

Call1

ConnCreatedEv C
ConnConnectedEv C
CallCtlConnEstablishedEv C
TermConnCreatedEv C
TermConnActiveEv C
CallCtlTermConnTalkingEv C

 

META_CALL_TRANSFERRING

Call2

TermConnDroppedEv B
CallCtlTermConnDroppedEv B
ConnDisconnectedEv B
CallCtlConnDisconnectedEv B

 

META_CALL_TRANSFERRING

Call2

TermConnDroppedEv C
CallCtlTermConnDroppedEv C
ConnDisconnectedEv C
CallCtlConnDisconnectedEv C
CallInvalidEv C

 

Conference

When conferencing two calls together, JTAPI specifies that all the parties from one call be moved to the other call. The call whose parties are moved away and that subsequently becomes invalid gets identified as the "merged" or "consult" call. The call to which the merged parties move gets identified as the "final" call hereafter. When parties move from the merged call to the final call, the application receives events that indicate that all parties dropped from the merged call and events that indicate that the parties reappeared on the final call.

To correlate the newly created connection objects with the old connection objects, use the CiscoConection.getConnectionID() method to obtain CiscoConnectionID objects for all old connections and all new connections. Matching connections will have identical CiscoConnectionID objects when compared by using the CiscoConnectionID.equals() method.

Conference support exists for the following methods:

javax.telephony.callcontrol.CallControlCall.conference(Call)

javax.telephony.callcontrol.CallControlCall.getConferenceController()

javax.telephony.callcontrol.CallControlCall.getConferenceEnable()

javax.telephony.callcontrol.CallControlCall.setConferenceController(TerminalConnection)

javax.telephony.callcontrol.CallControlCall.setConferenceEnable(boolean)

Cisco Extensions

Cisco Unified JTAPI implementation provides two extra events that signal the Start and End of Conference: CiscoConferenceStartEv and CiscoConferenceEndEv. These events get sent when Conference initiates and when it completes. They give handles to the final call, the merged conference (consult) call, and the two controlling TerminalConnections (in HELD and TALKING state).

CiscoConferenceStartEv

This event gets sent when call1.conference(call2) is invoked or if the Conference button is pressed for the second time on an IP phone. The ConferenceStartEv signifies the start of the merging process. A sequence of merging events that are reflected by the Conference process in Cisco Unified Communications Manager follows.

CiscoConferenceEndEv

This event gets sent at the end of the merge process after a ConferenceStartEv is sent. It signifies the completion of the merge of the Consult (or Merged) call into the Final Conference Call. The Merged call specifies in INVALID state and an ObservationEndedEv gets sent for the call observer.

CiscoCall.setConferenceEnable()

The Cisco Unified JTAPI implementation uses the CiscoCall.setConferenceEnable() and the CiscoCall.setTransferEnable() methods to control whether the consult call will be initiated via the conference or the transfer feature. If none of the features is enabled explicitly, transfer gets used by default.

Conference Scenarios

The following scenarios describe the two typical types of Conference that can be invoked.

Consult Conference; B as the Conference Controller

The following sequence of steps typically describes this scenario:

A calls B (Call 1).

B answers.

B Consults C (Call 2).

setConferenceEnable()

call2.consult(tc, C)

C answers.

B Completes Conference.

Call1.conference(Call2)


Note You must invoke the conference() method on the original call to complete a conference after a consultation. Invoking conference in the consult call object throws an exception.


Arbitrary Conference; B as the Conference Controller

The following sequence of steps typically describe this scenario:

A calls B (Call 1).

B answers.

B places the call on hold.

B calls C (Call 2).

C answers.

B Completes Conference.

Call1.conference(Call2) or

Call2.conference(Call1)

Conference Events

Table 1-4 provides the sequence of Core, Call control, and Cisco Extension events when Call1.Conference(Call2) is called:

Table 3-3 Sequence of Events 

Meta Event Cause
Call
Event
Fields

META_UNKNOWN

Call1

CiscoConferenceStartEv

consultCall = Call2
finalCall = Call1
conferenceController=
TermConnB

META_CALL_MERGING

Call1

CallCtlTermConnTalkingEv B

 

META_CALL_MERGING

Call1

ConnCreatedEv C
ConnConnectedEv C
CallCtlConnEstablishedEv C
TermConnCreatedEv C
TermConnActiveEv C
CallCtlTermConnTalkingEv C

 

META_CALL_MERGING

Call2

TermConnDroppedEv B
CallCtlTermConnDroppedEv B
ConnDisconnectedEv B
CallCtlConnDisconnectedEv B

 

META_CALL_MERGING

Call2

TermConnDroppedEv C
CallCtlTermConnDroppedEv C
ConnDisconnectedEv C
CallCtlConnDisconnectedEv C
CallInvalidEv C

consultCall=Call2
finalCall=Call1
conferenceController=
TermConnB

META_UNKNOWN

Call2

CallObservationEndedEv

 

META_UNKNOWN

Call1

CiscoConferenceEndEv

 

Transfer and Conference Enhancement

All parties who are involved in the call transfer get sent CiscoTransferStartEv and CiscoTransferEndEv. All parties involved in the call conference get sent CiscoConferenceStartEv and CiscoConferenceEndEv. A call transfer still generates two events—the dropping of a connection to the first call and the creation of a connection to the second call. Cisco Unified Communications Manager Release 3.1 changed this order of events. Connections first get created in the final call and then get dropped in the consult call.


Note In Cisco Unified Communications Manager Release 3.0, not all parties who are involved in the transfer of calls received these events



Note Applications should not rely on the order of events between CiscoTransferStartEv and CiscoTransferEndEv or between CiscoConferenceStartEv and CiscoConferenceEndEv for transferring and conferencing when porting applications from Cisco Unified Communications Manager Release 3.0 to 3.1.


Consult Without Media

Applications can inform Cisco Unified Communications Manager that a consultation call for a transfer is being placed without establishing the media path. The system does not require establishing the media path for the intermediate call, if the consultation call is being placed to determine whether an agent is available before the actual transfer. The consultWithoutMedia method as defined in the CiscoConsultCall interface creates a consultation call without establishing the media path.


Note The system allows only transferring the consultation call; it does not allow the call to be conferenced.


Media Termination Extensions

The media termination feature allows applications to transmit and capture the bearer of a call, for example, audio or video. This action sometimes gets referred to as "rendering and recording" or "sourcing and sinking" media. It remains distinct from call control because media termination concerns the data that flows between endpoints in a call, not the details of setting up or tearing down calls. For example, an automatic call distributor (ACD) uses call control to route calls among available agents but does not terminate media. An interactive voice response (IVR) application, on the other hand, uses call control to answer and disconnect calls and uses media termination to play sound files to callers.

Although no telephony applications are solely interested in media termination, this feature always gets used in combination with call control. JTAPI 1.2 primarily represents a call control specification and offers very limited support for applications that require media termination. Because the Cisco Unified Communications Solutions platform supports media termination to a much greater degree than JTAPI standard, the Cisco Unified JTAPI implementation extends JTAPI to add full support for this feature.

In Cisco Unified JTAPI, software-based media termination occurs by using Computer Telephony Integration (CTI) ports. They include one or more lines (dialable numbers) that can be used to originate or receive calls. They however need a controlling application to provide the source and sink of the media. An application registers its interest in the media termination port with the Cisco Unified Communications Manager. The Cisco Unified Communications Manager then delivers all the events that relate this virtual device to the application. In Cisco Unified JTAPI, CTI Ports get referred to as CiscoMediaTerminals. Figure 1-3 shows the CTI port configuration. For details about administering and configuring a CTI Port, refer to the Cisco Unified Communications Manager Administration information.

Figure 3-1 CTI Port Diagram

To implement a softphone application (where the PC acts as the telephone set, for example), the Cisco Unified JTAPI application would manage a CTI port.

Cisco Unified Communications Manager Media Endpoint Model

Endpoints represent the entities within the Cisco Unified Communications Solutions platform that terminate media, such as IP telephones and gateways. A call from one endpoint to another results in media flowing between the two endpoints. All endpoints in the Cisco Unified Communications Solutions platform transmit voice data by using real-time protocol (RTP). The Cisco Unified Communications Solutions telephones and gateways, for example, include built-in RTP stacks. Applications may also act as endpoints in a Cisco Unified Communications Solutions system; that is, they may terminate media. Because all Cisco Unified Communications Solutions endpoints use RTP, applications also must be able to transmit and receive RTP packets.

Payload and Parameter Negotiation

In addition to bearer data and payload, each RTP packet contains a header that helps endpoints to determine how to reassemble and decode a sequence of such packets into a media stream. RTP does not provide, however, a means for endpoints to negotiate which payload type to use for a particular stream. For example, audio data that is encoded by using the G.711 standard. Furthermore, RTP does not offer a means of negotiating unique payload type parameters such as the sampling rate of the encoded data or the number of samples that are to be transferred in each RTP packet. Instead, RTP usually gets used in conjunction with another protocol such as H.323, which specifies its own method for endpoints to negotiate these parameters. All such negotiation occurs prior to transmitting RTP packets between endpoints.

Cisco Unified Communications Manager, not the endpoints, has responsibility for selecting the payload and encoding parameters for RTP streams. The following five steps that are involved in a typical bidirectional audio telephone call apply:

Initialization

Payload Selection

Receive Channel Allocation

Starting Transmission and Reception

Stopping Transmission and Reception

Initialization

Upon startup, each endpoint informs Cisco Unified Communications Manager of its media capabilities, that is, G.711, G.723, G.729a, and so on. Startup for an IP phone for example, occurs when the phone is first turned on, or after it recontacts Cisco Unified Communications Manager after losing its former connection. The endpoint cannot express a preference for one payload type versus another, but it can specify certain parameters for each payload type, such as, packet size.

The capability list that the endpoint registers remains exclusive and immutable. If the endpoint specifies that it can support both G.711 and G.723, it implicitly declares that it cannot support G.729a. Moreover, the endpoint must disconnect from Cisco Unified Communications Manager and reinitialize to change the list of capabilities that it supports.

JTAPI applications perform this step by registering a CiscoMediaTerminal with Cisco Unified Communications Manager. The CiscoMediaTerminal.register() method allows applications to supply an array of media capability objects for registration with Cisco Unified Communications Manager. This step informs Cisco Unified Communications Manager that the application will act as the endpoint for all calls to or from a particular directory number, as determined by the device configuration in the Cisco Unified Communications Manager configuration.

Payload Selection

When a bidirectional media stream is about to be created between two endpoints, for instance, when a call is answered at an endpoint, Cisco Unified Communications Manager selects an appropriate payload type (codec) for the media stream. Cisco Unified Communications Manager compares the media capabilities of both endpoints that are involved in the call and selects the appropriate common payload type and payload parameters to use.

The basis for payload selection includes endpoint capabilities and location, although other criteria may get added to this selection logic in the future. Endpoints do not get dynamically involved in selecting payload types on a call-by-call basis.

Receive Channel Allocation

If Cisco Unified Communications Manager can find a common payload type for the RTP stream between the two endpoints, it requests that each endpoint create a logical "receive channel;" that is, a unique IP address and port at which the endpoint will receive RTP data for the call. Each endpoint returns an IP address and port to Cisco Unified Communications Manager in response to this request.

Currently, only IP phones and gateways perform this step. Cisco Unified Communications Manager requires JTAPI applications to specify a fixed IP address and port during initialization. Therefore, JTAPI applications cannot terminate more than one media stream simultaneously for the same endpoint. Applications that want to terminate multiple media streams must register multiple endpoints simultaneously.

If the endpoint does not respond to the open receive channel request quickly enough, Cisco Unified Communications Manager disconnects the call. Because JTAPI applications always supply an IP address when registering CiscoMediaTerminals, calls to application-controlled endpoints do not get disconnected for this reason. However, if Cisco Unified Communications Manager cannot find a common payload type between the two endpoints that are involved in the call, Cisco Unified Communications Manager disconnects the call.

Starting Transmission and Reception

After Cisco Unified Communications Manager receives channel information for both parties, it informs each endpoint of the codec parameters that it selected for the RTP stream and the destination address for the other endpoint. This information gets conveyed in two messages to each endpoint: a start transmission message and a start reception message.

JTAPI applications receive the CiscoRTPOutputStartedEv and CiscoRTPInputStartedEv events that contain all the codec parameters that are necessary for sending and receiving RTP data.

As a part of the QoS baselining effort in JTAPI, CiscoRTPOutputStartedEv provides the getPrecedenceValue() API to applications. CTI presents this value, "The DSCP for Audio Calls" to JTAPI. Using this value, applications can set the DSCP value for the media streams that they open.

Stopping Transmission and Reception

When the RTP stream must be interrupted because of a feature such as hold or disconnect, Cisco Unified Communications Manager requests that each endpoint stop its transmission and reception of RTP data. Just as when the media flow is started, the stop transmission and stop reception messages get sent separately.

JTAPI applications receive the CiscoRTPOutputStoppedEv and CiscoRTPInputStoppedEv.

Cisco MediaTerminal

In JTAPI, the terminal object represents the logical endpoint for a call and is presumed to be able to receive and transmit data (digital encoded voice samples, for example). Thus, terminals in JTAPI represent Cisco Unified IP Phones. Even though gateways terminate media, terminals do not represent them. The CiscoMediaTerminals in particular represent a special kind of endpoint for which applications take responsibility for media termination.

The following four steps associate with using CiscoMediaTerminals:

Provisioning

Registration

Adding Observers

Accepting Calls

Provisioning

Ensure CiscoMediaTerminals, which are analogous to physical terminals, get provisioned accordingly in Cisco Unified Communications Manager, even though they do not represent actual hardware IP phones or gateways. Just as IP phones must be added to Cisco Unified Communications Manager database by using the Device Wizard, CiscoMediaTerminals get added the same way, so Cisco Unified Communications Manager can associate the application endpoint with a directory number and other call control properties such as call forwarding. No device type called "CiscoMediaTerminal" exists in the DeviceWizard. Instead, Cisco Unified Communications Manager has one or more device types that support application registration—each of these types get exposed as a CiscoMediaTerminal through JTAPI. Currently, only the device type "CTI port" represents a CiscoMediaTerminal in JTAPI.

This procedure lists the steps for provisioning a CTI port for use as an application-controlled endpoint.

Procedure


Step 1 Within the Cisco Unified Communications Manager configuration web pages, add a "CTI port" device from the Device-Phone web page by using the Device Wizard. The CTI port device name specifies the name of the corresponding CiscoMediaTerminal in JTAPI.

Step 2 Add the new CTI port device, by using the User-Global Directory web page, to the list of devices that the application controls by using the User web page.


For more information, refer to the Cisco Unified Communications Manager Administration Guide.

Registration

After a media termination device is properly provisioned in Cisco Unified Communications Manager, the application may obtain a reference to the corresponding CiscoMediaTerminal object by using either the Provider.getTerminal() method or CiscoProvider.getMediaTerminal() method. The the two methods differ in that the CiscoProvider.getMediaTerminal() method only returns CiscoMediaTerminals, whereas Provider.getTerminal() will return any terminal object that is associated with the provider, including those representing physical IP phones.

Use the CiscoMediaTerminal.register() method to notify Cisco Unified Communications Manager of the intent to terminate RTP streams of certain payload types. The CiscoMediaTermina.register() method takes an IP address, a port number, and an array of CiscoMediaCapability objects that indicate the types of codecs that are supported by the application as well as codec-specific parameters.

The IP address and port indicate the address where the application can receive media streams. The following sample code demonstrates how to register a CiscoMediaTerminal and bind it to a local address, port number 1234:

CiscoMediaTerminal registerTerminal (Provider provider, String terminalName) {
  final int PORT_NUMBER = 1234;
  try {
   CiscoMediaTerminal terminal = provider.getTerminal (terminalName);
   CiscoMediaCapability [] caps = new CiscoMediaCapability [1];
   caps[0] = CiscoMediaCapability.G711_64K_30_MILLISECONDS;
   terminal.register (InetAddress.getLocalHost (), PORT_NUMBER, caps);
  }
  catch (Exception e) {
    return null;
  }
}

For this sample code to work, ensure the specified provider is IN_SERVICE. Further, be aware that this code uses the constant CiscoMediaCapability.G711_64K_30_MILLISECONDS. This actually represents a static reference to a CiscoG711MediaCapability object that specifies a 30-millisecond maximum RTP packet size. The CiscoMediaCapability class predefines this and other common media formats.

To specify a media payload that is not listed in the CiscoMediaCapability class, two options exist. If the desired payload type is a simple variation of one of the existing subclasses of CiscoMediaCapability, you only need to construct a new instance of the subclass. For instance, if an application can support G.711 payloads with a 60-millisecond maximum RTP packet size, it can construct the CiscoG711MediaCapability object directly, specifying 60 milliseconds in the constructor.

Alternatively, if no existing subclass of CiscoMediaCapability that matches the desired payload type exists, construct an instance of the CiscoMediaCapability class directly. The maximum packet size, for example, 30-milliseconds, represents the only other parameter that may be specified when constructing a CiscoMediaCapability.

The following code illustrates registering a custom payload capability:

CiscoMediaTerminal registerTerminal (Provider provider, String terminalName) {
  final int PORT_NUMBER = 1234;
  try {
   CiscoMediaTerminal terminal = provider.getTerminal (terminalName);
   CiscoMediaCapability [] caps = new CiscoMediaCapability [1];
   caps[0] = new CiscoMediaCapability (
     RTPPayload.G728,
     30  // maximum packet size, in milliseconds
     );
   terminal.register (InetAddress.getLocalHost (), PORT_NUMBER, caps);
  }
  catch ( Exception e) {
    return null;
  }
}

The payload type parameter that is used for constructing the CiscoMediaCapability object corresponds to the payload field in the RTP header. The RTPPayload interface defines a number of well-known payload types for this purpose.

Adding Observers

To receive events that indicate where and when to transmit and receive RTP data, place a CiscoTerminalObserver on the CiscoMediaTerminal. The CiscoTerminalObserver extends the standard JTAPI TerminalObserver interface without defining any new methods; it provides a marker interface that signals the application interest in receiving RTP events.


Note Because this is a TerminalObserver, not a CallObserver, it must get added by using the Terminal.addObserver() method, not the Terminal.addCallObserver() method.


Additionally, add a CallControlCallObserver to the Address object that is associated with the CiscoMediaTerminal. This guarantees that the application will get notified when calls are offered to the CiscoMediaTerminal. Unlike regular IP phones, which automatically accept any offered call, CiscoMediaTerminals accept, disconnect (reject), or redirect any call that is offered to it. Because the CallCtlConnOfferedEv is only presented to CallControlCallObservers that are placed on Address objects, not Terminal objects, the application places its CallControlCallObserver in the correct place.


Note Be sure to implement the CallControlCallObserver interface, not just the CallObserver interface; the CallCtlConnOfferedEv will not get delivered to observers that implement only the core CallObserver interface.


Accepting Calls

When an inbound call arrives at the CiscoMediaTerminal address, it must be accepted by using the CallControlConnection.accept() method before a terminal connection gets created. This process does not apply for outbound calls —the connection will occur in the CallControlConnection.ESTABLISHED state as soon as the call progresses beyond digit recognition. After the connection is accepted, answer the ringing terminal connection to start media flow. Assuming that Cisco Unified Communications Manager can match the capabilities that were registered with the capabilities of the calling endpoint, Cisco Unified Communications Manager sends the Media Flow events, so the application can begin transmitting and receiving RTP data.

Receiving and Responding to Media Flow Events

Whenever a media stream must be created between two endpoints, Cisco Unified Communications Manager issues start transmission and start reception events to both endpoints. In JTAPI, the CiscoRTPOutputStartedEv and CiscoRTPInputStartedEv events represent the start transmission and start reception events. The CiscoRTPOutputStartedEv.getRTPOutputProperties() method returns a CiscoRTPOutputProperties object, from which the application can determine the destination address of its peer endpoint in the call, as well as the other RTP properties for the stream such as payload type and packet size. Similarly, the CiscoRTPInputStartedEv.getRTPInputProperties() method returns a CiscoRTPInputProperties object that informs the application of the RTP characteristics for the inbound stream.

At any time while media is flowing, the current CiscoRTPOutputProperties and CiscoRTPInputProperties also remain available from the CiscoMediaTerminal.getRTPOutputProperties() and CiscoMediaTerminal.getRTPInputProperties() methods as well. These methods throw an exception if the CiscoMediaTerminal is not currently supposed to transmit or receive media.

When Cisco Unified Communications Manager wants the application to stop sending or receiving media as the result of a call disconnecting or being put on hold, for example, it sends the CiscoRTPOutputStoppedEv and CiscoRTPInputStoppedEv events. These events mean that the current RTP media stream that exists between the two endpoints should be torn down.

Inbound Call Media Flow Event Diagram

Table 3-4 illustrates the dialogue between Cisco Unified Communications Manager and a JTAPI application when a call is presented to an application-controlled endpoint. The events in the left column represent JTAPI events that are sent to the CallObserver of the application, and the requests in the right column represent methods that the application invokes.

Table 3-4 Inbound Media Flow Event 

JTAPI Event
Direction
Application Request

CallActiveEv

ConnCreatedEv

ConnProceedingEv

CallCtlConnOfferingEv

Æ

 
 

¨

CallControlConnection.accept ()

CallCtlConnAlertingEv

TermConnCreatedEv

TermConnRingingEv

Æ

 
 

¨

TerminalConnection.answer ()

ConnConnectedEv

CallCtlConnEstablishedEv

TermConnTalkingEv

CiscoRTPOutputStartedEv

CiscoRTPInputStartedEv

Æ

 
 

¨

CallControlConnection.disconnect ()

CiscoRTPOutputStoppedEv

CiscoRTPInputStoppedEv

TermConnDroppedEv

CallCtlConnDisconnectedEv

Æ

 


Note Table 3-4 shows JTAPI events for the local connection: that is, for the application endpoint. The actual JTAPI meta event stream contains events that describe the state of the calling party.


Cisco Unified Communications Solutions RTP Implementation

The Cisco Unified Communications Solutions architecture puts a premium on performance, and thus Cisco Unified Communications Solutions phones and gateways do not implement some of the features of RTP and its often-associated real-time control protocol (RTCP). To ensure its compatibility, applications must consider the following points:

Because RTCP is not supported. Cisco Unified Communications Solutions endpoints will not send RTCP messages, and they will ignore any such messages that are sent to them.

Cisco Unified Communications Solutions endpoints do not currently make use of the synchronization source (SSRC) field in the RTP header. Applications must not multiplex RTP streams by using the SSRC field, or phones and gateways may not correctly decode and present the media.

Redirect

JTAPI 1.2 specifies that one of the preconditions of the CallControlConnection.redirect() method is for the state of the connection to be in either the CallControlConnection.OFFERING or the CallControlConnection.ALERTING state. Cisco Unified JTAPI also allows a connection in the CallControlConnection.ESTABLISHED state to be redirected.

The redirect() method includes the following overloaded form in the CiscoConnection interface. It allows applications to specify the behavior that is desired when a failure occurs while redirecting a call, specifying the calling search space, or resetting the original called field.

Applications choose the desired behavior, by passing one of the following INT parameters in the overloaded redirect method from the CiscoConnection interface:

Redirect drop on failure—When a call is directed to a busy or an invalid destination, Cisco Unified Communications Manager can either drop the call if the redirect fails or leave the call at the redirect controller. The JTAPI application can then take corrective action, such as redirecting the call to another destination. The option for the redirect mode parameter follow:

CiscoConnection.REDIRECT_DROP_ON_FAILURE

CiscoConnection.REDIRECT_NORMAL

Calling Address search space—Redirect uses the calling search space parameter to indicate which callingSearchSpace is used. Applications can either use the calling party search space or the redirect controller search space. The parameter options for this scenario follow:

CiscoConnection.CALLINGADDRESS_SEARCH_SPACE

CiscoConnection.ADDRESS_SEARCH_SPACE

Resetting original called—The called address option parameter gets used to reset the original called fields. The options for this scenario follow:

CiscoConnection.CALLED_ADDRESS_UNCHANGED

CiscoConnection.CALLED_ADDRESS_SET_TO_REDIRECT_DESTINATION. This option affects the fields when the call arrives at the redirect destination.

For more information, refer to the com.cisco.jtapi.extensions.CiscoConnection documentation.

For the scenario where A Calls B, B redirects to C, and C (redirect destination) is not a provider observed address, JTAPI would provide CallCtlConnAlertingEv for C with cause code Ev.CAUSE_NORMAL. Prior to release 5.0, the cause code was Ev.CAUSE_REDIRECT for the same scenario.

This change was made to keep the behavior consistent for scenarios where C observed or did not observe the provider.


Note When C is observed, for the same scenario, CallCtlConnAlertingEv at C is provided with CAUSE_NORMAL from releases prior to 5.0, and that behavior continues without change.


Routing

Routing in JTAPI requires the configuration of a CTI Route Point on the Cisco Unified Communications Manager. Multiple calls can be queued to this Route Point, but only a single line can be configured on a CTI Route Point device.

JTAPI implementation of adjunct Routing, as described in the call center package, includes the following actions:

Registering route callbacks on Route Addresses

Creating appropriate handlers in response to the various routing events (routeSelect, routeEnd)


Note CTI Route Points represent devices that can process any number of incoming calls simultaneously on the same line. You can route calls by using the methods in the javax.telephony.callcenter package, or you can accept, redirect, or disconnect calls by using the methods in the javax.telephony.callcontrol package. You can configure each CTI Route Point with only one line in the Cisco Unified Communications Manager. A single CTI Route Point supports a maximum of 34 lines. To support more than 34 lines, provision additional route points. For details on how to configure and administer the CTI Route Point, refer to the Cisco Unified Communications Manager Administration Guide.


Figure 1-4 shows the CTI Route Point configuration.

Figure 3-2 CTI Route Points

Cisco Route Session Implementation

When a call comes in to the RouteAddress, the implementation starts a Route Session thread and sends the application a RouteEvent. This thread in turn starts a timer thread to time the application response to a RouteEvent with either a routeSelect() or an endRoute(). If the application responds with a routeSelect (String[] selectedRoutes), JTAPI verifies that all preconditions are satisfied and then attempts to route the call to the first destination that is specified in the array. If the destination is a valid and available number, the call gets routed, and the application gets a RouteUsedEvent followed by a RouteEndEvent. Otherwise, if an error occurs in routing (which may be caused by an invalid/busy/unavailable destination), the application gets a ReRouteEvent. JTAPI starts the Timer Thread again before it sends the re-Route Event. Because Cisco Unified Communications Manager does not support re-Routing, if the routing was unsuccessful, the caller will either receive a busy tone, or the call will get dropped. The application can clean up all failure instances and/or send JTAPI an endRoute to clean up the RouteSession. If the application does not respond with an endRoute(), the JTAPI timer once again expires, and JTAPI cleans up the Route Session by sending the application a RouteEndEvent().

If the routing timer expires before the application returns with a selectRoute() or an endRoute() method, the Cisco Unified Communications Manager applies same treatment as when a call is made to an unregistered phone (that is play fast busy). If ForwardNoAnswer is configured on the Route Point, the call immediately forwards to that number when the timer expires.

If the application cannot respond with a valid address to which to route the call, the application may choose to call endRoute with an error. The JTAPI specification defines three errors in the RouteSession interface: ERROR_RESOURCE_BUSY, ERROR_RESOURCE_OUT_OF_SERVICE, and ERROR_UNKNOWN. If an endRoute is invoked on the RouteSession, the implementation currently accepts() the call at the RouteAddress, so the caller may begin to receive ringback. If forwarding is configured for the Route Point, the call gets forwarded when the Forwarding Timer expires.

Select Route Timer

Configure this timer via the JTAPI.ini configuration file that has a key called RouteSelectTimeout=5000. Use milliseconds as the unit. The default value for this timer specifies 5 seconds; however, depending on the needs of the application, you can extend or decrease this timer to improve Route Session cleanup efficiency. Ensure that this timer is not unreasonably large. Each Route Session as a thread represents a call to the Route Point, and these Route Sessions should be cleaned up. Should an application expect significant delays between receiving the Route Event and responding with a routeSelect/endRoute event, the application would want to appropriately extend this timer.

Forwarding Timer

You can configure the timer for Forward on No Answer that is currently systemwide (that is, it applies to all devices on Cisco Unified Communications Manager) via the Cisco Unified Communications Manager Service Parameters configuration. The default value for this timer specifies 12 seconds. In future releases, a separate timer for CTI Route Points might be included, so that forwarding for the route point takes effect immediately after JTAPI accepts the call (when the application calls an endRoute or if the routing timer expires).

Route Session Extension

CiscoRouteSession acts as a Cisco Extension to the JTAPI specification. Most importantly, this extension exposes the underlying Call object to the Applications. CiscoRouteSession.getCall() returns CiscoCall, and this call exposes other Call Model Objects such as the associated Addresses, Connections, and so on. The extension also defines additional errors for the application.

Caller Options Summary

In the absence of a callback, or if RouteSession.routeSelect() or endRoute() has not responded to a routeEvent, the caller receives nothing until

The application can disconnect() or reject() the connection on the Route Point and thereby the caller receives a busy tone.

The application can accept the call, and the Forward No Answer, if configured, kicks in.

The application can drop the call. The caller holds the receiver but does not know what happened.

With a callback, if the application chooses to call an endRoute(), after endRoute() returns, the caller receives a ringback until

The client calls a disconnect() that would drop the call.

The client redirects() the call.

The forward on no answer timer that is configured via the scm.ini will kick in and forward the call unless the preceding two options have already kicked in.

If no forwarding is configured for the Route Point, the caller continues to receives a ringback unless the first two options kick in.

Fault Tolerance When Using Route Points

One way for an application that uses route points to deal with fault tolerance requires connecting two JTAPI applications to two different Cisco Unified Communications Managers, each registering a different RouteAddress. For example, Application1 manages RouteAddress1 by using Communications Manager1. Application2 manages RouteAddress2 by using Communications Manager2. In Cisco Unified Communications Manager Administration, ensure the ForwardNoAnswer configuration for these CTI Route Points is administered so they point to each other. In this example, RouteAddress1 would have FNA=RouteAddess2, and RouteAddress2 would have FNA=RouteAddress1. If Communications Manager1 goes down, calls forward to RouteAddress2, so Application2 takes over. Furthermore, both applications could be configured to reconnect to the proper Cisco Unified Communications Manager server when they receive a ProviderShutdown event.

Redundancy

Configuration requires that devices are configured into device pools and are assigned static Cisco Unified Communications Manager groups. Devices register with a particular Cisco Unified Communications Manager server that handles call control signaling. When a server fails, the devices failover to the backup server in the group. When the primary server comes back online, it waits until no active calls exist on the device, then re-homes to the primary Cisco Unified Communications Manager server. Cisco Unified JTAPI informs the applications of this transition by sending a temporary out-of-service message while registering to the backup server.

Cluster Abstraction

The CTIManager provides a virtual representation of all the Cisco Unified Communications Managers in a cluster. Cisco Unified JTAPI applications communicate with the CTIManager instead of with a specific Cisco Unified Communications Managers. The CTIManager also maintains connection between Cisco Unified Communications Managers in a cluster. This allows a provider to represent any devices in the cluster under the CTIManager. Figure 3-3 illustrates "Single-box Configuration with JTAPI, Cisco Unified Communications Manager, and CTIManager in One Box." Figure 1-6 illustrates "Redundant Cisco Unified Communications Manager and CTIManagers with JTAPI Deployed as a Separate Client."

For more details about the cluster administration and device pool settings, refer to the Cisco Unified Communications Manager help pages.

Figure 3-3 Single-box Configuration with JTAPI, Cisco Unified Communications Manager, and CTIManager in One Box

Figure 3-4 Redundant Cisco Unified Communications Manager and CTIManagers with JTAPI Deployed as a Separate Client


Note In previous releases of Cisco Unified Communications Manager, applications that are running on Cisco Unified JTAPI could only control or monitor devices that are registered under a single Cisco Unified Communications Manager. If a Cisco Unified Communications Manager server went down, the connection between the Cisco Unified Communications Manager server and JTAPI would terminate and the Provider would shut down. Cisco Unified Communications Manager Release 3.1, introduced CTIManager service.


Cisco Unified Communications Manager Server Failure

If a Cisco Unified Communications Manager server fails, the associated devices re-home to the next Cisco Unified Communications Manager server in the group. The prioritized list of Cisco Unified Communications Managers in the device pool information configuration for each device defines this process.

Failure of a Cisco Unified Communications Manager server only results in a partial outage of devices in the cluster. Those devices remain available following a successful Cisco Unified Communications Manager failover and registration with a secondary Cisco Unified Communications Manager.


Note A device such as a Cisco Unified IP Phone 7960 fails over to a secondary Cisco Unified Communications Manager server only when no active calls exist on that device. The failure of a Cisco Unified Communications Manager server during a call results only in termination of observation of that device. The media path continues to exist but without any further call control features.


Cisco Unified JTAPI communicates this partial outage to applications by using CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv events. When the Cisco Unified Communications Manager fails over, the device must successfully register to the secondary Cisco Unified Communications Manager before the device is available to the JTAPI applications. Cisco Unified JTAPI will send the CiscoAddrInServiceEv and CiscoTermInServiceEv events.

The Provider remains in service during this time. Devices on other Cisco Unified Communications Manager servers remain available for call control. The events get sent on callbacks of the respective Address or Terminal observer objects. CiscoAddrOutOfServiceEv and CiscoAddrInServiceEv events get sent to an object that is implementing the AddressObserver and get added to an Address by using the addressChangedEvent() callback object method. The CiscoTermOutOfServiceEv and CiscoTermInServiceEv events get sent to an object that is implementing the TerminalObserver interface and get added to a Terminal that is using the terminalChangedEvent( ) callback method.

If the devices are currently in a call, a CallObservationEnded message is sent on the CallObserver callChangedEvent() callback, followed by the CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv messages.


Note Applications must monitor for and respond to the CiscoAddrOutOfServiceEv, CiscoTermOutOfServiceEv, CiscoAddrInServiceEv, and CiscoTermInServiceEv events before the calling call control functions on the address or terminal. Applications that do not support this action may encounter unexpected errors because the applications do not know the exact state of the system.


Redundancy in CTI Managers

Cisco Unified JTAPI also offers transparent applications for redundancy via the CTI Manager. When the primary CTIManager fails, Cisco Unified JTAPI automatically connects to the backup CTI Manager and communicates the reconnection to applications. Instead of connecting to a single Cisco Unified Communications Manager server, applications now connect to a set of CTIManagers. The applications supply the CTIManager server names when they invoke JTAPI.

Cisco Unified JTAPI and the CTIManager maintain bidirectional heartbeat signals to detect a loss of connectivity between them. The CTIManager detects when an application no longer runs and cleans up its allocated resources. Figure 1-7 illustrates the"Logical Representation of JTAPI, CTIManager and Cisco Unified Communications Manager in a Cluster"


Note After Cisco Unified JTAPI successfully connects to the primary CTIManager, it alternately will attempt to reconnect to the primary or backup CTIManager if the JTAPI connection to the CTIManager fails.


Figure 3-5 Logical Representation of JTAPI, CTIManager and Cisco Unified Communications Manager in a Cluster

Invoking CTIManager Redundancy

When getProvider() method on the CiscoJtapiPeer is called during the application startup, Cisco Unified JTAPI attempts a connection to the first CTIManager in the list and tries a connection to the next CTIManager if connection attempt fails with the first. If all the CTIManagers in the list are not available or if connection is refused by all CTIManagers, an exception gets sent to the application and no further reconnection attempts occur. After the first successful connection, Cisco Unified JTAPI alternatively attempts to connect to the backup or primary CTIManager when a failure to CTIManager or connection to CTIManager is detected.

The list of redundant CTIManagers designates a comma-separated list that is passed into the CiscoJtapiPeer.getProvider(String providerString) method as a String. The usage for the providerString follows:

providerString = CTIManager;login=XXX;passwd=YYY;appinfo=ZZZ (Non-redundant feature)

providerString = CTIManager1,CTIManager2;login=XXX,passwd=YYY;appinfo=ZZZ (Redundant feature)


Note Because the appinfo parameter is optional, the application provides no specific appinfo parameter. Cisco Unified JTAPI generates one from a JTAPI instance ID and the local host name.


Additionally, the jtapi.ini file may define different CTIManager lists to support the CiscoJtapiPeer.getServices() method. Cisco Unified JTAPI accepts the following definition:

CtiManagers=<CTIManager1>,<CTIManager2>;<CTIManager3>

where

<CTIManager1>,<CTIManager2> specifies a redundant group.

<CTIManager3> specifies a nonredundant group.

CTIManager Failure

When Cisco Unified JTAPI detects a loss of connection to a CTIManager, the application receives notification of this loss in service. The following events get sent to the application on the appropriate Observers:

A CallObservationEndedEv event gets sent to all Call Observers on an address and calls in progress end. The calls get physically connected, but the application observation of the call ends because Cisco Unified JTAPI cannot send call state changes.

A CiscoAddrOutOfServiceEv event gets sent to all addresses on a terminal and a CiscoTermOutOfServiceEv event gets sent to the terminal.

This process repeats for all Terminals in the Provider user-controlled list. (A CiscoAddrOutOfServiceEv event gets sent only to the addresses that have an active AddressObserver, and a CiscoTermOutOfServiceEv event gets sent only to terminals with an active TerminalObserver.)

The provider gets set in the out-of-service state, and the ProvOutOfServiceEv event gets delivered on any ProviderObserver callbacks present on the provider.

Cisco Unified JTAPI attempts a connection to the next CTIManager in the list, and the ProvInServiceEv gets sent to the ProviderObserver. The devices that previously registered under the application control get reinstated in the new CTIManager After the device is reinstated, CiscoAddrInServiceEv and CiscoTermInServiceEv events get sent to the application via the respective Observers. All previously added observers are maintained. If any calls exist on the devices, a snapshot of the call gets sent to the respective CallObservers.

CTI Ports that were previously registered are reregistered with the same media parameters. RouteAddress callbacks are maintained as before, and these calls get recovered on the new CTIManager. No call snapshot, however, gets delivered to the RouteAddresses.

Heartbeats

Cisco Unified JTAPI and the CTIManager maintain heartbeat signals to discover a failure in either the CTIManager or JTAPI. The CTIManager server controls the heartbeat parameters in the bidirectional heartbeat. Applications can request a desired server heartbeat interval when they are initializing Cisco Unified JTAPI, but the CTIManager can override it.

Applications specify the desired heartbeat parameter by using DesiredServerHeartbeatInterval in the jtapi.ini setting.

Cisco Unified JTAPI specifies the desired heartbeat interval for the client during initialization. The CTIManager specifies the client side heartbeat interval to Cisco Unified JTAPI and specifies the interval at which the server (CTIManager) will send heartbeats. A failure to receive heartbeat message for twice the server-specified interval results in a client-initiated teardown of the connection. To minimize heartbeat traffic, any messages from the client to the server or events from the server to the client substitute for a heartbeat.

Calling Party Display Name

The CiscoCall interface provides methods to get name displays of the calling party and the called party in a call. Applications can use getCurrentCallingPartyDisplayName() to get the display name of the calling party.

JTAPI applications can use the following interface to get the display names of the calling party and the called party.

{
..
..
	/**
	 *This interface returns the display name of the called party in the call.
	 *It returns null if display name is unknown.
	*/
	public String getCurrentCalledPartyDisplayName();

	/**
	 *This interface returns the display name of the calling party.
	 *It returns null if display name is unknown.
	*/
	public String getCurrentCallingPartyDisplayName();
}

The address objects store the display name internally, and the name gets updated when currentCallingAddress and currentCalledAddress are updated. NULL returns if the call is not in the active state and if currentCalling and currentCalled addresses of the call are not initialized.


Note The system does not support Call.getCurrentCalledAddress() and call.getCurrentCallingAddress() for conference calls. Also, the system does not support call.getCurrentCalledPartyDisplayName() and call.getCurrentCallingPartyDisplayName() for a conference call.


Set MessageWaiting

SetMessageWaiting provides a method for applications to set the message-waiting lamp or indicator for an address. Invoke the method on an address that is in the same partition as the destination.

The following interface specifies whether the message waiting indicator should be activated or deactivated for the address that the destination specifies. If enable is true, message waiting activates if not already activated. If enable is false, message waiting deactivates if not already deactivated.

{
public void setMessageWaiting (java.lang.String destination, boolean enable)
	throws		javax.telephony.MethodNotSupportedException,
			javax.telephony.InvalidStateException,
			javax.telephony.PrivilegeViolationException
}

Quiet Clear

QuietClear occurs at the other end when two parties are on a call, and one address goes OutOfService because of a network outage, the Cisco Unified Communications Manager goes down, the application controlling CTIPort goes down, or CTIManager goes down. At this stage, the other end of the call can only drop the call or disconnect the connection. It cannot perform any other callControl operations.

For the party that went Out Of Service, applications will perceive ConnDisconnectedEv and/or TermConnDroppedEv, and the other end of the call receives ConnFailedEv with CiscoCause of CiscoCallEv.CAUSE_TEMPORARYFAILURE.

If applications try to invoke the following features during QuietClear mode, PlatformException with error code of CiscoJtapiException.CTIERR_OPERATION_FAILER_QUIETCLEAR gets thrown:

Consult transfer

Consult conference

Blind transfer

Hold

Unhold


Note Applications may only drop the call in this mode.


GetCallInfo

GetCallInfo interface on address provides applications with the ability to query CallInfo on an address. A query returns the CiscoAddressCallInfo object, which contains information about the number of active or held calls, maximum number of active or held calls, and the Call object for current calls on the address. This interface also specifies what calls are at a specific address at a specific time.

Use the following interface to get information about calls that are present at the terminal:

{ public CiscoAddressCallInfo getAddressCallInfo(Terminal iterminal);
}

DeleteCall

DeleteCall interface provides applications with the ability to delete a call that was created by using the createCall interface. This method accepts a call and throws an InvalidStateException if a provider is not in service or if the call is not in the IDLE state. DeleteCall moves the call to the INVALID state.

The following interface gets added to CiscoProvider:

{ public void deleteCall( Call call ) throws InvalidStateException;
}

Applications can use this interface to delete the call that was created by using createCall interface. This method accepts a call and throws an InvalidStateException if the provider is not in service or if the call is not in the IDLE state. DeleteCall moves the call to the INVALID state.

To successfully delete a call, the application creates the call by using createCall, and the call should be in the IDLE state.

GetGlobalCallID

GetGlobalCallID provides an interface on the CiscoCallID to get the nodeID and the Global Call ID (GCID) of the call; this exposes the GCID information that is available in the internal call object.

The following methods get added to the CiscoCallID interface:

{	/**
	* returns the callmanager nodeID of the call
	*/
public int getCallManagerID();

	/**
	* returns the GlobalCallID of the call
	*/
public int getGlobalCallID ();
}

GetCallID in RTP Events

GetCallID provides an interface on RTP events to access any call information, such as calling party or called party, so applications can link RTP events with the calls.

The callLegID that is received in the RTP events from CTIManager gets used to determine the ICCNCall on the client side. This call passes on to the JTAPI layer, and the CiscoCall gets determined, from which CiscoCallID is obtained. This information gets used to construct the RTP events that are delivered to the application.

The following interface gets added to CiscoRTPInputStoppedEv, CiscoRTPInputStartedEv, CiscoRTPOutputStoppedEv, and CiscoRTPOutputStartedEv:

{ public CiscoCallID getCallID();
}

XSI Object Pass Through

Applications can pass XML objects through JTAPI and CTI interfaces to the phone. The XML object can contain display updates, softkey update/enable/disable, and other types of updates on the phone that are available through IP phone services features. This allows applications to access IP phone service capabilities through JTAPI and CTI interfaces without maintaining independent connections to the phones.

CiscoTerminal Method

Applications can send an XSI object in the byte format to the Cisco Unified IP Phone through the CiscoTerminal interface method. The system limits the payload to 2000 bytes of data with this interface.

CiscoTerminal must be in the <CODE>CiscoTerminal.REGISTERED</CODE> state; its Provider must be in the <CODE>Provider.IN_SERVICE</CODE> state. Successful response indicates that the data that was pushed has arrived at the phone. However, the application cannot receive any XML, including the CiscoIPPhoneResponse object from the push, back from the phone. If the application request is not successful, a PlatformException is thrown. Any request with more than 2000 bytes of data is rejected.

public String sendData (String terminalData) throws InvalidStateException, MethodNotSupportedException;

Before the application can make use of this feature, it must add TerminalObserver on the Terminal.

Authentication and Mechanism

Sending an HTTP POST request to the phone web server, which requires the phone IP address, performs an object push. The web server parses the request, authorizes the request through the HTTP returned to the Cisco Unified Communications Manager, executes the request, and returns an XML response that indicates the success or failure of the request to the application.

With XSI, the IP phone services object gets sent directly to the phone by the Skinny Client Control Protocol (SCCP). The phone does not authenticate the request, because the JTAPI client is trusted and does not require the phone IP address. For more information on actual XML contents, refer to the Cisco IP Phone Services Application Development Notes.

Cisco VG248 and ATA 186 Analog Phone Gateways

Cisco Unified JTAPI supports control of analog phones that are connected to the Cisco VG248 and ATA 186 Analog Phone Gateways. By adding the Cisco VG248 and ATA 186 Analog Phone Gateways to the user-controlled list, applications can control the devices.

Applications receive events for the devices in a way similar to other IP phones. Applications can also initiate calls and invoke other features except answer Request through APIs. Make call works only when the device goes physically off hook.

Applications cannot answer calls from APIs for the devices. If an application attempts to answer () on TerminalConnection for the VG248 and ATA 186 Terminal, the system throws PlatformException with error CiscoJtapiException.COMMAND_NOT_IMPLEMENTED_ON_DEVICE. To answer calls, you must manually pick up the handset, and then you can invoke other call control features such as transfer, conference, blind transfer, and park from the API.

Multiple Calls Per DN

Multiple calls per DN represents the ability to support multiple calls on a line (DN) and the features operation on these calls. Prior to Cisco Unified Communications Manager Release 4.0(1), the system supported only a maximum of two calls. Cisco JTAPI now supports multiple calls per line, which lets have multiple calls on the same line and feature operation on that line.

No no interface or message flow changes occurred for Multiple Calls Per DN.

Shared Line Support

Shared line represents the same DN appearances on multiple terminals. CiscoJtapi provides support for Shared Line, which provides applications with the ability to control shared DN terminals, hold a call on one shared DN Terminal and unhold the same call from another shared DN Terminal, make calls between two shared lines, initiate a call from one shared line terminal while another active call exists on another shared line terminal with the same DN.

Share line provides the following interfaces:

CiscoAddress.getInServiceAddrTerminals()—Returns an array of terminals for which the address is in service.

Terminal {} getInServiceAddrTerminals();

CiscoAddrOutOfService.getTerminal()—Returns the terminal that is going OutOfService.

Terminal getTerminal();

CiscoAddrInService.getTerminal()—Returns the terminal that is going InService.

Terminal  getTerminal();

CiscoConnection.setRequestController(TerminalConnection tc)—Allows an application to select a terminalConnection that is associated with a connection on which you can perform park, redirect, or disconnect operations. You need to do this in a situation where more than one active TerminalConnection exists in a SharedLine scenario.

CiscoConnection.getRequestController()—Returns TerminalConnection set by application as request controller.

CiscoAddrAddedToTerminalEv—Gets sent when the following conditions occur:

A Terminal/Device gets added into the user controlList that contains a SharedDN, which sends the event to the application. In other words, if user has an address in control list, and a new device gets added with same address in control list, this event gets sent.

An EM (extension mobility) user logs into the terminal with a profile that contains a SharedDN. In this scenario, this event notifies that a new terminal is added to an already existing Address.

A new SharedDN is added to a device in a user control list

Interface getTerminal() returns the terminal that gets added to the address.

Interface getAddress() returns the address on which a new terminal is added.

CiscoAddrRemoveFromTerminalEv—Gets sent when the following conditions occur:

A user removes a Terminal/Device from the user controlList that contains a SharedDN. In other words, if a user has a shared address in a control list, and one of the devices with same address gets removed, this event gets sent.

An EM(extension mobility) user logs out from the terminal that had a profile that contains a SharedDN. This event notifies applications that one of the terminals is removed from an existing Address.

A new SharedDN (SharedLine) is removed from a device in a control list.

Interface getTerminal() returns the terminal that gets removed from the address.

Interface getAddress() returns the address from where the terminal gets removed.

The following are the changed or new behaviors for a SharedLine:

Behavior changes for CiscoAddress event include:

JTAPI applications will receive multiple CiscoAddrInServiceEv for shared line addresses. Applications can use CiscoAddrInServiceEv.getTerminal() to get the terminal on which address goes InService.

JTAPI applications receive multiple CiscoAddrOutOfServiceEv for shared line addresses. Applications can use CiscoAddrInServiceEv.getTerminal() to get terminal on which address goes OutOfService.

The address state goes InService when a first shared line goes InService; for example, when the first CiscoAddressInServiceEv gets received.

The address state goes OutOfService when the last Shared Line goes OutOfService; for example, when the last CiscoAddressOutOfServiceEv gets received.

For an incoming call, all the line appearances of a shared line ring. To applications, this gets presented as one active call (callActiveEv), one Connection(ConnCreatedEv), and multiple terminalConnection(TermConnCreatedEv one each for each shared line).

Calls get presented to all terminals. When a call is in a ringing state, the state of the terminal connection equals Ringing. When a the Shared Line answers, the terminalConnection state goes to an active state, while other terminalConnections on the shared line go to a passive state, and callControlTerminalConnection for all the shared lines at this point go into a bridged state. When a call is put on hold, all the terminal connections go into an active state, and callControllTerminalConnection goes to a held state. At this point, any terminal can retrieve the call. The retrieving terminal terminalConnection remains in an active state, and callControlTerminalConnection goes to a talking state while all other shared terminals terminalConnections go into a passive state. Simultaneously, CallControlTerminalConnection changes from a held state to a bridged state.

A shared line can make a call to another shared line of the same DN. In this scenario, the call includes only one connection and multiple terminal connections.

When a shared line makes a call to another shared line of the same DN, the post condition for this equals only one connection.

For a shared line connection with two active terminalConnections (such as barge), Connection.Disconnect() does not result in disconnected connection.

If an application is monitoring only a SharedDN Connection with only a passive or bridged TerminalConnection, invoking any API on the connection results in a PreConditionException.

Similar to the previous scenario, if all the connections of a Call monitored by an application have only a Passive or Bridged TerminalConnection, all APIs on the call throw a PreConditionException (such as Call.Drop()).

If more than one active TerminalConnection exists on a shared line, Call.drop() does not return in CallInValid in the following scenarios:

A normal two-party call between A and B, where A represents a SharedLine with A' and A' barged into the call

The application does not monitor A' and B. If the application issues a Call.drop(), the A' TerminalConnection goes into a passive state, but the call does not go InValid.

Similar to above, if A, A' , A" and B are in a Conference Call

The application monitors only A and A', and Call.drop() does not result in the call going InValid. Only the A and A' terminal connections go passive.

A, A', and B, B' represent a SharedLine address

A Calls B, B answers, and A' and B' barge into the call. The application monitors only A and B. In this scenario, Call.drop() results in a TerminalConnection of A and B going passive, but the call does not go InValid.

If a TerminalConnection is in a passive or bridged state or Passive/InUse state, all APIs on the TerminalConnection() throw a PreConditionException. A TerminalConnection only allows an API Terminal ConnectionJoin() (called Barge) in the passive or bridged state. TerminalConnection does not currently support TerminalConnection Join().

If more than one active or talking TerminalConnections exists in a connection, applications may have to end one before issuing an API on the connection like Redirect(), Park(), Disconnect(). A TerminalConnection can be selected by using API Connection.setRequestController (TerminalConnection tc).

If a call gets held on SharedLine terminals and an application issues a Connection.Disconnect (), the applications may set a particular TerminalConnection through API Connection.setRequestController(TerminalConnection tc). If requestcontroller is not set, all HeldTerminalConnections get dropped, and connection goes to a disconnected state. If only one HeldConnection gets dropped, the call remains present on other SharedLines terminals. The call appearance disappears from the dropping terminal, which disallows the terminal from barging into the call or participating in feature operations on the call.

For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for shared lines, see Appendix A, "Message Sequence Charts."

Transfer and DirectTransfer

The transfer feature provides the ability to transfer a call.

The direct transfer feature is the ability to transfer any of the two calls present on the line so that controller of the call drops out and other two parties remain active on the call. This functionality gets supported with one enhancement, which is this feature can be done in any state of the call and also redesign to work with new CTI events. The following enhancements apply to the transfer feature:

The application can transfer two held calls.

The application can have OneHeld and OneConnected call in any order.

The application can transfer any two calls present on the line.

The following are the changed or new interfaces for Transfer and DirectTransfer:

CiscoTransferStarted. getTransferControllers()—This new interface, which is provided for SharedLine scenarios, supports multiple terminalConnections if a SharedLine is a TransferController. When a transferController is not a SharedLine, only a TerminalConnection occurs in the list. This method returns null if the transfer controller is not being observed.

CiscoTransferStarted. getTransferController()—This current interface, which behaves as it does for a normal transfer, may exhibit a different behavior for SharedLines. When a transferController is a SharedLine, multiple TerminalConnections exist. This method returns an ACTIVE TerminalConnection, however, if the application is not observing the ACTIVE TerminalConnection, this method returns one of the PASSIVE TerminalConnections.

CiscoTransferEnded isSuccess()—This new interface, which is provided for the CiscoTransferEnded event, returns true if the transfer operation succeeds and false if the transfer fails. Transfer failure may result from the following:

The party dropped the call before CallProcessing could complete the transfer.

CallProcessing cannot Complete the transfer.

The following are changed or new behaviors for JTAPI Transfer.

No Hold or UnHold messages occur with an arbitrary transfer.

If a pre-condition for a transfer request has been modified, an application can issue transfer in any state of the call.

If an application does not have an active TerminalConnection that is passed as an argument, Call.consult() throws a PreConditionException/InvalidArgumentException.

If controller does not have any active TerminalConnection, Call.Transfer() throws a PreconditionException/InvalidArgumentException.

To view the message flow for Transfer and DirectTransfer, see Appendix A, "Message Sequence Charts."

Conference and Join

The Conference Feature provides the ability to conference more than two people into a single Call. Events at CTI layer change and Cisco Unified JTAPI gets enhanced to support the new CTI events.

Join Feature is ability to join multiple calls into one single conference call. This functionality was limited to joining only two calls and called Arbitrary Conference. Now it supports multiple calls. Applications need to pass an array of calls to be conferenced together.

The following are new or changed interfaces for conference and Joining of multiple calls into one conference call:

The following interface allows Join to conference multiple calls into one conference call:

Call.Conference(Call[] otherCalls)


Note A precondition requires that all the otherCalls must have controller as one leg of the call.


The following are new or modified interfaces in CiscoConferenceStartEv:

TerminalConnection getHeldConferenceController()—This interface is useful only for the arbitrary conferencing of two calls and returns only one of the held calls.

TerminalConnection[] getHeldConferenceControllers()—This interface gets all of the held calls when joining multiple calls.

TerminalConnection getTalkingConferenceController()—This interface returns the talking conference controller; however, if no talking conference controller exists when all the calls being joined into conference are held, this interface returns null.

Call getConferencedCall()—This interface returns only one of the many calls going to join into a conference and may not have any meaning for a join conference when more than two calls exist.

New interface in CiscoConferenceEnded event boolean isSuccess():

This interface Returns True or False depending on whether Conference is successful or failed. Application can use interface to find whether Conference is successful. Following are defined as Conference Failure:

If the application issues the request Call.conference(otherCalls[]), this conference would be considered failed if one or more than one calls could join into conference. Applications can use the interface getFailedCalls() to find the failed call.

If no Conference Bridge is available and the conference could not be completed at all. The application can use getFailedCalls() to get a list of calls that could not join the conference.

A party that was being conferenced dropped out before conference could be completed.

An interface on the CiscoConferenceEnded event (Call[] getFailedCalls()) gets all the calls that failed to join the conference when the conference fails.

The following are the new or changed behaviors for Conference:

There will not be a hold or unHold message such as applications see when an arbitrary conference occurs.

An arbitrary conference does not require, as a precondition, that any of the calls be in a talking state. However, all the otherCalls must have a controller as one leg of the call.

Applications can conference two or more held calls into a conference call. In finalCall, the controller automatically gets retrieved to a talking state.

Always include an active call in the request Call.Conference(otherCalls). If an active call is not included in the conference request, the request fails.

If there is no active call at the controller, the Call.Conference(otherCalls) request remains successful. However if one active call exists, it the request must include it, as previously stated.

If the application does not have an active TerminalConnection passed as an argument, Call.consult() throws a PreConditionException/InvalidArgumentException.

If the controller does not have an active TerminalConnection, Call.Conference()/Call.Conference(Call[]) throws a PreconditionException/InvalidArgumentException.

For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for conference and join, see Appendix A, "Message Sequence Charts."

Barge and Privacy Event Notification

The Barge Feature provides the ability for Shared Addresses to Barge into an established Call of Address on another terminal. This feature gets activated when an address TerminalConnection is in the Passive State and CallCtlTerminalConnection is in the Bridged State. This version of Cisco Unified JTAPI only supports feature activation manually on application-controlled terminals (IP phones). For this release, the feature can not be activated through an API.

The Privacy feature provides the ability to enable or disable other shared addresses to barge into call. When privacy is enabled, other shared addresses cannot barge into a call and vice versa. Privacy is a terminals property. IP phones have a "Privacy" softkey and pressing it enables or disables the privacy. Privacy can be dynamically enabled or disabled for the active calls on the terminal. When Privacy is on for the call, the TerminalConnection for the call appearances on the shared address appear in the "InUse" state. If privacy status changes during the CallProgress, CiscoTermConnPrivacyChangedEvent gets delivered to the application.

There are two types of Barge feature functionalities provided in Cisco Unified Communications Manager: one uses built-in Conference Bridge called "Barge", while another uses Shared Conference Bridge resources called "CBarge". From the application point of view, there are no interface changes between Barge and CBarge, however, there are some behavioral changes, which are described in the message flow diagram in Appendix A, "Message Sequence Charts."

Barge, CBarge, and Privacy have these interfaces:

Interface CiscoTerminalConnection.getPrivacyStatus()

boolean getPrivacyStatus()

This interface returns the privacy status of a call on the terminal.

Interface CiscoTermConnPrivacyChangedEv

javax.telephony.TerminalConnection getTerminalConnection()

A new reason code, CiscoCall.CAUSE_BARGE gets added to CiscoCall for Barge events.

JTAPI provides CallCtiCause as CiscoCall.CAUSE_BARGE when a SharedLine TerminalConnection or CallCtiTerminalConnection goes to an active or talking state as a result of barge. This cause code also gets provided in CallCtiEvents for dropping temporary calls that are created during the barge operation.

This cause code is not provided for the CBarge scenario.

For details on these interfaces , see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for barge, CBarge, and privacy, see Appendix A, "Message Sequence Charts."

CallSelect and UnSelect Event Notification

You can select or unselect call on a phone for doing DirectTransfer or join or any other feature operation. When a SharedLine user selects a call, the RemoteInUse shares line TerminalConection will go passive, and CallCtlTermiCallConnection goes in InUse state. When call is unselected, CallCtlTerminalConnection goes into a bridged state. An application cannot invoke any API on Passive/InUse TerminalConnection. CallProcessing also performs a Select/UnSelect operation during features (such as transfer/conference) operation. Applications will also see these events if the RemoteInUse terminal is monitored by applications.

For example, if A and A' are SharedLine, and A selects the call, CallCtlTerminalConnection of A' goes into a passive or InUse state. If A "UnSelects" the call, the CallCtlTerminalConneciton of A' goes into the passive or bridged state.

To view the message flow for CallSelect or UnSelect, see Appendix A, "Message Sequence Charts."

Dynamic CTI Port Registration

This feature lets applications provide an IP address (ipAddress) and port number (portNumber) for each call or whenever media is established. To use this feature, applications must register the media terminal by supplying media capabilities. When a call is answered at this media terminal, CiscoMediaOpenLogicalChannelEv is sent to applications. This event gets sent whenever media is established. Applications must react to this event and specify the IP address and port number where media gets established.

A CiscoMediaTerminal is a special kind of CiscoTerminal that allows applications to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoMediaTerminal does not represent a physical telephony endpoint, which is observable and controllable in a third-party manner. Instead, a CiscoMediaTerminal is a logical telephony endpoint, which may be associated with any application that terminates media. Such applications include voice messaging systems, interactive voice response (IVR), and softphones.


Note Only CTIPorts appear as CiscoMediaTerminals through Cisco Unified JTAPI.


Terminating media is a two-step process. To terminate media for a particular terminal, an application adds an observer that implements the CiscoTerminalObserver interface by using the Terminal.addObserver method. Finally, the application registers its IP address and port number to which the terminal incoming RTP streams are directed using the CiscoMediaTerminal.register method.

To register the ipAddress and portNumber dynamically on a per-call basis, applications must register by only providing capabilities that they support. Applications must react to CiscoMediaOpenLogicalChannelEv that gets sent whenever media is established. If any features are performed before applications react to CiscoMediaOpenLogicalChannelEv, the features may fail.

If the applications do not respond to this event during the time that is specified in the Media Exchange Timer in the Cisco Unified Communications Manager Administration windows, the call may fail.

For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for Dynamic CTIPort Registration Per Call, see Appendix A, "Message Sequence Charts."


Note The ChangeRTPDefaults interface is not supported on CiscoMediaTerminal.


The following are the new or changed interfaces for Dynamic CTIPort Registration Per Call:

Interface CiscoMediaOpenLogicalChannelEv Extends CiscoTermEv

int

getpacketSize()

Returns the packet size of the far end in milliseconds.

int

getPayLoadType()

Returns the payload format of the far end, one of the following constants:

CiscoRTPHandle

getCiscoRTPHandle ()

Returns the CiscoTerminalConnection object on which applications must invoke the setRTPParams request.


Interface CiscoRTPHandle

int

getHandle()

Returns an integer representation of this object, currently the Cisco Unified Communications Manager CallLeg ID.


CiscoProvider

CiscoCall

getCall (CiscoRTPHandle rtpHandle)

Returns the call object with the rtpHandle that is associated with a specific terminal. If no callobserver gets added to the terminal at the time when the applications receive CiscoRTPHandle in CallOpenLogicalChannelEv, CiscoCall may be null.


Media Termination at Route Point

This feature enables multiple active calls at the route point, and applications can terminate media for all active calls by specifying the IP address and port number for each call or whenever media is established.
To use this feature, applications must register the route point by supplying media capabilities. When a call gets answered at this route point, CiscoMediaOpenLogicalChannelEv gets sent to the applications. This event gets sent whenever media is established. Applications must react to this event and specify the IP address and port number to where they want to terminate media.

A CiscoRouteTerminal is a special kind of CiscoTerminal that allows applications to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoRouteTerminal does not represent a physical telephony endpoint, which is observable and controllable in a third-party manner. Instead, a CiscoRouteTerminal represents a logical telephony endpoint, which may be associated with any application that desires to route calls and also terminate media. Unlike CiscoMediaTerminal, CiscoRouteTerminal can have multiple active calls at the same time. Typically, CiscoRouteTerminals get used to place calls in queue until an agent is available to service the caller.


Note Only RoutePoint Terminals appear as CiscoRouteTerminal through JTAPI.


Terminating media is a three-step process.


Step 1 The application registers its media capabilities with this terminal by using the CiscoRouteTerminal.register method.

Step 2 An application adds an observer that implements CiscoTerminalObserver interface by using the Terminal.addObserver method.

Step 3 The application must add addCallObserver on CiscoRouteTerminal or on CiscoRouteAddress to receive CiscoCall object from the provider by using CiscoRTPHandle.


Applications receive CiscoMediaOpenLogicalChannelEv for each call and must supply the IP address and port number by using the setRTPParams method on CiscoRouteTerminal.

Applications written for the CiscoJtapiClient 1.4(x) release or earlier must be modified to register with CiscoRouteTerminal.NO_MEDIA_TERMINATION if the applications are not interested in media termination.

Multiple applications can register with the same route point as long as they are registered with the same media capabilities and registrationType. All applications, if they have registered with CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION and then add a terminal observer, receive CiscoMediaOpenLogicalChannelEv, but only one application can invoke setRTPParams.


Note Applications that terminate media must use the CallControl package for answering and redirecting calls. Applications that only route calls can use a routing package.



Note Applications should be aware that if any features are performed before reacting to CiscoMediaOpenLogicalChannelEv, the features may fail. If applications do not respond to these events in the time specified in the Media Exchange Timeout parameter in the Cisco Unified Communications Manager Administration windows, the call may fail.


The following are the new or changed interfaces for Media Termination at Route Point:

Interface CiscoRouteTerminal Extends CiscoTerminal

boolean

isRegistered()

If the CiscoMediaTerminal gets registered, this method returns true. Otherwise, it is false.

boolean

isRegisteredByThisApp()

If the application issues a successful registration request, this method returns true and remains true until the application unregisters the device. This remains valid even if the device is out of service because of CTIManager failure.

void

register (CiscoMediaCapability[] capabilities, int registrationType)

The CiscoRouteTerminal must be in the CiscoTerminal.UNREGISTERED state, and the provider must be in the Provider.IN_SERVICE state.

void

setRTPParams (CiscoRTPHandle rtphandle, CiscoRTPParams rtpParams)

Applications set the ipAddress and the RTP port number to dynamically stream media for a call.

void

Unregister()

The CiscoRouteTerminal must be registered, and the provider must be in the Provider.IN_SERVICE state.


Interface CiscoMediaOpenLogicalChannelEv Extends CiscoTermEv

int

getpacketSize()

Returns the packet size of the far end in milliseconds.

int

getPayLoadType()

Returns the payload format of the far end, one of the following constants:

CiscoRTPHandle

getCiscoRTPHandle ()

Returns the CiscoTerminalConnection object on which applications must invoke the setRTPParams request.


Interface CiscoRTPHandle

int

getHandle()

Returns an integer representation of this object, currently the Cisco Unified Communications Manager CallLeg ID.


CiscoProvider

CiscoCall

getCall (CiscoRTPHandle rtpHandle)

Returns the call object with the rtpHandle hat is associated with a specific terminal. If no callobserver gets added to the terminal at the time when the applications receive CiscoRTPHandle in CallOpenLogicalChannelEv, CiscoCall may be null.


For details on these interfaces, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for media termination at route point, see Appendix A, "Message Sequence Charts."

Redirect Set Original Called ID

Cisco Unified JTAPI applications can specify the preferred original called party DN in the redirect request. The Redirect Set Original Called ID feature lets applications redirect a call on a connection to another destination while letting the applications set the OriginalCalledID to any value. This enables applications to transfer the call directly to another user's voice mail. For example, if A calls B and B wants to transfer the call to C VoiceMail, applications can specify in the enhanced redirect request C as the preferred original called party and destination party as C VoiceMail profile. With this request, calls appear in C VoiceMail profile with the Cisco Unified Communications Manager originalCalledParty field as C. Typical voice mail applications look for originalCalledParty information to identify a user voice mailbox.

Any application that redirects a call to a party by modifying the original called party can take advantage of this feature.


Note This feature also changes the lastRedirectedAddress to the preferredOriginalCalledParty that gets specified in the redirect request.


Below is the callControlConnection interface for Redirect Set Original Called ID:

Interface CiscoConnection Extends callControlConnection With Additional Cisco Unified Communications Manager-Specific Capabilities

javax.telephony.Connection

redirect (java.lang.String destinationAddress, int mode, int callingSearchSpace,
java.lang.String preferredOriginalCalledParty)

This method overloads the CallControlConnection.redirect() method.


For details on the interface, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for Redirect Set Original Called ID, see Appendix A, "Message Sequence Charts."

Single Step Transfer

This interface allows applications to transfer a call to an address. Cisco Unified JTAPI continues to support this interface as defined in JTAPI 1.2 specification, but the events that are delivered to applications are changed from the previous versions of Cisco Unified JTAPI.

In previous versions of Cisco Unified JTAPI, the original call goes to a held state and a new call gets created between the transfer controller and destination when applications use this interface. After successful completion of transfer, both calls on transfer controller go to an IDLE state. If a transfer fails, the original call remains in a held state, and applications retrieve the call. CiscoTransferStart and end events get delivered to the applications at the start and completion of the transfer operation.

Applications get the following changes:

A new call is not created.

CiscoTransferStartEv and CiscoTransferEndEv are not delivered to applications.

The state of the original call is retained if the transfer operation fails.

The pre and post conditions of this interface did not change.

To view the message flow for Single Step Transfer, see Appendix A, "Message Sequence Charts."

Autoupdate of API

When the Cisco Unified Communications Manager is upgraded to a higher version, the APIs may or may not be compatible with the new Cisco Unified Communications Manager version. The APIs must be upgraded to a compatible version so the applications work as expected. Because the APIs are installed locally on the client server, the upgrade must take place on multiple machines. In the case of fewer client applications, you can easily do this by connecting to the Cisco Unified Communications Manager Administration and downloading and installing the Cisco Unified Communications Manager compatible plug-in.

For multiple client applications, this feature provides a facility by which an application at startup can identify itself to a web server via an HTTP request and receives a response with the version of the required JTAPI API.

The application compares the version that is available on the server to the local version in the application classpath and determines whether an upgrade is necessary. This allows applications to refresh the jtapi.jar component to match the Cisco Unified Communications Manager and provides a way to centrally deploy the jtapi.jar to which applications can auto update.

The API that is required to perform this functionality is packaged in the form of an updater.jar. The jtapi.jar and updater.jar are packaged with the standard manifest, which can be used to compare versions.


Note This feature does not update JTAPI Preferences, JTAPITestTools, Updater.jar and javadoc components. If applications require these components, install JTAPI from the Cisco Unified Communications Manager plug-in pages. Auto Update supports JTAPI Release 2.0 and later.


Refer to Chapter 4, "Cisco Unified JTAPI Installation" for more information.

The following are new or changed interfaces for autoupdate of APIs:

Class com.cisco.services.updater.ComponentUpdater

Component

queryLocalComponentVersion (java.lang.String componentName, 
java.lang.String path)

Throws an IOException, IllegalArgumentException.

Component

queryServerComponentVersion (java.lang.String componentName, 
java.lang.String urlString)

Throws an IOException, IllegalArgumentException, and sends an HTTP query to the server to determine the remote server installed components version.


Interface com.cisco.services.updater.Component

int

compareTo (Component otherComponent)

Component

fetchFromServer()

Performs an HTTP fetch of the component from the server and writes to the local file system with the file name temp.jar in the local directory.

java.lang.String

getBuildDescription ()

Returns the string 'Release' for a version of the form 'a.b(c.d) Release'.

int

getBuildNumber ()

Returns 'd' for a version of the form a.b(c.d).

java.lang.String

getLocation ()

The string form location of the component.

int

getMajorVersion ()

Returns 'a' version for a version of the form a.b(c.d).

int

getMinorVersion ()

Returns 'b' version for a version of the form a.b(c.d).

java.lang.String

getName ()

Returns the name of the component.

int

getRevisionNumber ()

Returns 'c' for a version of the form a.b(c.d).


The Autoupdater feature in JTAPI also allows applications to download the latest version of JTAPI.JAR directly from the Cisco Unified Communications Manager.

1. Updater creates a newjtapi.jar file in the current folder of the application, which is the new version of the jar file that was downloaded from the Cisco Unified Communications Manager.

2. Updater copies the current jtapi.jar to a file that is named component.temp in the classpath specified.

3. Updater replaces the current jtapi.jar file with the new jtapi.jar file.

At the end of this operation, the current jar file becomes component.temp and the new jar file becomes jtapi.jar. This operation is supported for both Linux and Windows.

Example Usage of Autoupdater

Command Line : java com.cisco.services.updater.ComponentUpdater <server> <component name> 
<login> <passwd>
Component localComponent, downloadedComponent;
ComponentUpdater updater = new ComponentUpdater();
String localPath = updater.getLocalComponentPath(args[1]);
localComponent = updater.queryLocalComponentVersion("jtapi.jar",localPath);
localComponent.copyTo("component.temp");
String provString = args[0] + ";login=" + args[2] + ";passwd=" + args[3];

CiscoJtapiPeer peer = (CiscoJtapiPeer) (JtapiPeerFactory.getJtapiPeer(null));
CiscoJtapiProperties tempProp = ( (CiscoJtapiPeerImpl) (peer)). getJtapiProperties();
tempProp.setLightWeightProvider(true);

Provider provider = peer.getProvider(provString);
String url = ( (CiscoProvider) (provider)).getJTAPIURL(); provider.shutdown();
Component serverComponent = updater.queryServerComponentVersion("jtapi.jar", url);

downloadedComponent = serverComponent.fetchFromServer();
int retVal = downloadedComponent.replaces(localComponent);

The "replaces" API will replace the existing JTAPI version with the new version.


Note The updater will only update the JTAPI.JAR file and not the other sample applications and Cisco JTAPI documentation that are bundled with the JTAPI plug-in. To get these other components, applications must download the plug-in from the Cisco Unified Communications Manager and install it.


Changes in DeviceType Name Handling

Currently, TSP hardcodes the DeviceTypeName depending on the DeviceType. When a new device type is added, we have to manually add the new device type name to the list of supported devices. Because CTI does not fetch and store the device type name in its cache, TSP cannot get this info from CTI. TSP needs to update the device type name when a new device type is added without any manual intervention.

In JTAPI, the changes have been made to ensure that QBE interface is changed to handle the receive devicetypename that is sent from CTI and is stored in the deviceInfo structure. It is not used anywhere in JTAPI and will not be exposed to applications. Only the QBE interface changed as follows:

public DeviceRegisteredEvent ( String deviceName, int deviceType, boolean 
allowsRegistration, int deviceID, boolean loginAllowed, UnicodeString userID, boolean 
controlled, int reasonInt, int registrationType, int unicodeEnabled,int locale,

// added for deviceTypeName change 
String devTypeName) {

public DeviceUnregisteredEvent ( String deviceName, int deviceType, boolean 
allowsRegistration, int deviceID, UnicodeString userID, boolean controllableBool, int 
reasonInt , int locale,
//added for devtypename support
String devTypeName) {

CiscoTerminal Filter and ButtonPressedEvents

Prior to the JTAPI 2.0 release, Cisco Unified JTAPI applications did not have direct control over Terminal events. Applications can now receive button pressed events by setting the appropriate filter in the terminal observer. Applications no longer need to add call observer to get RTP events.

When setButtonPressedEv gets enabled using CiscoTermEvFilter, applications receive CiscoTermButtonPressedEv when a digit gets pressed on the phone.

The following are the new or changed interfaces for CiscoTerminal Filter and ButtonPressedEvents:

CiscoTerminal

void

setFilter (CiscoTermEvFilter terminalEvFilter)

Allows an application to have more control over the events that get delivered to the TerminalObserver.


CiscoTermEvFilter

boolean

getButtonPressedEnabled()

Gets the enable or disable status of the button-pressed events for the terminal. The default value is disabled.

boolean

getDeviceDataEnabled()

Gets the enable or disable status of the device data events for the terminal. The default value is disabled.

boolean

getRTPEventsEnabled()

Gets the enable or disable status of the RTP events for the terminal. The default value is disabled.

void

setButtonPressedEnabled (boolean enabled)

Enables or Disables the button pressed events for the terminal.

void

setDeviceDataEnabled (boolean enabled)

Enables or Disables the device data status events for the terminal.

void

setRTPEventsEnabled (boolean enabled)

Enables or Disables the RTP events for the terminal.


CiscoTermButtonPressedEv

int

getButtonPressed ()

For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for CiscoTerminal Filter and ButtonPressedEvents, see Appendix A, "Message Sequence Charts."

Modifying Calling Number

This feature enables applications to modify the calling party DN in the select route API from the route point. Applications may pass an array of modifying calling numbers in the selectRoute API and an array length of modifying calling numbers may be equal to the length of the route selected. If there is no modifying calling number element present for a corresponding routeSelected index or if the element is null, then no modifying calling number gets set for that route selected element.

Two new interfaces getModifiedCallingAddress () and getModifiedCalledAddress () are exposed on the call object, which returns modified calling or called number. If there is no modification, these interfaces may return the same values as getCurrentCallingAddress () and getCurrentCalledAddress () interfaces. If an application is only controlling the route point and modifies the calling number using selectRoute API, it may not get modified calling address in the getModifiedCallingAddress interface. If an application is controlling any of calling or called parties, it may get correct values once it receives call control events after the calling number is modified.

A new interface, getRouteSelectedIndex (), exposed on the new class CiscoRouteUsedEvent, an extension of RouteUsedEvent, which gives the index of the selected route. Applications need to cast the RouteUsedEvent to the CiscoRouteUsedEvent in order to get access to this method.

Example


routeSelected[0] = 133555 
routeSelected[1] = 144911 
routeSelected[2] = 143911 
routeSelected[3] = 5005  

modifiedCallingNumber[0] =null
modifiedCallingNumber[1] =9721234567
modifiedCallingNumber[2] =9721234568
modifiedCallingNumber[3] =null

If routeSelected[0] or routeSelected[3] is selected for routing, the modifying calling number may not be applied.

You can only use this feature after an administrator enables the modifying calling number check box in the Cisco Unified Communications Manager Administration for a particular user, which by default is False. If it is not configured, a RerouteEvent with the cause of RouteSession.CAUSE_PARAMETER_NOT_SUPPORTED gets sent to the applications. The application that is modifying the calling number needs to be aware that display name on the called party is affected, and subsequent feature interactions of the calling or called party may result in inconsistent behavior.

The following are new or changed interfaces for Modifying Calling Number:

CiscoRouteSession

void

selectRoute (java.lang.String[] routeSelected, int callingSearchSpace, 
String[] modifiedCallingNumber)

This interface allows applications to modify the calling party number to the routeSelected address. If no modifiedCallingNumber element exists for the corresponding routeSelected element, the calling number does not get modified if a call gets routed to that particular routeSelected element.


CiscoCall

javax.telephony.Address
getModifiedCalledAddress ()

This interface returns a modified called address for the call if an application modifies the calling party using the selectRoute API. However, this information may not be accurate if an application is only controlling the route point that modifies the calling number. If no modified calling number gets performed, this is similar to the getCurrentCalledAddress interface. Typically, this gets varied from getCurrentCalledAddress when a feature gets invoked after modified calling number modifications.

javax.telephony.Address
getModifiedCallingAddress ()

This interface returns a modified calling address for the call if an application modifies the calling party using the selectRoute API. However, this information may not be accurate if an application is only controlling the route point that modifies the calling number. If no modified calling number gets performed, this interface is similar to the getCurrentCallingAddress interface.


CiscoRouteUsedEvent

int

getRouteSelectedIndex ()

This method returns an array index of the route to where the call gets routed.


For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for Modifying Calling Number, see Appendix A, "Message Sequence Charts."

AutoAccept Support for CTI Ports and Route Points

This feature provides applications the ability to enable or disable AutoAccept for the addresses on CTIPorts and Route Points. When AutoAccept status changes for the address, Cisco Unified JTAPI provides the event to inform the application for changes.


Note The maximum number of lines supported for route points equals 34.


The new interface setAutoAcceptStatus(), provided on the CiscoAddress object, allows the capability to set AutoAccept to ON or OFF. Interface getAutoAcceptStatus(), also provided on the CiscoAddress object, allows applications to query the current status of AutoAccept on the address.

When AutoAccept status changes for the address, applications get CiscoAddrAutoAcceptStatusChangedEv on AddressObservers. This event includes the interface getTerminal(), which returns the terminal on which the AutoAccept status gets changed, and the interface getAutoAcceptStatus(), which returns integers that specify whether AutoAccept is ON or OFF. If an address observer is not added, the event does not get provided.

The following interfaces support AutoAccept on CTIPort and RoutePoint:

CiscoAddress

int

getAutoAcceptStatus (javax.telephony.Terminal terminal)

Ciscoaddress.getAutoAccept(Terminal iterminal) returns an AutoAccept status of address on terminal.

void

setAutoAcceptStatus (int autoAcceptStatus, 
javax.telephony.Terminal terminal)

This allows an application to enable AutoAccept for addresses on the CiscoMediaTerminal and or the CiscoRouteTerminal.


CiscoAddrAutoAcceptStatusChangedEv

Public interface: CiscoAddrAutoAcceptStatusChangedEv

Extends com.cisco.jtapi.exension.CiscoAddrEv

The CiscoAddrAutoAcceptStatusChangedEv event gets sent to applications whenever AutoAccept status for the address on the terminal gets changed. If an address has multiple terminals, this event gets sent for the address AutoAccept status on each individual terminals.

This event provides the following interface:

int

getAutoAcceptStatus ()

CiscoAddrAutoAcceptStatusChangedEv.getAutoAcceptStatus returns the following value of AutoAccept status of address on terminal CiscoAddress.AUTOACCEPT_OFF CiscoAddress.AUTOACCEPT_ON.

com.cisco.jtapi. 
extensions.CiscoTerminal
getTerminal ()

Returns the terminal at which this address AutoAccept status gets changed.


For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for AutoAccept on CTIPort and RoutePoint, see Appendix A, "Message Sequence Charts."

CiscoTermRegistrationFailed Event

This event gets provided to the application when CiscoMediaTerminal or CiscoRouteTerminal registration fails asynchronously. Usually when registration fails, the application gets a CiscoRegistrationFailedException. However, it is possible that the registration request was successful, but the registration was rejected by the CTI. This event is provided for the cases where the registration request is successful, but the registration gets rejected. The application should have TerminalObserver to receive this event. Upon receipt of this event, the applications should reregister with the new parameter depending on the error code that is provided for this event.

The following list provides the errors that get returned and the actions to take, by the application, to resolve them.

Error Message    CiscoTermRegistrationFailedEv.MEDIA_CAPABILITY_MISMATCH

Explanation    Registration cannot get done because the terminal is already registered. Do the second registration with the same media capability.

Recommended Action    Try reregistering with the same capability.

Error Message    CiscoTermRegistrationFailedEv.MEDIA_ALREADY_TERMINATED_NONE

Explanation    Registration cannot get done because the terminal is already registered with media termination type 'none'.

Recommended Action    Try reregistering with media termination type 'none'.

Error Message    CiscoTermRegistrationFailedEv.MEDIA_ALREADY_TERMINATED_STATIC

Explanation    Registration cannot get done because the terminal is already registered with static media termination. For static registration, the second registration is not allowed.

Recommended Action    Wait until the terminal UnRegisters.

Error Message    CiscoTermRegistrationFailedEv.MEDIA_ALREADY_TERMINATED_DYNAMIC

Explanation    Registration cannot get done because the terminal is already registered with dynamic media termination.

Recommended Action    Try reregistering with dynamic media termination.

Error Message    CiscoTermRegistrationFailedEv.OWNER_NOT_ALIVE

Explanation    When trying to register the terminal, registration gets in a race condition.

Recommended Action    Try reregistering the terminal.


The following interface is defined for this event:

int

getErrorCode ()

Returns the errorCode for this exception.


There are no changes in the message flow.

SelectRoute Interface Enhancement

The SelectRoute interface gets enhanced to take the parameters "PreferredOriginalCalledNumber" and "PreferredOriginalCalledOption." This enables applications to reset the OriginalCalled value to a specified "PreferredOriginalCalledNumber" when the call gets routed. This interface takes a list of "PreferredOriginalCalledNumber," "PreferredOriginalCalledOption," and corresponds them to the "RouteSelected" list. If the call gets routed to Route at index "I" in the RouteSelected list, the PreferredOriginalCalledNumber and PreferredOriginalCalledOption at index "I" get used. Applications get the following behavior with different values for these parameters.


Note Below x, point to the index where the call is being routed. For example, if the call gets routed to Route n, then value of x will be n. If a PreferredOriginalCalledOption at index x is invalid or out of range, JTAPI defaults it to CiscoRouteSession.DONOT_RESET_ORIGINALCALLED, and if PreferredOriginalCalledOption is null, all the routing gets done with option CiscoRouteSession.DONOT_RESET_ORIGINALCALLED.


When PreferredOriginalCalledOption[x] is set to CiscoRouteSession.RESET_ORIGINALCALLED

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list contains O1, O2, ... On, if R1 is available, then call will be routed to R1, and OriginalCalledNumber will be set to O1; if R1 is busy and R2 is available, then call will be routed to R2, and OriginalCalledNumber will be set to O2 ... and so on.

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list contains O1, O2, ... Om, and m < n, if R1 is available, the call will be routed to R1, and preferredOriginalCalled will be set to O1; if R1 is busy and R2 is available, the call will be routed to R2, and OriginalCalledNumber will be set to O2 and so on until m. From Route m+1, if Rm+1 is available, the call will be routed to Rm+1, and OriginalCalledNumber will be set to Rm+1, and so on. Lastly, if Rn is available, the call gets routed to Rn, and OriginalCalledNumber gets set to Rn".

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list is NULL, then if R1 is available, the call will be routed to R1, and OriginalCalledNumber will be set to R1; if R1 is busy and R2 is available, the call will be routed to R2, and OriginalCalledNumber will be set to R2 ... and so on.

When PreferredOriginalCalledOption[x] is set to CiscoRouteSession.DONOT_RESET_ORIGINALCALLED

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list contains O1, O2,.. On, the call will be routed to one of the available routes, and the OriginalCalledNumber will remain unchanged.

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list contains O1, O2, ... Om, and m < n, the call will be routed to one of the available routes, and the OriginalCalledNumber will remain unchanged.

If RouteSelected list contains Routes R1, R2 .. Rn, and preferredOriginalCalled list is NULL, the call will be routed to one of the available routes and OriginalCalledNumber will remain unchanged.


Note When OriginalCalled gets set to PreferredOriginalCalled, LastRedirectingParty number also gets reset to PreferredOriginalCalled.


The following are new or changed interfaces for SelectRoute Interface Enhancement:

int

selectRoute (java.lang.String[] routeSelected, int 
callingSearchSpace, java.lang.String[] 
preferredOriginalCalledNumber, int[] 
preferredOriginalCalledOption)

Selects one or more possible destinations for routing a call.


PreferredOriginalCalledOption takes one of the following values:

static int

DONOT REESET_ORIGINALCALLED 

Optional parameter value for PreferredOriginalCalledOption that specifies not to reset OriginalCalled.

static int

REESET_ORIGINALCALLED 

Optional parameter value for PreferredOriginalCalledOption that resets OriginalCalled to preferredOriginalCalledNumber.


For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation." To view the message flow for SelectRoute Interface Enhancement, see Appendix A, "Message Sequence Charts."

Presentation Indicator for Calls

The presentation indicator (PI) on a call provides the application with the ability to hide or reveal Calling/Called/CurrentCalling/CurrentCalled/LastRedirecting parties name and number to the end user. JTAPI provides get functions on CiscoCall to get PI value for the party. Use this PI info to present the parties information to the end user. These get functions return a value of true or false. A value of "True" indicates that presentation in "Allowed," and a value of "False" indicates the presentation is "Restricted."

For a conference call, the interfaces on CiscoCall do not return a correct value. Applications must iterate through all the connections in the call to get the PI value that is associated with the address for which the connection gets created. The interface provided on CiscoConnection is getAddressPI().

The following new interfaces provided on CiscoCall retrieve PI values:

CiscoCall

boolean

getCalledAddressPI()

Returns the PI that is associated with getCalledAddressPI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getCallingAddressPI()

Returns the PI that is associated with getCallingAddressPI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getCurrentCalledAddressPI()

Returns the PI that is associated with CurrentCalledAddressPI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getCurrentCalledDisplayNamePI()

Returns the PI that is associated with CurrentCalledDisplayNamePI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getCurrentCallingAddressPI()

Returns the PI that is associated with getCurrentCallingAddressPI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getCurrentCallingDisplayNamePI()

Returns the PI that is associated with getCurrentCallingDisplayNamePI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.

boolean

getLastRedirectingAddressPI()

Returns the PI that is associated with getLastRedirectingAddressPI. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.


The following interface on CiscoConnection retrieves the PI value for the address that is associated with the connection:

CiscoConnection

boolean

getAddressPI()

Returns the PI that is associated with the address on which the connection gets created. If it returns true, the application displays the address name. If it returns false, the application must not display the address name.


There is no change in the message flow.

Progress State Converted to Disconnect State

If an outbound call is initiated through the API to an unallocated directory number across the European PSTN, the application will see the ConnFailedEv event with the cause as CiscoCallEv.CAUSE_UNALLOCATEDNUMBER. For the US PSTN, the application may not see any event.

To make the behavior consistent across the European and American PSTNs and also to address backward compatibility issues, a new service parameter UseProgressAsDisconnectedDuringErrorEnabled was added to the jtapi.ini file starting with JTAPI Version 1.4(3.21), which, when enabled (1=enable; 0=disable; the default is disable), causes applications to see ConnFailedEv in both cases.

Device State Server

The Device State server provides the cumulative state of all the addresses on a terminal. These events are delivered as TerminalEvent. Applications need to add TerminalObserver to get these events.

The states are:

IDLE—If no calls exist on any of the addresses on the terminal, then the DeviceState is considered IDLE, and Cisco Unified JTAPI sends CiscoTermDeviceStateIdleEv to applications.

ACTIVE—If any of the addresses on the terminal have an outgoing call (in CTI State Dialtone, Dialing, Proceeding, Ringback, or Connected) or an incoming call (in CTI State Connected), then the DeviceState is ACTIVE, and Cisco Unified JTAPI sends CiscoTermDeviceStateActiveEv to the application.

ALERTING—If none of the addresses on the terminal has an outgoing call (in CTI State Dialtone, Dialing, Proceeding, Ringback, or Connected) or an incoming call (in CTI State Connected) and at least one of the addresses on the terminal has an unanswered incoming call (in CTI State Offering, Accepted, or Tinging), then the DeviceState is ALERTING, and Cisco Unified JTAPI sends CiscoTermDeviceStateAlertingEv to the application.

HELD—If all the calls on any of the address on the terminal are held (in CTI State OnHold) the DeviceState is HELD and Cisco Unified JTAPI sends CiscoTermDeviceStateHeldEv to the application.

New Events

CiscoTermDeviceDeviceStateIdleEv

CiscoTermDeviceStateActiveEv

CiscoTermDeviceStateAlertingEv

CiscoTermDeviceStateHeldEv

New and Changed Interfaces

public int getDeviceState() returns the device state of the terminal.

The following new interfaces on CiscoTermEvFilter set and get the device state:

void

setDevideStateActiveEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceStateActiveEv filter.
The default value is disable.

void

setDeviceStateAlertingEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceAlertingEv filter.
The default value is disable.

void

setDeviceStateHeldEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceHeldEv filter.
The default value is disable.

void

setDeviceStateIdleEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceIdleEv filter. The default value is disable.

boolean

getDeviceStateActiveEvFilter()

Gets the CiscoTermDeviceStateActiveEv filter status.

boolean

getDeviceStateAlertingEvFilter()

Gets the CiscoTermDeviceStateAlertingEv filter status.

boolean

getDeviceStateActiveEvFilter()

Gets the CiscoTermDeviceStateAlertingEv filter status.

boolean

getDeviceStateActiveEvFilter()

Gets the CiscoTermDeviceStateAlertingEv filter status.


For details on the interface changes, see Chapter 5, "Cisco Unified JTAPI Implementation."

Forced Authorization and Client Matter Codes

Forced Authorization Codes (FACs) force the user to enter a valid authorization code prior to extending calls to specified classes of dialed numbers (DN), such as external, toll, or international calls. Authorization information is written to the Cisco Unified Communications Manager CDR database.

Client Matter Codes (CMCs) let the user enter a code before extending a call. Customers can use Client Matter Codes for assigning accounting or billing codes to calls placed, and Client Matter Code information is written to the Cisco Unified Communications Manager CDR database.

Supported Interfaces

Cisco Unified JTAPI supports FAC and CMC in the following interfaces:

Call.Connect()

Call.Consult()

Call.Transfer(String)

Connection.redirect()

RouteSession.selectRoute()

Call.Connect() and Call.Consult()

When an application initiates a call with one of these interfaces to a DN that requires an FAC, CMC, or both codes, CiscoToneChangedEv is delivered on a CallObserver that also contains which code or codes are required for the DN. The getCiscoCause() interface returns CiscoCallEV.CAUSE_FAC_CMC for this even if it is delivered because of FAC_CMC feature. The getTone() interface returns CiscoTone.ZIPZIP to indicate that a ZIPZIP tone has played.

Upon receiving the CiscoToneChangedEv, applications need to enter the appropriate code or codes by using the connection.addToAddress interface with a # terminating string. Digits either can be entered one at a time within the interdigit timer value (T302 timer) for each digit including the # terminating character, or all the digits, including the # termination character, can be entered within the T302 timer value that is configured in Cisco Unified Communications Manager Administration.

When FAC and CMC Are Both Required

For a DN that requires both codes, the first event is always for the FAC and the second code is for the CMC, but the application has the option to send both codes, separated by a pound sign (#), in the same request. The second event remains optional, based on what the application sends in the first request.

The application can send both codes at the same time, but both codes must end with #. as shown in the following example:

connection.addToAddress("1234#678#")

where 1234 is the FAC and 678 is the CMC.

In this case, the application does not receive a second CiscoToneChanged.

The first CiscoToneChangesEv will have getWhichCodeRequired()=CiscoToneChanged.FAC_CMC_REQUIRED, and getCause()=CiscoCallEv.CAUSE_FAC_CMC.

In response, one of the following cases can occur:

The application sends FAC and CMC in the same connection.addToAddres(code1#code2#) request. In this case, no second CiscoToneChangedEv gets sent to the application.

The application sends only a FAC code in connection.addToAddress(code#1). In this case, the application receives a second CiscoToneChangedEv with getWhichCodeRequired()=CiscoToneChangedEv.CMC_REQUIRED.

The application sends only part of the first code or the complete first code and incomplete second code (if the code is not terminated with #, it remains is incomplete and the system waits for the T302 timer to expire and tries to validate the code). If the code is incomplete, a second CiscoToneChangedEv tone gets generated with getWhichCodeRequired()=CiscoToneChangedEv.CMC_REQUIRED and getCause()=CiscoCallEv.CAUSE_FAC_CMC.

PostCondition Timer

The PostCondition timer resets each time the connection.addToAddress interface is invoked to send code. FAC and CMC must have the terminal # [for example, Connection.assToAddress("1234#"), where 1234 is the FAC]. The system waits for the T302 timer to expire, then extends the call if all codes have been entered. If all codes have not been entered, the system plays reorder tone. In this case, the application could receive PlatformException with postConditionTimeout even if the call is extended. To avoid this, the application needs to increase the postcondition timeout by using JTAPI Preferences.

If the application uses call.connect() or call.consult() to initiate a call, but the FAC or CMC (including #) is not entered from a Cisco IP Phone within the postcondition timeout limit, then the request could get a platformException with postCondition timeout, but the call may actually be extended. To avoid this, the application needs to increase the postcondition timeout by using JTAPI preferences.

Shared Lines

If the initiating party is a shared line, then applications need to use setRequestController to set active terminalConnection before passing additional digits by using the connection.addToAddress interface.

Invalid or Missing Codes

If a code is invalid or no code is entered before the T302 timer expires, the call gets rejected with callCtlCause cause code as CiscoCallEv.CAUSE_FAC-CMC.

Call.transfer(String) and Connection.redirect()

Two additional string parameters (facCode, cmcCode) are added to these interfaces to support FAC and CMC. The default value for these codes are null values.

No CiscoToneChangedEv gets delivered for these requests for DNs that require codes. A call that is conditionally redirected to a DN, a FAC, a CMC, or both, does not get rejected but remains connected if either of the codes is incorrect.

RouteSession.selectRoute()

Two additional arrays of string parameters (facCode, cmcCode) support FAC and CMC. For each routeselect element, applications can specify the code for the DN. Applications need to specify null values for DNs that do not require any codes. The default values for the codes are null values.

If one routeselected element does not contain the correct code, the next element in the arrays gets tried. If all of them fail, then reRouteEvent gets sent to the application.


Note The system does not support forwarding to a DN that requires an FAC or CMC code. The application can set the forward number to these DNs by using the Address API, but calls forwarded to these numbers are rejected.


Super Provider (Disable Device Validation)

When a JTAPI application user is configured, the system administrator normally associates a certain set of terminals (Cisco Unified IP Phones and devices) with this application user, who can control and monitor only this set of terminals. The Super Provider feature gives applications the ability to control and monitor any terminal in a Cisco Unified Communications Manager cluster.

The new createTerminal() new interface in CiscoProvider lets the application create a terminal by specifying a terminalName. JTAPI does not provide the capability to get the terminalName through any interface. The CiscoProvider.createTerminal(terminalName) returns the terminal. If the terminal already exists in the provider domain, JTAPI returns the existing terminal.

A second new interface, CiscoProvider.deleteTerminal(), lets the application delete the CiscoTerminal objects created using the CiscoProvider.createTerminal() interface. If the terminal object does not exist or the application did not create the terminal with the CiscoProvider.createTerminal() interface, JTAPI throws exceptions.

JTAPI also provides a new interface on CiscoProviderCapabilities, canObserveAnyTerminal(), which can be enabled for application users through Cisco Unified Communications Manager Administration user configuration. Applications can use this interface to determine if they have sufficient capability to invoke the createTerminal(terminalName) interface. If the application does not have sufficient capability and this interface is invoked, JTAPI throws a PrivilegeViolationException. If the application provides a terminalName that does not exist in the Cisco Unified Communications Manager cluster, JTAPI throws a InvalidArgumentException.

Q.Signaling (QSIG) Path Replacement

QSIG Path Replacement, a network feature, optimizes the real-time protocol (RTP) path when calls are transferred or forwarded to other PBXs connected through QSIG trunks. When path replacement is in progress a small window of time exists when the feature requests from applications would be ignored and JTAPI would throw an exception to the application.

The Global Call ID or the call is changed when the RTP path is optimized with a direct path between the starting terminating PBXs. JTAPI provides new interfaces to monitor the call.

Network Events

In previous releases of Cisco Unified JTAPI, when a call is made to an address outside the cluster, CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv events are delivered for the far-end address.

In later versions of Cisco Unified Communications Manager (4.0 and above), these events are not delivered. In these versions CallCtlConnection for the far-end address goes to the ESTABLISHED state from OFFERED state. The application will receive CallCtlConnOfferedEv, CallCtlConnEstablishedEv for the far-end address. The CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv events are not delivered to application. To receive network events, the "Allow overlap sending" flag on the route pattern configured for the gateway must be turned on.

A new jtapi.ini parameter called "AllowNetworkEventsAfterOffered" is introduced to allow the application to control the delivery of these events. Applications that need the network events but cannot turn on this flag can use this new jtapi.ini parameter to receive network events for outgoing calls.

To turn on the parameter complete the following steps:


Step 1 Run jtprefs and select the required options. This creates jtapi.ini file in c:\winnt\java\lib, if Cisco Unified JTAPI is installed in the default directory. If the jtapi.ini file already exists, you can update the file directly without running jtprefs.

Step 2 Add AllowNetworkEventsAfterOffered=1 to the end of the file and save it.

Step 3 Repeat the preceding step every time Cisco Unified JTAPI is reinstalled.

When the AllowNetworkEventsAfterOffered flag is enabled, the application will receive CallCtlConnOfferedEv, CallCtlConnNetworkReachedEv or CallCtlConnNetworkAlertingEv and CallCtlConnEstablishedEv for the far-end address.