Export (0) Print
Expand All

Updating the manifest of a mail app from schema v1.0 to v1.1

apps for Office

Learn why and how you can update the manifest of a mail app that uses version 1.0 of the schema for apps for Office manifests to use schema v1.1.

Last modified: April 01, 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

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

In this article
Why update the manifest
Updating the manifest while keeping the same activation to only read forms
Extending the manifest to support compose forms
Appendix A: Sample manifest using schema v1.0
Appendix B: Sample manifest for activation in only read forms using schema v1.1
Appendix C: Sample manifest for activation in read and compose forms using schema v1.1
Additional resources

If you are upgrading a mail app to use the new features in version 1.1 of the JavaScript API for Office, you should also update your manifest to use v1.1 of the schema.

The next section shows how to update a manifest of the sample YouTube mail app from schema v1.0 to v1.1 while keeping app activation to only read forms of appointments or messages. Appendix A: Sample manifest using schema v1.0 shows the manifest that used schema v1.0, and Appendix B: Sample manifest for activation in only read forms using schema v1.1 shows the updated manifest that uses schema v1.1. Following that is a hypothetical extension of the mail app that allows it to be activated in compose forms as well. Appendix C: Sample manifest for activation in read and compose forms using schema v1.1 shows the extended manifest.

Note Note

Because schema v1.1 is compatible with office.js v1.1, if you update the manifest to use v1.1, you should also update the HTML file of your app to include office.js v1.1, as shown below.

<!-- Use the CDN reference to Office.js v1.1. -->
<script 
  src="https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js"
  type="text/javascript">
</script>

This section describes how to update a manifest created with schema v1.0 to use schema v1.1, while keeping the app to be activated in only read forms, as supported by schema v1.0. Figure 1 shows the 3 parts of the manifest to update.

Figure 1. Updating a mail app manifest from using schema v1.0 to using schema v1.1

Update mail app manifest from schema v1.0 to v1.1.

Table 1 describes the 3 parts to update:

Table 1. How to update a manifest to use schema v1.1 while keeping the same activation in read mode

Schema v1.0 manifest

Schema v1.1 manifest

Changes

OfficeApp element

OfficeApp element

Change the xmlns attribute to point to the URL of schema v1.1:

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

Capabilities and Capability elements

Optional Host element

Requirements. Sets and Set elements

Add the optional Host element to specify "Mailbox" as the host name:

<Hosts>
  <Host Name="Mailbox" />
</Hosts>

Replace Capabilities and Capability by Requirements, Sets and Set elements, specifying Mailbox as the required set of JavaScript API of Office, and where necessary, specifying MinVersion or DefaultMinVersion. For more information, see Hosts and office.js requirements in Step 3: Specifying the scope of support of the app.

<Requirements>
  <Sets DefaultMinVersion="1.1">
    <Set Name="Mailbox" />
  </Sets>
</Requirements>

DesktopSettings, TabletSettings, PhoneSettings

FormSettings, Form as new parents of DesktopSettings, TabletSettings, PhoneSettings in a read form.

First, specify the form type that the mail app is activated in (Form with type ItemRead), then the source files for each form factor in DesktopSettings, TabletSettings, and PhoneSettings as appropriate.

<FormSettings>
  <Form xsi:type="ItemRead">
    <DesktopSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube.htm" />
      <RequestedHeight>216</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube.htm" />
      <RequestedHeight>216</RequestedHeight>
    </TabletSettings>
  </Form>
</FormSettings>

Version 1.0 of the schema supports mail app activation in only read forms. To extend a manifest that was created using schema v1.0 to support activation in compose forms, do the changes described in Table 1 and Table 2. See the extended manifest in Appendix C: Sample manifest for activation in read and compose forms using schema v1.1.

Table 2. Additional changes to extend a manifest from schema v1.0 to v1.1 to support activation in compose mode

Schema v1.0 manifest

Schema v1.1 manifest

Changes

DesktopSettings, TabletSettings, PhoneSettings

FormSettings, Form as parents of DesktopSettings, TabletSettings, PhoneSettings in a compose form.

Add a Form element with type ItemEdit, and then the source files for each form factor.

Note Note

In read forms, the app pane is horizontal and you can customize the default height for your app on desktop and tablet form factors. In compose forms, the app pane is a vertical pane on the right, and you cannot customize the default height.

The following example shows how to specify the FormSettings and Form elements to include separate source files for each supported form factor (desktop and tablet) in read forms and compose forms:

