Since the arrival of the Asterisk REST Interface (ARI) requests have been made to allow for event type filtering capabilities. Consumers have wanted a way to make it so Asterisk only sends a specified subset of events to the connected application. Guess what, the wait is finally over! Starting with Asterisk 13.26.0, and Asterisk 16.3.0 this feature will now be available.
Use Case
It’s probably easy to imagine a use case for this feature, but I’ll briefly explain one anyway. A generic scenario would be a simple ARI application which listens on the connected websocket for events. This application only needs to monitor for certain events. When an event that it’s interested in arrives into the application it then triggers some action. Let’s say this application really only cares about two event types. That means the majority of received events are non actionable events, thus useless to the application. Depending on which event subsystem the application needed to subscribe to in order to receive said events there’s potential for a lot of unneeded network traffic. It sure would be nice if there was a way to limit that communication!
Event Subscriptions
Speaking of event subscriptions why do we need this added filtering? Can’t we just subscribe, or not subscribe to a particular subsystem of events? Yes you can, and it will continue to work that way. As a matter of fact, in order to receive a particular event type you’ll still need to subscribe to the appropriate subsystem, or you won’t receive the event even if it is in your allowed list filter. Conversely, the added filtering though is just that, a filter not a subscription. It allows for refined control on top of any event subscriptions, or events received outside of subscriptions.
Event Filtering
Okay enough of the why and onto the how. First, it should be said that not designating an event filter maintains current behavior. You can add an event filter for your application using the following path:
PUT /applications/{applicationName}/eventFilter
You use the message body (a JSON formatted object) to specify the type of filtering (allowed and/or disallowed), as well as the event types to be filtered. Here’s what the basic structure should be for an “allowed” filter (substitute the bracketed <EventType> for a valid event type):
{ “allowed”: [ { “type”: “<EventType1>” }, …, { “type”: “<EventTypeN>” } ] }
Including items in the allowed list means only those event types specified are sent, from Asterisk, to the application. For example:
{ “allowed”: [ { “type”: “StasisStart” }, { “type”: “StasisEnd” } ] }
This means that Asterisk will only send the “StasisStart” and “StasisEnd” events to the application. The application should not receive any other events outside of those.
Similarly, here is the basic structure for a “disallowed” filter:
{ “disallowed”: [ { “type”: “<EventType1>” }, …, { “type”: “<EventTypeN>” } ] }
Including items in the disallowed list means all event types are sent, from Asterisk, to the application except those specified. For example:
{ “disallowed”: [ { “type”: “StasisStart” }, { “type”: “StasisEnd” } ] }
This means that Asterisk will not send the “StasisStart” or “StasisEnd” events to the application. It will continue to send all other event types though. Not really sure why you would want to, but you can even have both an allowed, and disallowed list at the same time:
{ “allowed”: [ { “type”: “<EventType1>” }, …, { “type”: “<EventTypeN>” } ] “disallowed”: [ { “type”: “<EventType1>” }, …, { “type”: “<EventTypeN>” } ] }
Note though, that if you do this, event types found in the disallowed list override those same event types found in the allowed list. Meaning if an event type is found in both lists the event will still be disallowed.
Both list types can be reset (made emptied), or overwritten with a new filter by issuing another PUT command with an empty, or new dataset. Setting a list type to empty restores default behavior for that list type. One other thing to probably mention is that the object keys, and event types are case sensitive.
Finis
Hopefully this has been enough for you to have gained a basic idea on the why, and the how of event type filtering using ARI. It’s possible for this functionality to be expanded, so if this seems like something useful be sure to let us know. Also for the most current up to date documentation be sure to check out the wiki.
3 Responses
Hey Kevin, this is so helpful!
I now won’t need to filter events on client side anymore, which improves the performance of my client a lot! Really looking forward to 16.3.0
Thank you so much 🙂
Lukas, thanks for the feedback. Glad to hear it’s going to help improve things for you!
Great very interesting to read this….. thanks for sharing.