Configuring a JMQ Notification Service (Task)

h1. Configuring a JMQ Notification Service (Task)

This section briefly describes how a JMQ notification plug-in fits into the context of a complete Message Queue service. It then provides detailed instructions for configuring a JMQ notification plug-in.

This page contains the following sections:
{toc:minLevel=2|maxLevel=2}

For related topics on JMQ notification, see the following pages:
* [Enabling JMQ Notification (Example)]
* [JMQ Notification Overview]
* [JMQ Notification Messages and Properties (Reference)|JMQ Notification Messages and Properties]

h2. Planning for Your JMQ Notification Service

A JMQ notification plug-in is only one part of a Message Queue service. A messaging service also includes clients that consume the messages and the Message Queue infrastructure (the broker, administration components, and so on).

The following steps outline the tasks you should perform to create a Message Queue service that supports Messaging Server:
# _Design your notification message service._\\
Define the notification messages needed for your Messaging Server installation. The planning and design phases of your message-service development lifecycle lie outside the scope of this chapter. However, you should answer the following design questions before you configure the JMQ notification plug-in:\\
** Which message events do you need to produce notifications? For a list of the available notification messages, see [Notification Messages|JMQ Notification Messages and Properties#Notification Messages].\\
** Do you intend to produce messages to a queue, a topic, or both?\\
** Do you intend to use the proprietary Event Notification Service as well as the Message Queue service?\\
The answers to these questions will help you decide whether to configure one notification plug-in or multiple plug-ins, and to determine how to configure each plug-in.\\
# _Install, configure, and deploy the Message Queue product._\\
For information about installing Message Queue, see the _Sun Java System Message Queue Installation Guide_.\\
For information about configuring and deploying Message Queue, see the _Sun Java System Message Queue Administration Guide_.\\
# _Write one or more Message Queue clients that will consume the JMQ notification messages._\\
The clients must conform to the requirements for a Message Queue client API. A simple example of client source code, written in C, is available in the following path:\\
{code}
/opt/SUNWmsgsr/examples/jmqsdk/
{code}
The source file name is {{jmqclient.c}}.\\
This client source code receives messages from the JMQ notification messages defined by the parameters in the {{libjmqnotify}} library. It then sends the message output to {{stdout}}.\\
For information about writing Message Queue clients in C or Java, see the _Sun Java System Message Queue Developer's Guide for C Clients_ or the _Sun Java System Message Queue Developer's Guide for Java Clients_.\\
# _Configure and enable the JMQ notification plug-in for producing notification messages._\\
The remainder of this chapter describes how to configure the notification plug-in.\\
# _Configure and start the runtime Message Queue clients._\\
For information about deploying the runtime Message Queue clients, see the _Sun Java System Message Queue Administration Guide_.\\{anchor:gcshh}

h2. To Configure a JMQ Notification Plug-in

In this procedure, you first configure the message events that will produce notifications. Next, you specify the information needed by Message Queue. Finally (in step 9), you configure the plug-in name by specifying a parameter after the name of the plug-in library:
{code}
'/opt/SUNWmsgsr/lib/libjmqnotify$_plug-in_name_'

* Sun Java System Message Queue 3.6 SP3 2005Q4 or later\\
{info:title=Note - }Most of the {{configutil}} parameters you will configure in the following steps are optional. For a list of their default values, see [Table 22-2|JMQ Notification Messages and Properties#gcsin].\\
{info}

# Configure the notification message parameters.
For each kind of notification message you want to include in the plug-in, use the {{local.store.notifyplugin}} command with the {{configutil}} utility.
For example, to enable notifications for new messages, enter:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.NewMsg.enable -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} enables notifications for this message. A value of {{0}} disables notifications for this message.
For a list of all the JMQ notification messages, see [Notification Messages|JMQ Notification Messages and Properties#Notification Messages].
For definitions of the {{configutil}} parameters that enable the JMQ notification messages, see [Messaging Server Configuration].
A few notification messages use more than one {{configutil}} parameter to enable the message with additional features. For example, some messages can carry message headers in the notification text. For instructions on how to configure these messages, see [Syntax for newflags and oldflags Properties|JMQ Notification Messages and Properties#gcsik].
{info:title=Note - }You must configure parameters separately for each plug-in you configure.\\Thus, if you configure two plug-ins, named {{jmq1}} and {{jmq2}}, and you want to enable new-message notifications for both plug-ins, you must run the {{local.store.notifyplugin}} command twice:\\
{code}
configutil -o local.store.notifyplugin.jmq1.NewMsg.enable -v 1
{code}
{code}
configutil -o local.store.notifyplugin.jmq2.NewMsg.enable -v 1
{code}
{info}
# Specify the host where the Message Queue destination (broker) is running.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqHost -v "127.0.0.1"
{code}
where _jmqnotify_ is the name of the plug-in
and {{"127.0.0.1"}} is the IP address of the host machine for the Message Queue broker.
# Specify the port for the Message Queue broker.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqPort -v "7676"
{code}
where _jmqnotify_ is the name of the plug-in
and {{"7676"}} is the port for the Message Queue broker.
# Specify the user ID and password of the Message Queue user authorized to produce messages to the service.
For example, enter the following commands:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqUser -v "guest"
{code}
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqPwd -v "%$#a62t&amp;"
{code}
where _jmqnotify_ is the name of the plug-in
and {{"guest"}} and {{"%$#a62t&amp;"}} are the user ID and password, respectively, for the Message Queue user.
# Configure the type of destination (topic or queue) and the name of the destination to which messages will be sent.
Follow these steps:
# Specify whether the destination is a topic or queue.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.DestinationType -v "queue"
{code}
where _jmqnotify_ is the name of the plug-in
and {{"queue"}} specifies that the destination is a queue. The allowed values for this parameter are {{"queue"}} and {{"topic"}}.
# Specify the destination name.
For example, enter one of the following commands:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqQueue -v "JES-MS"
{code}
or
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.jmqTopic -v "JES-MS"
{code}
where _jmqnotify_ is the name of the plug-in
{{jmqQueue}} or {{jmqTopic}} identifies the destination type. The {{jmqQueue}} and {{jmqTopic}} parameters are synonymous and mutually exclusive; you can only use one of these parameters in one plug-in.
{{"JES-MS"}} is an example name of the queue or topic to which messages will be sent.
# {anchor:indexterm-2194} Specify the message priority.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.Priority -v 3
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 3}} is the Message Queue priority assigned to messages produced by this plug-in.
The default value of the {{Priority}} is 4.
# {anchor:indexterm-2195} Specify the length of time (in milliseconds) that messages are retained by the Message Queue broker.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.ttl -v 100
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 100}} specifies that a message is retained by the Message Queue service for 100 milliseconds before being either delivered or discarded. A value of 0 means that a message is retained permanently; it does not time out.
# {anchor:indexterm-2196} Specify the message persistence.
For example, enter the following command:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.Persistent -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} specifies that persistent messages are used in the Message Queue service. Allowed values are 1 (persistent) and 0 (non-persistent).
# {anchor:indexterm-2197} Configure the plug-in name.
To configure a single plug-in with the default name, you can enter either the fully qualified name of the plug-in library or the name of the library and its plug-in parameter:
{code}
configutil -o local.store.notifyplugin -v /opt/SUNWmsgsr/lib/libjmqnotify
{code}
or
{code}
configutil -o local.store.notifyplugin -v '/opt/SUNWmsgsr/lib/libjmqnotify$jmqnotify'
{code}
where {{libjmqnotify}} is the library name
and {{jmqnotify}} is the default name of the plug-in parameter.
Use the dollar sign ($) to separate the library name from the parameter.
Enclose the entire value in single quotes ('_value_'); if you do not, the shell will interpret the dollar sign.
The {{configutil}} parameters read by the default plug-in have the following names:
{code}
local.store.notifyplugin.jmqnotify.*
{code}
To configure a different plug-in name such as {{jmq42}}, you would enter the following command:
{code}
configutil -o local.store.notifyplugin -v '/opt/SUNWmsgsr/lib/libjmqnotify$jmq42'
{code}
The {{configutil}} parameters read by the {{jmq42}} plug-in have the following names:
{code}
local.store.notifyplugin.jmq42.*
{code}{anchor:gcsiq}

