Communication Manager API Release Notes Release 2.1, Build , May

Transcription

1 INTRODUCTION Communication Manager API Release Notes Release 2.1, Build , May This document introduces the latest release of the Communication Manager API (Release 2.1), describes new features, important notes, and known issues. Release 2.1 continues to improve the reliability and scalability of the infrastructure from Release 2.0. It provides a number of new enhancements including the exposure of XML API enabling the utilization of alternate languages for client applications, shared phone control for DCP and IP stations (shared control of IP requires Communication Manager 2.1) and the exposure of the Media Stack API (available through a separate media stack jar library) which provides media handling for applications that wish to handle their own media stream. WHAT S NEW Release 2.1 supports the following new features: H.323 stack Unicode fix. Communication Manager 2.2 (included Unicode implementation) will require Build or above. Without Build , the registration fails when a Communications Manager API server is connected to Communications Manager 2.2. Replacement of JBoss infrastructure with JMX. This changes the installation and related start-up of the server. The RPM installs CMAPI under /opt/cmapi. The directory structure has been flattened to the following: /opt/cmapi/bin shell scripts /opt/cmapi/lib jar files /opt/cmapi/conf all configurations files /opt/cmapi/logs all log files /opt/cmapi/deploy services deployed at runtime (ie: hot deploy) (2.1.2) The startup of the server remains the same from the user s point of view and is documented in the Quick Start and Installation & Administration guides. First exposure of XML API allows application developers to work directly at the XML layer and provides alternate language bindings on the client. First exposure of Media Stack API provides media handling (through a separate media stack jar library) for applications controlling their own media stream. A simplified tutorial application built on top of a re-usable station class to provide an abstraction on top of physical device services. A simple IVR (Interactive Voice Response) application that demonstrates playing and recording of announcements, collection of digits, multiple call handling, as well as transfer and conference capabilities. Enhanced application with station class and shared phone control.

2 2 Release 2.1 Build History: Release 2.1 Change(s) Build st 2.1 Alpha build released to DevConnect and customers st 2.1 Beta build released to DevConnect and customers with the following changes: 1. Fixed GetDisplay to match the last DisplayUpdated event. 2. Recommend upgrading to JDK v1.4.2_03. It appears a memory leak was introduced into v1.4.2 and fixed in v1.4.2_02. The leak appears to be related to the specific garbage collection settings in use and was exposed by the small ByteBuffers used for G.729 play st General Available release to DevConnect and customers with the following changes: 1. Change: add and remove listener methods in Java API are now in Monitoring Services 2. New Voice Unit Services request supported: Delete Message 3. New Telecommuter mode in Terminal Service's Register Device request allows a Communication Manager or non-communication Manager physical phone to be associated with a CMAPI softphone 4. New Java sample applications 5. New Media Stack API and Javadoc 6. New XML API, XMLdoc, XML sample applications and XML Programmer's Guide Fix: Allows a client to restore its connection to the CMAPI server if the socket goes down. 2. Fix: XMLdoc now includes documentation for all supported services, responses and events Change: The IP address format has changed. Users of the Java API who were utilizing the client media mode will HAVE TO CHANGE THEIR CODE to use Release 2.1, Build In previous releases, the IP address for client media were specified in the form of an array of bytes. Now, an IP address must be specified in the form of a string (e.g ). 2. Fix: Potential memory leak resolved. While performing a GetDeviceID on a nonexistent station every 3 seconds, the CMAPI server appeared to stop responding in approximately 15 minutes. 3. Fix: XML users can now use client media. 4. Fix: Added an exception to report invalid IP addresses. 5. Change: On the response of an unregistration request, a reason code is implemented in the private data. If the station was registered previously, the response contains the reason indicating that the unregistration is in progress normally. If the station was unregistered previously, the response contains the reason indicating the station was already idle. In this case, there will be no unregisteration event. If the station was in the process of unregisteration previously, the response contains the reason indicating the station was in the process of unregisteration. Please refer to the Java doc on how to retrieve the reason code in the private data Fix: H.323 stack Unicode fix. Required for use with Communication Manager Fix: Resolved callr info button failures due to incorrect constant and directory values. 2. Fix: Changed registerdevice to throw InvalidActiveDeviceStateExceptions when registration or unregistration is in progress and to throw InvalidDeviceStateException if already registered. 3. Fix: Activated GetRingerStatus in CstaUnmarshaller.

