| Oracle® Mail Administrator's Guide 10g Release 1 (10.1.1) Part Number B14491-03 |
|
|
View PDF |
| Oracle® Mail Administrator's Guide 10g Release 1 (10.1.1) Part Number B14491-03 |
|
|
View PDF |
E-mail servers process and manage extremely large volumes of data because e-mail is typically used for simple collaboration and communication. Increasingly, it is also used for dynamic workflows. The power and simplicity of e-mail adds to its own problems. Employees typically manage many megabytes for stored e-mail, and process hundreds of messages in a typical day or week. With this growth in e-mail, levels of productivity suffer.
The rules engine within Oracle Mail can make the processing of e-mail information more efficient, improving employee productivity. Unlike some e-mail client-based rule technologies, server-side rules operate in the server—and, therefore, do not require a user to be connected to the network—and can be integrated more easily with backend server processes, or business logic. Client-side rules, common with many mail programs, are typically no more than filters for simple filing or deleting of messages based on recipient or subject string attributes. Since they are client-side, they limit users to a single interface—they might not apply, for example, when checking e-mail from an internet terminal, or wireless device. And of course, nothing happens if the user isn't connected and logged in.
Whether the rule is a personal rule, or a system-wide rule not visible to an end-user, the properties of the rule, how it is stored and how it works, are the same. This chapter will show differences between rule types for their conditional processing and possible actions.
This chapter includes the following topics:
Rules allow the creation of conditional actions based on the properties of a message and its processing by the MTA. They can be as simple as a rule created by an end-user to move messages from their boss to a special folder, to more complex rules created by system administrators to perform secondary PL/SQL routines for every message passing through the MTA.
Before defining the components of a server-side rule, consider the typical lifecycle of an e-mail message, as shown in Figure 9-1. First, consider an incoming message sent to the system. It will typically transition through four distinct states, or processes:
Arrival: A message is transported to the system through a Transport Agent and placed in the System Inbox queue for processing (paths 4 and 5 in Figure 9-1)
Delivery: The Delivery Agent processes queue is processed and the system places the message into a recipient's Inbox (paths 6 and 7 in Figure 9-1)
Processed: The message is in a user's workspace and may be filed, copied, or tagged with status flags using the user's e-mail client (path 8 in Figure 9-1)
Deleted: The user deletes the message and the system removes all associated data (path 9 in Figure 9-1)
Outgoing messages are a little more simple because sent messages pass through only two states:
Composed: A user creates a message from their e-mail client and passes it to some Transport Agent through the System Outbox or places it in a queue for processing, when they click Send
Dispatched: The system processes the recipient list for the message and delivers it to its destination
Paths 1, 2, and 3 in Figure 9-1 are events in the lifecycle of an outgoing message.
Each time a message changes from state to state, it can be identified as a specific event, and trigger the rules engine. Conditions and attributes of the messages can then be evaluated, and relevant actions taken. Since the rule is executed in the server, integration with other business logic, for example, is not dependent on a client connection. Rules processing is continuous, 24 hours a day.
Figure 9-1 Lifecycle of an E-mail Message
A server-side rule is a combination of three properties:
An event that triggers the rule
A condition is made up of an expression that resolves to true or false
An action that is performed if the condition is met
The events that trigger rule processing are defined internally within the Oracle Mail server, and they define points in the lifecycle of a message as it is processed through the MTA and managed in the Oracle Collaboration Suite Database.
Events
Events are instants in the lifecycle of a message, defined points in the processing of a message, that enable the rules engine to perform condition testing when they occur.
There are eight basic events where rules can be condition tested.
Relay: When a message is transferred through the MTA to an external location.
Reception: When a message is received by the SMTP Inbound queue before the recipient names are resolved. This is triggered once for each message. This event can only be caught by a system-wide rule. You cannot create a domain-wide or user-level rule with this event because it is triggered before the name resolution.
Deliver: When a message is delivered to a recipient's Inbox, after name resolution. This event is triggered for every recipient of the message.
Flag change: The status of a message changes, such as from unread to read or to marked for deletion.
Copy: When a message is copied to an IMAP folder. Copying to a local folder does not trigger any rule.
Move: When a message moves to another IMAP folder. Moving a message to a local folder sets the deleted flag, meaning that the message is deleted from the IMAP server when the message moves to a local folder.
Expunge: When messages are purged or folders are compacted from the client.
Expire: A message is marked with an expiry date, and during the execution cycle of the Housekeeper server it is determined that this date has passed.
Notice that these events cover most of the significant stages in the normal lifecycle of an e-mail message as it passes in or out of the system and Oracle Collaboration Suite Database. Some events are more applicable to the internal operation of the MTA (such as message relay), while others are more relevant to end-user e-mail management (such as message copy). It will subsequently be described how the context within which the rule is defined (whether it is system-wide, or for an individual user) impacts when the rule can be executed, and the actions it can perform. While there is no difference in the creation or operation of a rule as a result of which context it belongs to, there are some restrictions on the detailed rule definition. User-level rules, for example, cannot be used to check messages as they are relayed by the MTA.
There are three different contexts within which a rule may execute:
System-wide: For all messages in the system regardless of sender or recipient
Domain-wide: For all messages sent to or from one e-mail domain
User: For all messages sent to a specific user. User-level rules typically are used to take actions based on end-user actions, such as message delivery and automatically filing messages.
It is important to note that not all events occur in every context. For example, Relay is a system event, not a user event. End-users cannot create rules that check conditions when messages are relayed, just as they cannot normally view the internal queue status of the mail server in their everyday interaction with the mail system. Conversely, system and domain rules do not have permissions to perform actions that would normally be part of the end-user's interaction with the system, such as copying messages to subfolders of the mail account.
Conditions
A condition determines whether the action for the server-side rule is executed. Conditions can be compounded to support greater flexibility in the invocation of rule actions.
Typically, conditions fall into one of the following categories:
Conditions built using the rule engine expression syntax of operators and attributes
Custom PL/SQL functions loaded into the es_mail schema, that return 0 (if the condition is true) or 1 (if the condition is not true) status
Conditions that perform message body searches
If no condition is present in a rule definition, the action is taken every time the event is triggered.
Expressions
An expression is the logic that determines whether the condition is true or false. It is defined by a special syntax of operators and attributes. If the result of the condition is true, the action is performed, otherwise it is ignored.
The syntax of expressions includes operators such as equals, contains, and istrue. Conditions can also be compounded with logical and, or, and negation, allowing great flexibility. When creating expressions, the rule engine exposes a number of message attributes that can be used to test. Most of these are taken from the message header (such as the sender or subject), or relate to particular attributes of the message (such as the message_id, character set, or flag that is set).
Table 9-1 lists various server-side rule expressions.
Table 9-1 Server-Side Rule Expressions
| Operator | Description |
|---|---|
equal |
Numerical operator that tests whether an attribute is numerically equal to the operand |
greaterthan |
Numerical operator that tests whether an attribute is numerically greater than the operand |
greaterequal |
Numerical operator that tests whether an attribute is numerically greater than or equal to the operand |
lessthan |
Numerical operator that tests whether an attribute is numerically less than the operand |
lessequal |
Numerical operator that tests whether an attribute is numerically less than or equal to the operand |
stringequal |
String operator that tests whether a string attribute is the same as the operand |
startswith |
String operator that tests whether the operand is a prefix of the attribute |
endswith |
String operator that tests whether the operand is a suffix of the attribute |
contains |
String operator that tests whether the operand is a substring of the attribute |
isnull |
String operator that tests whether the attribute value is an empty string (NULL) |
between |
Range operator that requires two operands for lower limit and upper limit |
in |
Range operator that requires one or more operands to form a discreet list and test whether the attribute value is present in the list |
istrue |
Boolean operator that tests whether the attribute value is true or false |
Attributes
Attributes are the set of variables available within the rules engine extracted from the message. They can be used in conditions and, in some cases, for dynamic substitution with rule actions. They loosely fall into two categories: information taken from the message header and status attributes of the message or the rule context, as defined in Table 9-2 and Table 9-3.
Table 9-2 Message Header Attributes
| Attribute | Description |
|---|---|
Rfc822From |
Message from field |
Rfc822to |
Message to field |
Rfc822CC |
Message cc field |
Rfc822Date |
Message date field |
Rfc822Subject |
Message subject field |
Rfc822ReplyTo |
Message replyto field |
Xheader |
Custom extended header |
Sender |
Message sender field |
Recipients |
Expanded recipients |
ReceivedDate |
Internal received date |
ContentType |
MIME content-type from the first MIME body part header |
Charset |
MIME charset header from the first MIME body part header |
Xpriority |
Message Xpriority field from the message header |
Message_id |
Unique identifier for a message |
MessageType |
Identifies messages as e-mail, voice mail, or FAX |
Table 9-3 Message Status Attributes
| Attribute | Description |
|---|---|
MessageSize |
Message size in bytes |
Folder |
Current folder in the processing context |
Flag |
Flag that changed during flagchange event |
OverQuota |
Whether the user account is over quota |
RuleStatus |
Return status of the previous rule |
Sendhost |
Internal |
Actions
An action is the final stage of rule processing after an event and a condition are successfully matched. The product provides a standard set of mail operations, such as forward, copyto, and reject, and is also expandable to allow custom PL/SQL to be integrated as a site-specific rule action.
The possible actions are:
discard: Silently drop the message without delivery, without notifying the sender
reject: Reject the message, notifying the sender of a reason
notify: Send an additional message to some other destination notifying the recipient of this event
Since these actions differ in their functionality, each requires a different set of parameter values. For example, the reply action requires three parameters: a recipient list, a subject field, and a message body.
Table 9-4 lists each action and the associated parameters required by that action.
Table 9-4 Server-Side Rule Actions
| Action | Parameter 1 | Parameter 2 | Parameter 3 | Description |
|---|---|---|---|---|
forward |
recipient |
subject |
message template |
Forwards message to new recipient list using Parameter 2 for subject and Parameter 3 for the message body |
discard |
|
|
|
Silently discards message from system |
bcc |
Bcc recipient |
|
|
Bcc message to new recipient |
pass |
|
|
|
Messages proceed as though no rules have been invoked |
reject |
Reason string |
|
|
Message is rejected, with DSN return to sender. This action can only be invoked under |
moveto |
Folder name |
|
|
Moves message to specified folder |
copyto |
Folder name |
|
|
Copies message to specified folder |
setprop |
Property name |
Property value Value: |
|
Sets following properties of message:
|
notify |
Recipient |
Subject |
Message template |
Notifies recipient in Parameter 1 of event that triggered the rule |
reply |
Duration of reply |
Subject |
Message template |
Replies to sender on event that triggered rule, with reply message constructed from Parameters 2 and 3 |
replyall |
Duration of reply |
Subject |
Message template |
Replies to all recipients on event that triggered rule, with reply message constructed from Parameters 2 and 3 |
break |
|
|
|
Stops subsequent rule processing |
call |
Procedure name |
User-defined |
User-defined |
Calls an external PL/SQL procedure (defined by user) |
Not all actions are available in every context. For example, reject is an action of the SMTP process that is only available in the System context—an end-user cannot tell the system to reject a message; copyto is an action within the user environment, not available to System and Domain rules.
For some actions, the parameters can include variable values generated at runtime by the rules engine. For example, the notify action automatically sends an e-mail to the address specified in the rule. The third parameter to the notify action is a message template string that defines the message body of the notification. When generating this message, values from the triggering e-mail can be extracted by enclosing the attribute name with %...% delimiters. For example:
...
<action>
<command tag="notify" />
<parameter>mailadmin@domain.com</parameter>
<parameter>Notifying you of this event</parameter>
<parameter>Message sent by %rfc822from%</parameter>
</action>
...
This action will notify mailadmin@domain.com when the rule condition is matched and generate a message body including the message's sender.
The call is a special case action allowing a user-defined PL/SQL procedure to be executed. When defining this action, two user-defined parameters are passed to the PL/SQL package. Additionally the system also passes the event ID, mail session ID, and a mail message object to your procedure. Following is an example of the procedure:
procedure myProc(p_eventid in integer,
p_sessionid in integer,
p_msgobj in mail_message_obj,
myparam1 in varchar2,
myparam2 in varchar2,
p_status out number)
The value of p_status should be set to 0 on successful completion, since this may influence subsequent rule events.
This section discusses managing server-side rules, including creation, editing, how rules are stored, and how they are stored.
This section includes the following topics:
There are two ways to create server-side rules: using the oesrl administrative command-line utility, or using an end-user e-mail interface. Only user-level rules can be created with an e-mail interface, but any kind of rule can be created with oesrl.
When using oesrl, there are two input formats for rule creation: XML or a java-style properties file.
This section includes the following topics:
Use the -p option with oesrl to display a set of server-side rules in the native XML format. This output format can be edited to modify or create new rules.
Examples
To list all the rules belonging to user1@domain.com:
$ oesrl –p user1@domain.com
To list all the rules applying to the domain.com domain:
$ oesrl –p domain.com
To list all the rules applying systemwide to all messages:
$ oesrl –p um_system
Entering the command oesrl -x filename loads the server-side rules contained in the filename file. Rule syntax must be correctly provided, or oesrl will report an error. The format of the XML file used by oesrl includes two high level sections:
account: This section defines the qualified name of the rule owner, and the type of rule (system, domain, or user). For example, <account qualifiedName="domain.com" ownerType="domain">.
rulelist: This section defines all the rules that apply for a given event. Within this XML tag, all attributes, conditions, and actions (Table 9-4) will be defined. For example, <rulelist event="deliver">.
In the rulelist section, server-side rules are defined with the rule tag. Each rule contains a condition to check, and an action to perform if the condition evaluates to true. Note that the condition is optional, so it is possible to perform the action for every message by simply omitting the condition clause. Following is a full example XML file that sends a BCC of the message to an administrator when mail is relayed to the yahoo.com domain:
<account qualifiedName="UM_SYSTEM" ownerType="system">
<rulelist event="relay">
<rule description="Rule" group="all" active="yes" visible="yes">
<condition negation="no" junction="and">
<attribute tag="rfc822to"/>
<operator caseSensitive="no" op="contains"/>
<operand>yahoo.com</operand>
</condition>
<action>
<command tag="bcc" />
<parameter>mailadmin@domain.com</parameter>
</action>
</rule>
</rulelist>
</account>
Rules can be set as inactive without physically deleting them by setting active="no". Also, if an administrator has to force an end-user to use a particular rule, it is possible to hide a rule from the Oracle WebMail client by setting active="no".
See Also:
"oesrl" for more examples of server-side rulesTo edit existing rules, or add new rules from the command line, first print existing rules to a file, then edit that file with new rules or modifications. Then reload that file to overwrite the existing rule set.
Note:
Supported e-mail clients can be used to edit user-created rules.Remove the <rule></rule> block from XML file for each rule you want to delete.
Only Oracle WebMail, Oracle Connector for Outlook, and Oracle Web Access Client can be used to create rules because server-side rule syntax is specific to Oracle Mail. These clients can be used to create and manage rules, though, as noted previously, only rules created by end-users can be created this way.
The server-side rule definition is stored internally within Oracle Internet Directory, and normally is not something that needs to be managed. All interaction with rules should be through the published interfaces. Within the LDAP directory information tree (DIT), rules are stored in their XML format alongside the corresponding directory element to which they apply. For example, user-created rules are stored in the Oracle Mail server container part of the DIT with the person to which that the rule belongs. Domain level rules are a sub-entry of the e-mail domain, and system rules sit at the top level of the Oracle Mail DIT.
The following three examples show how each type of rule is stored in the DIT.
System rule:
orclmailrulescope=System_Rule,cn=UM_SYSTEM,cn=EMailServerContainer,cn=Products,cn=OracleContext
Domain rule:
orclmailrulescope=Domain_Rule,dc=oracle,dc=com,cn=UM_SYSTEM,cn=EMailServerContainer,cn=Products,cn=OracleContext
User-created rule:
orclmailrulescope=User_Rule,mail=janed@domain.com,cn=Users,dc=domain,dc=com,cn=UM_SYSTEM,cn=EMailServerContainer,cn=Products,cn=OracleContext
Note:
This DIT location is not formally a public interface and is subject to change in future releases of Oracle Mail. Additionally, dynamic PL/SQL is also created internally to the Oracle Collaboration Suite Database for each rule. It is important to always use published interfaces when modifying rules to ensure future compatibility and prevent corruption of the directory and database schema.Server-side rule execution is a simple sequence. The break action, if present, terminates further rule processing for this event. Apart from this limited control, it is not currently possible to execute certain rules based on previous rules, or execute in a different sequence based on a particular result. In summary, rules are executed:
By context, in the following order:
System
Domain
User
Sequentially, as they are read from Oracle Internet Directory, in the current context
User-created rules execute in the order determined by the creator in the client.
