Creating a manifest for a mail app to activate in a read form in Outlook (schema v1.0)

apps for Office

Walk through the four basic steps to create a manifest for a mail app using version 1.0 of the apps for Office schema. The manifest allows the mail app to be activated in a read form in Outlook, which is the only kind of forms supported for mail app activation in v1.0.

If you are creating a mail app, you should use at least v1.1 of the apps for Office manifest schema, and refer to Creating a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1). For more information about the different versions, see Choosing a version of the platform for your mail app for Outlook.

Last modified: October 20, 2014

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

   Office.js: v1.0

   Apps for Office manifests schema: v1.0

Note Note

"Outlook" in this article refers to Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), and Outlook Web App. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

In this article
Anatomy of a typical manifest
Step 1: Specifying the root element
Step 2: Identifying the app
Step 3: Specifying the scope of support of the app
Step 4: Specifying information for app operations
Appendix A: sample XML manifest
Additional resources

Figure 1 shows the four steps to create an example manifest for a mail app to view YouTube videos in Outlook. The rest of this article describes the four steps using the same YouTube mail app as the example. Follow Build along to create a skeleton of your own manifest. Appendix A: sample XML manifest lists the complete sample manifest.

Figure 1. Anatomy of a typical manifest for a mail app

Purpose of elements in typical manifest Outlook

4 basic steps of creating a manifest for a mail app for Outlook

Button for step 1 of creating manifest   Specifying the root element

Button for step 2 of creating a manifest   Identifying the app

Button for step 3 of creating a manifest   Specifying the scope of support

Button for step 4 of creating a manifest   Specifying information for operations

Icon to suggest copying and pasting XML for step 1   At each step, copy the XML and replace each instance of MyValue with your own values.

  

Applying the four steps to other types of apps for Office

In the four-step process, steps 1 and 2 are generally applicable to all types of Office apps—content, mail, and task pane apps. Some elements in steps 3 and 4 are relevant only to mail apps. For a complete set of elements supported by the app schema, please refer to Schema reference for apps for Office manifests (v1.1).

Note Note

In each step, replace each instance of MyValue in the XML listed on the right with a value appropriate for your scenario.

Specify OfficeApp as the root element in the manifest and place all other elements in the manifest within its open and close tags. Figure 2 is an example for the YouTube mail app.

First in a row of 4 build buttons

Figure 2. Specifying the root element for a mail app

Root element of manifest
<?xml version="1.0" encoding="utf-8"?>
<OfficeApp 
  xmlns="http://schemas.microsoft.com/office/appforOffice/1.0"
  xmlns:ver="http://schemas.microsoft.com/office/appforoffice/1.0"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:type="MailApp">

  <!-- Insert Id and other XML code from step 2 here. -->

</OfficeApp>

Default namespace

The OfficeApp element specifies the appforoffice schema, v1.0, as the default namespace:

xmlns="http://schemas.microsoft.com/office/appforoffice/1.0

One schema, different app types

The YouTube sample manifest uses the xsi:type attribute of the OfficeApp element to specify that the manifest is for a mail app:

xsi:type="MailApp"

As the root element, the OfficeApp element supports child elements that apply to all types of apps for Office, regardless of the host application. We’ll talk about these common child elements in the steps 2 and 3. To support the specificity of each type of app, however, the schema defines the OfficeApp element as an abstract type. You can use the xsi:type attribute to extend this abstract type as a ContentApp, MailApp, or TaskPaneApp complex type. Specificity refers to how an app is to be used and displayed in the host application, and the kinds of permissions that the app requests.

You will see in steps 3 and 4 the use of elements that are specific to mail apps.

In this step, you provide identification information for the app. Figure 3 shows how the example YouTube mail app provides such information in the manifest and where such information is surfaced in the Exchange Admin Center (EAC).

Second in a row of 4 build buttons

Figure 3. Identifying the mail app

Identification information in schema
    <!-- Insert Id as the first element under  -->
    <!-- OfficeApp. -->
    <Id>MyValue</Id>
    <Version>MyValue</Version>
    <ProviderName>MyValue</ProviderName>

    <!-- Insert DefaultLocale from step 3 here.  -->

    <DisplayName DefaultValue="MyValue"/>
    <Description DefaultValue="MyValue">

        <!-- Insert optional Override for the description  -->
        <!-- from step 3 here. -->

    </Description>
    <IconUrl DefaultValue="MyValue"/>

    <!-- Insert Capabilities and DesktopSettings XML code -->
    <!-- from step 3 here. -->