3 3 Release 2.1 Build Change(s) 4. Fix: Changed getringerstatus to return the correct ringmode. 5. Fix: Resolved application failures due to DecodeException. 6. Fix: Resolved callappearance offhook issues. 7. Fix: Changed GetHookSwitchStatus to return a response. 8. Fix: Added the following button/lamp IDs to the ButtonIDConstants class: Change: Updated CallInformationServices in the Call Info Javadoc and XMLdoc to accurately reflect where Call Information Services is supported Change: GetCallInformation extension is no longer a required field. API CHANGES FOR NEW FEATURES Chapter 1 What s New in the Avaya Communication Manager API Java Programmer s Guide details the API enhancements for this release. This section provides a brief summary of these changes, Red Hat Enterprise Linux 3.0 supported Release 2.1 supports Red Hat Enterprise Linux 3.0; however, customers updating to 3.0 with Red Hat updates do so at their own risk. Telecommuter mode support - allows an application to redirect a softphone-enabled CM phone's media to another physical phone, either within the CM domain or outside the CM domain. The application is still notified of call control events, but does not receive the media. Shared registration and control of DCP and IP phones. The API enhancements include: Ability to register a device in shared control mode. This applies to all DCP/IP phones with built-in speaker except for the DCP 8400 series. Media API enhancements increasing access to play, record and digit collection. The API enhancements include: Ability to specify an alphanumeric filename for playback or record. Ability to specify a list of alphanumeric filenames to be played sequentially. Support for new terminating conditions for playback including DTMF digit detected. Support for new terminating conditions for record including DTMF digit detected and recording for a specified duration. Ability to stop play and record with a single stop request. This also applies to resume and suspend requests. Addition of new methods to stop either play or record independently. Similar methods were added for resume and suspend requests. Addition of new methods to stop either play or record independently. Ability to suspend and resume play and record. The length, position and cause values are now supported in the appropriate Voice Unit Listener play, record and stop events. Data Collection Service is now deprecated. New Tone Detection Service and Tone Collection Service have been added. Tone Detection Service allows the application to receive notification of incoming DTMF digits as they are received by the connector server.

4 4 Tone Collection Service buffers incoming DTMF digits on the connector server and allows the application to specify retrieval criteria which when satisfied will cause it to be notified with the appropriate set of DTMF digits. Support for delete message service - ability to delete a recording (or any other file) from the recording directory. For more detailed information see the Java Programmer s Guide and the Java Programmer s Reference for Voice Unit Service, Extended Voice Unit Service, Tone Detection Service and Tone Collection Service. Support for G.729 playback. In Release 2.0, files could only be recorded in G.729. The API enhancements include: Ability to playback a file recorded in G.729 format. Ability to dub over a G.729 recording. API CHANGES AFFECTING COMPABILITY Chapter 1 What s New in the Avaya Communication Manager API Java Programmer s Guide details the API changes that affect backward compatibility for existing applications. This section provides a brief summary of these changes. The RegisterDevice request been has changed for shared control and for future extensibility. The Voice Unit Service stop, suspend and resume requests no longer use the message ID parameter to determine whether to stop, suspend or resume either play or record, instead it now stops, suspends or resumes both play and record. Extended Voice Unit Services now contains methods to stop, suspend or resume either play or record. The Voice Unit Services play and record requests and responses now provide helper classes to more easily set and retrieve private data. Applications that set or retrieved private data for play and record must now use the helper classes. Data Collection Service has been deprecated. Methods for adding and removing listeners have been moved to the new Monitoring Services.

5 5 IMPORTANT NOTES This release of the CMAPI server is compatible with Communication Manager 2.0, 2.1 and 2.2. The Connector Server recommended configuration: 2.4 GHz Pentium IV 1 GB memory 1,000 MB disk space for the CMAPI server Communication Manager servers supported: S8300 (with Communication Manager 2.0) S8300B (with Communication Manager 2.1 and 2.2) S8500 S8700 HP380 DEFINITY Server SI DEFINITY Server CSI Communication Manager media gateways supported: G350 G600 G650 G700 MCC1 SCC1

