A Developer’s Intro to Avaya Engagement Call Control (ECC)

I need to start by telling you that I am a Java programmer. Having experienced quite a few computer languages over the years, I started writing in Java fairly exclusively in the late 1990s. I love the elegance, power and flexibility of Java. It ran circles around other object oriented languages such as C++ and made my life as a software designer much easier.

However, I recognize that Java isn’t for everyone or for every circumstance. While it’s not necessarily a difficult language to learn, it requires a particular way of thinking. You can’t write Java code the way you may have written software in other languages – object-oriented or not – and I understand why some people get frustrated with Java and turn to other languages for their development projects.

Even more importantly, I realize that in certain areas, pure Java can feel like a square peg in a round hole. To avoid developer/application mismatch, it’s important to keep an open mind and be willing to adapt to the situation at hand.

The new Avaya Engagement Call Control (ECC) Snap-in is the perfect example of something different being the right choice. Built on top of the Avaya Engagement Development Platform (EDP), ECC exposes a wide array of RESTful Web services that allows developers to quickly and easily add a myriad of call control features into their applications.

While much of the ECC functionality is supported natively by EDP, EDP interfaces require Java and, by their very nature, are a bit more difficult to use than Web services.

On the other hand, ECC features can be used by any language or scripting tool that supports Web services. This includes Python, Ruby, Node.js, .NET, PHP and, yes, even Java. So, while hardcore programmers might prefer a more traditional language, powerful ECC applications can be quickly built with easy-to-use and highly portable Ruby. In fact, there may be times when an application is prototyped with Python and productized with .NET. Developers have choices and are not locked into a single platform or a specific way of programming.

Read additional articles from Andrew Prokop at SIP Adventures.

A powerful difference between ECC Web services and EDP Java interfaces is the ability for ECC to monitor and control calls of all types. While EDP applications are limited to calls to and from trunks, ECC can act upon trunk calls as well as station-to-station calls. That alone makes ECC worth the price of admission.

This difference comes from the fact that the ECC Snap-in uses the Avaya Application Enablement Server (AES) to provide telephony features, while EDP Java applications run as sequenced applications on Session Manager. By using AES, ECC Web services extend AES’s close relationship with Communication Manager (CM). In other words, any call that CM can see, ECC can also see.

The following list is a more comprehensive look at the differences between the ECC and Java APIs:


A Look at the ECC Interfaces

ECC Web services support the following call control interfaces:

  • Make Call
  • Get Call
  • Drop Call
  • Drop Connection
  • Answer Call
  • Hold Call
  • Retrieve Call
  • Get Call Forward
  • Set Call Forward
  • Cancel Call Forward
  • Get Connections By Address
  • Get Call Connections
  • Get Connections Details
  • Redirect Call
  • Single Step Transfer
  • Consult Initiate
  • Complete Transfer
  • Complete Conference

As a software developer, I can immediately envision a myriad of applications made possible by these 18 function calls. For instance, it would be painless to add click-to-call capability to a corporate Web page or an employee services portal. The same holds true for CRM or workflow management packages. Although Avaya Communicator makes it unnecessary, it wouldn’t be that difficult to write your own soft client. The possibilities are endless.

In addition to operations that create and manage voice calls, ECC supports a number of Web services that act upon Avaya Aura Messaging. These are:

  • Get Messagebox by ID
  • Get Message by ID
  • Get All Messages
  • Get Message Flags
  • Set Message Flags:
  • Get Message Parts
  • Get Message Part by ID
  • Get Message Part Content
  • Purge All Messages in Trash

Again, there are quite a few applications that could be built from these interfaces with Visual Voice Mail being the most obvious. It would be very simple to create a Web page that displayed and played a user’s voice mails. I don’t know about you, but I am all for anything that keeps me from entering DTMF commands from my telephone. I have been a Modular Messaging user for years and still refer to the cheat sheet of commands pinned on my bulletin board.

Digging Deeper

As a developer, I want more than function names. Thankfully, Avaya has done a great job of documenting every Web service and its associated data structures. Before I did anything with ECC, I downloaded the documentation and poked around the function calls.

For instance, the Make Call operation consists of an invocation and subsequent response. The Make Call invocation looks like this:


“id” :”#MakeCall”,
“type” : “object”,
“properties” : {
“from” : { “type” : “string”},
“to” : { “type” : “string”}
},”additionalProperties”: false

And a successful response (200 OK) looks like this:


