Under the Hood - Alerts

Introduction

Alerts are a great new feature, but they can be difficult to get your arms around to begin with. This article is a step by step under-the-hood look at the Alerts mechanism in ATG's portal server.

One thing to think about is that Alerts are only created by the SendAlertAction, everything up to that point is just JMS and JavaBeans. So a gear doesn't send Alerts. The gear is a message source which uses the GearMessagePublisher as a helper to send messages instead of going straight to the JMS.

Components

The Gear (or any other component really)

In the case of alerts all the gear has to do is post a JavaBean to the GearMessagePublisher instance.

GearMessagePublisher - /atg/portal/alert/GearMessagePublisher

Used by gears and form handlers to dispatch the GearMessages to the correct topic in the messaging system. The JNDI topic name for alerts is localdms:/local/PAF/GearEvent.

MessagingManager - /atg/dynamo/messaging/MessagingManager

The MessagingManager ensures the correct routing of all the JMS messages in Dynamo.
In this case it ensures that the messages sent to the GearEvent topic are dispatched to the ScenarioManager for processing.

ScenarioManager - /atg/scenario/ScenarioManager

The ScenarioManager runs all the scenarios on the site, for a GearMessage to become an alert we'll need to create a scenario which fires the SendAlertAction with the GearMessage.

SendAlertAction - Scenario Server custom action

This pre-configured custom action dispatches the GearMessage to the AlertRouter, specifying the routing information. Who the alert actually gets sent to, which communities, roles or individuals, is specified at scenario design time, in the call to the action.

AlertRouter - /atg/portal/alert/AlertRouter

The AlertRouter builds an Alert (AlertTargetMessage) from the GearMessage and dispatches it to the sqldms:/atg/portal/alert/AlertQueue (obviously via the MessagingManager). Important here to note that this is where the Alert goes 'off-thread' since everything up to this point was on-thread via the local jms.

AlertManager - /atg/portal/alert/AlertMgr

The AlertManager is a sink on the AlertQueue. Upon receiving the AlertTargetMessage the AlertManager looks into the Profile repository, specifically at the users' alertNotifyPreferences to determine which  which of the alert channels should be used.

Each user may have different preferences for each community and for each channel:

• email - optional depending on the emailChannel property
• wirelessEmail - optional depending on the  wirelessEmailChannel property
• web (always on)

Each of the channels is processed in it's own way. The web channel by adding an Alert to the AlertRepository consisting of the original serialized GearMessage and the target type information (user, role, community ...?). The email channel is fulfilled by sending out the appropriate template in a batch.

Configuration and Coding Work

GearMessage

Your new GearMessage class defines a serializable bean with certain known properties:

• messageType - the JMS message type associated with this bean (constant)
• gearId - The gear which sent the message
• communityId - The community in which the message was created
• profileId - The user whose actions caused the message
• creationDate - the time when the event was created
• startDate - 0 by default
• endDate - 0 by default
• expirationDate - 0 by default

These beans will be serialized into the alert repository and form the basis of the web alerts. The Dynamo supplied class atg.portal.alert.GearMessage is a good base class for your messages.

Scenario

You need to write a scenario which is triggered by your GearMessage and dispatches an Alert using the SendAlertAction, that will typically look something like this

Alert Filtering

There are various places which control whether alerts are sent and whether users get to see them alerts, or not. These are all repository items:

Alert Repository : alert_default_pref

These are the default properties for each gear in the system for each messageType, where the messageType is the JMS type of the GearMessage in question.

These values are manipulated using the jsp tag: paf:handleAlertConfig

Profile Repository : AlertNotificationPreference

Accessible via the userProfiles's alertNotifyPreferences property, this set of properties is the user's own preferences about the messages. In this case eventType is the JMS type of the message.

These values are set via the AlertFormHandler on the forms

What to set

In principal your selected channels need to be set to true in the alert_default_pref for your gear/messageType combination. Also if optInOut is set to yes_locked you need to make sure that the AlertNotificationPreference for this user has webChannel set to true.