Activation rules for contextual Outlook add-ins
Outlook activates some types of add-ins if the message or appointment that the user is reading or composing satisfies the activation rules of the add-in. This is true for all add-ins that use the 1.1 manifest schema. The user can then choose the add-in from the Outlook UI to start it for the current item.
Important
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. The following APIs will also be retired.
- Office.context.mailbox.item.getEntities()
- Office.context.mailbox.item.getEntitiesByType(entityType)
- Office.context.mailbox.item.getFilteredEntitiesByName(name)
- Office.context.mailbox.item.getSelectedEntities()
To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.
- An alternative implementation of the Join Meeting button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join Meeting button.
- Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Use regular expression activation rules to show an Outlook add-in.
For more information, see Retirement of entity-based contextual Outlook add-ins.
Specify activation rules in a manifest
Note
Outlook add-in features that depend on activation rules aren't supported when the add-in uses a Unified manifest for Microsoft 365 (preview).
To have Outlook activate an add-in for specific conditions, specify activation rules in the add-in manifest by using one of the following Rule elements.
- Rule element (MailApp complexType) - Specifies an individual rule.
- Rule element (RuleCollection complexType) - Combines multiple rules using logical operations.
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 further define one of the following types of rules.
For example, the following rule defines an ItemIs rule.
<Rule xsi:type="ItemIs" ItemType="Message" />
The FormType attribute applies to activation rules in the manifest v1.1 but is not defined in VersionOverrides v1.0. So it can't be used when ItemIs is used in the VersionOverrides node.
The following table lists the types of rules that are available. You can find more information following the table and in the specified articles under Create Outlook add-ins for read forms.
| Rule name | Applicable forms | Description |
|---|---|---|
| ItemIs | Read, Compose | Checks to see whether the current item is of the specified type (message or appointment). Can also check the item class and form type.and optionally, item message class. |
| ItemHasAttachment | Read | Checks to see whether the selected item contains an attachment. |
| ItemHasKnownEntity | Read | Checks to see whether the selected item contains one or more well-known entities. More information: Match strings in an Outlook item as well-known entities. |
| ItemHasRegularExpressionMatch | Read | 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.More information: Use regular expression activation rules to show an Outlook add-in. |
| RuleCollection | Read, Compose | Combines a set of rules so that you can form more complex rules. |
ItemIs rule
The ItemIs complex type defines a rule that evaluates to true if the current item matches the item type, and optionally the item message class if it's stated in the rule.
Specify one of the following item types in the ItemType attribute of an ItemIs rule. You can specify more than one ItemIs rule in a manifest. The ItemType simpleType defines the types of Outlook items that support Outlook add-ins.
| Value | Description |
|---|---|
| Appointment | Specifies an item in an Outlook calendar. This includes a meeting item that has been responded to and has an organizer and attendees, or an appointment that does not have an organizer or attendee and is simply an item on the calendar. This corresponds to the IPM.Appointment message class in Outlook. |
| Message | Specifies one of the following items received in typically the Inbox.
|
The FormType attribute is used to specify the mode (read or compose) in which the add-in should activate.
Note
The ItemIs FormType attribute is defined in schema v1.1 and later but not in VersionOverrides v1.0. Do not include the FormType attribute when defining add-in commands.
After an add-in 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, see Item Types and Message Classes.
The following example is an ItemIs rule that lets users see the add-in in the Outlook add-in bar when the user is reading a message.
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
The following example is an ItemIs rule that lets users see the add-in in the Outlook add-in bar when the user is reading a message or appointment.
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
</Rule>
ItemHasAttachment rule
The ItemHasAttachment complex type defines a rule that checks if the selected item contains an attachment.
<Rule xsi:type="ItemHasAttachment" />
ItemHasKnownEntity rule
Before an item is made available to an add-in, the 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 ItemHasKnownEntity that shows your add-in 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
You can optionally include a regular expression in the RegularExpression attribute so that your add-in 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 add-in 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 activates the add-in 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 Match strings in an Outlook item as well-known entities.
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 the add-in bar and displays the add-in. 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.
The following example shows an ItemHasRegularExpressionMatch that activates the add-in when the body of the selected item contains "apple", "banana", or "coconut", ignoring case.
<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
For more information about using the ItemHasRegularExpressionMatch rule, see Use regular expression activation rules to show an Outlook add-in.
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 add-in. When a logical OR is specified, an item that matches any of the specified rules in the collection shows the add-in.
You can combine RuleCollection rules to form complex rules. The following example activates the add-in when the user is viewing an appointment or message item and the subject or body of the item contains an address.
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read"/>
</Rule>
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>
The following example activates the add-in when the user is composing a message, or when the user is viewing an appointment and the subject or body of the appointment contains an address.
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>
</Rule>
Limits for rules and regular expressions
To provide a satisfactory experience with Outlook add-ins, you should adhere to the activation and API usage guidelines. The following table shows general limits for regular expressions and rules but there are specific rules for different applications. For more information, see Limits for activation and JavaScript API for Outlook add-ins and Troubleshoot Outlook add-in activation.
| Add-in element | Guidelines | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Manifest Size | No larger than 256 KB. | |||||||||
| Rules | No more than 15 rules. | |||||||||
| ItemHasKnownEntity | Outlook on Windows and on Mac applies the rule against the first 1 MB of the body, and not to the rest of the body. | |||||||||
| Regular Expressions | For ItemHasKnownEntity or ItemHasRegularExpressionMatch rules for all Outlook applications:
|
See also
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for