6 6 RELEASE 2.1 COMMUNICATION MANAGER API CONNECTOR SERVER CAPACITIES: The following table lists the capacities of the connector server for the different configurations of Communication Manager API. The supported capacities are for only specific type of applications. If an application uses different features then the capacity limit can be lower or higher. Mode Exclusive Control Server Media G.711 Exclusive Control Server Media G.729 Exclusive Control Client Media Exclusive Control - Telecommuter Shared Control Connector Server: Simultaneous Sessions (MAX) Supported Connector Server: BHCC (MAX) Supported Connector Server: Registered Endpoints (MAX) Supported Tested Capacity Traffic tested with a call recording application Traffic tested with a call recording application Traffic Tested with a Call generation application with 400 simultaneous calls and a 4 minute hold time for calls This mode has not been tested for capacity Traffic tested with a call monitoring ( ) application. This application has been tested only for 4000BHCC. Comments (1) (2) (3) (1) (2) (3) (1) (3) (4) (5) (1) (3) (4) (5) (1) (3) (4) (5) (1) Application and CMAPI on different machines. (2) This capacity limit is for a call recording type of application that uses the Connector Server s VoiceUnitServices. (3) IMPORTANT: Applications that use different features may have a higher or lower capacity limit. The capacity limit could be CPU resources, memory resources, file resources, hard disk resource among others on the connector server. (4) This capacity limit is for an application that makes a call or receives a call without invoking any features like conferencing. (5) Supported registration rate is 200 station registrations per minute.

7 7 KNOWN ISSUES AND WORKAROUNDS 1. Incorrect installation documentation. The instructions in the CMAPI installation documentation are incorrect for changing the File/Socket Descriptor Limit on the CMAPI Server. The correct procedure follows: In the /etc/security/limits.conf file, add the following two lines to increase the file/socket descriptor limit: avaya hard nofile xxxx avaya soft nofile xxxx where xxxx is the number to increase the descriptor limit. After changing this file, reboot, login again as root, su to avaya and check to see if the limit has be changed with "ulimit -a" 2. Release 2.1 does not support multiple processor environments (including Hyper-Threaded Processors) at this point in time. Any use of these types of environments may result in unstable server or client conditions. 3. A parse error warning message (for the audio control message) may occur when a CMAPI phone is in shared-control with a DCP phone. An audio control message should only be sent to the DCP phone, which has an audio stream and not to the CMAPI phone. However, Communication Manager is sending the audio control message to both phones. This warning message can be ignored. The warning message is as follows: WARNING: Parse error, index=3,buffer={e1,50,1a,1a,2a,99,b,a0,c7,3d,c1,8c,f3,3} 4. Installation issue: If a Communication Manager API server RPM package earlier than version is currently installed, the following behavior may be observed when installing a version or later RPM package. * RPM queries will display package information for both the earlier and later version of the package. * The upgrade could potentially overwrite configuration files that are normally preserved when upgrading the Communication Manager API server package. * Server operation is otherwise unaffected when this occurs. Work Around: To prevent this from occurring, remove the earlier package before installing the later package. 5. Too many open files exception: Sun's JDK1.4+ has a file descriptor leak when opening DatagramChannels. Each DatagramChannel uses an additional file descriptor that is not released until the DatagramChannel is garbage collected. When the number of available file descriptors has been exceeded, an exception with the message, "Too many open files" will result. This exception can occur any place the Java virtual machine attempts to allocate a file descriptor, including creating sockets, opening files, etc. This problem is

