- Telephony Web Service
- SMS Web Service
- Getting Started with AE Services
- Training Course: Developing with AE Services
Sample Applications & Tutorials
- Application Event Monitoring using the DMCC Java SDK
- Application Initialization using the DMCC Java SDK
- C# Telecommuter
- Call Control using the DMCC Java SDK
- Call Detection using the DMCC Java SDK
- Record, Playback, Transfer & Conference (RPTC)
- Setting up a Development Environment for the DMCC Java SDK
- Setting up a Development Environment for the DMCC XML SDK
- Telephony Web Service
- SMS Web Service
- DMCC APIs
- Development Tools & Configurations
- Compliance Testing
Registering and Unregistering
- Are there any best practices related to DMCC Multiple Registrations?
- What does it mean when I receive 'Registration Reject reason: securityDenial' when the application attempts to register?
- How fast can my application send requests to the AE Server?
- What does it mean when I receive a "Received unregistration request from switch reason=2018 text=2018-Rebooting Ext released"?
- What does it mean when I receive an "Out of IP Registrations - error code 1823" in response to a registration request?
- What does it mean when I receive a "Registration Failed: The number of registered stations exceeded the capacity specified on the license file" response to a registration request?
- What does it mean when I receive "Release DeviceID Exception - session[*] is using this device, not you" when unregistering?
- What does it mean when I receive a "Gatekeeper Reject reason: terminal Excluded" when my application tries to register?
- Does my application need to wait for a response to an unregister request?
- How can I tell if my application successfully registered?
- What does it mean when I receive 'ch.ecma.csta.errors.ResourceBusyException: The device [40010::192.168.17.129:0] is being used by another application' when the application attempts to register?
- What is the difference between 'RegisterTerminalRequest' and 'RegisterDevice' in DMCC?
- What could be the reason for getting the event: "Received unregistration request from switch reason:2009 text:2009-Unregistering User moved, extension: #### "?
- What does it mean when I receive a "Registration Failed: resourceUnavailable Invalid product ID is specified. Check the version of switch or license file" in response to a registration request?
- How many RegisterTerminalRequests can an AE Services server or a Communication Manager handle in a specific period of time?
- What causes the 'Registration reject reason: undefinedReason Shared control denied because of incompatible set type - only DCP and IP phone w/speaker are allowed' error to occur while registering CallMaster IV/VI phones with DMCC version 4.0?
- How can I troubleshoot why a DMCC registration request fails with an 'Unspecified' reason or a response similar to:
CM Connection lost - protocol timeout: GRQ timer, tried 3 times. Possible problem(s) include:
- Network connection is not working or is congested
- IP address to the switch is not correct
- Switch translation for the extension is not setup correctly
Are there any best practices related to DMCC Multiple Registrations?
Device Media and Call Control (DMCC) Multiple Registrations (MR) allows more than one H.323 terminal (or equivalent) to register against a single extension in Communication Manager.
There are limitations to using the MR functionality, some inherent in the service, and some that come from the overall environment in which an application may utilize the service. The most notable limitation of the service is that, while it allows the application to receive the RTP stream that Communication Manager is sending to the endpoint, it does not allow multiple terminals to send RTP to Communication Manager simultaneously for that party in the call (there is only one ‘talker’ per extension allowed at a time). Additionally, the ‘talking’ terminal does not receive a copy of their RTP stream back in the receive RTP stream whereas the non-talker device registrations do receive a copy of the talker’s RTP stream. Receiving the RTP information from all talking participants is useful for call recording applications. The talker role can be passed between terminals on a common extension.
MR service also is limited in the total number of registrations supported per station. Up to three H.323 terminals can be simultaneously registered against an extension. This is typically a desk phone or soft phone and two additional DMCC device registrations. Each DMCC registration must use a unique “Device Instance Number” in the registration request to differentiate them, this value ranges from 0-2, and the application must guess at an available one unless it has some other way of knowing a free one at any moment in time.
The most significant environment restriction comes from the workload created by device registration and un-registration activity on AE Services and Communication Manager. This workload consumes a lot of CPU due to the large number of messages that are exchanged in the process of handling each of those activities. The total message counts and the fact that two separate servers are incurring work means that there is a reasonable amount of real time that transpires between when the application makes a request to un/register and when it completes. The total amount of real time is dependent on the other work load on AE Services (other CTI traffic) and the other work load on Communication Manager. In fact, it can take several seconds or more for a terminal to be fully registered/unregistered.
Underlying the work load on Communication Manager is built in protection against activity that Communication Manager classifies as hyperactivity. If for some reason, like a power failure or network outage recovery, many registrations are occurring in a small window of time, or overall call traffic is high, Communication Manager may ignore some or all, of the registration attempts in an effort to protect the overall operation of the system from degrading past certain thresholds. Stations and CTI applications are expected to retry the registration later (after some reasonable back-off time).
There are also race conditions between activity on Communication Manager (e.g. the start of a call, state changes on calls, and administration activity on the device) and when an application may initiate a registration request. The net of this is that a MR application that frequently registers and unregisters, may incur delays in a registration completing. This can impact the service the application is trying to provide. In a call recording context, this can result in missed recordings or a portion of the beginning of the recording not being present. The race conditions between call activity and registration activity may lead to an application missing some events.
Unless the application is tolerant of these limitations, and the possibility of a significantly delayed (or even rejected) registration, the preferred approach is to register the application’s MR terminal once when the application initializes (or perhaps when the agent logs in for the work day) and unregister it when the application is shut down or the agent logs out (or similar).
There is a "Max. Simultaneous Devices" feature within a SIP User’s Session Manager Profile that allows multiple SIP registrations against a single SIP station extension. The DMCC MR functionality may be used in conjunction with the "Max. Simultaneous Device" feature. If “Allow H.323 and SIP Endpoint Dual Registration” is enabled within the SIP User’s Communication Endpoint Profile (which would allow both an H.323 and SIP primary registration), “Max. Simultaneous Devices” must be set to 1 (one).
Some applications may choose to use a dynamic approach to terminal registrations (e.g. a call recorder that only records a subset of the calls occurring at a station/extension). When a more dynamic approach to multiple registrations is utilized, make sure to use the following best practices:
- The Applications Enablement Server should be configured to do DMCC License Reservations (see the Administering and Maintaining Avaya Aura Application Enablement Services Guide – section titled “Reserving DMCC licenses”). Enabling license reservations reduces a round trip delay between the license server process/server and the DMCC application on AE Services each time a un/registration occurs.
- Auto answer for the agent/station should be disabled.
- The agent should be configured for an automatic after call work interval of at least a few seconds.
- In both inbound and outbound contact center environments, even with the agent configured for automatic after call work intervals (e.g. direct call to the station occurs), there may be very short (milliseconds) delays between active calls at an agent/call handler. If the application is recording all calls at the agent/station, the application should implement a delay before unregistering its DMCC device to allow for a subsequent call to be handled/recorded. The interval of this delay should be factored into the provisioned after call work interval.
- Disable media shuffling for the station the agent is using to login on.
- The application must wait for an unregister notification (not just the confirmation to the unregister request) before trying to register the same extension/Device Instance Number pair again. Ignoring this constraint will cause race conditions between the unregister and the register which will result in unpredictable behaviors.
- A round robin policy should be implemented for the DMCC device instance number. A strategy to avoid immediately reusing the DMCC device instance number will help prevent collisions with activity that has not finished on the prior instance number when there is a subsequent activity (i.e. a new reservation) on the same extension. In some environments when all three instance numbers are being utilized this will not be possible.
- The application must tolerate rejected registrations and retry them after a delay. Multiple failed registrations back to back (even across multiple extensions) should cause the application to use larger and larger delays as it can indicate Communication Manager is in an overloaded state.
- Per general guidance related to request traffic from an application to AE Services, any application (using MR or any set of services) should not have more than 10 outstanding requests to AE Services at any one moment in time. When a ‘final’ response to an outstanding request is received a new request can be placed. This strategy allows for other applications to send requests to AE Services and factor in the event traffic that may be occurring simultaneously.
What does it mean when I receive 'Registration Reject reason: securityDenial' when the application attempts to register?
Registration failed because Registration Reject reason: securityDenial
Login Denied - Access Code invalid diagnostic string= code= 63773
The password that is being provided for the deviceID (extension) is invalid.
How fast can my application send requests to the AE Server?
An application should provide some interval between the sending of each request to the AE Server. In some cases (e.g. dialing digits or feature function button pushes), if the application sends a sequence of requests to the AE Server rapidly enough, although each request receives a response from the AE Server, as the stimuli are processed by Communication Manager, requests may be silently discarded due to a perceived overload condition at Communication Manager. A suggested inter request interval is 200ms.
The application must also wait between a feature button push (e.g. call appearance or no hold conference) and the pushing of digit buttons for CM to enter into the proper feature state to accept the digits provided by the application has been entered at CM. This delay should be at least 500 ms.
While it is possible in both cases for the application to work without the suggested delays, under load in a real customer network the loss of button requests has been observed and traced to the underlying overload controls in Communication Manager.
What does it mean when I receive a "Received unregistration request from switch reason=2018 text=2018-Rebooting Ext released"?
The reason code of 2018 is provided by CM when a busy-out and release of the port being monitored at the Communication Manager has occurred. A busy-out event may occur due to hardware failure, communications failure (with the hardware), or command at the SAT.
A complete list of reason codes is not available. In general a condition has occurred on CM and it has unregistered the device. The application must begin attempting to re-register with AE Services, and then re-acquire the state information for the monitored device.
What does it mean when I receive an "Out of IP Registrations - error code 1823" in response to a registration request?
Registration Failedsession[null] com.avaya.csta.binding.RegisterFailedEvent@2bfdff
Registration failed because Registration Reject reason: resourceUnavailable
Request rejected from switch with error code= 18239
This message indicates that the maximum number of registered IP endpoints has been exceeded. Check the second page of the "display system-parameters customer-options" form to see the number administered. Customers will need to purchase licenses for additional IP endpoint registrations to overcome this situation. The use of the "list registered" command will show all active registered IP devices.
What does it mean when I receive a "Registration Failed: The number of registered stations exceeded the capacity specified on the license file" response to a registration request?
Registration Failed session[null] com.avaya.csta.binding.RegisterFailedEvent@19ea173
Registration failed because Registration Reject reason: resourceUnavailable
The number of registered stations exceeded the capacity specified on the license file.
Application is terminating; performing cleanup....
The number of IP_API_A licenses is insufficient to support the number of registered applications. In the example, there are zero available. The information is accessed using the "display system-parameters customer-options" form, page 2 on the Communication Manager's System Access Terminal.
What does it mean when I receive "Release DeviceID Exception - session[*] is using this device, not you" when unregistering?
The following XML can be received by an application in response to a releaseDeviceID request:
1808 07/04 15:53:03.122 =>  <ReleaseDeviceId xmlns="http://www.avaya.com/csta"> <device typeOfNumber="other" mediaClass="" bitRate="constant"> 10.202.8.187:38605:0 </device> </ReleaseDeviceId>
1808 07/04 15:53:03.603 <=  <?xml version="1.0" encoding="UTF-8"?> <CSTAException> <exceptionClass> ch.ecma.csta.errors.InvalidDeviceIDException </exceptionClass> <message> Client=session is using this device, not you(session ) so you can't release it </message> <stackTrace> com.avaya.mvap.extsvc.DeviceServicesImpl.releaseDeviceID(DeviceServicesImpl.java:160) sun.reflect.GeneratedMethodAccessor14.invoke(Unknown Source) sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) java.lang.reflect.Method.invoke(Method.java:324) com.avaya.mvcs.proxy.CstaRouter$ServiceMethod.invoke(CstaRouter.java:223) com.avaya.mvcs.proxy.CstaRouter.routeRequest(CstaRouter.java:168) com.avaya.mvcs.proxy.CstaRouterService.routeRequest(CstaRouterService.java:69) com.avaya.mvcs.proxy.CstaRouterNode.processPacket(CstaRouterNode.java:210) com.avaya.mvcs.proxy.AbstractPipelineNode.process(AbstractPipelineNode.java:102) com.avaya.mvcs.proxy.Pipeline$PipelineSubscriber.inform(Pipeline.java:364) N more removed
The cause for this response is that a different socket (and therefore different session) is releasing the DeviceID than the one that originally got the DeviceID (that is being unregistered). An application cannot share DeviceID across different CMAPI sessions (sockets). Alternatively, a different instance of the application (or different application altogether) presumably on a separate AE Services server has "stolen" the device out from underneath this instance of the application by using a registrationRequest with the
option sent with the request. When the application that initially secured the deviceID received notification that the device had been unregistered the application may have attempted to release the deviceID in question causing the error to be thrown.
What does it mean when I receive a "Gatekeeper Reject reason: terminal Excluded" when my application tries to register?
The extension the application is registering against (provided as part of the deviceID) is not administered on the Communication Manager that is accessed by the provided IP address or H.323 Gatekeeper List.
Does my application need to wait for a response to an unregister request?
When unregistering devices (e.g. during the cleanup or shutdown phase of an application), the application should wait for the unregistered event (in Release 3.0 the event is an unregistered() event sent to the terminalListener in 3.1 it is a UnregisterTerminalResponse to the terminalServices.unregister() request) before stopping monitoring and releasing the device ID. Under some conditions if the unregistered event is not received before the application continues shutting down, then the application will not be able to re-register the device until the previous session's SessionDurationInterval expires even though the session has been released.
How can I tell if my application successfully registered?
Observing the response from the AE Services Server is one method, another is to use a command at the system access terminal (SAT) of Communication Manager. Utilize the list registered command to observe all active registrations for IP stations.
For applications using the Java API RegisterDevice (3.0) returns an asynchronous event indicating the success or failure of the registration request. In Release 3.1 RegisterTerminalRequest (3.1) returns a synchronous indication of the result of the registration for applications using the Java API.
What does it mean when I receive 'ch.ecma.csta.errors.ResourceBusyException: The device [40010::192.168.17.129:0] is being used by another application' when the application attempts to register?
DMCC only allows one application to have shared or exclusive control of a specific extension. The most common cause of this exception is the application has restarted (via a crash or management action) without releasing the device IDs from the previous instance of the application AND the registration request has occurred with in the interval (default 3 minutes) before the AES releases the registered device IDs automatically due to the Application Session timing out. The developer should review the information in the application programmer's guide(s) regarding Session Management, and proper shutdown procedures.
What is the difference between 'RegisterTerminalRequest' and 'RegisterDevice' in DMCC?
Functionally, there is no difference between 'RegisterTerminalRequest' and 'RegisterDevice'. 'RegisterTerminalRequest' should be used in AE Services 3.1 and later versions of AE Services, because 'RegisterDevice' is deprecated in the more recent versions.
What could be the reason for getting the event: "Received unregistration request from switch reason:2009 text:2009-Unregistering User moved, extension: #### "?
This event occurs when an extension #### is already registered, and subsequently CM receives a 'Force Login' request for the same extension. This could occur when an application makes a 'RegisterTerminalRequest' request with a force login set to true and the extension is already registered by some other application. CM interprets the request to mean that the extension is moved to a new location. CM then sends a 'Forced Unregister' request to the extension, which leads to this message. The event can also occur when an application is monitoring (shared control) an extension and the user does a forced login from a different station.
What does it mean when I receive a "Registration Failed: resourceUnavailable Invalid product ID is specified. Check the version of switch or license file" in response to a registration request?
registration failed reason=Registration Reject reason: resourceUnavailable
Invalid product ID is specified. Check the version of switch or license file
Starting with AE Services Release 5.1 the license allocation behavior for DMCC changed. Please review the FAQ titled When is a DMCC_DMC license allocated and when is it not? for more details.
This message indicates that AE Services could not allocate a DMCC_DMC license for a variety of reasons, and attempted to fall back to IP_API_A license allocation from Communication Manager. That fallback license allocation failed, either because a switch connection is not provisioned, it is out of service, or Communication Manager holds no available IP_API_A licenses.
Use AE Services web OA&M to check for a provisioned switched connection and its status. Use Communication Manager SAT to check for IP_API_A licenses using "display system-parameters customer-options" The information is on page 10/11 in Communication Manager Release 6.2.
How many RegisterTerminalRequests can an AE Services server or a Communication Manager handle in a specific period of time?
This depends upon the type of Media mode (server or non-server) and Signaling Encryption used. For more information on this, refer to the AE Services 4.1 Overview document, document ID 02-300360 Release 4.1 Issue 4 dated December 2007, available on the DevConnect portal (www.avaya.com/devconnect). The tables on pages 24 and 25 in this document list the capacities of RegisterTerminalRequests with respect to the type of server and signaling encryption used.
What causes the 'Registration reject reason: undefinedReason Shared control denied because of incompatible set type - only DCP and IP phone w/speaker are allowed' error to occur while registering CallMaster IV/VI phones with DMCC version 4.0?
Registering a terminal allows the application access to the signaling and possibly the media of the DCP or IP telephone, or an extension that is administered for softphone access on Communication Manager. Only devices that are speaker phone enabled can be successfully registered. A speaker phone is required so that Communication Manager can force the device off-hook when performing call control actions (makeCall, answer) or physical device hook-switch control. CallMaster IV/VI phones are not speaker phone equipped and fail to meet this DMCC requirement. If an attempt is made to register a device that is provisioned on Communication Manager as a CallMaster station, DMCC throws the specified error.
How can I troubleshoot why a DMCC registration request fails with an 'Unspecified' reason or a response similar to:
CM Connection lost - protocol timeout: GRQ timer, tried 3 times. Possible problem(s) include:
1. Network connection is not working or is congested
2. IP address to the switch is not correct
3. Switch translation for the extension is not setup correctly
This response indicates that AE Services made an attempt to send a registration request to Communication Manager and was unsuccessful. There are many possible reasons for the registration to fail. This FAQ provides some general guidelines for how to proceed, however it can not cover all possible sources for the problems that will result in this response.
As a first step, use the Communication Manager System Access Terminal and verify that the extension you are trying to register is administered as a H.323 station, that there is a security code provisioned, and that the IP Softphone flag on page 1 is set to y.
Next, you need to determine if Communication Manager is reachable from AE Services. Get a Linux prompt on AE Services, and ping the IP address of the Communication Manager. Make sure to use the appropriate source NIC. Most AE Services servers have at least two NICs. One is intended to handle traffic between AE Services and Communication Manager. The other is used to connect to the client applications. See the AE Services Installation and Maintenance guide for more details. You can determine what IP address to use for the Communication Manager IP by examining the deviceID that you are trying to register. The CLAN/procr IP address that will be used is usually imbedded in the deviceID. If the IP address is not present in the device ID, check that the H.323 Gatekeeper's list associated with the Switch Connection Name (also usually imbedded in the device ID) has the correct set of IP addresses for CLAN/procr interfaces on Communication Manager. If the application provides the IP address during the getDeviceId() operation, verify it is the correct IP address for Communication Manager. Note that Communication Manager has many IP addresses. There are typically one group dedicated for handling H.323 station registrations (a subset of these should be dedicated to handling AE Services device registrations - an exception to this guidance is on smaller systems where just the procr is utilized). There will be other IP addresses associated with Communication Manager (e.g. a management related address for accessing the SAT, media processors, IPSIs, etc). These addresses are typically not configured to accept AE Services device registrations (or other H.323 station registrations). Make sure AE Services or the application is configured to use IP addresses on communication manager that are dedicated and configured to handling H.323 and AE Services device registrations
If there is ping level connectivity between AE Services and Communication Manager (note that this is not on the same ports that H.323 traffic will be sent), access the Communication Manager System Access Terminal (SAT), and run the command 'list trace ras ip-station XXXXX'. Now, try to register the DMCC device. If there is output from the command, check for any denial codes. The denial codes are cryptic but very useful when they are available. If there is not even a GRQ (Gatekeeper Request) appearing, then verify that the target CLAN/procr for the registration is accepting H.323 registrations; examine the Allow H.323 Endpoints flag on the 'display ip-interface' form. Note that you may need to do a 'list ip-interface' to find the board address for the CLAN/procr with the Communication Manager IP address you are working with.
Use a normal H.323 IP station (e.g. 9620) to attempt the registration. Statically set the Call Server IP address to the same IP address as is being used by AE Services as the Communication Manager registration IP address. Assuming that works, move the station to be in the same subnet as AE Services (physically as close to AE Services as possible), and re-run the test. In some network arrangements, we have seen a firewall or router issue blocking the registration attempt.
If the 'list trace' command produces a denial event 2041: IP RRJ-No DSP Resource message, verify that Communication Manager has medpro resources that are accessible from the network region that the registration is occurring in. Use the SAT command 'list media-gateway' or use 'list ip-interface medpro' to make sure that there are media processor resources configured on Communication Manager. Use the 'list ip-interfaces all' command along with an examination of the 'display ip-network-region X' form to check that the network region that the device is registering into (from the associated CLAN/procr) is allowed to use medpro resources either in the same network region or some remote network region. If the registering device can not access medpro resources then the registration will be blocked. Note that the network region assigned to a CLAN/procr can be overridden for specified originating IP addresses using the 'change ip-network-map' form.
Are all registrations failing or only some? If only some, then look closely at the provisioning of those stations for differences (e.g. station type), or other differences (e.g. the IP address the registrations are being sent to, or the network-region).
Can you register through AE Services using the DMCC Dashboard? If yes, then the problem is most likely that the application is not well behaved. Look for errors in the registration request itself (dependency mode, media mode, etc).
Does the provisioned station type support a speakerphone (this is required for DMCC registrations to succeed)? Change the station type to something that does (e.g. 4620).
It is possible that the CLAN/procr is out of available sockets? Use the SAT 'status socket-usage' command to gain insight.
Are there adequate DMCC_DMC or IP_API_A licenses? Check using the AE Services WebLM interface (the Administration and Maintenance Guide provides release specific access details). Also check the Communication Manager IP_API_A licenses using the 'display system-parameters customer-options' form. There must be one type or the other available.
A device registration requires that a DMCC license can be acquired. DMCC licenses can reside on the WebLM server associated with AE Services (DMCC_DMC), or they can reside on Communication Manager (IP_API_A). When AE Services can allocate a DMCC_DMC license, AE Services needs to inform Communication Manager that it has done so prior to initiating the device registration. This notification is done through the "DAPI link." The DAPI link uses the switch connection between AE Services and Communication Manager for transport of messages. If the switch connection is not operational, then this notification can not be sent and the registration attempt releases the DMCC_DMC license and attempts to register 'the old way'. If Communication Manager does not have any available IP_API_A licenses, the registration is blocked. Verify that the deviceID has a switch connection name in it, and that the corresponding switch connection's state is 'Talking'.