Avaya Breeze™
Version 3.1.1 API

Package com.avaya.collaboration.eventing

The Eventing Framework provides the ability for a snap-in to generate notifications about "interesting events" that can then be received by other snap-ins with an interest in these events.

See: Description

Package com.avaya.collaboration.eventing Description

The Eventing Framework provides the ability for a snap-in to generate notifications about "interesting events" that can then be received by other snap-ins with an interest in these events. A snap-in that generates events operates in the role of an event producer while a snap-in that receives events operates in the role of an event consumer. A snap-in may operate as a producer at one point in its operation and operate as a consumer at another point. Conceptually the Eventing Framework operates in a fashion somewhat similar to Java Messaging Service (JMS) topics.

One important characteristic of the Eventing Framework is that the communication mechanism it provides results in a loose coupling of producers to consumers. This characteristic is achieved both by allowing producers to publish events without regard to which consumers may actually receive the event and by allowing consumers to indicate interest in receiving an event through subscriptions.

Another important characteristic of the Eventing Framework is its preferred version capabilities. Within Avaya Breeze, snap-ins of different versions can be installed and active, and one of the versions can be designated as the preferred version. A couple options available when subscribing for events allow a snap-in to indicate that it wants preferred version handling of the subscription. More information about the preferred version capabilities appears below.

Events are identified by their types, which are then organized into families. Events can be represented in a fully qualified form as family:type (for example, Call:CALL_OFFERED_FROM_CALLING_PARTY).

For example, notifications about the setup and termination of calls are a common type of event in Avaya Breeze. A snap-in wishing to receive call-related events would subscribe for any or all of the following event types in the Call family:

    CALL_OFFERED_FROM_CALLING_PARTY - a new call has been initiated by a calling party
    OFFERING_CALL_TO_CALLED_PARTY - a new call is being routed to a called party
    CALL_ALERTING - the called party's phone is alerting the party about the arrival of a new call
    CALL_ANSWERED - the called party has answered the call
    CALL_ENDED - the call has ended

The producer for call events is a snap-in named "Call Event and Control", which is provided with Avaya Breeze. As calls are processed through the system, the Call Event and Control snap-in operates as a producer and publishes all of the events listed above. A snap-in that has subscribed for these events is then notified of these events through an event listener that it implements.

General Purpose Framework

The Eventing Framework is not limited for use with pre-defined events. The framework is a general purpose API and provides substantial flexibility for passing events through it. A producer that makes use of the Eventing Framework simply needs to define an event by deciding what the event will contain. Required data for an event are an event family, an event type, and an event version number. The event family is a higher level identifier used to group like event types together. The version number allows a producer to define different versions of events, if desired. In addition to these required data elements, an event typically will include an event body (which is also referred to as the event "payload"). The payload is one or more pieces of data that carry information that would generally be of interest to a consumer. For example, the calling/called party and call ID are some of the pieces of data that are included with events from the Call family. The event body typically might contain a JSON representation of the data, but it might also be represented as XML. Or it might simply be a single-valued string. The format of the event body is determined by the producer; the Eventing Framework imposes no particular requirements on the structure, other than the data must be representable as a string.

Of course for a consumer to make use of an event -- and in particular, the event body -- the definition of the event must be known by the consumer. An event catalog exists for this purpose. Administration of the event catalog is done through the Avaya Aura® System Manager. The event catalog provides a place in which event definitions may be stored (for this release it is recommended that the catalog be used only for events specifically designed for use with the Avaya Engagement Designer -- see the section "Other Events" below for more information). However, the Eventing Framework does not require an event to be present in the catalog for it to be published by a producer and delivered to a consumer. No validation against the event catalog is done for events that pass through the framework. This means that as long as a producer and a consumer have a common definition of an event, it can be passed through the Eventing Framework. Further, the Eventing Framework does not require advance knowledge about an event before it accepts subscriptions for or publication of an event. All that has to happen for an event to be passed from a producer to a consumer is this. The consumer must subscribe for the event by specifying a family, an optional type, and possible additional filtering data (discussed below). A producer must then publish an event that matches the family, type, and additional filtering data. The published event is then "resolved" by matching it to the subscriptions of the consumer, and the event is delivered.

Sample code that illustrates these capabilities are available in the com.avaya.collaboration.eventing.sample portion of this Javadoc.

