RHQ 4.9
Alert Sender Plug-ins
The idea is to let users write and deploy new types of AlertNotification senders e.g. Microblog (Twitter), Mobicents, Trouble-Ticket-System, Irc, AIM, yet unknown 3rd party system, custom operations on resources, starting of cold-standby boxes etc.
With the current implementation this is very hard to do, as it involves tons of work and is error prone.
In the future we want to allow the user to deploy a jar file with some java classes and a plugin descriptor (like the one for the agent plugins). The system will deploy the plugin, populate the system-config table with the provided defaults1 and also generate the GUI elements from the meta data in the plugin descriptor.
Current situation
The following list shows the tasks that need to be done in order to install a new Alert Sender:
-
Enhance DB Schema + enhance / create additional domain objects - Add one column per alert sender type type on RHQ-ALERT_NOTIFICATION - Add one or more columns per alert sender type type to RHQ_ALERT_NOTIF_LOG
-
add new AlertNotification Type domain class - new AlertNotificationLog Type
-
Enhance system-configuration for defaults (like e.g general availability of the new service, global configuration (this includes backing beans + entries in system-config table )
-
Enhance AlertManagerBean - call the right sender
-
Enhance the alert template UI - fields for new Alert Sender - Backing beans – currently this needs writing many many JSP/struts items
-
Enhance AlertNotificationManagerBean - methods to set/get alert notification properties
Pluggable architecture in the future
Assumptions
This design document currently makes the following assumptions:
-
Alert Sender Plugins will be deployed for us by the server side plugin handling and the XML plugin descriptor will already be parsed and provided via JAX-B classes to us
-
System preferences for an alert sender plugin (see below) will be handled by the server side plugin container. It will tell us how to get the data (i.e. inject or have some special keys to look data up in the system preferences database table
-
Each AlertSender (plugin) must have a unique name.
Requirements
The new architecture needs to support the following core use cases:
-
Deploy a new alert sender plugin into the system
-
Update an existing alert sender plugin
-
Set up a global configuration for a sender plugin, that all senders will use (e.g. smtp server to use)
-
Set up sender (group) templates: lists of alert senders, that can later be re-used to set up notifications for alerts
-
Set up alert notifications from selecting senders or by selecting templates and customizing them
-
There need to be alert notifiers that get all alerts and can react on them.
-
There must be auditing information provided for alerts fired (with success / failure indication)
-
There must be auditing information provided about the user who created an alert definition
-
The UI must support mini-perspectives, so a user can supply facelets for complex GUIs
-
The UI must support being generated from plugin-supplied meta data.
-
User must be able to use an alert sender multiple times per alert definition (e.g. microblog sender sending to twitter and then microblog sender sending to laconi.ca)
-
Order of alert senders needs to be configurable by users
GUI mockups
Those are for explanations, not necessarily to show how the UI should look in the future
Alert Definition Page
This page is used to show the alert conditions and to set up notifications for this alert. The upper part is used to show the conditions and the lower part to set up the notifications.

To set up notifications, the user clicks on Add new... from where he can select new senders. This is shown below. When senders are defined, they are listed in a scroll list, where each line represents one sender. The text identifies the sender and also contains additional (sender specific) information on the properties of this sender. To view the detailed data of a sender can be viewed and changed by pressing the View/Edit... button. Selected senders can be removed from this list via selecting it in the first column and pressing Remove selected...
Senders in the list will be executed in top to bottom order. To change order, the user can use up and down buttons to move the selected line.
For all buttons JavaScript will enable and disable according to what makes sense.
The configuration will be persisted and supplied to an AlertSender instance.
This lower part of the page can also be used to initially select sender templates from within the Administration menu.
Add new dialog
This dialog is shown when the user clicks on Add new... on the AlertDefinition page. The top of the page shows a selector for Sender or template. Depending on this the drop down lists senders or templates; this drop down is empty as default selection. If a sender or template is selected, the lower part will show the respective information as shown on the next screen shots:
Sender case:

When a sender is selected, the system will show the properties of this sender from metadata (see also below) and the user can fill them in. When she is done, she can click on OK to get back to the AlertDefinition page where the newly selected sender will be appended to the list of senders (if this UI is called from the ,Create template' page, the user will return back to the ,create template' page.
Template case:

If a template is selected, the system presents the list of senders that make up the template, which is view only. The user can accept by clicking OK, from where control is returned to the AlertDefinition page. There, the user can edit individual senders in the list of senders.
System preferences

The system preferences in the administration menu will (need to) get a new section for the alert plugins (and actually other server side plugins too). The data of the sections will come from a configuration within the deployment descriptor and will automatically be rendered by the server side plugin container. This container will also provide the configuration object to our AlertSenderManager.
Important requirement here is that the preferences of one Plugin Container Type are all grouped together.
Code changes
-
Create new AlertSenderManager that manages all aspects around individual plugins
-
Give list of tabs for the Alert definition page.
-
Give the properties for a certain tab. This includes the individual fields
-
Takes the result of the UI for changes in the configuration (CRUD) of AlertNotification
-
Creates new AlertSender objects and injects system preferences for this AlertSender plugin, the Alert and the AlertNotification data
-
Create abstract class AlertSender
-
Subclasses of this need to implement the send() method that does the actual sending
-
-
Provides methods for initialization via AlertSenderManager
-
AlertManagerBean:fireAlert(): remove creation of AlertNotificationLog
-
AlertManagerBean:sendAlertNotification()
-
loop over AlertNotification for this alert
-
Get new AlertSender from AlertSenderManager
-
Send via AlertSender and capture return
-
persist return value as new AlertNotificationLog item
-
-
Change AlertNotification
-
Properties per AlertSender are stored in a configuration (flat, list of simple properties)
-
Name of the AlertSender (= its type) is stored in a separate column
-
-
AlertNotificationLog
-
add a type column to identify the AlertSender type
-
add a generic varchar column that holds the whole message for the given type and alert id.
-
Remove the relation to Alert, so that the NotificationLog is not deleted when the alert is deleted
-
-
UI
-
List of defined senders must be created dynamically from recorded data
-
-
Struts based UI needs to be ripped out and replaced by a JSF based one, that fits into the existing JSF gui – this needs to be coordinated with the perspective service.
Relation to other services
The AlertSenderManager must be able to query the server side plugin container to obtain a list of deployed plugins plus their meta data.
Deployment Descriptor
The deployment descriptor is defined in an XML Schema This Schema extends rhq-serverplugins.xsd so that the Server side plugin container can actually deploy the plugin.
The descriptor will look like the following:

The global alert-plugin element will have two children for configuration information of the preferences (plugin-configuration) and of the alert definition UI (alert-configuration). Other elements are
-
short-name: Name of this sender as it appears in the UI
-
plugin-class: name of the class that implements the abstract AlertSender class
-
custom-ui: this is not yet active and will (hopefully) be used to allow for custom UI snippets in case the RHQ-configuration-based UI is not enough.
Migration scripts
As we are already having customers that are using alerts in RHQ, we need to ensure existing information in the database is not lost. This migration can be done via dbupgrade-scripts
Maven setup for plugins
Each plugin will live in its own maven subproject - standard maven conventions apply.
Required QE
-
Ensure that after update, existing alerts continue to work. Create some alerts for subject / role, then do an upgrade to the new RHQ version with the pluggable alert senders and check that those alert definitions still exist and still fire
-
Deploy a new alert sender plugin and make sure
-
Its system preferences show up (if defined by the plugin)
-
Its system preferences are persisted (if defined by the plugin)
-
It appears on the list of notification tabs in the alert definition UI
-
Data can be entered on the notification tab in the alert definition UI and is persisted
-
Alerts are actually sent through this alert sender
-
-
Alerts can be sent to a combination of senders (e.g. roles + subject + Microblog)
-
Check RHQ_ALERT_NOTIF_LOG table to see that alerts are recorded there
-
Re-deploy an (unchanged) alert sender plugin and make sure the checks from above all give valid results.
Documentation
We need to provide two kinds of documentation for users and plugin developers
User documentation
Existing user documentation must be updated with information on how to deploy a alert sender plugin4. The sections on system preferences and the alert UI itself need to mention that the number of tabs and preferences are not static and can change depending on the plugins deployed.
Depending on the (new) alert sender plugins we deliver in a product, documentation needs to be written for them as well.
Developer documentation
We need to write developer documentation on how to write plugins: describe the code contracts and the plugin descriptor.
Open Questions
* Do we really want to remove AlertNotification Log information? This could be important for auditing purposes and should perhaps not be deleted when an alert or resource is deleted. I rather think we should have them in some „append only" table and after some admin-definable time remove the oldest ones5.
-
Mazz writes that the plugin name of the server plugins must be unique across all plugins - should this per plugin type (alert, content, ...)? Also will plugin author etc. be provided by the generic xsd?
-
I've used the terms AlertSender and AlertSenderManager – much of this is what is currently the AlertNotificationManager.
-
Can I use the generic plugin lifecycle listener to e.g. log into an irc server at plugin start and log out at termination? What about re-logging in in case of connection drop?
-
Does the page that lists notification senders (lower half of the AlertDefinition page above) need buttons to reorder the senders?