This information describes how to configure a JMQ notification plug-in.
Topics:
Specifying Notification Messages that Use More Than One msconfig Option
To Configure New-Message and Updated-Message Notifications with Message Headers and Message Bodies
To Configure Deleted-Message Notifications with Message Headers
For related topics on JMQ notification, see the following pages:
A JMQ notification plug-in is only one part of a Message Queue service. A Message Queue service also includes clients that consume the event 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 Oracle Communications Messaging Server installation. The planning and design phases of your message-service development lifecycle lie outside the scope of this information. 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."
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 help you decide whether to configure one instance of the notification plug-in or multiple instances, and to determine how to configure each instance.
Install, configure, and deploy the Message Queue product. For information about installing Message Queue, see the Sun GlassFish Message Queue 4.4 Update 1 Installation Guide. For information about configuring and deploying Message Queue, see the Sun GlassFish Message Queue 4.4 Administration Guide.
Write one or more Message Queue clients that consume the JMQ notification messages. The clients must conform to the requirements for a Message Queue Java application programming interface (API). For information about writing Message Queue clients in Java, see the Sun GlassFish Message Queue 4.4 Developer's Guide for Java Clients.
Configure and enable the JMQ notification plug-in for producing notification messages. The remainder of this information 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 GlassFish Message Queue 4.4 Administration Guide.
Note:
The libibiff and libjmqnotify notification plugins are now built-in.In this procedure, you first configure the message events that produce notifications. Next, you specify the information needed by Message Queue. Finally (in step 10), you configure the instance name by specifying a option after the name of the plug-in library:
msconfig set notifytarget:<instance>.notifytype jmq
You should install, configure, and deploy the following products:
Messaging Server
Oracle GlassFish Message Queue (see the Messaging Server Release Notes for more information)
Note:
Most of the configuration options that you configure in the following steps are optional. For a list of their default values, see the Messaging Server Reference.The msconfig options used by the default instance have names of the following form:
notifytarget:<instance>.<option>
Configure the notification event message options. For each kind of notification event message you want to include in the instance, use the notifytarget:instance.event option. For example, to enable notifications for new messages, type:
msconfig set notifytarget:<jmqnotify>.newmsg 1
where jmqnotify is the name of the default instance and 1 enables notifications for this event. A value of 0 disables notifications for this event. For a list of all the JMQ notification messages, see "Notification Messages." A few notification messages use more than one option 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."
Note:
You must configure options separately for each instance you configure. Thus, if you configure two instances, named jmq1 and jmq2, and you want to enable new-message notifications for both instances, you must set that option for both instances:msconfig set notifytarget:jmq1.newmsg 1 msconfig set notifytarget:jmq2.newmsg 1
Specify the host where the Message Queue destination (broker) is running. For example:
msconfig set notifytarget:<instance>.jmqhost "127.0.0.1"
Specify the port for the Message Queue broker. For example:
msconfig set notifytarget:<instance>.jmqport "7676"
Specify the user ID of the Message Queue user authorized to produce messages to the service. For example:
msconfig set notifytarget:<instance>.jmquser "guest"
Specify the password of the Message Queue user. You need to do this in interactive mode, for example:
msconfig msconfig> set -prompt notifytarget:<instance>.jmqpwd Password: Verify: msconfig# write msconfig> exit
Specify whether the destination is a "topic" or a "queue". For example:
msconfig set notifytarget:<instance>.destinationtype "queue"
Specify the destination topic or queue name. For example, type one of the following commands:
msconfig set notifytarget:<instance>.jmqqueue "JES-MS"
or
msconfig set notifytarget:<instance>.jmqtopic "JES-MS"
The jmqqueue and jmqtopic options are synonymous and mutually exclusive. You can only use one of these options in one instance."JES-MS" is an example name of the queue or topic to which messages are sent.
Specify the Message Queue priority assigned to messages produced by this instance. For example:
msconfig set notifytarget:<instance>.priority 3
The default value of the priority option is 4.
Specify the length of time (in milliseconds) that messages are retained by the Message Queue broker. For example:
msconfig set notifytarget:<instance>.ttl 100
This example 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.
Specify the message persistence. For example:
msconfig set notifytarget:<instance>.persistent 1
The 1 specifies that persistent messages are used in the Message Queue service. Allowed values are 1 (persistent) and 0 (non-persistent).
Configure the instance name. To configure a single instance with the default name, type the following:
msconfig set notifytarget:<instance>.notifytype jmq
Note that jmqnotify is the default instance name.
To configure a different instance name such as jmq42, type the following command:
msconfig set notifytarget:jmq42.notifytype jmq
The msconfig options read by the jmq42 instance would have names like:
notifytarget:jmq42.<option>
{code:none}
h2. To Configure Multiple Instances
Configure a separate set of JMQ notification parameters for each instance you intend to create.
For example, suppose you configure two instances named {{jmq1}} and {{jmq2}}. Assume you want to enable new-message notifications for both instances and purged-message notifications for the {{jmq2}} instance only. In this case, you would set the following options:
{code:none}
msconfig set notifytarget:jmq1.newmsg 1
msconfig set notifytarget.jmq2.newmsg 1
msconfig set notifytarget.jmq2.purgemsg 1
You also must specify options that enable the instances to communicate with the Message Queue service. For step-by-step instructions for configuring the all the notification options, see "To Configure an Instance of the JMQ Notification Plug-in."
Configure the instance names. To configure two instances named jmq1 and jmq2, type the following command:
msconfig set notifytarget:jmq1.notifytype jmq msconfig set notifytarget:jmq2.notifytype jmq
In this example, the first instance builds its configuration from options with the name jmq1:
notifytarget:jmq1.<option>
The second instance builds its configuration from options with the name jmq2:
notifytarget:jmq2.<option>
For most notification messages, you specify the message by running a single msconfig notifytarget command.
However, the following notification messages are (or can be) configured with more than one msconfig notifytarget command:
newmsg
updatemsg
deletemsg
msgflags
The following procedures describe how to set up these notification messages.
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:
msconfig set notifytarget:<instance>.newmsg 1 msconfig set notifytarget:<instance>.updatemsg 1
Specify the maxheadersize option with a value greater than zero:
msconfig set notifytarget:<instance>.maxheadersize 1024
The default value of maxheadersize is 0, which sends no header information with the message.
Specify the maxbodysize option with a value greater than zero:
msconfig set notifytarget:<instance>.maxbodysize 1024
The default value of maxbodysize is 0, which sends no body with the message.
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:
msconfig set notifytarget:<instance>.deletemsg.enable 1
Specify the expungemsg option:
msconfig set notifytarget:<instance>.expungemsg 1
Setting the value to 1 enables message headers to be carried with deleted-message notifications. The default value of expungemsg is 0, which prohibits deleted-message notifications from carrying header information. You must configure the expungeheaders option to enable deletemsg messages to carry message headers.
Specify the maxheadersize option with a value greater than zero, as in the following example:
msconfig set notifytarget:<instance>.maxheadersize 1024
The default value of maxheadersize is 0, which sends no header information with the message.
You can configure a notification message to be sent when an email message has changed status.
A message-flag notification is produced whenever a status flag has changed because the email message was:
Answered
Flagged
Deleted
Seen (read)
Draft
When a message-flag 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--character strings.
For a description of the values of these two properties, see "Syntax for newflags and oldflags Properties."
To enable message-flag notifications, you must configure the following msconfig option:
notifytarget:<instance>.msgflags 1
This option 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 option is instance specific. If an instance does not use message-flag notifications, be sure that this option is disabled (default).
This task enables 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."
Follow all the steps in "To Configure an Instance of the JMQ Notification Plug-in."
Disable notifications for all users:
msconfig set notifytarget:<instance>.enable 0
Specify the name of the LDAP attribute which, if present in the user's LDAP entry, enables notifications for that user and specify the instance to use:
msconfig set notifytarget:<instance>.ldapdestination mailEventNotificationDestination
Add the attribute to the LDAP entries of the users who require notifications. For example:
mailEventNotificationDestination: jmqnotify
where jmqnotify is the default instance name.
Ensure that this LDAP attribute is cached in enqueued messages and carried in LMTP deliveries.
msconfig set LDAP_SPARE_1=mailEventNotificationDestination msconfig set SPARE_1_SEPARATOR 259
Rebuild the configuration file and restart Messaging Server.
stop-msg imsimta cnbuild start-msg
This task enables 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."
Follow Step 1, Configure the notification message options, in "To Configure an Instance of the JMQ Notification Plug-in."
Disable notifications for all users:
msconfig set notifytarget:<instance>.enable 0
Specify the name of the LDAP attribute which, if present in the user's LDAP entry, enables notifications for that user and specify the instance to use:
msconfig set notifytarget:<instance>.ldapdestination mailEventNotificationDestination
Add the attribute to the LDAP entries of the users who require notifications. For example:
mailEventNotificationDestination: mqdestination1
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 (instance) in the options that you set to provide configuration information needed by Message Queue. These options are listed in the next step.
Use the msconfig set command to configure the following JMQ configuration options:
notifytarget:<jmq_destination_name>.jmqhost notifytarget:<jmq_destination_name>.jmqport notifytarget:<jmq_destination_name>.jmquser notifytarget:<jmq_destination_name>.jmqpwd notifytarget:<jmq_destination_name>.destinationtype notifytarget:<jmq_destination_name>.jmqtopic or notifytarget:<jmq_destination_name>.jmqqueue notifytarget:<jmq_destination_name>.priority notifytarget:<jmq_destination_name>.ttl notifytarget:<jmq_destination_name>.persistent
For example:
msconfig set notifytarget:mqdestination1.jmqhost "127.0.0.1"
For details about how to configure these options, see Steps 2 through 10 in "To Configure an Instance of the JMQ Notification Plug-in."
For each different JMQ destination that 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 go to the second destination, add:
mailEventNotificationDestination: messagequeuedestination2
For all users whose notifications go to the third destination, add:
mailEventNotificationDestination: messagequeuedestination3
Set each JMQ configuration option (such as jmqhost) to its specific value. For example:
msconfig set notifytarget:mqdestination2.jmqhost "127.0.0.2"
msconfig set notifytarget:jmqdestination3.jmqhost "127.0.0.3"
and so on for each option.
Restart Messaging Server.
stop-msg start-msg