Filtering

Ideally a consumer should receive all events for which it has interest and no events for which it does not have interest. This is the purpose of the filtering capabilities provided by the Eventing Framework. For producers, in addition to the event data already mentioned (family, event type, version, and event body), additional data elements called "metadata" can be provided as part of an event publication (the EventMetaData class is used to provide this data during publication). The intent of these metadata fields is to allow a consumer to provide a filter at subscription time as a way of excluding events for which the consumer has no interest. The following general purpose metadata can be provided by a producer:

    user
    correlation ID

The meaning of the data provided for these elements is determined by the producer and they are all optional. The purpose of the user element is to provide a value that represents a user associated with the event, if there is a meaningful value for such a user. The correlation ID is intended to hold a value that can be used to associate the event with some other prior interaction between the producer and consumer. Additionally, arbitrary key/value pairs of strings can also be provided using the setValue method of the EventMetaData class. The EventMetaData class also allows the producer to specify the producer name and version; at this time no filtering is possible against these values.

A consumer can filter on these values through use of the EventFilter class, which has the following elements that correspond to the metadata values on the producer side:

    user - used to filter against the metadata user
    correlation ID - used to filter against the metadata correlation ID
    criterionMap - used to filter against the metadata key/value pairs
    criterionIgnoreCaseMap - used to filter against the metadata key/value pairs using a case-insensitive match on the values

An additional element called "serviceProfile" can be specified in the EventFilter. A value specified here will be matched against the service profile configured in Avaya Aura System Manager for the user given in the metadata (if any such service profile has been configured for the user).

The option specified through the method setMatchConsumerToUserViaServiceProfile of the EventSubscriptionAttributes class also includes an element of dynamic filtering based on user and service profile.

"On behalf of" Subscriptions

When specifying the attributes of a subscription, the framework allows a consumer (snap-in) to specify a snap-in name and version using the methods setConsumerName and setConsumerVersion of the EventSubscriptionAttributes class. The purpose of these methods is to allow one snap-in to subscribe on behalf of another. Typical use cases for this type of action might be when a group of snap-ins are organized in a parent/child relationship or when one snap-in acts as a broker for other snap-ins. In such cases it is useful for the "parent" or "broker" snap-in to include information about the "dependent" snap-in on whose behalf the subscription is being made. Setting the consumer name and version has no effect on which snap-in receives the event; events are always delivered to the subscribing snap-in. It simply acts as a form of "documentation" so that an arriving event can be easily matched to the dependent snap-in. It is interesting to note that these methods are used internally by the Avaya Engagement Designer snap-in to subscribe for events on behalf of workflow definitions.

Preferred Version

Many areas of Avaya Breeze support a form of routing of requests and/or data to snap-ins that uses preferred version routing. Essentially, the functionality makes it possible, when multiple versions of a snap-in are installed, to indicate a preferred version in Avaya Aura System Manager as the one that should be considered the "active" one for most operations.

The Eventing Framework supports preferred version routing at two levels:

The "deliver to preferred version" option behaves as follows. Assume there are two or more versions of a consumer snap-in installed on the system. Each of them has subscribed for the same event. When the deliver-to-preferred-version option has not been selected, a published event that matches these subscriptions will result in delivery of the event to each version of the snap-in. However, if they all have subscribed using this option, only a single event will be delivered and it will be delivered to the version marked as preferred. If no version is configured as preferred, then delivery is to the latest version.

The "populate consumer preferred version" works in conjunction with the methods setConsumerName and setConsumerVersion of the EventSubscriptionAttributes class as follows. Assume that a parent or broker snap-in (as described in an earlier section above) creates two or more subscriptions that are identical except for the consumer name and version settings. Further they specify the same snap-in name but different versions of the snap-in. If the populate-consumer-preferred-version option has not been selected, a published event that matches these subscriptions will result in the delivery of multiple events, one per version. However, if the populate-consumer-preferred-version option has been selected, only a single event will be delivered and the version number of the preferred version will be the value provided in the event. If no version is configured as preferred, then the value will be set to the latest version installed on the system.

Replication of Subscriptions

The Eventing Framework replicates subscriptions throughout a cluster. This is useful for scenarios where activity on a single node -- perhaps an HTTP request arriving at a snap-in -- triggers the snap-in to subscribe for an event. The replication of the subscription throughout the cluster then ensures that a matching event published on any node will be delivered to the snap-in on that node, thereby creating a form of distributed processing of events.

