General format of ruleset files

This section describes the required overall format of the XML ruleset files.

All ruleset files must be located in the Custom Filter Rules folder, in the main Enterprise Vault folder (typically C:\Program Files\Enterprise Vault) on the computer hosting the archiving tasks that are enabled for custom filtering.

Ruleset files have the following general format:

<?xml version="1.0"?>
<RULE_SET xmlns="x-schema:ruleset schema.xdr">

 <RULE [NAME="rule_name"] [ACTION="match_action"]
   [ATTACHMENT_ACTION="match_action"]
   [CONTENTCATEGORY="content_category"]
   [RETENTION="retention_category"]
   [ARCHIVEID="archiveid"]>

	 <message_attribute [attribute_value_operators]>
	 <attribute_value>
	 [<attribute_value>]
	 </message_attribute>

	 [<message_attribute>... </message_attribute>]
	 
	 [<attachment_attributes> [attribute_value_operator]>
	 <attachment_attribute_values>
	 [<attachment_attribute_values>]
	 </attachment_attributes>]

	 [<attachment_attributes>... </attachment_attributes>]

 </RULE>

 [<RULE> ... </RULE>]
</RULE_SET>

The ruleset can contain one or more rules. Naming a rule (NAME="<rule_name>") is optional. It is advisable to include it for documentation purposes and to distinguish the rule in trace output.

Each rule contains one or more message attribute filters for evaluating messages. A rule may also contain attachment attribute filters for evaluating attachments to messages.

You can use a combination of the following message attributes to select messages:

You can use the following attachment attributes to select specific files attached to messages:

Matching against attribute values is case-insensitive. All message attribute filters in a rule will be applied to a message, so the order of message attribute filters in a rule is not significant. A message matches a rule when it matches all the message attribute filters contained in that rule. When a message matches a rule, the action specified by ACTION= is applied to the message.

If the message attributes satisfy a rule, any attachments are then evaluated using attachment attributes. When an attachment matches a rule, the action specified by ATTACHMENT_ACTION= is applied to the attachment.

Each rule has a message action associated with it. ACTION="<match_action>" defines the action to be applied to the message when it matches a rule. For example, an action could be to mark the item as evaluated but not archive it (ACTION="MARK_DO_NOT_ARCHIVE"). If the action is to archive the item, additional actions can be specified, such as assigning a specific retention category (RETENTION="<retention_category>") or storing the item in a particular archive (ARCHIVEID="<archive_ID>"). If no action is specified, it defaults to "ARCHIVE_ITEM".

The preferred way to specify how messages that match a rule are to be archived is to assign a content category. A content category is a group of settings that are to be applied to an archived item. This can include a retention category, an archive ID and a list of the additional properties that are to be indexed by Enterprise Vault. You define content categories in the file custom properties.xml.

If attachments to messages are to be evaluated, a rule must have an attachment action associated with it; ATTACHMENT_ACTION="<match_action>". If an attachment action is specified, an attachment attribute element ( <FILES> element) must also be present in the rule. This defines the file names or file size (or both) to use when matching attachments. If attachments match the specified attachment filter, the attachment action is performed. Attachments to nested messages are also processed by the filter.

Note:

For messages (and then attachments), each rule in the ruleset file will be evaluated in the order in which it appears in the file and only the first matching rule will be executed. For this reason, it is important to put the highest priority rules first.

More Information

Content categories