Caveats for All Releases
This section lists the caveats that are common for all JTAPI releases and contains these topics:
Single Versus Multiple CallObserver Clarification
There are two primary ways to observe addresses with Cisco JTAPI's CallObservers: an application can observe all of the addresses with a single CallObserver object or it can have a separate CallObserver object for each of address. These two approaches cause slightly different events to be seen, mostly with regard to reason codes.
When an application uses a single CallObserver to observe all the addresses, they are connected with one object. When A calls B, both the events at A and at B are sent to the same CallObserver object. If B redirects to C, and C was observed with the same object, all its events are delivered to the same observer. The application observes the CallCtlConnOfferedEv to C with reason REDIRECT, because the observer at C knew all about the previous events on the call.
Conversely, when an application uses an independent CallObserver for each Address, this information is not so easily shared. When A calls B, call events of A go to the observer for A, and B's go to the observer for B. They each know about the other end, for example A will know that B is ringing, but they are no longer the same observer. When B redirects the call to C, the observer at C knows absolutely nothing about the call. The observer at C was not involved in the original call at all, and does not know who is on it, what events had happened previously. This information has to be made up by JTAPI to build an accurate call model at C. All the call events for a basic call between A and B have to be simulated so that the call model, from C's perspective makes sense.
This is done by using a snapshot event. JTAPI looks at the call, in this case the one between A and B, and figures out what events have to have happened for the call to exist the way it does. This makes up up the basic call events required, and give them to the observer on C, so that it can build a proper call model.
Since this event set is made up by JTAPI, the reason codes are not available. For example, if A had originally called D, and D redirected to B, the made up snapshot event set would not be concerned with the redirect at all. JTAPI does not store this information anywhere, and when it generates a snapshot, it creates the simplest event set possible to recreate the call model, and reports all the events with reason NORMAL.
So, when A calls B, and then B redirects to C, the observer on C gets a snapshot event that allows it to recreate the call model for a basic call from A to B. Also in this snapshot event is the CallCtlConnOfferedEv for C. As part of the snapshot, this event comes in with reason NORMAL, even though it is the result of a redirect. CallObservers on A or B will see the CallCtlConnOfferedEv for C with reason REDIRECT, but there is no way for the observer at C to know that.
This creates a noticeable difference in the reason codes available to applications depending on how they implement their CallObservers. There have not been any issues regarding this from the customer side.
This is the way it has been since Cisco JTAPI's inception and this is a clarification of the existing behavior.
SIP and SCCP Dialing Differences with Overlapping Directory Number Patterns
An overlapping Directory Number Pattern is when one Directory Number is a part of a longer Directory Number. For example, a Directory Number 1000 overlaps a Directory Number 10001. Cisco Unified Communications Manager (Cisco Unified CM) and JTAPI both support overlapping Directory Number patterns, but there are some important things to note regarding this.
When you dial 1000 from a normal phone, there is a delay. The Cisco Unified CM does not know if you want to dial 1000 or 10001, so it waits for you to make a choice. This Digit Analyzer waits for 15 seconds if you press nothing else. During this time, nothing happens, no call is extended, and it just sounds like a dead call for the calling party. This can be short circuited by hitting # to let Cisco Unified CM know that you actually intend to call 1000. The 15 second wait is a configurable service parameter, known as T302 Timer, and can be set as low as 3 seconds.
JTAPI using SCCP phones avoid the Digit Analyzer entirely by communicating directly with Cisco Unified CM. JTAPI sends the intended Directory Number when it is making a call, and if it sends 1000, it means only that, and Cisco Unified CM knows it will not be dialing any more digits.
JTAPI using SIP phones is quite different. JTAPI communicates with the phone, which then communicates with the Cisco Unified CM. The phone takes care of the dialing, and JTAPI will pass it the digits 1000 to dial. Due to this, JTAPI cannot avoid the Digit Analyzer, and is subject to the T302 wait outlined above. JTAPI sits idly and waits while the Digit Analyzer figures out that the SIP phone actually wants to dial 1000.
Apart from this, by default the JTAPI CTI Postcondition value is also set to 15 seconds. This means that when JTAPI sends a request to the CTI layer, it waits for 15 seconds before it assumes something has gone wrong, and throws a timeout exception. This means that the delay for Digit Analysis for overlapping DN patterns is very likely to cause JTAPI to time out.
The Digit Analysis delay cannot be completely removed for SIP phones, but this problem can be greatly mitigated through the use of service or jtapi.ini parameters. As noted above, the T302 Timer for Digit Analysis can be set as low as three seconds, which is much lower than the 15 it takes JTAPI to time out. You can also increase the JTAPI CTI Postcondition timeout to 20 seconds in the jtapi.ini file. This issue can also be avoided by not having overlapping DNs.
Translation Pattern Support
If the callingparty transformation mask is configured for a Translation Pattern that is applied to the controlled addresses of JTAPI application, the application may observe some extra connections being created and disconnected when the application observes both calling and called party. Otherwise, a connection is created for the transformed callingparty and CiscoCall.getCurrentCallingParty() returns the transformed calling party address when the application observes only the called party. In general, JTAPI has a problem in creating an appropriate call connection and may not be able to provide correct callinfo such as currentCalling, currentCalled, calling, called, and lastRedirecting parties. For example, Translation Pattern X is configured with calling party transformation mask Y and calledparty transformation mask B; A calls X, and call goes to B. In this scenario:
-
If the application observes only B, JTAPI creates connection for Y and B, and CiscoCall.getCurrentCallingParty() returns Address Y.
-
If the application observes both A and B, connections for A and B are created, connection for Y is temporarily created and dropped, and CiscoCall.getCurrentCallingParty() returns Address Y.
Other inconsistencies could occur in callinfo if more features are used for basic call. It is recommended that you do not configure callingparty transformation mask for Translation Pattern which might get applied to JTAPI Application controlled Addresses.
DT24+ Limitation with PRI NI2 Trunk
When a PRI NI2 trunk used by DT24+ gateway is involved in a call scenario between two clusters, for example, A from cluster-1 calls B in cluster-2 via DT24+ PRI NI2 trunk, the LastRedirectAddress and CalledAddress may not be accurate on B’s side. Besides, if there are any changes for A’s side of the call in cluster-1 due to redirect, transfer, or forward, the changed information is not propagated to B’s side due to protocol limitation of PRI NI2 truck.
Connection for Park Number Not Created
JTAPI does not create a Queued state connection for Park Number if the call is parked across the gateway. There are two possibilities here:
-
If CLI is configured, application sees an Unknown connection
-
If CLI is not configured, the calling does not see any Unknown connection.
For Example, If A calls B across gateway (with CLI configured) and B parks the call then A sees an unknown connection instead of a connection (with STATE = QUEUED) for Park Number.
But, if A calls B across gateway (with no CLI configured) and B parks the call then A does not see any new connection.
Inconsistency Between SIP and SCCP Phone
sendData() API on CiscoTerminal is used to send data to the phone. In case of SIP phones, if invalid byte data is sent by the application, the method throws PlatformException. However, in case of SCCP phones, the byte data sent in the request is not validated, and would return successfully without throwing an exception.
Failure to Route Calls Across Destinations
When a call is redirected to a device outside the cluster over an H323 gateway that is out of service, before call control can determine the Out-of-Service status of H323 gateway, the call is disconnected. This is because the default value of the service parameter CTI NewCallAccept timer is four seconds where as call control takes five seconds to determine that the gateway is out of service, so calls are disconnected due to expiration of CTI NewCallAccept timeout.
Implications of the above behavior is seen in JTAPI selectRoute() API which internally uses CTI redirect API to route the call. If applications specify multiple destinations with selectRoute() and the first destination is across an out-of-service H323 gateway, the call fails before JTAPI can route the call to the second destination. Hence JTAPI, cannot route the call to the second route specified in selectRoute() interface call.
To avoid this, the value of CTI New Call Accept Timer service parameter can be set as greater than H225 TCP Timer service parameter.
Incorrect Return Value for getCallingAddress()
In a transfer scenario, where caller and transferController are not observed, that is, where A calls B and transfers the call to C and the application is observing only C then before the transfer, JTAPI will not have any information about the first call (that is, call from A to B). So, when the transfer feature is invoked, the calling and called address are B and C respectively. On completing the transfer, application updates callInfo and JTAPI exposes the correct parties through getCurrentCallingAddress(), getCurrentCalledAddress(), getModifiedCallingAddress(), and getModifiedCalledAddress(). However, getCallingAddress() API which should return the original calling address still reports B, that is, the original calling party of B to C call.
To avoid this issue, application can observe the controller as well, so that JTAPI expose the correct party (that is A, in this case) with getCallingAddress() API.
Call Fails to Disconnect Held Shared Line
In a scenario where A calls B (B is a shared line present on terminals T1 and T2); privacy is set as ON for T1 and initially CUCM service parameter Enforce Privacy Settings on held calls is set to True. B(T1) answers and goes to Talking state while B(T2) goes to Passive state (TermConn = Passive; CallCtlTermConn = InUse). B(T1) puts the call on hold, since Enforce Privacy Setting on held calls is set to True, B(T2) remains in passive state (TermConn = Passive; CallCtlTermConn = InUse). Now the service parameter Enforce Privacy Settings on held calls is set to False. This does not trigger any change in the state of TerminalConnection, so B(T2) still remains Passive-InUse (TermConn = Passive; CallCtlTermConn = InUse). At this point, if the application sets the requestController as B(T1) and disconnects the call at B, the connection of B is not disconnected and call does not go IDLE. Even on the phones, the call on A remains in Established state while the other party in call is B(T2) which remains in Passive-InUse (TermConn = Passive; CallCtlTermConn = InUse) state. Call is cleared when A disconnects the call.
Limitation with sendData() API on CiscoTerminal
If JTAPI applications make simultaneous back to back requests for sendData() API on the same CiscoTerminal, without any delay between requests, then some of these requests may fail. Applications cannot determine whether a request was successful or not, as Cisco JTAPI API returns successfully as soon as the phone receives data and does not wait for a response from the phone. Also, the IP phone might display a blank screen on sending simultaneous requests to send data.
To avoid these issues, JTAPI applications should ensure some time delay between two successive sendData() requests while pushing XSI data to the IP phones via Cisco JTAPI.
Limitation in Using ; (Semi-Colon) and = (Equal) in User ID and Password
Sun JTAPI 1.2 specification does not support use of the semicolon ';' and equals ' = ' characters when populating the Host Name, UserID, and Password fields in string used as parameter in getProvider() method. If ';' or ' = ' are used in these fields, items such as 'pass = word' or 'pass;word' are treated as 'pass' and your request could fail and you must not use these characters in userid and password fields.
Connection to Unknown Address When Unparking a Conference Call
When a conference call is parked, JTAPI call will have connection to the remaining parties in the call. When this call is unparked using the UnPark API or connect API, connections to unknown address will be temporarily created. This connection to unknown address will be disconnected when un park is completed.
The following will be seen in JTAPI traces:
2002 : (P1-InProv) 103023/1 ConnCreatedEv Unknown:null:4 187 Cause:100 CallCtlCause:0 CiscoCause:31 FeatReason:10 CAUSE_NORMAL
....
2002 : (P1-InProv) 103023/1 ConnDisconnectedEv Unknown:null:4 187 Cause:100 CallCtlCause:0 CiscoCause:31 FeatReason:10 CAUSE_NORMAL
CTI Redirect to Voice Mail Wont Work with QSIG
When applications redirect a call to voice mail through a QSIG trunk, voice mail will not play the voice prompt of the redirecting party. A generic prompt asking the user to enter the voice mail box is played. This is due to the fact that CTI redirect doesn't pass correct original called party and redirecting party to the voice mail system. Applications can work around this by using a SIP trunk.
Phone A calls Phone B (CUCILYNC in Deskphone mode). Toast popup of "envelope" appears for incoming call.
User clicks on the envelope, redirecting the call across an H.323 trunk with QSIG tunneling. Unity/Unity Connection won't recognize original called party, so call will not go to user's voice mailbox. This is because Re-direct/Original Called Party information not carried across the trunk when CTI redirect is used.
CiscoAddress.getForwarding() Returns Correct Value Only for In-Service Addresses
Unsupported CTI Events for SIP Phones
The following CTI events are not generated for SIP phones. Third party applications that expect these call events should use SCCP phones:
-
CallOpenLogicalChannelEvent
-
CallRingEvent
-
DeviceLampModeChangedEvent
-
DeviceModeChangedEvent
-
DeviceDisplayChangedEvent
-
DeviceFeatureButtonPressedEvent
-
DeviceKeyPressedEvent
-
DeviceLampModeChangedEvent
-
DeviceRingModeChangedEvent