h2. To Configure Multiple Plug-ins
# Configure a separate set of JMQ notification parameters for each plug-in you intend to create.
For example, suppose you configure two plug-ins named {{jmq1}} and {{jmq2}}. Assume you want to enable new-message notifications for both plug-ins and purged-message notifications for the {{jmq2}} plug-in only. In this case, you would run the {{local.store.notifyplugin}} command three times, as follows:
{code}
configutil -o local.store.notifyplugin.jmq1.NewMsg.enable -v 1
{code}
{code}
configutil -o local.store.notifyplugin.jmq2.NewMsg.enable -v 1
{code}
{code}
configutil -o local.store.notifyplugin.jmq2.PurgeMsg.enable -v 1
{code}
You also must specify parameters that enable the plug-ins to communicate with the Message Queue service.
For step-by-step instructions for configuring the all the notification parameters, see [To Configure a JMQ Notification Plug-in|#gcshh].
# Configure the plug-in names.
To configure two plug-ins named {{jmq1}} and {{jmq2}}, you would enter the following command:
{code}
configutil -o local.store.notifyplugin
-v '/opt/SUNWmsgsr/lib/libjmqnotify$jmq1$$/opt/SUNWmsgsr/ \
lib/libjmqnotify$jmq2'
{code}
In this example, two instances of the plug-in library are run.
Use a single dollar sign ($) to separate the library name from the parameter that specifies the plug-in name.
Use two dollar signs ($$) to separate the first plug-in instance from the next one.
Enclose the entire value in single quotes ('_value_'); if you do not, the shell will interpret the dollar signs.
In this example, the first instance builds its configuration from parameters with the name {{jmq1}}:
{code}
local.store.notify.jmq1.*
{code}
The second instance builds its configuration from parameters with the name {{jmq2}}:
{code}
local.store.notify.jmq2.*
{code}{anchor:gcsij}

h2. Specifying Notification Messages that Use More Than One {{configutil}} Parameter

For most notification messages, you specify the message by running a single {{local.store.notifyplugin}} command.

However, the following notification messages are (or can be) configured with more than one {{local.store.notifyplugin}} command:
# {{NewMsg}}\\
# {{UpdateMsg}}\\
# {{DeleteMsg}}\\
# {{MsgFlags}}\\

The procedures that follow describe how to set up these notification messages.{anchor:gcsiy}

h2. To Configure New-Message and Updated-Message Notifications with Message Headers and Message Bodies

You can add the message headers and message bodies to the text of notification messages sent when there are new or updated email messages.

Including message headers and message bodies is optional; you can include both features, one feature only, or neither feature. The default is to send messages without message headers or message bodies.
# Specify the new-message or updated-message notification:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.NewMsg.enable -v 1
{code}
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.UpdateMsg.enable -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} enables notifications for these messages. A value of {{0}} disables notifications.
# Specify the {{maxHeaderSize}} parameter with a value greater than zero, as in the following example:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.maxHeaderSize -v 1024
{code}
where _jmqnotify_ is the name of the plug-in
and {{1024}} is the maximum size of the header to be sent. The default value of {{maxHeaderSize}} is {{0}}, which sends no header information with the message.
# Specify the {{maxBodySize}} parameter with a value greater than zero, as in the following example:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.maxBodySize -v 1024
{code}
where _jmqnotify_ is the name of the plug-in
and {{5120}} is the maximum size of the message body to be sent. The default value of {{maxBodySize}} is {{0}}, which sends no body with the message.{anchor:gcsht}

