JMQ Notification Messages and Properties

h1. JMQ Notification Messages and Properties

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

For related topics on JMQ notification, see the following pages:

Notification messages can be generated for various kinds of events that occur in the message store. For example, when a user logs in, a {{Login}} message can be produced and delivered to the Message Queue broker.

{{MQ_MESSAGE_TYPE_HEADER_PROPERTY}}

The JMQ Notification plug-in supports the messages shown in the following table.

For a list of the {{configutil}} parameters that enable these messages, see [Default Values of the {{configutil}} Parameters|#gcshx].

h4. {anchor:gcsiv} Table 22-1 JMQ Notification Messages
||Notification Message ||Description ||
|{{DeleteMsg}}|Messages marked as “Deleted” are removed from the mailbox. This is the equivalent to IMAP expunge.|
|{{Login}}|User logged in from IMAP, HTTP, or POP. (This message is enabled with the {{configutil}} parameter {{local.store.notifyplugin.*.LogUser.enable}}.)|
|{{Logout}}|User logged out from IMAP, HTTP, or POP. (This message is enabled with the {{configutil}} parameter {{local.store.notifyplugin.*.LogUser.enable}}.)|
|{{MsgFlags}}|Message flags on a message have been changed. The old and new flags are carried with this message.|
|{{NewMsg}}|New message was received by the system into the user’s mailbox. Can contain message headers and body.|
|{{OverQuota}}|Operation failed because the user’s mailbox exceeded one of the quotas (diskquota, msgquota). The MTA channel holds the message until the quota changes or the user’s mailbox count goes below the quota. If the message expires while it is being held by the MTA, it will be expunged.|
|{{PurgeMsg}}|Message expunged (as a result of an expired date) from the mailbox by the server process imexpire. This is a server side expunge, whereas DeleteMsg is a client side expunge. This is not a purge in the true sense of the word.|
|{{ReadMsg}}|Message in the mailbox was read. (In the IMAP protocol, the message was marked Seen.)|
|{{TrashMsg}}|Message was marked for deletion by IMAP or HTTP. The user may still see the message in the folder, depending on the mail client’s configuration. The messages are to be removed from the folder when an expunge is performed.|
|{{UnderQuota}}|Quota went back to normal from OverQuota state.|
|{{UpdateMsg}}|Message was appended to the mailbox by an IMAP operation. For example, the user copied an email message to the mailbox. Can contain message headers and body.|
{anchor:gcsir}

h2. Rules and Guidelines for Notification Messages

The following rules and guidelines apply to the supported notification messages:
* The text of most notification messages is a single blank space. (The blank space is used because Message Queue does not permit an empty message body.) The exceptions are as follows:\\
** The {{NewMsg}}, {{UpdateMsg}}, and {{DeleteMsg}} messages can include a message header when configured with the {{maxHeaderSize}} parameter. You must set {{maxHeaderSize}} to a value greater than zero.\\
To include a message header with a {{DeleteMsg}} message, you also must set the {{ExpungeHeaders}} parameter to a value of {{1}}.\\
** {{NewMsg}} and {{UpdateMsg}} message can include a message body when configured with the {{maxBodySize}} parameter. You must set {{maxBodySize}} to a value greater than zero.\\
For {{NewMsg}} and {{UpdateMsg}}, by default the message body is not delivered (is turned off). This prevents overloading Message Queue. No other messages include a message body.\\
* {anchor:indexterm-2207} Notification messages can be generated for changes to the {{INBOX}} alone, or to the {{INBOX}} and all other folders. The following configuration parameter allows for {{INBOX}} only (value = {{0}}), or for both the {{INBOX}} and all other folders (value = {{1}}):\\
{code}
local.store.notifyplugin._jmqnotify_.noneInbox.enable
{code}
The default setting is to generate messages from the {{INBOX}} only (value = {{0}}).\\
There is no mechanism to select folders; all folders are included when the variable is enabled (value = {{1}}).\\
* The {{NewMsg}} notification is issued only after the message is deposited in the user mailbox (as opposed to “after it was accepted by the server and queued in the message queue”).\\
* Messages are not generated for POP3 client access.\\
* All messages can be suppressed by issuing {{XNOTNOTIFY}}. For example, an IMAP script used for housekeeping only (the users are not meant to be notified) might issue it to suppress all messages.\\{anchor:gcshb}

h2. Notifications for Particular Message Types

Notifications can deliver status information about messages of different types, such as text messages, voice mail, and image data. Users often expect these heterogeneous message types to be stored in the same mail folder. For example, a user may want new text messages and voice mail to arrive in the user's cell phone inbox.

To configure these message types, you use {{configutil}} commands such as {{store.messagetype.enable}}. For information about configuring and managing message types, see “Managing Message Types” in “Chapter 18: Managing the Message Store.”

Once the message types have been configured, JMQ notification messages can identify the particular message types. You can write your Message Queue client to interpret notification messages by message type and deliver status information about each type to the mail client.

For example, suppose new messages of different types arrive in a user's mailbox. A {{NewMsg}} notification message can carry data to tell the user that, for example, there are seven new voice mail messages and four new text messages in the user's inbox.

The following notification messages can carry information that tracks particular message types:
{code}
NewMsg
UpdateMsg
ReadMsg
TrashMsg
DeleteMsg
PurgeMsg
OverQuota
UnderQuota
{code}

The JMQ notification function counts the number of messages currently in the mailbox, by message type. Instead of sending one count, an array specifying the count for each message type is sent with the notification message.

The message-specific count is carried in the {{numMsgs}} property and delivered with the notification message. For {{ReadMsg}} and {{TrashMsg}} notification messages, the number of messages seen ({{numSeen}}) and the number marked as deleted ({{numDeleted}}) are also counted by message type.
{info:title=Note - }The Event Notification Service does not support message types. Use a JMQ notification plug-in to deliver information about message types.\\
{info}
{anchor:gcshx}

h2. Default Values of the {{configutil}} Parameters{anchor:indexterm-2208} {anchor:indexterm-2209}

The notification messages and the configuration information needed by Message Queue are configured with {{configutil}} parameters.

[Table 22-2|#gcsin] shows these parameters and their default values.

For complete definitions of the {{configutil}} parameters, see [Messaging Server Configuration].

h4. {anchor:gcsin} Table 22-2 {{configutil}} Parameters and Their Default Values

||{{configutil}} Parameter ||Default Value ||
|{{local.store.notifyplugin.*.maxBodySize}}|0 — Disabled|
|{{local.store.notifyplugin.*.maxHeaderSize}}|0 — Disabled|
|{{local.store.notifyplugin.*.NewMsg.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.UpdateMsg.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.ReadMsg.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.DeleteMsg.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.PurgeMsg.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.LogUser.enable}}|1 — Enabled|
|{{local.store.notifyplugin.*.MsgFlags.enable}}|0 — Disabled|
|{{local.store.notifyplugin.*.noneInBox.enable}}|0 — Disabled|
|{{local.store.notifyplugin.*.jmqHost}}|“127.0.0.1”|
|{{local.store.notifyplugin.*.jmqPort}}|7676|
|{{local.store.notifyplugin.*.jmqTopic}}|“JES-MS”|
|{{local.store.notifyplugin.*.jmqQueue}}|“JES-MS”|
|{{local.store.notifyplugin.*.jmqUser}}|“guest”|
|{{local.store.notifyplugin.*.jmqPwd}}|“guest”|
|{{local.store.notifyplugin.*.destinationtype}}|“topic”|
|{{local.store.notifyplugin.*.Priority}}|4|
|{{local.store.notifyplugin.*.ttl}}|0 — Indicates that messages never time out.|
|{{local.store.notifyplugin.*.Persistent}}|1 — Enabled|
|{{local.store.notifyplugin.*.enabled}}|1 — Turned on by default.|
|{{local.store.notifyplugin.*.ldapdestination}}|null — Turned off by default.|
{anchor:gcshk}

h2. Notification Message Properties{anchor:indexterm-2210}

Every message carries additional information defined in properties. Different properties are present for different messages. For example, {{NewMsg}} indicates the IMAP {{uid}} of the new message.{anchor:gcsit}

h3. Standard Notification Message Properties

[Table 22-3|#gcshi] describes the standard notification message properties. These properties are present in all JMS messages.

h4. {anchor:gcshi} Table 22-3 Standard Notification Message Properties
||Property ||Data Type ||Description ||
|{{hostname}}|ConstMQString|The host name of the machine that generated the message.|
|{{pid}}|MQInt32|ID of the process that generated the message.|
|{{process}}|ConstMQString|Specifies the name of the process that generated the message.|
|{{timestamp}}|MQFloat64|Specifies the number of milliseconds since the epoch (midnight GMT, January 1, 1970).|
{anchor:gcsil}

h3. Properties Specific to Particular Notification Messages

[Table 22-4|#gcsig] describes the properties carried with particular notification messages.

Each message includes a subset of the properties shown in the table below. For a list of the properties associated with each message, see [Table 22-5|#gcsjr].

h4. {anchor:gcsig} Table 22-4 Properties Specific to Particular Notification Messages
||Property ||Data Type ||Description ||
|{{client}}|ConstMQString|The IP address of the Message Queue client associated with the message.|
|{{diskquota}}|MQInt32|The disk space quota, in kilobytes, for the user associated with the message. The value is set to -1 to indicate no quotas.|
|{{diskquotaused}}|MQInt32|The amount of disk space used by the user associated with the message, in kilobytes.|
|{{hdrLen}}|MQInt32|The size of the message header. Note that this might not be the size of the header in the message body, because it might have been truncated.|
|{{imapUid}}|MQInt32|The IMAP uid property associated with the message.|
|{{lastUid}}|MQInt32|The last IMAP uid value used in the mailbox.|
|{{mailboxName}}|ConstMQstring|The message-store mailbox name associated with the event. The mailboxName has one of the following formats (where {{uid}} is the user's unique identifier):{{uid}} — identifies the inbox of a user in the default (primary) domain.{{uid@domain}} — identifies the inbox of a user in a hosted domain.{{uid/mailboxname}} — identifies the top-level mailbox of a user in the default domain.{{uid@domain/mailboxname}} — identifies the top-level mailbox of a user in a hosted domain.{{uid/foldername/mailboxname}} — identifies a mailbox in a folder of a user in the default domain.{{uid@domain/foldername/mailboxname}} — identifies a mailbox in a folder of a user in a hosted domain.|
|{{msgquota}}|MQInt32|The user's quota for the maximum number of messages. The value is set to -1 to indicate no quotas.|
|{{newflags}}|ConstMQString|The flags set for the user's mailbox message after they were changed by the current operation. This property is always present, together with {{oldflags}}, when a {{MsgFlags}} notification message is produced. For the syntax and values for {{newflags}}, see [Syntax for newflags and oldflags Properties|#gcsik], below this table.|
|{{numDeleted}}|MQInt32|The number of messages in the mailbox marked as deleted. This number counts the messages deleted by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as {{DeleteMsg}}).|
|{{numDeleted}}_nn_|MQInt32|The total number of messages in the mailbox marked as deleted, specified for each message type. If message types are configured, a {{numDeleted}}_nn_ property carries a count for each message type _nn_. The {{numDeleted}} property is always sent; it counts the total number of all messages marked as deleted, including all types.For example, if 20 messages are marked as deleted, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: {{numDeleted=20}}{{numDeleted3=10}}{{numDeleted16=7}}|
|{{numMsgs}}|MQInt32|The total number of messages now in the mailbox.|
|{{numMsgs}}_nn_|MQInt32|The total number of messages now in the mailbox, specified for each message type. If message types are configured, a {{numMsgs}}_nn_ property carries a count for each message type _nn_. The {{numMsgs}} property is always sent; it counts the total number of all messages in the mailbox, including all types.For example, if 20 messages are currently in the mailbox, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: {{numMsgs=20}}{{numMsgs3=10}}{{numMsgs16=7}}|
|{{numSeen}}|MQInt32|The number of messages in the mailbox marked as seen (read).This number counts the messages read by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as {{ReadMsg}}). |
|{{numSeen}}_nn_|MQInt32|The total number of messages in the mailbox marked as seen (read), specified for each message type. If message types are configured, a {{numSeen}}_nn_ property carries a count for each message type _nn_. The {{numSeen}} property is always sent; it counts the total number of all messages marked as seen, including all types.For example, if 20 messages are marked as seen, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: {{numSeen=20}}{{numSeen3=10}}{{numSeen16=7}}|
|{{numSeenDeleted}}|MQInt32|The number of messages in the mailbox marked as seen (read) and marked as deleted.This number counts the messages marked as read and deleted by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as {{ReadMsg}}and {{DeleteMsg}}). |
|{{numSeenDeleted}}_nn_|MQInt32|The total number of messages in the mailbox marked as seen (read) and marked as deleted, specified for each message type. If message types are configured, a {{numSeenDeleted}}_nn_ property carries a count for each message type _nn_.The {{numSeenDeleted}} property is always sent; it counts the total number of all messages marked as seen and deleted, including all types.For example, if 20 messages are marked as seen and deleted, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: {{numSeenDeleted=20}}{{numSeenDeleted3=10}}{{numSeenDeleted16=7}}|
|{{oldflags}}|ConstMQString|The flags set for the user's mailbox message before they were changed by the current operation. This property is always present, together with {{newflags}}, when a {{MsgFlags}} notification message is produced. For the syntax and values for {{oldflags}}, see [Syntax for newflags and oldflags Properties|#gcsik], below this table.|
|{{quotaRoot}}|ConstMQString|This can be a user name, folder name, or message type.|
|{{size}}|MQInt32|The size of the message. Note that this may not be the size of message body, since the body is typically a truncated version of the message.|
|{{uidValidity}}|MQInt32|The IMAP uid validity property.|
|{{userid}}|ConstMQString|The userid associated with the message.|

{info:title=Note - }Subscribers should allow for undocumented properties when parsing the message reference. This allows for future compatibility when new properties are added.\\
{info}
{anchor:gcsik}

h4. Syntax for newflags and oldflags Properties

The {{newflags}} and {{oldflags}} properties are 5–character strings. The string must have the following values:
* If the /answered flag is set, the first character is {{"A"}}. If not, it is blank (“ “).\\
* If the /flagged flag is set, the second character is {{"F"}}. If not, it is blank (“ “).\\
* If the /deleted flag is set, the third character is {{"D"}}. If not, it is blank (“ “).\\
* If the /seen flag is set, the fourth character is {{"S"}}. If not, it is blank (“ “).\\
* If the /draft flag is set, the fifth character is {{"R"}}. If not, it is blank (“ “).\\{anchor:gcsii}

h3. Properties Carried with Each Notification Message{anchor:indexterm-2211}

[Table 22-5|#gcsjr] shows the properties associated with each notification message.

For example, to see which properties apply to a {{TrashMsg}} message, look in the column header for “ReadMsg, TrashMsg.” A {{TrashMsg}} message can use {{mailboxName}}, {{numMsgs}}, {{uidValidity}}, {{numSeen}}, and {{numDeleted}} (in addition to the standard properties).

h4. {anchor:gcsjr} Table 22-5 Properties Carried with Each Notification Message
||Property ||NewMsg, UpdateMsg ||ReadMsg, TrashMsg ||DeleteMsg, PurgeMsg ||MsgFlags ||Login, Logout ||OverQuota, UnderQuota ||
|{{client}}|No|No|No|No|Yes|No|
|{{diskquota}}|No|No|No|No|No|Yes|
|{{diskquotaused}}|No|No|No|No|No|Yes|
|{{hdrLen}}|Yes|No|No|Yes|No|No|
|{{hostname}}|Yes|Yes|Yes|Yes|Yes|Yes|
|{{imapUid}}|Yes|No|Yes|Yes|No|No|
|{{lastUid}}|No|No|Yes|No|No|No|
|{{mailboxName}}|Yes|Yes|Yes|Yes|No|No|
|{{msgquota}}|No|No|No|No|No|Yes|
|{{newflags}}|No|No|No|Yes|No|No|
|{{numDeleted}}|Yes|Yes|Yes|No|No|No|
|{{numDeleted}}_n_|Yes*|Yes*|Yes*|No|No|No|
|{{numMsgs}}|Yes|Yes|Yes|No|No|Yes|
|{{numMsgs}}_n_|Yes*|Yes*|Yes*|No|No|No|
|{{numSeen}}|Yes|Yes|Yes|No|No|No|
|{{numSeen}}_n_|Yes*|Yes*|Yes*|No|No|No|
|{{numSeenDeleted}}|Yes|Yes|Yes|No|No|No|
|{{numSeenDeleted}}_n_|Yes*|Yes*|Yes*|No|No|No|
|{{oldflags}}|No|No|No|Yes|No|No|
|{{Owner}}|No|Yes|No|No|No|No|
|{{pid}}|Yes|Yes|Yes|Yes|Yes|Yes|
|{{process}}|Yes|Yes|Yes|Yes|Yes|Yes|
|{{quotaRoot}}|No|No|No|No|No|Yes|
|{{size}}|Yes|No|No|No|No|No|
|{{timestamp}}|Yes|Yes|Yes|Yes|Yes|Yes|
|{{uidValidity}}|Yes|Yes|Yes|Yes|No|No|
|{{userid}}|No|Yes|No|No|Yes|Yes|

{info:title=Note - }* The {{numDeleted}}_n_, {{numMsgs}}_n_, {{numSeen}}_n_, and {{numSeenDeleted}}_n_ properties are carried with notifications only if message types are defined in the message store.\\
{info}