ATG Portal Alerts
Document Objectives
- Describe the Portal Alerts Architecture
- Describe the Alerts preferences and settings
- Describe how to issue an Alert
- Describe how to write an Alert Source Gear
Portal Alerts Architecture
Overview
The Alerts system is a database based message system. An alert is a message targeted for a specific principal. A principal may be either a user, a community, an organization or a role. As such an individual user will receive alerts sent to any principal which includes them.
Gears send alerts into the system, perhaps as a result of a user doing something with the gear; adding a document or changing something or perhaps as a result of some external event; a stock price change or the temperature rising above 100F.
These messages are dispatched via JMS to the scenario server and from there on to the AlertMgr which stores them in the database and sends off any email notifications.
From there a user 'sees' their alerts in the portal alert gear which will display the events which are in the database. They may also have receive the alert via email or some other channel such as SMS.
From GearMessage to AlertMessage
Although 'Alerts' are actually stored in the database they start off as JMS
messages. A JMS message is issued by the GearMessagePublisher component in response to a
call to it's writeMessage() method. This method serializes the
original 'gear message bean' into the body of an 'Alert message' which is then
dispatched via the JMS implementation to the ScenarioManager component. The
message only proceeds from this point if a scenario has been written to dispatch
the message further. Each of the shipping gears which issues events also
provides a Scenario to dispatch the gear alerts to their targets.
Here is the Calendar gear's Alert dispatch scenario:
If a scenario has been written and enabled, the 'Send Alert' actions are performed by the atg.portal.alert.SendAlertAction class dispatching the message to the AlertRouter with recipient information.
When the AlertRouter receives the call it dispatches a JMS message with JMS Type '/atg/portal/alert/AlertTargetMessage' to the sqldms:/atg/portal/alert/AlertQueue destination. There the AlertTargetMessages wait to be processed by the AlertMgr.
Alert Message Processing
AlertMgr is a sink for sqldms:/atg/portal/alert/AlertQueue. As this is implemented via a SQLJMS queue this processing is now happening asynchronously to the user whose actions originally fired the event.
First AlertMgr adds the Alert tothe AlertsRepository using the AlertRepositoryManager then the AlertMgr rifles through the users for whom the alert was intended and ensures that the alert channel handlers are called for each active channel for each user. Enabling isLoggingDebug on the AlertMgr component will illuminate this process.
In addition to 'Alerts' being stored in the database, they may also be dispatched to one of a number of other 'channels', only 'Email' is available in the installed product.
So now our Alert is in the repository and the auxiliary channels have been fired off. What happens next?
Viewing the Alerts
For a portal user to view alerts the community administrator must have added the Alerts gear to a community page.
The administrator can specify which alerts will be displayed in the Alerts gear via the gear instance configuration. For more details on this please see the Alert Gear section below.
|
The alert gear is based on the GetAlertsTag the source code for which is provided in the Portal.alert module's src folder. Basically it just goes off to the AlertMgr and gets a list of all the alerts for this context (the user and the user's communities). In addition, the alert gear jsp pages themselves may filter the messages depending on the gear's instance configuration, such that users only see messages addressed to one or all of the target principals groups as the source for alertShared.jsp from the same module shows. |
 |
Main Components
The key components for Alerts are in the /atg/portal/alert folder and can be viewed here http://localhost:8830/nucleus/atg/portal/alert/ if you have Dynamo Portal Framework running
/atg/portal/alert/GearMessagePublisher
Used by gears to dispatch a gear message off to the ScenarioManager. The gear message is serialized into the body of an ObjectMessage whose JMS-Type comes from the GearMessage's messageType property.
/atg/portal/alert/AlertRouter
Called by the scenario's SendAlert action. It receives the serialized GearMessages inside of ObjectMessage wrappers and dispatches them off as AlertTargetMessages to the AlertQueue for asynchronous processing by the AlertMgr
/atg/portal/alert/AlertMgr
Picks AlertTargetMessages out of the SQL JMS AlertQueue as dispatches them off to the database using the AlertRepositoryManager and ensures that the users' configured alert channels are called.
Implements Alert localization via resource bundles which is used during the display of the alerts to users, by the Alert Gear and for the selection of the email template to be used by the email dispatcher.
/atg/portal/alert/AlertRepositoryManager
Stores and retrieves Alerts from the AlertRepository
It's getAlerts() method used by the GetAlertsTag within the alert gear jsp pages. This method figures out the id's and target types to query for based on the alert type sent in to getAlerts(). Then queries the AlertRepository and returns the Alerts to the GetAlertsTag.
/atg/portal/alert/AlertRepository
The alert repository where the alerts as well as the configuration information are stored.
/atg/portal/alert/EmailAlertChannel
This component is registered in the AlertsRepository as a Channel. With the id 'Email'. It is called by the AlertMgr when an Alert needs to be dispatched to the Email Channel. It's an instance of atg.portal.alert.AlertChannel.
It implements public void executeAlertHandler(AlertTargetMessage pMsg, List pUsers, AlertMgr.MessageMapProps pMsgProps) by delegating to the configured alertHandler. Which by default is /atg/portal/alert/EmailAlertHandler (below)
It looks like you would create other instances of AlertChannel for each custom channel and set the alertHandler property to point to an instance of your Handler handler which implements the atg.portal.alert.AlertHandlerInterface.
/atg/portal/alert/EmailAlertHandler
An instance of atg.portal.alert.EmailAlertHandler this component gets called by the (Email)AlertChannel to actually dispatch the emails. It implements the atg.portal.alert.AlertHandlerInterface.
Provided the message, the target users and the properties of the message (extracted from the JMS-Type of the gear message) and using it's own settings and the /atg/portal/alert/DefaultTemplateEmailInfo as a basis it creates the TemplateEmailInfo used for sending out the emails via the AlertEmailSender.
/atg/portal/alert/DefaultTemplateEmailInfo
Contains the default settings for email, used by the EmailAlertHandler if no template is available.
/atg/portal/alert/AlertEmailSender
The email sender used by the EmailAlertHandler to actually dispatch the messages.
Alert Channels
Alert Channels provide an additional means by which alerts can be dispatched to users via different mediums. An email dispatch channel is provided, but you can add other channels too such as SMS or some other messaging system.
The list of active AlertChannels can be found in the ACC: List all the items of type AlertChannel in the AlertsRepository. Instructions on adding a new custom channel are found in the Gear Developers Guide - Adding Alert Channels.
For information on user configuration of Alert Channels click here (or keep reading.)