h2. To Configure Deleted-Message Notifications with Message Headers

You can add the message headers to the text of notification messages sent when email messages are deleted.

Including message headers is optional. The default is to send notifications without message headers.
# Enable notifications to be sent when email messages are deleted:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.DeleteMsg.enable -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} enables notifications for this message. A value of {{0}} disables notifications.
# Specify the {{ExpungeHeaders}} parameter:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.ExpungeHeaders -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} enables message headers to be carried with deleted-message notifications. The default value of {{ExpungeHeaders}} is {{0}}, which prohibits deleted-message notifications from carrying header information.
You must configure the {{ExpungeHeaders}} parameter to enable {{DeleteMsg}} messages to carry message headers.
# Specify the {{maxHeaderSize}} parameter with a value greater than zero, as in the following example:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.maxHeaderSize -v 1024
{code}
where _jmqnotify_ is the name of the plug-in
and {{1024}} is the maximum size of the header to be sent. The default value of {{maxHeaderSize}} is {{0}}, which sends no header information with the message.{anchor:gcsis}

h3. Configuring Notifications for Changes in Message Status

You can configure a notification message to be sent when an email message has changed status.{anchor:gcsif}

h4. Information Delivered in Message-Flag Notifications

A message-flags notification is produced whenever a status flag has changed because the email message was:
* Answered\\
* Flagged\\
* Deleted\\
* Seen (read)\\
* Draft\\

