Export (0) Print
Expand All

Activate mail apps in Outlook clients

apps for Office

Learn how to define activation rules in a mail app manifest file to specify the context where Outlook would display the app in the UI.

Last modified: August 14, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
Activation in a compose or read scenario
Items supporting activation
Specifying activation rules in a manifest
ItemIs rule
ItemHasAttachment rule
ItemHasKnownEntity rule
ItemHasRegularExpressionMatch rule
RuleCollection rule
Additional resources

Outlook activates a mail app and displays it in the Outlook UI if the message or appointment item that the user is composing or reading satisfies the activation rules of the mail app. The user can then choose the app in the Outlook UI to start it for the current item.

The location in the UI that Outlook displays an activated mail app depends on the following:

  • The version of the schema for apps for Office manifests that the mail app uses.

  • The type of form that the mail app is activated in.

Using schema v1.0, you can have Outlook activate mail apps in only read forms, and Outlook always displays the activated mail app in the app bar. Starting with schema v1.1, you can have Outlook activate mail apps in compose or read forms. In a compose form, when you choose the Apps for Office button in the ribbon, the app selection pane opens and displays the activated compose apps. Figure 1 shows the Apps for Office button and an example of mail apps activated in the app selection pane for the message in an inline compose form in the background. Figure 2 shows mail apps activated in the app bar for the message in the Reading Pane.

Figure 1. The app selection pane showing 2 mail apps activated for the message in an inline compose form

Templates mail app activated for composed item
Figure 2. The app bar showing 2 mail apps activated for the message in the Reading Pane read form

App bar showing activated read mail apps

See the following sections for more information on the specific user scenarios where compose and read apps can activate:

Outlook activates mail apps on only a message or appointment but not other item types. Outlook does not activate mail apps if the current message item, in a compose or read form, is one of the following:

  • Protected by Information Rights Management (IRM), in S/MIME format or encrypted in other ways for protection. A digitally signed message is an example since digital signing relies on one of these mechanisms.

  • 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.

  • A .msg file opened from the file system.

In general, Outlook can activate mail apps in read forms for items in the Sent Items folder, with the exception of mail apps that activate based on string matches of well-known entities. For more information about the reasons behind this, see Support for well-known entities.

To use contextual activation and have Outlook activate a mail app for the appropriate type of form and other specific conditions, specify activation rules in the app manifest. First, specify the type of app, MailApp, in the root element OfficeApp of the manifest:

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforOffice/1.1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="MailApp">

Then, specify the activation rules. There are two Rule elements that you can use:

NoteNote

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" FormType = "Compose" ItemType="Message" />

The types of rules that you can use depends on the type of forms – compose or read – that you intend your app to be activated in. Do you want your app to be available when the user is creating a message or appointment, or composing a response? Do you want it available when the user is reading a message or appointment? How about in both compose and read scenarios? Table 1 lists the rules that you can choose for compose or read forms. You can find more information following the table, and for rules applicable to only read scenarios, in the specified articles under Create mail apps for read forms in Outlook.

Table 1. Types of rules available in compose or read forms

Rule name

Applicable types of forms

Description

ItemIs

Compose forms: matches item to form type and item type.

Read forms: matches item to form type, item type and item message class.

Checks to see whether the current item is opened in the specified type of form (compose or read), is of the specified type (message or appointment), and optionally, item message class.

For schema v1.0, checks to see whether the selected item is of the specified item type or class. Outlook activates mail apps that use schema v1.0 in only read forms.

More information for read forms: How to: Activate a mail app in Outlook for a specific message class.

ItemHasAttachment

Read forms

Checks to see whether the selected item contains an attachment.

ItemHasKnownEntity

Read forms

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 forms

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 a mail app in Outlook.

RuleCollection

Compose or read forms

Combines a set of rules so that you can form more complex rules.

