GR:Gravity/Event Management

From Remain Software
Jump to navigation Jump to search
Translate this page

Gravity Event Management

Event management lies at the hart of Gravity's user collaboration support, and is one of the architectural starting points of Gravity.

Events

In Gravity, Events are the digital representation of User actions. For example, when you create an Item, Gravity will automatically create an Event and send it to the Gravity Event Manager. The Event Manager will deliver it to interested Event Handlers. There are also system generated events. For example there is a "clock" service that sends clock events. These enable event managers to run periodic tasks.


Gravity event.png


Below we explain the basic concepts and then follow-up with a "how-to".

Topics

The Topic tells you why the Event was triggered. It is an hierarchical description of the Event. A typical Topic would be 

gravity/wm/item/added

You can tell from the Topic what has happened. In Gravity WorkManagement an Item was Added. In theory, you are able to listen for Topics in the following way: 

gravity/*              (Listen to all Gravity Events)
gravity/wm/*           (Listen to all Gravity Events send by the Work Management Service)
gravity/wm/item/*      (Listen to all Item events send by the Work Management service within Gravity)
gravity/wm/item/added  (Listen only to this specific Topic)

However, as of today we only support the last form, the fully qualified topic.

Event Handlers

Once you have set your eye on an interesting topic, then you have to decide how you would like that information to be delivered to you. This is where event-handlers come into play.

Event Handlers listen to one or more specific Topics and are capable of processing an event in a way that is event-handler specific. Simply said, an event-handler will do something with an event in a way unique to that event-handler.


Using the previously fired event as an example, we can ask the event management to send an e-mail when this event occurs. To accomplish this the topic 'gravity/item/added' first has to be connected to the 'Notification EventHandler Service'.

Once connected the topic will be tracked by that event-handler service. From this point on Gravity event management will see to it that every time an item is added the 'Notification EventHandler Service' gets the opportunity to act on this event.

So now when anyone creates an item you will be notified of this fact by a pop-up window, which fades a way after a few seconds.

Event-handlers are capable of tracking any available topic, but as already mentioned, logic dictates that an event-handler can only handle event information in a way it was built for.

Connecting an Event to an EventHandler

First of we need to bring the 'Event Management' perspective to the foreground and if necessary the view 'All Topics' (which can be selected from main menu Gravity → Show View → Other – All Topics).

Selecting a topic

Gr em-1.png

In the 'All Topics' view (right pane) click on Work Management Service to expand and reveal Work Management Service topics, in the 'Event Management' view click on Event Handlers to expand and reveal available topic event handlers, a view similar to the one below should be displayed;


Gr em-2.png


Connecting a topic to an event-handler

To connect a topic to an event handler the topic needs to be dropped on the event-handler of choice, in the example below, the topic 'gravity/wm/item/added' will be dragged and dropped on the Notification EventHandler service:


Gr em-3.png


As a result of the drag and drop action the Notification EventHandler service will have the topic 'gravity/wm/item/added' included in its Tracked topics list.


Gr em-4.png


Creating the Text to Display (Templates)

You want to control the information you receive in the notification. For this you need to create a template that converts the information in the event to something readable.

Take it for a spin

Unless configured otherwise the tracked topic will be processed by the Notification EventHandler service every time an item added event (represented by the topic 'gravity/wm/item/added') is brought into existence. In our example a notification will be displayed as soon as a this event is processed by the event manager. It can take a couple of minutes for the event manager to react. This is because of the a-synchronized nature of the handling. You will see something like this.


Gr em-4b.png

Configuring a tracked topic

If you are not happy with the default processing characteristics of a tracked topic then you can alter the behavior of a tracked topic by editing and saving available tracked topic details. Default topic attributes always allow you to change the 'when' and 'how long' of a tracked topic.


To configure a tracked topic detail, 'double click' on the tracked topic of interest (under Event Handler management) and click on the 'Delivery Settings. You may need to adjust the existing view layout to sufficiently accommodate the new Topic Details' dialog, but if you do some view extending left and right Topic detail information should come in to picture.


Gr em-5.jpg

The following attributes directly influence the way event-management treats gravity events. Gravity event-management will use these attributes to decide when to pass an event on to an event-handler:

  • Always deliver/On Behalf User/Group
  • Active
  • Active From
  • Active Until
  • Delivery Requirement
  • Time to Live

The attribute 'Always deliver' denotes that User/Group information will NOT be used to determine who should bereceiving the information. The 'On Behalf User/Group' enable specifying that the selected user or the users belongong to the selected group will be notified. The User/Group must be related to the document in case of a document related topic.

The attribute 'Active' denotes the current state of the tracked topic. If the state is switched to in-active, de-flagged, then the topic related event will not be delivered to the event-handler service. De-activate a tracked topic only if you temporarily do not want to receive events of this kind. If you decide that you never want to receive these events then it is advised that the tracked topic be removed from the 'Tracked Topics' list (right mouse click on the tracked topic and select delete).

As long as the 'Active' attribute is flagged (true), a tracked topic event is passed on to an event-handler based on the values set in 'Active From', 'Active Until' and 'Time to Live'. If the values have a default value of -1 then an event will be delivered to a user, any time, any day for the period that the user is logged-in to Gravity.


Setting Active-From & Active-Until

Both the Active-From and Active-Until fields can be entered directly or can be graphically manipulated by clicking on the icon located at the end of the field. Initially the fields are day-time bound and only a time period between 0 and 24 hours can be set as illustrated below. Here an event delivery time setting has been chosen starting at 8 am and ending at 5 pm. For both fields the setting was done by clicking the time related icon (encircled in red) and moving the clock arms to the desired time.


Gr em-5b.jpg

The Active-From and Active-Until fields support a number of time and date notations that help you set the required time and or date constraints. As we have seen the default time based values have the net result that an event will be delivered in a daily 24 hour setting. If this does not cover your requirements then you can switch to a date or date & time setting by toggling the larger icon beside the Active-From/Until field.


Gr em-5c.jpg

Toggling the icon changes the smaller in-field icon and sets the field to be sensitive to the chosen time-date type. There are 3 selectable time-date types: time only, date only and time & date.

Be aware that if a value has been set in one time-date type then toggling to another type will automatically transform that value to become compatible with the newly chosen time-date type.

Setting Delivery Requirement

If you don't mind missing an event every now and then, then you can change the attribute Delivery Requirement from the default value 'Required' to the value 'Optional'. You would set this option only in the situation where it is not relevant that you receive all events emanating from an event service. With this option Gravity event-management will set an event to ´Unhandled´ if an event cannot be delivered because the event-handler service is in-active or because the user is not logged-in.

Setting Time to Live

Event expiration, how long an event stays in the system, is determined by the 'Time to live' attribute. When an event expires it is removed from active event-management by being marked as 'Unhandled'. The default value of -1 denotes that an event will never expire, meaning that Gravity event-management will try to deliver an event to an event-handler for as long it takes (of course as soon as an event is delivered it no longer partakes in event delivery).


In the example below the user has opted for a Time to Live of 3 days indicating that the user has no desire to be notified about a log-in event that occurred more than 3 days ago.


Gr em-5d.jpg

Setting Topic Parameter Description

Topic parameters are key value pairs that can be passed on to the event-handler service. An event-handler service can retrieve and use the parameters as context for a delivered event.

Viewing the state of events

To see which events have been processed or still have to be processed, expand the 'Events' section just below event-handler service name. This will show the event-management event-handle types, of which each will display a total number of events processed or to be processed. For the example Notifcation EventHandler service the following totals are displayed:


Gr em-6.jpg

In total, the service has zero events that have expired, 3 events processed by way of a window pop-up and and zero events that could not be delivered (unhandled). Double clicking on an event type will display a detailed list of involved events.