How to: Specify the Office host applications your app supports (manifest schema v1.0)

apps for Office

This topic describes how to specify the capabilities that your app for Office works with, which determines the host applications that will support your app.

Last modified: June 30, 2014

Applies to: Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Exchange Online | Exchange Server 2013 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 SP1 | Project Professional 2013 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0

   Apps for Office manifests schema: v1.0

In this article
Accessing what your app needs from the platform
Matching specified capabilities with eligible host applications
Facilitating app selection by specifying capabilities
Additional resources

Important note Important

To use the latest features of apps for Office and the JavaScript API for Office, instead of using this v1.0 method of specifying app capabilities, use the latest version app manifest schema and app project files when developing your app.

Note Note

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

The apps for Office platform provides an integrated JavaScript API for Office that is shared by all apps for Office and supporting host applications. For this integrated model to work, you have to do 2 things:

  • Specify one or more capabilities of your app in the app manifest. The remaining sections of this topic describe this step.

  • Verify at runtime the availability of certain API members before accessing them. For example, even though the Bindings object is available to task pane apps that specify the Document or Workbook capability, the addFromPromptAsync method of the Bindings object is available to only task pane apps running on Excel or Excel Online. While the task pane app can run on Word (and Excel clients), the task pane app should verify if the addFromPromptAsync is available and not simply assume it always works. See How to: Determine host application support for specific API members for more information on the verification.

When you create an app for Office, specify in the manifest one or more capabilities. You cannot explicitly specify the host applications for your app, but specifying capabilities determines the applications that can host your app. A capability maps to a subset of features supported by the JavaScript API for Office A capability identifies the subset that the app works with and requires in order to add value to that host application for the customer. An app can specify more than one capability. An application that supports one or more of the specified API features can become a host application for the app. In general an application hosts and exposes only apps that can add value based on a match between a capability that an app works with, and the capability that the host application offers.

The following are the currently supported capabilities:

  • Document—represents the subset of the API that supports document functionality.

  • Mailbox—represents the subset of the API that supports mailbox functionality.

  • Presentation—represents the subset of the API that supports presentation functionality.

  • Project—represents the subset of the API that supports project functionality.

  • Workbook—represents the subset of the API that supports workbook functionality.

For example, a task pane app that reads and writes into a workbook requires the capability to work with workbooks. You should specify in the manifest that the app requires the Workbook capability. Applications such as Excel and Excel Online support this subset of the API, which means that the app will be available for users on these eligible host applications. Figure 1 shows how apps that specify a capability requirement for a subset of the API are matched with applications that support that subset and become host applications.

Figure 1. Apps specify the capabilities they require to match eligible host applications that support the capabilities

Capabilities match apps with host applications


Notice that as an app developer, you can specify only the capabilities your app works with, but you cannot explicitly specify the applications to host your app. Also, multiple host applications can support a single app (that is, the app can require a capability that more than one application supports). For example, a mail app that specifies the Mailbox capability can be hosted on the Outlook rich client, Outlook Web App, or OWA for Devices. Alternatively, an app can work with multiple capabilities, and those applications that support at least one of the specified capabilities are eligible to host the app. For example, a task pane app that specifies Document or Workbook capabilities can be hosted on Word, the Excel rich client, and Excel Online.

This table summarizes API features included in each capability supported across app types (content, task pane, and mail) and the Office applications that can host them.

Capability name

Workbook

Mailbox

Presentation

Document

Project

Supported
Host applications

Excel
Excel RT
Excel Online

Outlook
Outlook RT
Outlook Web App
OWA for Devices

PowerPoint
PowerPoint RT

Word
Word RT

Project

Supported app types

Content

Task pane

Mail

Supported API features

Read/Write Text


Read only

Read/Write Matrix

Read/Write Table

Read/Write HTML

Read/Write
Office Open XML

Read task, resource,
view, and field properties

Get whole document

Bindings

Read/Write
Custom Xml Parts

Persist App state data


Per document


Per mailbox


Per document


Per document

Activate contextually
using rules and RegEx

Read Item properties

Read User profile

Get attachments


Outlook Web App
only

Get User identity token

Call Exchange Web Services

Apps specify the capabilities they work with in their manifests. A user in an application such as Excel, Word, Project, or Outlook can visit the Office Store to look for apps. The Office Store uses the capabilities specified in manifests of posted apps to identify those apps that the current application supports. For example, when an Outlook user looks in the Office Store to select mail apps, the Office Store displays only those apps that specify the Mailbox capability and which Outlook supports.

The apps for Office schema supports Capabilities and Capability elements that you can use to specify one or more capabilities in the manifest. Depending on the type of app that you specify at the beginning of the manifest, schema validation allows only capability values that are actually supported for that type of app. For example, Figure 2 shows that a content app should specify only Workbook as the capability in its manifest. For more information about validating a manifest against a schema, see XML Schema (XSD) validation tool?.

Figure 2. A content app specifying the Workbook capability in the manifest

An example manifest of a content app

The following table shows the supported capabilities for each type of app for Office.

Type of app

Use these elements in the manifest

Supported capabilities

Examples

Content app

Capabilities element (ContentApp complexType) and Capability element (Capabilities element)(ContentApp complexType)

Workbook

This content app specifies the Workbook capability:

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

Mail app

Capabilities element (MailApp complexType) and Capability element (Capabilities element)(MailApp complexType)

Mailbox

This mail app specifies the Mailbox capability:

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

Task pane app

Capabilities element (TaskPaneApp complexType) and Capability element (Capabilities element)(TaskPaneApp complexType)

A task pane app can specify one or more of the following capabilities in the manifest: Document, Presentation, Project, or Workbook.

This task pane app specifies three capabilities: Workbook, Document, Presentation or Project. This means the task pane app can work with any application that supports one or more of these capabilities. An application that supports at least one capability is an eligible host application, and the app will be available in the Office Store for that application.

<Capabilities>
     <Capability Name="Workbook"></Capability>
     <Capability Name="Document"></Capability>
     <Capability Name="Presentation"></Capability>
     <Capability Name="Project"></Capability>
</Capabilities>
Show:
© 2014 Microsoft