It will probably be of no surprise to realize that there are a class of events where the same subscriptions are most conveniently created on all nodes. The most obvious example of this type of subscription is for those subscriptions that need to be created during the start up of a snap-in. The Eventing Framework makes this action convenient by automatically detecting and eliminating identical subscriptions, whether the subscriptions are made across nodes or within a node. Further, identical subscriptions have the same subscription ID both across nodes and within a node. A side-effect of detecting and eliminating identical subscriptions is to extend the expiration time of the original subscription as if the renew method, described in the section "Subscription Expiration" below, was called. Exactly what constitutes identical subscriptions is covered in the next section.

Creating identical subscriptions on different nodes, in practice, is generally straightforward. Snap-ins that use common code and data to create subscriptions will almost naturally create identical subscriptions that resolve to a single subscription across nodes. However, there is an area to be careful with in this respect. Subscriptions provide the ability for a snap-in to provide consumer private data as part of a subscription. The consumer private data is any serializable Java element that a snap-in finds useful to have returned to it when an event is delivered. As will become apparent in the next section, subscriptions that are created with different values for their consumer private data will exist as distinct subscriptions. While this mechanism provides a great deal of flexibility, it also presents a possible pitfall. If the consumer private data of a subscription happens to include any pieces of data that vary on different nodes, subscriptions that are intended to be identical across nodes will end up being different. For example, the inclusion of a node ID in consumer private data would cause this kind of difference to be present. So it is important to keep this possibility in mind when deciding what to include in consumer private data.

The processes of subscribing, unsubscribing, and refreshing subscriptions are not performed as atomic operations. Therefore, if a subscribe takes place on one node in a cluster for a subscription around the time that an unsubscribe is taking place on another node in the cluster for the identical subscription, there is no guaranteed order in which they will be processed. This behavior generally should not cause a problem, since nodes within a cluster are homogeneous and an installed snap-in will exhibit the same behavior in the same timeframe on all nodes in those cases where multiple nodes are subscribing/unsubscribing for identical subscriptions. However, network propagation delays and natural variations in the timing of when snap-ins perform the “same” operations could result in non-deterministic results if subscribes and unsubscribes are performed repeatedly in a short period of time.

Identical Subscriptions

Subscriptions are considered to be identical if there are no differences in the values specified in the attributes of the EventSubscriptionAttributes class used to create the subscriptions. This means, for example, if one subscription is created for the Call family where no types are set in the EventSubscriptionsAttributes and another subscription is created with the same attributes except that a specific type is specified, the two subscriptions are not identical and two subscriptions will be created in the Eventing Framework. Similarly, if the correlation ID of a subscription filter is left as null in one subscription and it is set to an explicit value in another with all other attributes being the same, the subscriptions will exist as different subscriptions.

A subtle implication of this definition for identical subscriptions is that subscription identity is not affected by time, even if multiple subscribes and unsubscribes take place over a long period of time. Most people probably would find this characteristic to be counter-intuitive. But this characteristic of subscriptions is an important part of the algorithm used to match and eliminate duplicates across nodes.

Another implication of this definition is the following. Generally, one published event will be delivered to a consumer as one event per subscription that matches the published event. Therefore, a consumer may have multiple events delivered for a single publication of an event. For example, in the case where a correlation ID has been left null in one subscription and explicitly specified in another with all other attributes being equal, a published event matching the explicit correlation ID will also match the "wild card" case (a null correlation ID in the filter) and the event will be delivered twice.

There are three important exceptions to this behavior. The first is the event notification reduction that occurs as a result of the preferred version functionality described above.

The second is event notification reduction that occurs with the "match consumer to user via service profile" option (see the setMatchConsumerToUserViaServiceProfile method of the EventSubscriptionAttributes class). In this case the dynamic determination of consumer version will result in the elimination of duplicate events, if the only differences between events is in the version that gets determined dynamically.