“id” : “#Call”,
“type” : “object”,
“properties” : {
“callID” : { “type” : “string”},
“statusUrl” : { “type” : “string”}
},”additionalProperties”: false

In English, Make Call requires To and From destinations. For example, the To could be my telephone number (“+19524563516”) and the From might be my coworker, Debbie (“+19524563888”). Note that To and From are expressed as E.164 numbers.

A successful response contains a  callID that uniquely identifies the call. This  callID will be used in subsequent commands to manage the newly created call.

The remaining function calls follow a similar model of command and response.

ECC Events

Of course, it’s not enough to simply tell ECC to do something. You need to know when something has occurred. For that, ECC delivers the following events:

  • HELD

Applications will register an event handler that will subsequently be invoked for all new events. For example, an ECC application is made aware of a ringing call with an ALERTING event:

event {

callEvent: ALERTING


originalCallingParticipant: A

originalCalledParticipant: B

alertingParticipants: B

participants:A, B

callID: <call_id>

callHref: https://<CLUSTER-IP>/services/EngagementCallControl/calls/callID

address: A


An application could act upon that event by issuing an Answer Call command.

After the call has been answered, an ACTIVE event would be delivered to the application’s event handler.

event {

callEvent: ACTIVE

originalCallingParticipant: A

originalCalledParticipant: B

participants:A, B


callID: <call_id>

callHref: https://<CLUSTER-IP>/services/EngagementCallControl/calls/callID

connectionId: <connection_id>

connectionHref: https://<CLUSTER-IP>/services/EngagementCallControl/connections/connectionId

address: A

operations: [

endCallHref: https://<CLUSTER-IP>/services/EngagementCallControl/calls/callID holdCallHref:


consultCallHref: https://<CLUSTER-IP>/services/EngagementCallControl/connections/connectionId?action=consult]


Make note of connectionId. Like callID, this reference is used in commands that act upon calls and their various connections. For example, an application can use connectionId to drop a single participant from a conference call while not releasing the call itself.

Mischief Managed

My goal for this blog article was to provide an introduction to ECC, and I hope I accomplished that. In future articles, I may dig in a bit deeper to the commands, events and call models that ECC supports.

In the meantime, I highly recommend that you go to the Avaya DevConnect page, download the SDK and supporting documentation, take a look at the sample applications, and have a go at it. I think you’ll find it as easy to understand as I did!

Andrew Prokop is the Director of Vertical Industries at Arrow Systems Integration. Andrew is an active blogger and his widely-read blog, SIP Adventures, discusses every imaginable topic in the world of unified communications. Follow Andrew on Twitter at @ajprokop, and read his blog, SIP Adventures.

Related Articles:

Survivability and Avaya Media Gateways

Writing these technical articles serves two purposes. First, I love having the opportunity to play unified communications professor. I’ve been in this industry for a long time, and I truly enjoy sharing what I’ve learned about telephony, SIP, WebRTC and VoIP in general. Second, I find that I don’t really understand something until I’m forced to explain it to someone else.

I can’t tell you how many times I’ve started writing an article, got stumped about how to say something, did some research, and found that what I thought I knew was either inaccurate or not complete. So, as much as I hope that I’m helping my readers, I’m helping myself just as much.

Today, I’d like to tackle one of those “do I really understand this well enough to explain it to someone” subjects – Avaya media gateway survivability.

Are you ready? Great! Let’s go.

Avaya Media Gateways

Avaya supports two styles of media gateways. The first, and oldest, is the G650. The G650 is an 8U high, 14 slot chassis that was developed to give new life to Avaya TN card types. These are the cards used in the much older MCC and SCC cabinets. Examples include the TN799 C-LAN, TN224 digital line card, TN2602 IP Media Processor (DSP resources) and the TN2312 IP Server Interface.

These gateways communicate with a Communication Manager (CM) server through the TN2312 IP Server Interface.  Affectionately known as an IPSI, this card provides the control link between the CM and the gateway. A single G650 can support multiple IPSIs for redundancy purposes.

Traditionally, IP stations and trunks connected to a C-LAN. Like the IPSI, there can be multiple C-LAN cards in a single G650. These cards are used for both redundancy and capacity. You can configure different sets of phones to connect to different C-LANs.

C-LANs can also be used to connect to what I really want to write about today – H.248 gateways.

The H.248 gateway family consists of the G700, G250, G350, G430 and G450. Of those, only the G430 and G450 are available for purchase today.  The rest have been end-of-sale for a number of years.

Like the G650, the H.248 gateways support a variety of line cards and DSPs. However, these are newer vintage cards such as the MM710 T1 interface and the MM711 analog card. H.248 gateways do not support the TN form factor cards.

Also, H.248 gateways do not use C-LANs or IPSIs. Instead, these gateways connect to a CM server via a C-LAN in a G650 or directly to the CM through something called Processor Ethernet (PE). Think of PE as the network interface and IP address of the CM.

Media Gateway Lists

Now that I have the basics out of the way, I want to spend some time explaining how an H.248 gateway determines which CM to connect to.

I’ve mentioned “the CM server” a few times, but that’s not quite accurate. There can be several CM servers, and the gateways need to know which one they should hitch their wagon to.

There will always be a prime CM server. This is the main brain that runs the entire system. Call processing, vectors, call center, routing and device management all live there

What happens if the main brain dies? No problem. Avaya allows gateways to failover to another brain called an Enterprise Survivable Server (ESS).   Under sunny day conditions, an ESS is running, but it will not perform call processing or other CM tasks until a gateway registers to it. At that point, it wakes up and functions as if it was the prime processor.

Although Avaya supports up to 63 ESS processors in a single system, most enterprises implement far less than that.

There is another form of brain called a Local Survivable Processor (LSP). An LSP was originally designated to be a server that provides survivability for a branch location, but over the years, Avaya has increased its capacity and scale to the point where it now looks like its ESS brother.

How does an H.248 gateway know who to talk to?

This is where the Media Gateway Controller (MGC) list comes in. The MGC list instructs the H.248 gateway which processors it can connect to, in which order and under what conditions.

For example, an MGC list might consist of the IP addresses of the main CM’s PE, a C-LAN associated with that CM, an ESS and the 8300D processor embedded within the gateway itself. These IP addresses are priority ordered and the gateway attempts to register to them in the order that they are listed … sort of.

If the main processor’s PE or C-LAN doesn’t immediately respond, you might want to hold off trying the ESS or LSP. It would be smarter to attempt registration to the main processor a few times before entering into disaster recovery mode.  You don’t want a brief network hiccup to be the cause of a major reconfiguration.

This is where the transition point (TP) comes into play. The TP separates the primary server(s) from the survivable servers.

An H.248 gateway will first attempt to connect to the processor(s) above the TP. If my example had a TP of 2, the PE and C-LAN of the main CM will be tried several times (with 10 seconds between each attempt) before the gateway decides that they are not going to answer.

Honestly, I would love it if there were two transition points. One would divide main from ESS and the other would separate ESS from LSP. This would allow me to create a policy for enterprise survivability and another policy for local survivability. What say you, Avaya?

So, how long does a gateway keep trying? Every gateway will attempt to register to an IP address above the TP until the primary-search time is reached. After that, it attempts to connect to the servers below the TP.

With a TP of 2 and a primary-search of 10, a gateway will cycle through the two IP addresses of the main CM (PE and C-LAN) for 10 minutes before deciding it’s time to move on. At that point, it will try any IP addresses below the line following the same rule of 10-seconds between each registration attempt.

There is another value we need to be concerned with. The total-search time is the maximum number of minutes a gateway will attempt to register itself before giving up and rebooting.  This time includes attempts above and below the TP.

Making it real

Unfortunately, there is no centralized way to configure this. You make the magic work by setting the configuration parameters on every gateway in your Aura system.

The commands to create an MGC list similar to my example will look something like this:

clear mgc list

set mgc list

set reset-times transition-point 2

set reset-times primary-search 10

set reset-times total-search 15

In words, we have this:

Main Server (Processor Ethernet)

Main Server (C-LAN)

—————-Transition point————————————

ESS Location (Processor Ethernet)

LSP (Processor Ethernet)

Mischief Managed

That wasn’t too difficult, was it? Heck, even I learned something today. I wasn’t sure about the 10-second timer until I did a little research. So, even if you are still scratching your heads, it was a truly satisfying experience for me.

Andrew Prokop is the Director of Vertical Industries at Arrow Systems Integration. Andrew is an active blogger and his widely-read blog, SIP Adventures, discusses every imaginable topic in the world of unified communications. Follow Andrew on Twitter at @ajprokop, and read his blog, SIP Adventures.

Understanding SIP PRACK for Avaya Aura

As many of my readers know, every few months I teach a two and a half day class on “all things SIP.” My students are exposed to everything from “why SIP” to the nitty-gritty of SIP requests, responses and call flows. I even speak about some of the more esoteric topics such as To and From tags, the Replaces header, nonce values and TR-87.

Included in the esoteric list is the PRACK (Provisional Response Acknowledgement) method. PRACK wasn’t in the original SIP specification and was introduced later in RFC 3262. It came about after it was realized that some user agent servers need to know that a provisional response was received by a user agent client. Before PRACK, 1xx responses sent using UDP might get lost, and the sender would never know. PRACK adds a layer of reliability to an otherwise unreliable call flow.

I previously addressed PRACK in my article “Ducks Go Quack. SIP Goes PRACK.” Although I addressed most of the pertinent material, I was short on examples and real-life call flows. As I walked my most recent students through live calls on my company’s Avaya system, I happened to notice a few PRACKs and decided it was time to update my old article.

The following screenshots were gathered using the Avaya traceSM utility. I simply started traceSM on a live Aura system, let it run for a few minutes, and then stopped it after I noticed a few PRACK messages fly by. This was simply because I was unsure as to when Avaya uses PRACKs and when it does not.  In other words, “When in doubt, trace it out.”


Let’s start at the beginning. PRACK messages aren’t just sent out-of-the blue. The sender of an INVITE message must indicate that it is capable of sending PRACKS. It does that by including the header in the INVITE message:

Supported: 100Rel

This tells the recipient that, if requested, it will send PRACK messages for 1xx Responses.

The following shows an INVITE with such a header.


Now that the user agent server knows that PRACK messages are possible, it will include headers similar to the following in all 1xx Responses it wants to be PRACKed:

Require: 100Rel

Rseq: 1

The Requires header with a value of 100Rel tells the user agent client (the sender of the INVITE) that a PRACK is expected for this response. It’s important to know that the user agent server (the sender of the Response messages) has to request the PRACK. It’s not an automatic process and must be initiated with an Rseq header.

The value in Rseq is used by the user agent client when it creates a PRACK message. The user agent server is responsible for setting and incrementing this number.

The following 180 Ringing indicates that it expects a PRACK.


Upon receipt of this 180 Ringing, the user agent client must respond with a PRACK message. Of interest to this article is the Rack header. This header must contain the Rseq value sent in the previous 180 Ringing. Additionally, it will indicate the original INVITE session’s CSeq number. Look back at the INVITE in this call flow, and you will see a CSeq value of 1 (one). Therefore, the Rack will look as follows:

Rack: 1 1 INVITE


Next, the user agent server will send a 200 Ok for the PRACK. This tells the user agent client that the PRACK was received and processed.


For grins, I will now show you the 200 Ok for the original INVITE. Note that it does not have a Rseq header and 100Rel is not in the Requires header. Why not? That’s because this is not a provisional response. PRACKs are only sent for 1xx responses.


Mischief Managed

Before I close things out, I want to address the question I hinted at near the top of this article.  When does Avaya use PRACK?

While I honestly don’t know all the permutations, it appears that an INVITE from an Avaya endpoint will always indicate that it supports PRACK (Supported: 100Rel).  However, as you just learned, it’s the recipient of the INVITE that indicates if PRACK messages are required.

In the example above, the Avaya Modular Message voice mail server requests PRACK messages.  Additionally, PRACK is used when direct media is enabled.

There is a good chance that PRACK is used in other situations, but I am going to have to start up a few more traceSM sessions to learn where they show up.

That’s about all I really need to say about PRACK. I invite you to take a look at the RFC if you want to learn about any PRACK subtleties I might have missed, but for all practical purposes, I’ve said all that needs to be said. I hope you had as much fun today as I did. As is often the case, I learned something in the process of writing this article, and that’s always a good thing.

Understanding Avaya Aura SIP Registration

“Let’s start at the very beginning/a very good place to start/when you read you begin with A B C/when you sing you begin with Do Re Mi.”

I have always loved musicals, and Rogers and Hammerstein’s “The Sound of Music” is high on my list of favorites. Sure, it’s corny and far from historically accurate, but that doesn’t bother me in the least. I’m always willing to set aside any sense of reality for good singing, romance and adventure, and “The Sound of Music” has them all.

So … what does this have to do with unified communications? REGISTER, of course. Like Do Re Mi, you begin SIP with REGISTER.

This article is a continuation of the concepts I presented in A Close Look at Avaya Aura IMS Call Processing and An Even Closer Look at Avaya Aura IMS Call Processing, and I’d suggest you take a look at those before tackling this one.

Can you get SIP devices to communicate without REGISTER? Absolutely. In fact, when I teach my SIP class, the students put their SIP clients into point-to-point mode, which does not require REGISTER. This means that clients send SIP requests and responses directly to the other clients, not through a proxy. The clients can do everything all by themselves.

However, point-to-point without REGISTER has a serious downfall. The clients are required to know the IP addresses of all the other clients they wish to communicate with. While this is fine in a limited classroom environment, it becomes unwieldy after you grow beyond a handful of endpoints.

As an analogy, imagine having to know the IP address of everyone you wanted to send an email to. That’s the same problem you have if you don’t use REGISTER. It’s simply not practical.

The Tie that Binds

REGISTER associates a user’s identification, or Address of Record (AOR), with one or more locations. Note that I said locations. You are not limited to registering an AOR to a single device. Personally, I routinely register my AOR to a physical desk phone and multiple SIP soft-clients. Avaya Aura supports up to ten such registrations per user. That’s enough to make even the most device-crazy nerd happy.

You bind an AOR to an IP address with a Contact header.  For example, one of my soft clients might tell a SIP registrar that aprokop can be reached at with this Contact header.

Contact: Andrew Prokop <SIP:aprokop@>

Registrations are time-based and will eventually expire. This requires the client to periodically refresh a REGISTER with a new REGISTER. Actually, new isn’t the correct word to use for this. Subsequent REGISTER messages must contain the same Contact, To, From, call-ID and From Tag as the original registration. This allows the SIP registrar to know that it’s simply a refresh and not a new registration for the same AOR.

Note that CSeq will increment with each REGISTER sent.

Keeping Things Secure

I might tell my communications system that I am Andrew Prokop, but it would be foolish to trust me at face value. That’s why SIP allows a REGISTER to be challenged.

Before I go through a REGISTER challenge, allow me to define something known as a nonce.

Nonce stands for Number Once and is an arbitrary number used only once in a cryptographic communication. The recipient of a nonce will use it to encrypt his or her credentials. Number Once refers to the fact that encryption with this nonce can only be done one time. If someone were to sniff the LAN and obtain someone’s encrypted password, it won’t do them any good because it can only be used in a single transaction. It becomes stale and useless immediately after its first use.

A REGISTER flow is fairly simple and follows these steps:

  1. A user sends a REGISTER to the SIP registrar. For Avaya Aura, this is a Session Manager. The To and From headers contain the user’s AOR. The user specifies the number of seconds the registration should be valid in the Expires header. This value can be later raised or lowered by the registrar.
  2. The registrar returns a 401 Unauthorized response with a WWW-Authenticate header.  This header contains data that must be used to encrypt the user’s communications password. Specifically, it contains a nonce along with the name of the encryption algorithm that the client must use.
  3. The user sends a second REGISTER to the SIP registrar. This REGISTER contains an Authorization header. Within Authorization is the user’s encrypted password.
  4. If the correct password is received by the registrar, a 200 Ok response is sent to signify a successful registration. An Expires header may be present with a different value than what the user requested. This is the time the registration will be valid as determined by the registrar’s policies.

A registration is removed by sending a REGISTER with an Expires header value of 0 (zero).

In a picture, we have this.

Reg1Using the traceSM tool on an Avaya Aura Session Manager, I captured the following trace that shows a REGISTER, the challenge and a REGISTER with encrypted credentials.  Take a look at the headers, and you’ll see that they’re doing exactly what I said they would do.

Reg2 Reg3 Reg4


In the case of my daily work life, my various SIP devices will each send a REGISTER, be challenged and resend the REGISTER with the encrypted credentials. They periodically refresh their registrations to ensure that I am able to make and receive calls on all my devices until I am finished for the day.

Speaking of finished for the day, that’s about all I have to say about REGISTER. It’s not that complicated once you understand the basics. Just keep in mind that while registration isn’t absolutely mandatory, it enables a secure, scalable and easy to manage SIP solution.

… And these are a few of my favorite things!

Andrew Prokop is the Director of Vertical Industries at Arrow Systems Integration. Andrew is an active blogger and his widely-read blog, SIP Adventures, discusses every imaginable topic in the world of unified communications. Follow Andrew on Twitter at @ajprokop, and read his blog, SIP Adventures.