Rule element
Specifies the activation rules that should be evaluated for this contextual mail add-in.
Add-in type: Mail (contextual)
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.
Contained in
Attributes
Attribute | Required | Description |
---|---|---|
xsi:type | Yes | The type of rule being defined. |
The type of rule can be one of the following:
ItemIs rule
Defines a rule that evaluates to true if the selected item is of the specified type.
Attributes
Attribute | Required | Description |
---|---|---|
ItemType | Yes | Specifies the item type to match. Can be Message or Appointment . Message item type includes email, meeting requests, meeting responses, and meeting cancellations. |
FormType | No (within ExtensionPoint), Yes (within OfficeApp) | Specifies whether the app should appear in read or edit form for the item. Can be one of the following: Read , Edit , ReadOrEdit . If specified on a Rule within an ExtensionPoint , this value MUST be Read . |
ItemClass | No | Specifies the custom message class to match. For more information, see Activate a mail add-in in Outlook for a specific message class. |
IncludeSubClasses | No | Specifies whether the rule should evaluate to true if the item is of a subclass of the specified message class; the default is false . |
Example
<Rule xsi:type="ItemIs" ItemType= "Message" />
ItemHasAttachment rule
Defines a rule that evaluates to true if the item contains an attachment.
Example
<Rule xsi:type="ItemHasAttachment" />
ItemHasKnownEntity rule
Defines a rule that evaluates to true if the item contains text of the specified entity type in its subject or body.
Attributes
Attribute | Required | Description |
---|---|---|
EntityType | Yes | Specifies the type of entity that must be found for the rule to evaluate to true. Can be one of the following: MeetingSuggestion , TaskSuggestion , Address , Url , PhoneNumber , EmailAddress , or Contact . |
RegExFilter | No | Specifies a regular expression to run against this entity for activation. |
FilterName | No | Specifies the name of the regular expression filter, so that it is subsequently possible to refer to it in your add-in's code. |
IgnoreCase | No | Specifies whether to ignore case when matching the regular expression specified by the RegExFilter attribute. |
Highlight | No | Note: this only applies to <Rule> elements within <ExtensionPoint> elements. Specifies how the client should highlight matching entities. Can be one of the following: all or none . If not specified, the default value is all . |
Example
<Rule xsi:type="ItemHasKnownEntity" EntityType="EmailAddress" />
ItemHasRegularExpressionMatch rule
Defines a rule that evaluates to true if a match for the specified regular expression can be found in the specified property of the item.
Attributes
Attribute | Required | Description |
---|---|---|
RegExName | Yes | Specifies the name of the regular expression, so that you can refer to the expression in the code for your add-in. |
RegExValue | Yes | Specifies the regular expression that will be evaluated to determine whether the mail add-in should be shown. |
PropertyName | Yes | Specifies the name of the property that the regular expression will be evaluated against. Can be one of the following: Subject , BodyAsPlaintext , BodyAsHTML , or SenderSMTPAddress .If you specify BodyAsHTML , Outlook only applies the regular expression if the item body is HTML. Otherwise, Outlook returns no matches for that regular expression.If you specify BodyAsPlaintext , Outlook always applies the regular expression on the item body.Important: If you need to specify the Highlight attribute for the <Rule> element, you must set the PropertyName attribute to BodyAsPlaintext . |
IgnoreCase | No | Specifies whether to ignore case when matching the regular expression specified by the RegExName attribute. |
Highlight | No | Specifies how the client should highlight matching text. This attribute can only be applied to <Rule> elements within <ExtensionPoint> elements. Can be one of the following: all or none . If not specified, the default value is all .Important: To specify the Highlight attribute in the <Rule> element, you must set the PropertyName attribute to BodyAsPlaintext . |
Example
<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="SupportArticleNumber" RegExValue="(\W|^)kb\d{6}(\W|$)" PropertyName="BodyAsPlaintext" IgnoreCase="true" Highlight="all" />
RuleCollection
Defines a collection of rules and the logical operator to use when evaluating them.
Attributes
Attribute | Required | Description |
---|---|---|
Mode | Yes | Specifies the logical operator to use when evaluating this rule collection. Can be either: And or Or . |
Example
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="MeetingSuggestion" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" Highlight="none" />
</Rule>
See also
Office Add-ins
Feedback
https://aka.ms/ContentUserFeedback.
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:Submit and view feedback for