11 Using Contacts Server Notifications

This chapter describes the Oracle Communications Contacts Server notification architecture, how to enable notifications, the different types of notifications, and how to customize notifications.

Overview of Notification Architecture

Contacts Server is capable of generating notifications for changes to the address book data in the database, or for some preset trigger. Notifications are published as Java Message Service (JMS) messages. Contacts Server also includes a JMS consumer program that consumes the JMS notifications and sends email messages to end users. A notification is sent by the server when a user, different than the one being notified, makes a change to the contacts database, for example, by granting an address book permission.

Contacts Server notification services use a publish/subscribe paradigm. Contacts Server publishes messages, in this case, notifications. Receiving clients (the subscribers) receive only those messages that they are interested in.

Contacts Server utilizes the built-in Java Messaging Service (JMS) in the application server to communicate contact data changes. Contacts Server bundles a consumer program that "consumes" this information and sends email for certain subset of the notifications as detailed in "Notification Types." For more information, see the JMS website at:

http://java.sun.com/products/jms/

Figure 11-1 shows that the Contacts Server notification service consists of two major components, the Notification Service and Notification Consumer. The Notification Service component is part of Contacts Server itself, and is the publisher that posts messages of a pre-configured JMS topic managed by the JMS provider. The Notification Consumer component is the subscriber or the message consumer of that JMS topic.

Figure 11-1 Contacts Server Notifications Services Architecture

Description of ''Figure 11-1 Contacts Server Notifications Services Architecture''

The Notification Service component provides interfaces for Contacts Server to publish JMS messages to a specific JMS topic (DavNotificationTopic) of the JMS broker. The Notification Service component is part of the main Contacts Server servlet that is deployed in the application server web container. The Notification Consumer component listens on the JMS bus for the specific topic (DavNotificationTopic) notification messages, consumes the messages, and sends notification email to recipients, if applicable. The consumer checks the notification type and other instructions provided in the JMS message to determine what action is to be taken. The Notification Consumer component message-driven bean (MDB) runs in the application server J2EE container. The consumer MDB is deployed in EMBEDDED mode, and thus is running in the same JVM of the J2EE container.

You can choose to write your own customized Notification Consumer programs. See "Writing a Java Messaging Service Consumer".

About Server Email Notifications

Server notifications are used to notify users mostly about changes to their address books due to actions by other users, such as granting permission to an address book. To enable email notifications at a server level, both the notification.dav.enablejmsnotif and notification.dav.enableemailnotif configuration parameters must be set to true.

Enabling Contacts Server Notifications

Table 11-1 describes the Contacts Server notifications that are controlled by the configuration parameters.

Table 11-1 Notification Configuration Parameters

Parameter	Description
notification.dav.enableemailnotif	Controls server-wide email notification. When this parameter is set to true, Contacts Server sends email notifications for address book collection creation and sharing (access change). End users can choose to receive notifications either by enabling their own account through Convergence or by requesting that an administrator do so by using the davadmin command. These notifications are text emails sent to users. If set to false, server-wide email notification is disabled.
notification.dav.enablejmsnotif	Controls server-wide JMS notification. When set to true, Contacts Server publishes notifications to the JMS bus. This parameter must be set to true for any notification to work.

Parameter

Description

notification.dav.enableemailnotif

Controls server-wide email notification. When this parameter is set to true, Contacts Server sends email notifications for address book collection creation and sharing (access change). End users can choose to receive notifications either by enabling their own account through Convergence or by requesting that an administrator do so by using the davadmin command. These notifications are text emails sent to users. If set to false, server-wide email notification is disabled.

notification.dav.enablejmsnotif

Controls server-wide JMS notification. When set to true, Contacts Server publishes notifications to the JMS bus. This parameter must be set to true for any notification to work.

You can enable or disable these parameters by using Jconsole or the davadmin utility. You do not need to restart the application server for a change to these parameters to take effect.

The settings are not cumulative. That is, to receive email notification, not only should notification.dav.enableemailnotif be set to true, so should notification.dav.enablejmsnotif.

Other notification.dav.* configuration parameters control items such as the SMTP server to use and its settings, maximum notification payload, location of notification templates, and so on. The davcore.autocreate.enableemailnotification parameter determines if notification is enabled by default on a newly created account and the davcore.autocreate.emailnotificationaddressattr parameter specifies which LDAP attribute to set as the default notification address when autocreating an account. (The default value is mail.) For more details, see "Contacts Server Configuration Parameters".

Enabling Notifications on an Account

To enable notifications for all accounts:

Use the davadmin command to set the davcore.autocreate.enableemailnotification to true.
```
davadmin config modify -o davcore.autocreate.enableemailnotification -v true
```
If necessary, change the value of the LDAP attribute corresponding to davcore.autocreate.emailnotificationaddressattr, which is used to set the email notification address during account autocreation. The default value is mail.

Modifying Notifications on an Account

Contacts Server stores the values for the davcore.autocreate.enableemailnotification and davcore.autocreate.emailnotificationaddressattr parameters in the database as properties for each account. You modify these parameters by running the davadmin account command.

For more information on the davadmin account command see "davadmin account".

Managing Notification Templates

This section describes the Contacts Server notification service in more detail and how to customize notification templates for your deployment.

Topics in this section:

Notification Types
Templates, Resource Bundle, and Other Configuration Files
Customizing Templates
Preserving Customized Template Files During Upgrade

Notification Types

Table 11-2 describes the notification types. It also lists the payload data, which is the resource content (for example, contact data) in byte array format. Attachments are not included.

Table 11-2 Notification Types