Common ID elements occurring in sequence

The elements used for identification in this example are listed in the table below. These elements are some of the children of the root element OfficeApp. They follow a sequence as defined in the OfficeApp complexType (app manifest schema v1.1) complex type, and apply to all apps for Office. Other than IconUrl, they are mandatory.

Id

A UUID unique string for programmatic identification. The example uses a GUID as a value.

Version *

A string that specifies the current version of the app. The example specifies a version number of 1.0.

ProviderName *

The name of the individual or company that is offering the app. The example specifies Microsoft as its provider.

DisplayName *

The label for the app button. For mail apps, this button is displayed in the app bar when Outlook activates the mail app. The example uses YouTube as the label.

Note that the DisplayName element supports a DefaultValue attribute that corresponds to the locale specified by the DefaultLocale element. See step 3 for more information about DefaultLocale.

Description *

A string that typically explains the purpose of the app. The example provides the description "Watch YouTube videos referenced in the e-mails you receive without leaving your email client."

Note that the Description element supports a DefaultValue attribute that corresponds to the locale specified by the DefaultLocale element. See step 3 for more information about DefaultLocale.

IconUrl

The URI of an image file that should be used to represent the app.

Note that the IconUrl element supports a DefaultValue attribute that corresponds to the locale specified by the DefaultLocale element. See step 3 for more information about DefaultLocale.

*After the user installs the mail app, the values for Version, ProviderName, DisplayName, Description and IconUrl are surfaced in the EAC, as illustrated in Figure 3.

In this step, you specify the locales, host application, and in the case of mail apps, form factors and any custom user interface that the app supports for the corresponding form factor. Figure 4 shows how the example YouTube mail app specifies its scope of support.

Third in a row of 4 build buttons

Figure 4. Specifying the scope of support of the mail app

Scope of support information in manifest
    <!-- Insert DefaultLocale after the ProviderName element. -->
    <!-- Use en-us for US English. -->
    <DefaultLocale>MyValue</DefaultLocale>

Icon to build manifest alongside step 3

        <!-- Insert optional override for the description -->
        <!-- before the Description element closing tag. -->
        <Override Locale="MyValue" Value="MyValue"/>

Icon to build manifest alongside step 3

    <!-- Insert Capabilities after the optional IconUrl. -->
    <Capabilities>
        <Capability Name="MyValue" />
    </Capabilities>
    <DesktopSettings>
        <SourceLocation DefaultValue="MyValue"/>
        <RequestedHeight>MyValue</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
        <SourceLocation DefaultValue="MyValue "/>
        <RequestedHeight>MyValue</RequestedHeight>
    </TabletSettings>
    <PhoneSettings>
        <SourceLocation DefaultValue="MyValue"/>
    </PhoneSettings>

    <!-- Insert Permissions and  -->
    <!-- Rule XML code from step 4 here. -->

Locales and hosts are also mandatory

The elements that specify the default locale and required capabilities are described in the next table.

DefaultLocale

This is the locale that host application assumes for users of the app, and therefore the target locale to apply the default values of the Description, DisplayName, IconUrl (if present), and SourceLocation elements.

Capabilities

Capabilities and the child element Capability specify the Office applications that have the capabilities required by the app. For mail apps, the value for the Name attribute is always Mailbox. Note that the support for Outlook running on a tablet or smartphone is handled at the form factor level, which we will discuss later in this section.

DefaultLocale is a child element of the OfficeApp root element, and Capabilities is a child element of the MailApp type which extends the OfficeApp type. Both child elements are mandatory and defined in sequence, which means you must specify these elements in the manifest in the order as defined in the OfficeApp and MailApp complex types.

Supporting multiple locales

The example manifest applies a locale override for the Description element: it specifies a default locale of en-us and an English description, and specifies an Override statement with a French description for the fr-fr locale:

    <DefaultLocale>en-us</DefaultLocale>
…
    <Description DefaultValue="Watch YouTube videos referenced in the e-mails you receive 
        without leaving your email client.">
        <Override Locale="fr-fr" Value="Visualisez les vidéos YouTube référencées dans vos courriers 
            électronique directement depuis Outlook et Outlook Web App."/>
    </Description>

This means that the app assumes the en-us locale by default, specifies the English description for all locales unless the client computer’s locale is fr-fr, in which case the app provides a French description.

