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:
- family - the family parameter of the
createEventProducer method of the
EventingFactory
- type - the type parameter of the createEventProducer
method of the
EventingFactory
- eventBody - the eventBody parameter of the
createEventProducer method of the
EventingFactory
- version - the eventVersion parameter of the
createEventProducer method of the
EventingFactory
- metadata-user - the value set through the setUser method of the
EventMetaData
- metadata-correlationId - the value set through the
setCorrelationId method of the
EventMetaData
- metadata-producerName - the value set through the
setProducerName method of the
EventMetaData
- metadata-producerVersion - the value set through the
setConsumerName method of the
EventMetaData
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:
- Call:CALL_OFFERED_FROM_CALLING_PARTY
- Call:OFFERING_CALL_TO_CALLED_PARTY
- Call:CALL_ALERTING
- Call:CALL_ANSWERED
- Call:CALL_ENDED
Platform Event
The following platform event represents a basic state change at the Avaya Breeze
platform level:
- Eventing:SUBSCRIPTION_EXPIRING - see the section "Subscription Expiration"
above for more information.
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.