The third involves the way event types are handled. When multiple subscriptions differ only in the list of events that are specified in the subscription attributes, only a single event will be delivered, even though multiple, distinct subscriptions happen to exist within the Eventing Framework. So, for example, assume that subscription S1 specifies no event types and subscription S2 specifies event type T1 -- and the subscriptions are otherwise identical. A published event matches S2, which means it also matches S1, since S1 specified no types (meaning "match any type"). However, the Eventing Framework will reduce the two matches to one event delivery at the time of delivery, since they differ only in the event types they specified.

Publishing Events through HTTP

The Avaya Breeze by default includes a special snap-in called the EventingConnector on certains types of clusters. Among other things, this snap-in provides an HTTP interface into the Eventing Framework for publishing events. The interface exposes the majority of attributes that can be specified when using the Eventing Framework Java API. The format of the URL is:

    https://securityModuleIP/services/ EventingConnector/events

and it accepts the request as a post method using an encoding type of "multipart/form-data".

The following parameters are accepted and correspond to the "producer" portion of the Eventing Framework Java API as indicated:

Additionally, arbitrary parameters can be specified as "metadata-keyname", where "metadata-" is the literal "metadata-" and keyname is an arbitrary string (characters typically known to be special characters are best avoided). Parameters of this type are treated as key values pairs, where the key is formed by stripping "metadata-" from the parameter name and the value is the parameter value. These key/value pairs are then added to the EventMetaData object using the addValue method.

Example uses of this interface are provided in the com.avaya.collaboration.eventing.sample portion of this Javadoc

Special Use Events

One family of special use events are defined in the event catalog that are not available for general use by consumers. The events are those belonging to the CallIntercepted family. Although these events might reasonably be assumed to be generated by the Call Event and Control snap-in mentioned above, they in fact are only used internally by the Avaya Engagement Designer. Consumers that subscribe for these events will never receive any notifications of these events.

Subscription Expiration

As a means of clearing out orphaned subscriptions (subscriptions made by a snap-in that is no longer installed), subscriptions expire after about 8 to 9 hours. Therefore, snap-ins will need to renew subscriptions periodically. To make this process easy, a "SUBSCRIPTION_EXPIRING" event from the family "Eventing" will be sent to consumers shortly before expiration. Then, snap-ins are expected to renew the subscription by calling the "renew" method of the EventingService class upon receipt of this event to keep the subscription active. The SampleEventListener sample includes code showing how this is done.

Please note that the expiration functionality of the EF is for the purpose of eliminating subscriptions that have become non-functional due a snap-in being unable to receive a matching event. This condition can arise, for example, if a snap-in becomes non-functional or it has been uninstalled. A snap-in should not rely on this functionality to clean out subscriptions that it no longer needs; instead, unneeded subscriptions should be removed through an explicit "unsubscribe" near the time they are no longer needed.

There is no guarantee when an expired subscription will be purged from the system or even if an expired subscription will be purged. Therefore, if a snap-in relies on the expiration mechanism to remove unneeded subscriptions, it is possible that unneeded subscriptions may unnecessarily exhaust the resources available for holding subscriptions.

Additionally, given the imprecise timing when subscriptions may be purged, if a subscription is allowed to expire and then an identical subscription is subsequently created (essentially a re-subscription), it is possible that the pending purge of the expired subscription might cause the re-subscription to be purged.

Therefore, when the SUBSCRIPTION_EXPIRING event is delivered to a snap-in, the subscription should be renewed to ensure the desired behavior of the EF. An explicit unsubscribe of the subscription upon receipt of this event is also acceptable. Any other use of this event may lead to unexpected results.

Common Events

Call Events

A representative list of call events are:

Platform Event

The following platform event represents a basic state change at the Avaya Breeze platform level:

Other Events

As mentioned above the Eventing Framework supports the use of custom events by producers and consumers. Custom events do not need to be registered with the Eventing Framework, nor do they need to be present in the event catalog. All that is needed is for one or more producers and one or more consumers to use a common definition of an event, and that event can be passed through the framework from producer to consumer. In fact for this release of Avaya Breeze it is recommended that event definitions only be placed in the catalog if they are intended for use with Avaya Engagement Designer. This is because in this release events that are present in the catalog will appear in the designer, even if they have not been designed for explicit use with the designer.

Useful Constants

A set of constants useful for manipulating events are provided in com.avaya.collaboration.eventing.families for certain predefined events.

Since:
3.0
Avaya Breeze™
Version 3.1.1 API

Copyright © 2016 Avaya. All Rights Reserved.