Export (0) Print
Expand All

Choosing a version of the platform for your mail app for Outlook

apps for Office

Learn how to choose the appropriate "version" of the apps for Office platform that provides the features and functionality you need for your mail app.

Last modified: November 07, 2014

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

   Office.js: v1.1

   Apps for Office manifests schema: v1.1

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
What does choosing a version mean for mail apps
Example
Choosing the versions of office.js and the schema
Additional resources

This section explains a few concepts about choosing a version of the apps for Office platform for which to develop a mail app.

Why is choosing necessary

In general, the apps for Office platform lets you design apps to run on one or more Office hosts. Because innate differences and similarities exist among the hosts, you can differentiate apps by app type (content, task pane, or mail app), and state the app type in the manifest to identify that level of support you need from the platform. However, as new objects and members are released in each version of the JavaScript API for Office (office.js), not all the hosts for the same type of app necessarily support them. Even if some of them do, their support does not necessarily start in the same release or may differ slightly. To make sure that your app is able to access certain API at runtime, you should also specify such needs in the manifest, in terms of the version of office.js, API sets, or individual methods where applicable (by using the Requirements, Sets, Set and Methods elements). In general, specifying these elements helps guarantee that only hosts that support the required API activate the app. In particular, mail apps must specify these elements, as mail apps must include office.js as a library; see example in step 5 of Choosing the versions of office.js and the schema.

"Version" includes office.js and the schema

The apps for Office platform includes the JavaScript API for Office (office.js) and the schema for apps for Office manifests. Choosing a version of the platform for an app means determining the versions of 2 components: office.js and the schema. Figure 1 shows where you would specify the version of office.js for an app, and figure 2 shows that of the schema.

Figure 1. Specifying the version of office.js for an app

Where to specify the version of office.js
Figure 2. Specifying the version of the schema for an app

Where to specify the version of the schema

Activation depends on the versions supported by the user's Exchange mailbox and Outlook client

How do the versions that you choose matter?

  • The end user or administrator can install your app only if the user's Exchange Server and Outlook support the versions of office.js and of the schema you specify.

  • The end user or administrator can see your app activated and open the app only if his or her Outlook supports that version of office.js.

  • Depending on the adoption rate of newer versions of office.js and the schema of your target customers, you may or may not always want to code your app to use the latest versions, as this may limit your app to only early adopters who can technically install and use your app.

Identify mandatory and secondary features

Before you create a new app, consider the features that your app uses – which features are mandatory and must be supported? Which features are secondary and nice to have, but without which your app can still provide the intended intrinsic value?

Identify MinVersion of office.js for mandatory features

The earliest version of office.js that supports the mandatory features of your app is the minimum required version. That would be the version you specify in the manifest (as the MinVersion attribute of the Set element), which guarantees if a user can see your app activated in Outlook, the user will be able to use these mandatory, core features of your app. Because minor releases of office.js (for example, v1.0, v1.1) are backward-compatible, Exchange and Outlook that support a later version of office.js will be able to support your app as well.

Identify the desired version of office.js for secondary features

As for the secondary features: it's possible that your app gets installed and activated on Exchange and Outlook that do not support those later versions of office.js. To handle this, you should use JavaScript if statements to check for the existence of the corresponding objects, properties and methods in your app JavaScript code before accessing them.

Identify a compatible version of the schema

When determining the version of the schema, make sure the schema supports the mandatory features and works with the version of office.js you specify in MinVersion. If there is no common version of the schema that supports the mandatory and secondary features, scale back on the latter as necessary until you identify a compatible version of the schema.

New versions of office.js and the schema are not necessarily released at the same time, and it's possible that multiple versions of office.js will work with the same version of the schema. Once you have identified the version of office.js you need, refer to Table 1 which lists the version(s) of the schema that are optimal.

Note Note

Office.js v1.1 can work with schema v1.1 or v1.0, with schema v1.1 being optimal. It is fine to upgrade an existing mail app that uses schema v1.0 to reference office.js v1.1. This would allow you to take advantage of performance enhancements in office.js v1.1, without necessarily changing the manifest or JavaScript code of the app.

In general, if you are creating a mail app and can use either office.js v1.0 or v1.1, because of the extensive changes and new features in the latter, you should use v1.1 for both office.js and the schema.

Table 1. Finding an optimal version of the schema

Version of office.js

Compatible version of the schema

1.0

1.0

1.1

1.1

Figure 3 describes an example:

  • Office.js v1.1: the version that the mail app sets as the MinVersion.

  • Office.js v1.2: the version supported by the user’s Exchange server and Outlook.

  • Office.js v1.3: the version that provides all the secondary features for the mail app.

The app is guaranteed access for the API in v1.1 to support its mandatory features, and tests for the existence of the extra API in v1.2 or v1.3 for its secondary features before accessing it. Because the user’s Exchange Server and Outlook support up to v1.2, the secondary API supported in v1.2 is available, but the incremental API supported in v1.3 (but not in v1.2) is not. For more information on testing for such API, see How to: Determine host application support for specific API members.

Figure 3. An example of how choosing the versions of office.js affects API availability for a mail app

Testing existence of API above minVersion

How do you decide which version of office.js and the schema to use for a new mail app?

Choosing between office.js v1.0 and v1.1

If you are choosing only between office.js v1.0 and v1.1 for a mail app, the decision lies in whether your scenario requires activating the app in a compose form. If that's your mandatory scenario, you must use office.js v1.1 and schema v1.1.

Even if your scenario does not involve compose forms, if you are creating a new mail app at this point, you should use office.js v1.1 and schema v1.1, as future extension of the platform will be based on this release.

General approach

In general, beyond version 1.1, you should not expect to have to always choose the latest release. You can base your decision on current adoption data. As office.js will iterate periodically, the following general approach will help you plan ahead:

  1. First, if you are new to developing mail apps, see Mail apps for Outlook for an introduction to mail apps, and Start with fundamental concepts for mail apps in Outlook for a high-level overview of the features available to mail apps.

  2. Then, decide a scenario for your mail app, and identify the features that the mail app will use for that scenario. Then among all these features, determine the core features that are mandatory, and the nice-to-have features that are secondary.

  3. Referring to Mail app features per version, identify the minimum version of office.js and the version of schema that your app needs to support the core features. Also identify the desired version of office.js for any secondary features. The minimum version may be lower or the same as the desired version.

  4. Identify the CDN location for that desired version of office.js, and specify the CDN of that version in your HTML file. The following HTML example specifies using office.js v1.1 in the CDN:

    <!-- 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>
    
  5. Specify the Requirements, Sets, Set elements to require mailbox API:

    • Set the Name attribute of the Set element as mailbox. You must specify this value for Exchange to install the mail app; the string is case-insensitive.

    • Specify the minimum version as the MinVersion attribute of the Set element in the app manifest. The following example sets the minimum required version of office.js to v1.1:

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

      If your mail app must use features that are available in a version later than office.js v1.1, then set MinVersion to that later version instead.

  6. Specify the version of the schema in the app manifest. The following XML lines appear at the top of an app manifest and state that this mail app uses schema v1.1:

    <?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">
    
Show:
© 2014 Microsoft