<FormSettings>
  <Form xsi:type="ItemRead">
    <DesktopSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube_read_desktop.htm" />
      <RequestedHeight>216</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube_read_tablet.htm" />
      <RequestedHeight>216</RequestedHeight>
    </TabletSettings>
  </Form>
  <Form xsi:type="ItemEdit">
    <DesktopSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube_compose_desktop.htm" />
    </DesktopSettings>
    <TabletSettings>
      <!-- Change the following line to specify     -->
      <!-- the web server that hosts the HTML file. -->
      <SourceLocation DefaultValue=
        "https://webserver/YouTube/YouTube_compose_tablet.htm" />
    </TabletSettings>
  </Form>
</FormSettings>

Permissions element

Permissions element

Specify the minimum necessary permission, depending on the exact compose methods that you plan to use. For example, if your app sets item properties in a compose form, specify the ReadWriteItem permission as shown below:

<Permissions>ReadWriteItem</Permissions>

To verify the appropriate permission that you need, see Specify permissions for mail app access to the user's mailbox.

Rule element

Rule element

Add ItemIs rules to allow the mail app to activate in read and compose forms:

<Rule xsi:type="RuleCollection" Mode="Or"> 
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
      <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
    </Rule>
    <Rule xsi:type="ItemHasRegularExpressionMatch" 
      PropertyName="BodyAsPlaintext" RegExName="VideoURL" 
        RegExValue=
        "http://(((www\.)?youtube\.com/watch\?v=)|
        (youtu\.be/))[a-zA-Z0-9_-]{11}" />
  </Rule>
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" />
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" /> 
  </Rule> 
</Rule>

For more information about specifying rules for compose and read modes, see Step 4: Specifying information for app operations.

<?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-567F-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 that hosts the icon file. -->
  <IconUrl DefaultValue=
    "https://webserver/YouTube/YouTubeLogo.png"/>

  <Capabilities>
    <Capability Name="Mailbox"/>
  </Capabilities>

  <DesktopSettings>
    <!-- Change the following line to specify     -->
    <!-- the web server that hosts the HTML file. -->
    <SourceLocation DefaultValue=
      "https://webserver/YouTube/YouTube.htm"/>
    <RequestedHeight>216</RequestedHeight>
  </DesktopSettings>
  <TabletSettings>
    <!-- Change the following line to specify     -->
    <!-- the web server that hosts the HTML file. -->
    <SourceLocation DefaultValue=
      "https://webserver/YouTube/YouTube.htm"/>
    <RequestedHeight>216</RequestedHeight>
  </TabletSettings>

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

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

  <Id>971E76EF-D73E-567F-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 serverthat hosts the icon file. -->
  <IconUrl DefaultValue=
    "https://webserver/YouTube/YouTubeLogo.png"/>

  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="Mailbox" />
    </Sets>
  </Requirements>

  <FormSettings>
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube.htm" />
        <RequestedHeight>216</RequestedHeight>
      </DesktopSettings>
      <TabletSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube.htm" />
        <RequestedHeight>216</RequestedHeight>
      </TabletSettings>
    </Form>
  </FormSettings>

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

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

  <Id>971E76EF-D73E-567F-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 serverthat hosts the icon file. -->
  <IconUrl DefaultValue=
    "https://webserver/YouTube/YouTubeLogo.png"/>

  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="Mailbox" />
    </Sets>
  </Requirements>

  <FormSettings>
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_read_desktop.htm" />
        <RequestedHeight>216</RequestedHeight>
      </DesktopSettings>
      <TabletSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_read_tablet.htm" />
        <RequestedHeight>216</RequestedHeight>
      </TabletSettings>
    </Form>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_compose_desktop.htm" />
      </DesktopSettings>
      <TabletSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_compose_tablet.htm" />
      </TabletSettings>
    </Form>
  </FormSettings>

  <Permissions>ReadWriteItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="Or"> 
    <Rule xsi:type="RuleCollection" Mode="And">
      <Rule xsi:type="RuleCollection" Mode="Or">
        <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
        <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
      </Rule>
      <Rule xsi:type="ItemHasRegularExpressionMatch" 
        PropertyName="BodyAsPlaintext" RegExName="VideoURL" 
        RegExValue=
        "http://(((www\.)?youtube\.com/watch\?v=)|
        (youtu\.be/))[a-zA-Z0-9_-]{11}" />
    </Rule>
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" />
      <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" /> 
    </Rule> 
  </Rule>
</OfficeApp>

Show:
© 2014 Microsoft