When a message-flags notification is sent, the notification carries the following properties:
* The flags set for the email message before its status changed\\
* The flags set for the email message after its status changed\\

This information is carried in two properties, {{oldflags}} and {{newflags}}, which are 5&ndash;character strings.

For a description of the values of these two properties, see [Syntax for newflags and oldflags Properties|JMQ Notification Messages and Properties#gcsik].{anchor:gcshr}

h4. Configutil Parameters Needed for Message-Flag Notifications

To enable message-flag notifications, you must configure the following {{configutil}} parameters:
* {{local.store.notifyplugin.MsgFlags}}\\
* {{local.store.notifyplugin.*.MsgFlags.enable}}\\

The first {{MsgFlags}} parameter enables the IMAP server and message store to identify and track the changing values of the status flags so that this information can be delivered in notification messages.

This parameter applies to all notification plug-ins. Therefore, you must enable the parameter if _any_ notification plug-in uses message-flag notifications. If no plug-in uses message-flag notifications, be sure that this parameter is disabled (its default value).

The second parameter, {{*.MsgFlags.enable}}, allows message-flag notifications to be sent for a particular plug-in library.
{info:title=Note - }You must configure both parameters to enable notifications for message flags.\\
{info}
{anchor:gcshe}

h2. To Enable Notifications When Message-Status Flags Have Changed

# Enable status flags to be tracked and status information to be carried with message-flag notifications:
{code}
configutil -o local.store.notifyplugin.MsgFlags -v 1
{code}
where {{-v 1}} enables message-flag information to be sent with message-flag notifications. A value of {{0}} disables this notification.
# Enable message-flag notifications to be sent by a particular plug-in:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.MsgFlags.enable -v 1
{code}
where _jmqnotify_ is the name of the plug-in
and {{-v 1}} enables message-flag notifications for this plug-in. A value of {{0}} disables notifications.{anchor:gcsiw}

h2. To Enable Conditional Notifications for Specified Users

{panel:|borderColor=#ccc|bgColor=#FFFFCE}The functionality documented in this section was introduced in *Messaging Server 7 Update 2*.{panel}

This task allows you to configure notifications to be sent for specific users who require notifications rather than for all users in your deployment. The conditional use of notifications can greatly reduce the total number of notifications sent, thus reducing the overall load on the system.

For information about how conditional notifications work, see [Configuring Conditional Notifications for Specified Users|JMQ Notification Overview#Configuring Conditional Notifications for Specified Users].

h6. Before You Begin

Follow all the steps in [To Configure a JMQ Notification Plug-in|#To Configure a JMQ Notification Plug-in].

h6. Take These Steps

# Disable notifications for all users:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.enable -v 0
{code}
where _jmqnotify_ is the name of the plug-in library
and {{-v 0}} disables notifications for all users for this plug-in. (A value of {{1}} enables notifications for all users.)
# Enable notifications for those users with the notification attribute, {{mailEventNotificationDestination}}, set in their LDAP entries:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.ldapdestination -v mailEventNotificationDestination
{code}
# Add the following attribute to the LDAP entries of the users who require notifications. For example:
{code}
mailEventNotificationDestination: <jmqnotify>
{code}
where _jmqnotify_ is the name of the plug-in library.
# Ensure that this LDAP attribute is cached in enqueued messages and carried in LMTP deliveries by adding the lines to {{option.dat}}.
{code}
LDAP_SPARE_1=mailEventNotificationDestination
SPARE_1_SEPARATOR=259
{code}
# Rebuild the configuration file and restart Messaging Server.
{code}
./stop-msg
./imsimta cnbuild
./start-msg
{code}

h2. To Configure Conditional Notifications to Be Sent to Different Message Queue Destinations

{panel:|borderColor=#ccc|bgColor=#FFFFCE}The functionality documented in this section was introduced in *Messaging Server 7 Update 2*.{panel}

This task allows notifications for different sets of users to be sent to different Message Queue destinations in a distributed Message Queue environment. For example, for one set of users, notifications can be routed to one Message Queue host; for a second set, notifications can be routed to another Message Queue host.

This task begins with the similar steps as the preceding task, [#To Enable Conditional Notifications for Specified Users]. It extends that task to allow for multiple Message Queue destinations.

For more information about this feature, see [Sending Conditional Notifications to Distributed Message Queue Destinations|JMQ Notification Overview#Sending Conditional Notifications to Distributed Message Queue Destinations].

h6. Before You Begin

Follow *Step 1, Configure the notification message parameters*, in [To Configure a JMQ Notification Plug-in|#To Configure a JMQ Notification Plug-in].

h6. Take These Steps

# Disable notifications for all users:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.enable -v 0
{code}
where _jmqnotify_ is the name of the plug-in library
and {{-v 0}} disables notifications for all users for this plug-in. (A value of {{1}} enables notifications for all users.)
# Enable notifications for those users with the notification attribute, {{mailEventNotificationDestination}}, set in their LDAP entries:
{code}
configutil -o local.store.notifyplugin.<jmqnotify>.ldapdestination -v mailEventNotificationDestination
{code}
# Add the following attribute to the LDAP entries of the users who require notifications. For example:
{code}
mailEventNotificationDestination: <jmq_destination_name>
{code}
where {{jmq_destination_name}} is the name you assign to the Message Queue destination. For example:
{code}
mailEventNotificationDestination: mqdestination1
{code}
Here the LDAP attribute is set to the value {{mqdestination1}}. This value can be any string. However, this value must match the JMQ destination name in the {{configutil}} parameters you set to provide configuration information needed by Message Queue. These parameters are listed in the next step.
# Configure the following JMQ configuration parameters:
{noformat}
local.store.notifyplugin._jmq_destination_name_.jmqHost
local.store.notifyplugin._jmq_destination_name_.jmqPort
local.store.notifyplugin._jmq_destination_name_.jmqUser
local.store.notifyplugin._jmq_destination_name_.jmqPwd
local.store.notifyplugin._jmq_destination_name_.DestinationType

local.store.notifyplugin._jmq_destination_name_.jmqTopic
or
local.store.notifyplugin._jmq_destination_name_.jmqQueue

local.store.notifyplugin._jmq_destination_name_.Priority
local.store.notifyplugin._jmq_destination_name_.ttl
local.store.notifyplugin._jmq_destination_name_.Persistent
{noformat}
For example:
{code}
configutil -o local.store.notifyplugin.mqdestination1.jmqHost -v "127.0.0.1"
{code}
For details about how to configure these parameters, see *Steps 2 through 10* in [To Configure a JMQ Notification Plug-in|#To Configure a JMQ Notification Plug-in].
# For each different JMQ destination you want to create for different sets of users, repeat *Steps 3 and 4*, in this procedure.
For example, to create two additional JMQ destinations named {{mqdestination2}} and {{mqdestination3}}:
## Use these strings in the users' {{mailEventNotificationDestination}} LDAP attributes. For example, for all users whose notifications will go to the second destination, add:
{code}
mailEventNotificationDestination: messagequeuedestination2
{code}
For all users whose notifications will go to the third destination, add:
{code}
mailEventNotificationDestination: messagequeuedestination3
{code}
## Set each JMQ configuration parameter (such as {{jmqHost}}) to its specific value. For example:{code}
configutil -o local.store.notifyplugin.mqdestination2.jmqHost -v "127.0.0.2"
{code}
{code}
configutil -o local.store.notifyplugin.mqdestination3.jmqHost -v "127.0.0.3"
{code}
and so on for each parameter.
# Restart Messaging Server.
{code}
./stop-msg
./start-msg
{code}