This information describes JMQ notification messages and their properties.
This page contains the following topics:
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.
An msconfig option specifies each kind of message to be produced. You determine which events generate messages by configuring various options. The options are referenced by one or more JMQ Notification targets.
All messages are delivered to a topic or a queue, depending on whether the destination type is set to topic or queue. For information on how to configure the Message Queue destination, see "To Configure an Instance of the JMQ Notification Plug-in."
Each message is identified by the following message header:
MQ_MESSAGE_TYPE_HEADER_PROPERTY
The JMQ Notification plug-in supports the messages shown in Table 48-1.
For a list of the options that enable these messages, see Table 48-2, "notifytarget Options and Their Default Values".
Table 48-1 JMQ Notification Messages
| Notification Message | Description |
|---|---|
|
deletemsg |
Messages marked as "Deleted" are removed from the mailbox. This is the equivalent to IMAP expunge. |
|
expungemsg |
Messages are expunged from the mailbox. |
|
login |
User logged in from IMAP, HTTP, or POP. (This message is enabled with the notifytarget:*.loguser option.) |
|
logout |
User logged out from IMAP, HTTP, or POP. (This message is enabled with the notifytarget:*.loguser option.) |
|
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 is 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. |
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 expungemsg messages can include a message header when configured with the maxheadersize option. You must set maxheadersize to a value greater than zero.
newmsg and updatemsg messages can include a message body when configured with the maxbodysize option. 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.
Notification messages can be generated for changes to the INBOX alone, or to the INBOX and all other folders. The following option allows for INBOX only (value = 0), or for both the INBOX and all other folders (value = 1):
notifytarget:<jmqnotify>.noninbox
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.
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 options such as store.messagetype.enable. For information about configuring and managing message types, see "Managing Message Types in 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:
newmsg updatemsg readmsg trashmsg deletemsg purgemsg overquota underquota
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.
Note:
The Event Notification Service does not support message types. Use a JMQ notification plug-in to deliver information about message types.You can set separate notifytarget configuration options, including sending events to a different JMQ host, port, or type, on a per-messagetype basis. When doing so, do not create a per-message type instance, as it is created automatically based on the base instance. You only need to set the options you want to override from the base instance.
For example, assume that you want to use per-messagetype settings and your notifytarget configuration is the following:
notifytarget = /opt/sun/comms/messaging64/lib/libjmqnotify$msgjmqnotify
To set this configuration, you need to put the value in quotes to prevent the "$" from being interpreted by the shell. Be sure to double check the configuration after setting it.
The options for that base instance would be of the form:
notifytarget.msgjmqnotify.<option-name> = <option-value>
To override the notifytarget handling of type 1 messages, use options of the form:
notifytarget.msgjmqnotify.1.<option-name> = <option-value>
Even though there is no "msgjmqnotify.1" instance created explicitly in the notifytarget option, it is created automatically from the "msgjmqnotify" instance because messagetype 1 is defined. The notifytarget.msgjmqnotify.1.option-name settings are used to override the corresponding options from the notifytarget.msgjmqnotify.option-name settings.
The notification messages and the configuration information needed by Message Queue are configured with the options shown in Table 48-2. For complete definitions of the options, see the Messaging Server Reference.
Table 48-2 notifytarget Options and Their Default Values
| Option | Default Value |
|---|---|
|
notifytarget:*.annotatemsg |
0 — Disabled |
|
notifytarget:*.changeflag |
0 — Disabled |
|
notifytarget:*.copymsg |
0 — Disabled |
|
notifytarget:*.deletemsg |
1 — Enabled |
|
notifytarget:*.destinationtype |
"topic" |
|
notifytarget:*.enabled |
1 — Turned on by default |
|
notifytarget:*.expungemsg |
0 — Disabled |
|
notifytarget:*.jmqhost |
"127.0.0.1" |
|
notifytarget:*.jmqport |
7676 |
|
notifytarget:*.jmqpwd |
"guest" |
|
notifytarget:*.jmqqueue |
"JES-MS" |
|
notifytarget:*.jmqtopic |
"JES-MS" |
|
notifytarget:*.jmquser |
"guest" |
|
notifytarget:*.ldapdestination |
null — Turned off by default |
|
notifytarget:*.loguser |
1 — Enabled |
|
notifytarget:*.maxbodysize |
0 — Disabled |
|
notifytarget:*.maxheadersize |
0 — Disabled |
|
notifytarget:*.msgflags |
0 — Disabled |
|
notifytarget:*.msgtypes |
0 — Disabled |
|
notifytarget:*.newmsg |
1 — Enabled |
|
notifytarget:*.noninBox |
0 — Disabled |
|
notifytarget:*.overquota |
1 — Enabled |
|
notifytarget:*.persistent |
1 — Enabled |
|
notifytarget:*.priority |
4 |
|
notifytarget:*.purgemsg |
1 — Enabled |
|
notifytarget:*.readmsg |
1 — Enabled |
|
notifytarget:*.ttl |
0 — Indicates that messages never time out |
|
notifytarget:*.underquota |
1 — Enabled |
|
notifytarget:*.updatemsg |
1 — Enabled |
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.
Table 48-3 describes the standard notification message properties. These properties are present in all JMS messages.
Table 48-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). |
Table 48-4 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 48-5, "Properties Carried with Each Notification Message".
Table 48-4 Properties Specific to Particular Notification Messages
| Property | Data Type | Description |
|---|---|---|
|
attrn |
ConstMQString |
Annotation attribute name. |
|
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. |
|
entryn |
ConstMQString |
Annotation entry name. |
|
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. |
|
msgflags |
ConstMQString |
List of current message flags. |
|
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," 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). |
|
numDeletednn |
MQInt32 |
The total number of messages in the mailbox marked as deleted, specified for each message type. If message types are configured, a numDeletednn 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=20numDeleted3=10numDeleted16=7 |
|
numMsgs |
MQInt32 |
The total number of messages now in the mailbox. |
|
numMsgsnn |
MQInt32 |
The total number of messages now in the mailbox, specified for each message type. If message types are configured, a numMsgsnn 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=20numMsgs3=10numMsgs16=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). |
|
numSeennn |
MQInt32 |
The total number of messages in the mailbox marked as seen (read), specified for each message type. If message types are configured, a numSeennn 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=20numSeen3=10numSeen16=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). |
|
numSeenDeletednn |
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 numSeenDeletednn 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=20numSeenDeleted3=10numSeenDeleted16=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," 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. |
|
uidlist |
ConstMQString |
List of UIDs. |
|
uidValidity |
MQInt32 |
The IMAP uid validity property. |
|
userid |
ConstMQString |
The userid associated with the message. |
Note:
Subscribers should allow for undocumented properties when parsing the message reference. This allows for future compatibility when new properties are added.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 (" ").
Table 48-5 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).
Table 48-5 Properties Carried with Each Notification Message
| Property | newmsg, copymsg, updatemsg | readmsg, trashmsg | deletemsg, purgemsg | msgflags | login, logout | overquota, underquota | changeflag | annotatemsg | expungemsg | create | delete | rename |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
attrn |
No |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
|
client |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
No |
|
diskquota |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
|
diskquotaused |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
|
entryn |
No |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
|
fromUidValidity |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
Yes |
No |
Yes |
|
hdrLen |
Yes |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
|
hostname |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
|
imapUid |
Yes |
No |
Yes |
Yes |
No |
No |
No |
Yes |
No |
No |
No |
No |
|
lastUid |
No |
No |
Yes |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
|
mailboxName |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
Yes |
No |
Yes |
Yes |
Yes |
|
modseq |
No |
No |
No |
No |
No |
No |
Yes |
Yes |
Yes |
No |
No |
No |
|
msgflags |
No |
No |
No |
No |
No |
Yes |
Yes |
No |
No |
No |
No |
No |
|
msgquota |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
|
newflags |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
|
newName |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
Yes |
|
numDeleted |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numDeletedn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numMsgs |
Yes |
Yes |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
No |
|
numMsgsn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numSeen |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numSeenn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numSeenDeleted |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
numSeenDeletedn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
oldflags |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
|
operation |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
|
Owner |
No |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
peruser_flags |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
|
pid |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
|
process |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
|
quotaRoot |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
No |
|
size |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
system_flags |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
|
timestamp |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
|
uidlist |
No |
No |
No |
No |
No |
No |
Yes |
No |
Yes |
No |
No |
No |
|
uidValidity |
Yes |
Yes |
Yes |
Yes |
No |
No |
Yes |
No |
Yes |
Yes |
No |
Yes |
|
unchangedsince |
No |
No |
No |
No |
No |
No |
Yes |
No |
No |
No |
No |
No |
|
userid |
No |
Yes |
No |
No |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
Note:
The numDeletedn, numMsgsn, numSeenn, and numSeenDeletedn properties are carried with notifications only if message types are defined in the message store.