You can similarly use the Override element to provide locale-specific values for the DisplayName, IconUrl, and SourceLocation elements. For more information, see Localization.

Supporting multiple form factors such as tablets and smartphones

Specific to mail apps is the support for the default desktop form factor and the optional support for tablets and smartphones. You can customize a source file and user interface for each form factor or locale. The related elements are in the next table.

DesktopSettings

Settings for the mail app running on a desktop computer. Specify the actual settings in the corresponding child elements SourceLocation and RequestedHeight.

The example manifest specifies the source file YouTube.htm and a height of 216 pixels for the app pane on the desktop form factor.

TabletSettings

Settings for the mail app running on a tablet. Specify the actual settings in the corresponding child elements SourceLocation and RequestedHeight.

The example manifest specifies a custom source file YouTube_Tablet.htm and a height of 216 pixels for the app pane on the tablet form factor.

PhoneSettings

Settings for the mail app running on a smartphone. Specify the actual settings in the corresponding SourceLocation child element.

The example manifest specifies a custom source file YouTube_Phone.htm. Note that on a smartphone, the app pane takes the entire screen, and you cannot specify a specific height.

SourceLocation

A URI for the HTML source file that is appropriate for the parent form factor element. Note that applying a locale override to the SourceLocation element allows you to provide a specific source file for the specified locale for that form factor.

RequestedHeight

The number of pixels that the mail app requires as the height of the app pane, as appropriate for the corresponding desktop or tablet form factor.

See Overview of apps for Office for more information about the specific form factors and versions of browsers that mail apps support, and Set up a mail app for Outlook on desktops, tablets and mobile devices (schema v1.0) and Design guidelines for apps for Office for guidelines about designing mail apps for different form factors.

In this last step, a mail app specifies the desired permission and conditions for Outlook to display the app, which are also referred as activation rules. Figure 5 shows the permission and activation rules that the example YouTube mail app specify.

Fourth in a row of 4 build buttons

Figure 5. Specifying information for operations of the mail app

Info for operations in manifest
    <!-- Insert Permissions after  -->
    <!-- the optional PhoneSettings. -->
    <Permissions>MyValue</Permissions>
    <Rule xsi:type="ItemHasRegularExpressionMatch" 
        PropertyName="MyValue" 
        RegExName="MyValue"
        RegExValue="MyValue" 
        IgnoreCase="MyValue"/>

Icon to create manifest along step 4  Alternative 1

    <!-- Alternatively, use a rule collection of 2 or more rules. -->
    <Permissions>MyValue</Permissions>
    <Rule xsi:type="RuleCollection" Mode="MyValue">
        <Rule xsi:type="ItemIs" ItemType="MyValue"/> 
        <Rule xsi:type="ItemHasAttachment" />
        <Rule xsi:type="ItemHasKnownEntity" EntityType="MyValue" />
        <Rule xsi:type="ItemHasRegularExpressionMatch" 
            RegExName="MyValue" 
            RegExValue="MyValue" 
            PropertyName="MyValue"/>
    </Rule>

Icon to create manifest along step 4  Alternative 2

    <!-- Alternatively, request the lowest Restricted -->
    <!-- permission and use ItemIs rule. -->
    <Permissions>Restricted</Permissions>
    <Rule xsi:type="ItemIs" ItemType="MyValue" ItemClass="MyValue" 
    IncludeSubClasses="MyValue" />

3 tiers of permission determine available APIs

Element

Description

Supported permissions

Permissions

The permission that the mail app requires to carry out its operations.

Restricted, ReadItem, and ReadWriteMailbox

The supported permissions for Permissions are specific to mail apps. Figure 5 shows the permissions associated with each tier in this 3-tier model.

Figure 5. The 3-tier permission model for mail apps

3-tier permission model for user, developer, admin

  

The YouTube mail app requests ReadItem permission in the example manifest, so that it can use a regular expression in its activation rule as shown below:

<Permissions>ReadItem</Permissions>
<Rule xsi:type="ItemHasRegularExpressionMatch" PropertyName="BodyAsPlaintext" RegExName="VideoURL"
   RegExValue="http://(((www\.)?youtube\.com/watch\?v=)|(youtu\.be/))[a-zA-Z0-9_-]{11}"/>

See Specify permissions for mail app access to the user's mailbox for details about each tier of permission.

Addressing users’ concern for app security