Notification Type	Description	Payload	Contacts Server Consumer Action
AUTOCREATECARD	Initial creation of a user's home collection (and its default sub-collections)	None	Email sent if creation happened. Creation due to user login or explicit account creation by using the davadmin command does not trigger an email.
CREATE_COLLECTION	Creation of a address book collection	None	None.
CREATE_CARD_RESOURCE	Creation of an entry in a address book collection	Contact data	None.
DELETE_COLLECTION	Deletion of a address book collection	None	None.
DELETE_CARD_RESOURCE	Deletion of an entry in an address book collection	Contact data	None.
MODIFY_CARD_RESOURCE	Modification of an entry in an address book collection	Contact data	None.
MOVE_COLLECTION	An address book collection was moved	None	None.
MOVE_RESOURCE	An entry in an address book collection was moved	None	None.
SHARE_ACCOUNT	An account was shared	None	An email is sent if additional permission was granted.
SHARE_CARD_COLLECTION	An address book collection was shared	None	An email is sent if additional permission was granted.
NONE	Undefined type	Contact data	Not applicable.

The notification message contains a type field that indicates what action triggered the notification and thus helps the consumer decide how to process it.

Templates, Resource Bundle, and Other Configuration Files

This section contains the following topics:

Notification Configuration
Resource Bundles
Template Files

Notification Configuration

You enable or disable notifications and set the values of the SMTP server used by the notification consumer by using the davadmin command or Jconsole. See "Contacts Server Configuration Parameters" for details on each of the configuration properties that you can set for notifications.

Resource Bundles

The value of the user's locale/preferred language attribute (defined by the davcore.ldapattr.preferredlang configuration parameter) in the user's directory entry is used to localize notification email. The attribute is retrieved from LDAP every time a notification is triggered and is then passed along as part of the notification object being published. If the user does not have any preferred locale/language, it defaults to the consumer module's system's default.

Template Files

Notification templates are files that contain pre-formatted notification messages.

Table 11-3 describes the available notification email templates. In a deployed production environment, by default the templates should be located in the /config/templates sub-directory, for example, /opt/sun/comms/nabserver/config/templates/. The location of the templates directory is defined by the notification.dav.configdir configuration parameter.

Table 11-3 Scenarios That Trigger Notifications and Templates Files Used

Message Type	Notification Type	Template Files	From	To	Description
Auto creation	AUTOCREATECARD	autocreatecard.fmt	User's address	User's address	Notifies of auto creation of user's home collection due to login.
Address book creation	CREATE_COLLECTION	createaddressbook.fmt	User's address	User's address	Notifies of an address book being created.
Contact creation	CREATE_CARD_RESOURCE	createcontact.fmt	User's address	User's address	Notifies of a contact being created.
Address book deletion	DELETE_CARD_COLLECTION	deleteaddressbook.fmt	User's address	User's address	Notifies of an address book being deleted.
Contact delection	DELETE_CARD_RESOURCE	deletecontact.fmt	User's address	User's address	Notifies of a contact being deleted.
Share contact	SHARE_ACCOUNT	share_account.fmt	Sharer's email address	Sharee's email address	Notifies of an address book account being shared.
Share address book collection	SHARE_CARD_COLLECTION	shareaddressbook.fmt	Sharer's email address	Sharer's email address	Notifies of an address book collection being shared.

A recipient list stored in the property, SUN_NOTIFRECIPIENT. By default, it's the scheduling address of the LDAP user on behalf of whom the operation is processed. It can be modified through interfaces provided by WCAP or by using the davadmin command.

Customizing Templates

Because JavaMail has interfaces to parse an entire string into a MIME message, a notification template file is designed to be a well-formatted email MIME message that contains character sequences denoted by a starting "%{", and an ending "}".

A template contains the following trinket types:

Resource bundle key: A place holder for locale-specific resource, in the format of ${key};

For example, trinket ${summary} contains a key "summary" that uniquely identifies a locale-specific object in the resource bundle.
Value trinket: A place holder for notification field value, in the format of %{trinket};

For a complete list of keys, refer to the email.properties file.

For more information on values and trinkets, and template examples, see the topic on customizing templates in Calendar Server System Administrator's Guide. Though that guide is written for Calendar Server, the topic also applies to Contacts Server.

Preserving Customized Template Files During Upgrade

Customized notification template files are preserved during a Contacts Server upgrade. Normally, there should be no problem merging customized notification template files during the upgrade. If the upgrade encounters a problem with merging these files, the following message is displayed:

log_msg "There are conflicts in merging $file customization"
log_msg "Please finish the merge by manually resolving the conflicts in $cfgFileNew"

The $file and $cfgFileNew are substituted with actual file names.

Writing a Java Messaging Service Consumer

Contacts Server Notification Services use a publish/subscribe paradigm. All Contacts Server notification messages are posted to a pre-defined JMQ Topic called DavNotificationTopic. Each message consists of the associated contact data as the message body and some additional information passed in as properties.

For more information, see the topic on notification message format and sample code in Calendar Server System Administrator's Guide. Though that guide is written for Calendar Server, the topic also applies to Contacts Server.

Managing Contacts Server Java Messaging Server Destinations

You can manage Java Messaging Server (JMS) destinations in Contacts Server by using the imqcmd command. For a complete list of imqcmd options, see the "Command Utility" chapter in Sun Java System Message Queue 4.1 Administration Guide.

For more information, see the topic on managing JMS destinations in Calendar Server System Administrator's Guide. Though that guide is written for Calendar Server, the topic also applies to Contacts Server.