The ItemIs complex type defines a rule that evaluates to true if the current item is opened in the specified type of form (read or compose) and is of the specified item type (message or appointment). Note that if the user is in a compose form, the ItemIs rule matches only the form type and item type. If the user is in a read form, the ItemIs rule matches the form type and item type, and optionally the item message class if it’s stated in the rule. If you intend your mail app to be activated in compose forms, you must use an ItemIs rule. If you don’t specify an ItemIs rule, Outlook assumes this as equivalent to an ItemIs rule that activates in only read forms of messages or appointments.

You can specify one of the following form types in the FormType attribute of an ItemIs rule. The ItemFormType simpleType defines the types of Outlook forms in which Outlook would activate a mail app.

FormType value

Description

Read

Specifies the mail app to be activated in only read forms (of the specified ItemType).

Edit

Specifies the mail app to be activated in only compose forms (of the specified ItemType).

ReadOrEdit

Specifies the mail app to be activated in read and compose forms (of the specified ItemType).

Note Note

For mail apps that use schema v1.0, ItemIs rules evaluate to true for only read forms, and, if the selected item is of the specified item type or class. Do not include the FormType attribute as that attribute is not defined in schema v1.0.

Specify one of the following item types in the ItemType attribute of an ItemIs rule. You can specify more than one ItemType rule in a manifest. The ItemType simpleType defines the types of Outlook items that support mail apps.

ItemType value

Description

Appointment

In compose mode, specifies an invitation that is being authored and has not been sent. This item is in the Drafts folder, and if the user saves it, it is in the Calendar folder as well. (After the item is sent, Outlook saves the item as an appointment in the organizer's Calendar, and also creates a meeting request item in the organizer's Sent Items folder. That item has the message class IPM.Schedule.Meeting.Request.)

In read mode, specifies an item in an Outlook calendar. This includes an invitation that has been sent, 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

In compose mode, specifies a message in the Drafts folder, with the IPM.Note message class.

In read mode, specifies one of the following items received in typically the Inbox:

  • An email message. This corresponds to the IPM.Note message class in Outlook.

  • A meeting request, response, or cancellation. This corresponds to the following message classes in Outlook:

    IPM.Schedule.Meeting.Request

    IPM.Schedule.Meeting.Neg

    IPM.Schedule.Meeting.Pos

    IPM.Schedule.Meeting.Tent

    IPM.Schedule.Meeting.Canceled

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 is an ItemIs rule that lets users see the mail app in the Outlook app bar when the user is reading a message:

<Rule xsi:type="ItemIs" FormType = "Read" ItemType="Message" />

If your mail app uses schema v1.0, do not specify the FormType attribute. Specify the rule as follows:

<Rule xsi:type="ItemIs" ItemType="Message" />

The following example is an ItemIs rule that lets users see the mail app in the Outlook app bar when the user is reading a message, or in the Outlook app selection pane when the user is composing a message:

<Rule xsi:type="ItemIs" FormType="ReadOrEdit" ItemType="Message" />

The following example is an ItemIs rule that lets users see the mail app in the Outlook app bar when the user is reading a message or appointment, or in the Outlook app selection pane when the user is composing a message or appointment:

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" FormType="ReadOrEdit" ItemType="Message" />
  <Rule xsi:type="ItemIs" FormType="ReadOrEdit" ItemType="Appointment" />
</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" FormType = "Read" ItemType="Message" />
    <Rule xsi:type="ItemHasAttachment" />
</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 Match strings in an Outlook item as well-known entities.

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 Use regular expression activation rules to show a mail app in Outlook.

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 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 activates the mail app 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" FormType="Read" ItemType="Message" />
        <Rule xsi:type="ItemIs" FormType="Read" ItemType="Appointment" />
    </Rule>
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

The following example activates the mail app 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" FormType="Edit" ItemType="Message" /> 
    <Rule xsi:type="RuleCollection" Mode="And">
        <Rule xsi:type="ItemIs" FormType="Read" ItemType="Appointment" />
        <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
    </Rule> 
</Rule>

Show:
© 2014 Microsoft