You must explicitly specify the permission your app needs in the Permissions element in the manifest. If you submit the mail app to the Office Store, using the value you specify, the Office Store will provide consistent, contextual explanation for the extent of possible actions that the app can take in the app listing. End users or IT administrators can then explicitly grant such permission when installing the mail app. After installation, the requested permission is prominently displayed in the Exchange Admin Center (EAC). See Privacy, permissions and security for mail apps in Outlook and Specify permissions for mail app access to the user's mailbox for details.

Contextual sensitivity all lies in activation rules

Specific to mail apps is being able to use the Rule element to define specific contexts where the mail app is relevant and therefore Outlook should activate it. The Rule element is mandatory.

Element

Extending a Rule as this type

Activation condition

Attributes & possible values

Rule

ItemIs

Currently selected item is of the specified type (message or appointment)

ItemType: Message or Appointment

ItemClass: optional Outlook message class

IncludeSubClasses: optional, default is false

Rule

ItemHasKnownEntity

Currently selected item contains an instance of the specified entity, and optionally matches the specified regular expression

EntityType: a value in KnownEntityType

FilterName: the name of the optional regular expression for the entity

RegExFilter: optional regular expression for the entity

IgnoreCase: optional for matching the specified regular expression, default is false

Rule

ItemHasRegularExpression

Currently selected item contains a match to the specified regular expression

PropertyName: Subject, BodyAsHTML, BodyAsPlaintext, or SenderSMTPAddress

RegExName: the name of the regular expression

RegExValue: the regular expression

IgnoreCase: optional for matching the specified regular expression, default is false

Rule

ItemHasAttachment

Currently selected item contains an attachment

No attributes

Rule

RuleCollection

A rule collection that evaluate to true

Mode: logical And or Or

The sample YouTube mail app specifies an activation rule that if the selected item contains a URL for a video on YouTube, then the app becomes available to the end user who can then choose to play the video in a YouTube player within Outlook. Because URLs for YouTube videos follow a specific format, you can specify the following regular expression to detect such a URL in the selected item:

http://(((www\.)?youtube\.com/watch\?v=)|(youtu\.be/))[a-zA-Z0-9_-]{11}

You can specify this regular expression in an ItemHasRegularExpression activation rule, so that Outlook activates this app contextually when such URLs exist in the selected item. For more information about activation rules, see Activate mail apps in Outlook clients, Use regular expression activation rules to show a mail app in Outlook, and Match strings in an Outlook item as well-known entities.

The following is a listing of the XML manifest for the example YouTube mail app described in this topic.

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="MailApp">

    <Id>971E76EF-D73E-460F-ADAE-5A76B39052CF</Id>
    <Version>1.0</Version>
    <ProviderName>Microsoft</ProviderName>
    <DefaultLocale>en-us</DefaultLocale>
    <DisplayName DefaultValue="YouTube"/>
    <Description DefaultValue="Watch YouTube videos referenced in the 
     e-mails you receive without leaving your email client.">
        <Override Locale="fr-fr" Value="Visualisez les vidéos YouTube
         référencées dans vos courriers électronique directement depuis 
         Outlook et Outlook Web App."/>
    </Description>
    <!-- Change the following line to specify the web server where the image file is hosted. -->
    <IconUrl DefaultValue=
     "https://<domain>/YouTubeLogo.png"/>
    <Capabilities>
        <Capability Name="Mailbox" />
    </Capabilities>
    <DesktopSettings>
        <!-- Change the following line to specify the web server where the image file is hosted. -->
        <SourceLocation DefaultValue=
         "https://<domain>/YouTube.htm"/>
        <RequestedHeight>216</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
        <!-- Change the following line to specify the web server where the image file is hosted. -->
        <SourceLocation DefaultValue=
         "https://<domain>/YouTube_Tablet.htm"/>
        <RequestedHeight>216</RequestedHeight>
    </TabletSettings>
    <PhoneSettings>
        <!-- Change the following line to specify the web server where the image file is hosted. -->
        <SourceLocation DefaultValue=
         "https://<domain>/YouTube_Phone.htm"/>
    </PhoneSettings>
    <Permissions>ReadItem</Permissions>
    <Rule xsi:type="ItemHasRegularExpressionMatch" 
     PropertyName="BodyAsPlaintext" RegExName="VideoURL" RegExValue=
     "http://(((www\.)?youtube\.com/watch\?v=)|
     (youtu\.be/))[a-zA-Z0-9_-]{11}"/>
</OfficeApp>

Show:
© 2014 Microsoft