8 8 most likely to occur during repeated terminal registration attempts (two DatagramChannels are created for each attempt), for example, during a network outage. This bug has been reported to Sun (internal id, ). Work Around: Increase the number of file descriptors that the server can allocate (ulimit -n) from the default of Application listener throws a RuntimeException: If an application's listener throws a RuntimeException, the server logs a Warning message with the exception stack trace and removes the listener from receiving future event notifications. The application does not receive any notification that the listener has been removed. The application developer would need to check the server logs to debug the problem. Since these logs are currently configured to roll over, the log containing the warning message may be deleted. Work Around: none. 7. ConnectionID will not validate if both the deviceid and the connectionidsequence are set. The getdeviceid method on ConnectionID was modified to return the deviceid **or** the connectionidsequence.getdeviceid() if DeviceID is null. Unfortunately, the Castor code calls this getdeviceid and thinks that both the DeviceID and ConnectionIDSequence are set. The CSTA schema specifies a choice of DeviceID or ConnectionIDSequence. If both are set, the XML fails to validate against the schema. Work Around: The connector server (currently) uses the DeviceID and ignores CallID. To avoid a validation error, don't set the ConnectionIDSequence. That is, only set the DeviceID directly and leave the CallID unspecified. 8. FYI for Applications using the Recording Feature of the Witness/CMAPI Server: For ISV applications: The Record Feature (in VoiceUnitServices) of the CMAPI server is activated on a device(extension). Recording will continue even after a call on that device (extension) has ended. Recording on the device has to be stopped by the application. Once the Recording on the device has been stopped, a Stop Event in the VoiceUnitServices Listener will indicate when the Recording finished and the recorded file is ready for the application. The Play Feature (in VoiceUnitServices) of the CMAPI server is activated on a device(extension). Playing of the WAV file will stop only if the duration of the file has ended or the terminating conditions in Play Request are satisfied. Otherwise, playing will continue even after a call on that device(extension) has ended. Playing on the device has to be stopped by the application. Once the Playing on the device has been stopped (either explicitly by the application or implicitly by the CMAPI server), a Stop Event in the VoiceUnitServices Listener will indicate when the Playing finished. For ContactStore Call Recording applications:

9 9 In the On-Demand recording mode, if a user calls another party and conferences in the on-demand CMAPI extension and then hangs up, the on-demand CMAPI extension will continue recording the other party even though the originator of the on-demand recording has hung up. Only after the other party hangs up will the recording stop on the CMAPI server. Workaround: None. This is an Avaya Communication Manager feature that allows other parties on a conference call to continue talking even after the originator hangs up.

10 10 RELEASE HISTORY RELEASE CHANGES 1.3 Initial offer. 2.0 Use of remote proxy software to allow applications to reside in a Java virtual machine (JVM) separate from the connector server software. Call Information Link Recovery. G.729 and G.729A media recording. Codec specification/selection. Up to 75 simultaneous calls with G.711 or G.729 media (the connector server occupies no more than 60% CPU) when application is in the same JVM as the server. Up to 15 simultaneous calls when application is on a remote machine. Improved service provider interface. CVLAN co-residency. Sample applications and SDK documentation. 2.1 Service refactoring service separation for improved reliability and maintenance via Java Management Extension. Replacement of JBoss infrastructure with JMX. This changes the installation and related startup of the server. Channel manager separates protocol/data handling. Exposure of XML API allows application developers to work directly at the XML layer and provides alternate language bindings on the client. Shared registration and control of DCP and IP phones. Media refactoring separation of media services (player/recorder/ttd). Media API enhancements increasing access to play, record and digit collection. Media Stack API provides media and port handling for applications controlling their own media stream. Support for G.729 playback. In Release 2.0, files could only be recorded in G.729. Enhanced tutorial application with a re-usable station class. Enhanced application with station class and shared phone control. Change: add and remove listener methods in Java API are now in Monitoring Services New Voice Unit Services request supported: Delete Message. New Telecommuter mode in Terminal Service's Register Device request allows a Communication Manager or non-communication Manager physical phone to be associated with a CMAPI softphone. Up to 75 simultaneous calls for applications running on remote JVM with exclusive device control, server media mode and G.711 Codecs. Up to 120 simultaneous calls for applications running on remote JVM with exclusive device control, server media mode and G.729 Codecs. Up to 20,000 bhcc for applications with exclusive device control and client media mode. Up to 4,000 bhcc for applications with shared device control. WHERE TO OBTAIN SOFTWARE You can download the CMAPI server software, SDK and documentation from: DOWNLOADING SOFTWARE To install the connector server software, see the Quick Start guide. To install the SDK on a development machine, see the see the Java Programmer's Guide or the XML Programmer's Guide.