Defining rules to show a mail app in Outlook 2013
Published: February 26, 2013
You define rules in the manifest XML file of a mail app that determine when the app is shown in Outlook. This topic describes the rules that you can apply.
Applies to: apps for Office | Office 2013 | Office 365 | Exchange 2013 | Outlook 2013 | Outlook Web App
Note
|
|---|
|
Unless otherwise specified, references to "Outlook" apply to the Outlook 2013 rich client and Outlook Web App for Exchange Server 2013. |
In this article
Specifying rules in a manifest
Items supporting activation
Types of rules
Additional resources
Outlook activates a mail app and displays it in the app bar if the currently selected message or appointment item satisfies the activation rules of the mail app.
To use contextual activation, you specify activation rules in the app manifest. First, specify the type of extension, MailApp, in the root element OfficeApp of the manifest:
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforOffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ver=http://schemas.microsoft.com/office/appforoffice/1.0 xsi:type="MailApp">
Then, specify the activation rules. There are two Rule elements that you can use:
-
Rule element (MailApp complexType) (apps for Office) that specifies an individual rule
-
Rule element (RuleCollection complexType) (apps for Office) that combines multiple rules using logical operations
The following table lists the rules that you can use.
|
Rule name |
Applicable Rule element in manifest |
Description |
|---|---|---|
|
Rule element (MailApp complexType) |
Checks to see whether the selected item is of a specified type or class. |
|
|
Rule element (MailApp complexType) |
Checks to see whether the selected item contains an attachment. |
|
|
Rule element (MailApp complexType)
|
Checks to see whether the selected item contains one or more well-known entities. |
|
|
Rule element (MailApp complexType)
|
Checks to see whether the sender's email address, the subject, and/or the body of the selected item contains a match to a regular expression. |
|
|
Rule element (RuleCollection complexType) |
Combines a set of rules so that you can form more complex rules. |
Outlook activates mail apps on only a message or appointment but not other item types. Outlook does not activate mail apps if the currently selected message item is one of the following:
-
Protected by Information Rights Management (IRM).
-
In S/MIME format or encrypted in other ways for protection.
-
A draft (does not have a sender assigned to it), or is in the Outlook Drafts folder.
-
In the Junk Email folder.
-
A delivery report or notification that has the message class IPM.Report.*, including delivery and Non-Delivery Report (NDR) reports, and read, non-read, and delay notifications.
-
A .msg file which is an attachment to another message, or opened from the file system.
The rules to show your mail app are defined as XML complex types. The following sections describe these rules.
|
Note
|
|---|
|
The Rule element that you use to specify an individual rule is of the abstract Rule complex type. Each of the following types of rules extends this abstract Rule complex type. So when you specify an individual rule in a manifest, you must use the xsi:type attribute to specify one of the following types of rules. |
ItemIs rule
The ItemIs complex type defines a rule that evaluates to true if the item is of the specified type. The ItemType simpleType defines the types of Outlook items that support contextual activation of apps, which are also the types you can specify and test for using the ItemType attribute of an ItemIs rule. You can specify the following item types.
|
ItemType value |
Description |
|---|---|
|
Appointment |
Specifies a calendar item. This includes meeting items that have an organizer and attendees, and other appointments that do not have an organizer or attendee and are simply items on the calendar. This corresponds to the IPM.Appointment message class in Outlook. |
|
Message |
Specifies one of the following received items in Read mode:
|
After a mail app is activated, you can use the Mailbox.item property to obtain the currently selected item in Outlook, and the Item.itemType property to obtain the type of the current item.
You can optionally use the ItemClass attribute to specify the message class of the item, and the IncludeSubClasses attribute to specify whether the rule should be true when the item is a subclass of the specified class.
For more information about message classes and activating a mail app in Outlook based on its message class, see Item Types and Message Classes and How to: Activate a mail app in Outlook for a specific message class
The following example shows an ItemIs rule that shows the mail app when the item is message.
<Rule xsi:type="ItemIs" ItemType="Message" />
ItemHasAttachment rule
The ItemHasAttachment complex type defines a rule that checks if the selected item contains an attachment. Note that if you are interested in only a specific item type, for example, messages but not appointments, that contains attachments, then you can combine this rule with an ItemIs rule to form a rule collection to activate your mail app.
The following example shows a rule collection that shows the app if the currently selected item is a message that contains an attachment.
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasAttachment" />
</Rule>
ItemHasKnownEntity rule
Before an item is returned to Outlook, the Exchange server examines it to determine whether the subject and body contain any text that is likely to be one of the known entities. If any of these entities are found, it is placed in a collection of known entities that you access by using the getEntities or getEntitiesByType method of that item.
You can specify a rule by using the ItemHasKnownEntity complex type that shows your mail app when an entity of the specified type is present in the item. You can specify the following known entities in the EntityType attribute of an ItemHasKnownEntity rule:
-
Address
-
Contact
-
EmailAddress
-
MeetingSuggestion
-
PhoneNumber
-
TaskSuggestion
-
URL
These entities are defined as enumerated values in the KnownEntityType simple type.
You can optionally include a regular expression in the RegularExpression attribute so that your mail app is only shown when an entity that matches the regular expression in present. To obtain matches to regular expressions specified in ItemHasKnownEntity rules, you can use the getRegExMatches or getFilteredEntitiesByName method for the currently selected Outlook item.
The following example shows a collection of Rule elements that show the app when one of the specified well-known entities is present in the message.
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="MeetingSuggestion" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="TaskSuggestion" />
</Rule>
The following example shows an ItemHasKnownEntity rule with a RegularExpression attribute that shows an extension when a URL that contains the word "contoso" is present in a message.
<Rule xsi:type="ItemHasKnownEntity" EntityType="Url" RegularExpression="contoso" />
For more information about entities in activation rules, see Using well-known entities in a mail app for Outlook
ItemHasRegularExpressionMatch rule
The ItemHasRegularExpressionMatch complex type defines a rule that uses a regular expression to match the contents of the specified property of an item. If text that matches the regular expression is found in the specified property of the item, Outlook activates and displays the mail app in the app bar. You can use the getRegExMatches or getRegExMatchesByName method of the object that represents the currently selected item to obtain matches for the specified regular expression.
For more information about using the ItemHasRegularExpressionMatch rule, see Using regular expressions to show a mail app in Outlook.
RuleCollection rule
The RuleCollection complex type combines multiple rules into a single rule. You can specify whether the rules in the collection should be combined with a logical OR or a logical AND by using the Mode attribute.
When a logical AND is specified, an item must match all the specified rules in the collection to show the mail app. When a logical OR is specified, an item that matches any of the specified rules in the collection will show the app.
|
Note
|
|---|
|
The Rule element that you use to specify a collection of rules is of the abstract Rule complex type. The RuleCollection complex type extends this abstract Rule complex type. So when you specify a rule collection in a manifest, you must use the xsi:type attribute to specify the RuleCollection complex type. |
You can combine RuleCollection rules to form complex rules. The following example shows the app when either an appointment or a message contains an address.
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemIs" ItemType="Appointment" />
</Rule>
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>
