Adding Custom Alert Messages to Gears

If you would like your gears to send messages to the PAF when certain events occur, you will need to create the Java code necessary to define messages and publish them to the Java Messaging System (JMS). These messages form the basis of alerts, which can trigger actions through ATG Scenarios.

Note: This procedure uses Java classes that are provided with the PAF for convenience. In this example, we use the base class atg.portal.alert.GearMessage because it provides initialization of properties that most gears will need to use in their alerts. However, you can use other approaches to alerts. The only requirement is that your gear publish a JMS message, which can then be used by ATG Scenarios.

The following instructions provide a rough overview of the procedure for creating new alert messages in a gear:

  1. Determine which alerts you want your gear to send. You need to decide which events trigger an alert and what the alert message should contain.

    For example, if you are creating a document exchange gear, you might want to send alerts when documents are created, updated, or deleted, and each alert might contain the community, the document ID, the profile of the user, and the page.

  2. Create a JavaBean that extends atg.portal.alert.GearMessage for each message format you require. (See Sample GearMessage Extension below.)

    The GearMessage base class provides initialization and access to useful properties (community ID, profile ID, gear ID, and date properties).

    Each subclass of GearMessage should contain the member variables required to hold the necessary data for the message.

  3. In the case of a document exchange gear, for example, you might extend GearMessage by creating the DocExchMessage class to contain all the properties needed by all document exchange messages, such as the author’s name and the document name. You would then create classes that extend DocExchMessage with properties and values that are specific to each message type (for example, DocumentCreatedMessage, DocumentUpdatedMessage, DocumentDeletedMessage). Each message class must have a unique message type string defined. Add code to make the GearMessagePublisher global service component available. (See Adding GearMessagePublisher to the Gear below.)

    GearMessagePublisher is a Nucleus service that makes it easier to publish messages, by handling the initialization of JMS messages, the message destination lookup, and the message publishing.

    GearMessagePublisher exposes a method called writeMessage(), which can take any serializable object as its argument.

  4. Call the GearMessagePublisher.writeMessage() method from the appropriate gear code. (See Sample Sending Code below.)

  5. Define the message in the ATG Message System by creating a /atg/dynamo/messaging/dynamoMessagingSystem.xml file in the gear’s CONFIGPATH. (For example, create the <ATG10dir>/Portal/GEARNAME/config/atg/dynamo/messaging/dynamoMessagingSystem.xml file, where GEARNAME is the name of the gear.)

    Model the contents of the file after the code shown in Sample dynamoMessagingSystem.xml File below. For more information about configuring and using the ATG Message System, see the ATG Message System chapter in the ATG Platform Programming Guide.

  6. Create an alerts element in the gear manifest file inside the gear-definition tag. (See Adding the Alerts Element to the Gear Manifest File below.)

    Once you re-upload the gear’s manifest file, this makes the gear’s alerts available for configuration through the Portal Administration.

  7. For each message format and language locale, create a resource bundle properties file with the name referenced in the AlertMgr component. (See Creating a Resource Bundle Properties File below.)

  8. If you want your alerts to send e-mail, create the e-mail template file used in sending e-mail alerts about this event. (See Creating an E-mail Template File below.)

  9. Provide a form as part of the gear’s Instance Configuration mode that allows a Community Leader to enable or disable alerts for the gear. (See Creating an Alert Instance Configuration Form below.)

  10. Extend the Scenario user interface to handle your new message types as it does other alert messages. (See Extending the Scenario User Interface below.)

  11. Using the Scenario module, configure a scenario that will perform the desired response upon receiving a gear alert. (See Configuring a Scenario below.)