Using Outlook Addin Activation Rules

Outlook Activation Rules

As part of a larger series, I am building an Outlook Addin using Angular 2. This is proving to be a little more work than expected based on the recent RC-5 changes, but I wanted to get this quick post out since Outlook Addin Activation rules are independent of the client framework you choose to use.

Outlook can activate Addins based on rules that determine if the item the user is viewing meets certain criteria. If the item, in our case an email, satisfies the rules specified, then the Addin will be enabled and the user can choose the addin from the Outlook UI to use it with the current item.

Simple rules are always easy. Most of the samples will show how to define a simple regular expression or well known entity.

<Rule xsi:type="ItemHasKnownEntity" 
    EntityType="EmailAddress" />

The above rule will activate the addin if the item has a valid email address in the subject or the body of the email.

In a more complex scenario, for example an email with very specific criteria, how can we configure more complex rules. For the sample application/addin I am building, I wanted to check for the following in order to enable the Outlook Addin:

• the item must be an email message in read mode
• the item should have an attachment
• the item body should contain an email address
• the item body should contain the specific string "Candidate Name"
• the item body should contain the specific string "Salary and Rate"

In order to create these rules, and ensure that they are all combined properly, the manifest schema for the Addin allows for complex rule collections. The following snippet meets all of the above criteria.

  <Rule xsi:type="RuleCollection" Mode="And">
        <Rule xsi:type="ItemHasAttachment" />
        <Rule xsi:type="RuleCollection" Mode="And">
            <Rule xsi:type="ItemIs"
                        ItemType="Message"
                        FormType="Read"/>
            <Rule xsi:type="ItemHasKnownEntity"
                        EntityType="EmailAddress"/>
            <Rule xsi:type="RuleCollection" Mode="And">
                <Rule xsi:type="ItemHasRegularExpressionMatch" 
                    RegExName="CandidateName" 
                    RegExValue="Candidate Name" 
                    PropertyName="BodyAsHTML" />
                <Rule xsi:type="ItemHasRegularExpressionMatch" 
                    RegExName="CandidateRate" 
                    RegExValue="Salary and Rate" 
                    PropertyName="BodyAsHTML" />
            </Rule>
        </Rule>
    </Rule>

By using the RuleCollection complex type, you can combine the Rule elements using logical operators, the Mode="operator" attributes in the example above. These logical operators enable us to specify a set of logical rules that when combined meet all of our defined criteria.

Here are some of the best resources for the Activation Rules that I have found:

• Activation rules for Outlook add-ins in the Office Dev Center
• Contextual Addins documentation
• Match strings in an Outlook item as well-known entities documentation

HTH - Leave or comment or feedback below. More to come on the Outlook Addin that this is a part of.