What's new for mail apps in Office 2013 SP1

apps for Office

Learn about the significant enhancements in the apps for Office platform for mail apps in Office 2013 SP1, including a new manifest schema version 1.1 that lets mail apps activate in Outlook compose forms, new and extended objects and members in JavaScript API for Office version 1.1 that support getting and setting data, and managing attachments of a message or appointment while being composed. You can also list mail apps for purchase in the Office Store.

Last modified: June 16, 2014

Applies to: Exchange Online | Exchange Server 2013 SP1 | Outlook 2013 RT | Outlook 2013 SP1 | 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 the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
Mail apps in compose forms
New and extended JavaScript API objects and members
Designating Outlook as the host by requirement set
Attachment API available for all Outlook clients
Getting the entire selected item including item body from Exchange Server
OWA for Android is available
Providing high resolution icons for mail apps
Selling mail apps in the Office Store
Next steps
Additional resources

Using the previous v1.0 release of the schema for apps for Office manifests, Outlook could activate mail apps when the user viewed a message or appointment in a read form (in the Reading Pane or read inspector). In v1.1 of the schema, Outlook can also activate mail apps in a compose form, where the user is authoring a message or appointment in an inline reply or compose inspector. For ease of reference, we’ll call mail apps activated in read forms as read apps, and mail apps activated in compose forms as compose apps.

Note Note

Starting in the Office 2013 SP1 release, for an existing appointment or meeting item of which the user is the organizer, Outlook activates only compose apps that meet their activation rules. This is different from the Office 2013 release which supports only read apps. In the same scenarios in that release, Outlook activates read apps that satisfy their activation rules.

How to set up mail apps to work in compose forms

To make a mail app work in a compose form, use v1.1 of the schema and specify the following in the app manifest:

  • Use the Permissions element to request the appropriate permission, depending on the exact compose methods that you plan to use. As a general best practice, specify the minimum necessary permission. For example, if your mail app only reads but not write the to property of the message that is being composed, specify the ReadItem permission. On the other hand, if your mail app sets the to property of the message, then specify the ReadWriteItem permission, as shown in the following XML example:

    <Permissions>ReadWriteItem</Permissions>
    

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

  • Use an ItemIs rule to specify that the app works in a compose form, as shown in the following XML example.

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

    The new required FormType attribute lets you specify whether the app should activate in a compose form (FormType="Edit"), read form (FormType="Read"), or both types of forms (FormType="ReadOrEdit").

    Note that if you don't specify an ItemIs rule, by default, Outlook activates the mail app only in read forms, if existing rules are satisfied.

    Also, the other types of rules –ItemHasAttachment, ItemHasKnownEntity, and ItemHasRegularExpressionMatch – continue to apply to only read forms. In other words, to activate a mail app in a compose form, you can use only the ItemIs rule.

  • Use the new FormSettings and Form elements to specify the appropriate source HTML file for the mail app to work in compose forms. For the previous example where the mail app works in only compose forms, you would set the FormSettings and Form elements as in the following XML code:

    <FormSettings>
        <Form xsi:type="ItemEdit">
          <DesktopSettings>
            <SourceLocation DefaultValue="https://webserver/MailAppInComposeMode.htm"/>
          </DesktopSettings>
        </Form>
    </FormSettings>
    

    The following example sets a mail app to be activated in either a read or compose form:

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

    And specifies separate source files on webserver for the host to use in read mode and in compose mode.

    <FormSettings>
        <Form xsi:type="ItemRead">
          <DesktopSettings>
            <SourceLocation DefaultValue="https://webserver/MailAppInReadMode.htm"/>
            <RequestedHeight>250</RequestedHeight>
          </DesktopSettings>
        </Form>
      
        <Form xsi:type="ItemEdit">
          <DesktopSettings>
            <SourceLocation DefaultValue="https://webserver/MailAppInComposeMode.htm"/>
          </DesktopSettings>
        </Form>
    </FormSettings>
    

    Notice that for a compose form, the mail app does not get to specify the desired height, as it can do so for a read form using the RequestedHeight element.

    In each of the source files for read and compose modes, you will design the experience of your app in respectively a read form and in a compose form. There are features and corresponding objects and members in the JavaScript API for Office that work in both types of forms, and there are ones that work in only read forms, and ones only in compose forms. While the same objects and members that exist in office.js v1.0 are still available to mail apps in read mode, there are new and extended objects and members that work in both or only one mode. See the section New and extended JavaScript API objects and members for details.

What can mail apps do in compose forms

Activated in the compose form of a message or appointment, a mail app can get or set certain properties of that message or appointment. You can get the item type and message conversation ID, get or set the subject, recipients, and body of the message, or get or set the subject, attendees, location, and body of the appointment. You can also add or remove attachments from the message or appointment. Because while the item is being composed, the user can be changing these item properties dynamically, the methods to get and set them in compose mode are asynchronous. The following JavaScript code sample is a compose app that adds a recipient to the message that is being composed.

Office.initialize = function () {
    var mailbox = Office.context.mailbox;
    // Check for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Then add a recipient's email address 
        // to the To line.
        mailbox.item.to.addAsync(['Sam@Contoso.com'],
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                }
            });
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Aside from getting or setting properties of the item in a compose form, mail apps can also set data in a user-selected location in the body of the form. The following JavaScript example is a compose app that inserts a string "Confidential" to the message being composed – the string is inserted in the most recent cursor location, or, if the compose form just opened, the string is inserted at the beginning of the form.

Office.initialize = function () {
    var mailbox = Office.context.mailbox;
    // Check for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Insert "Confidential!" at the most recent 
        // cursor position in the body of the item
        // in compose mode, or prepend it if the item 
        // just opened in the compose form.
        mailbox.item.body.setSelectedDataAsync('Confidential!',
            { coercionType: Office.CoercionType.Text, 
            asyncContext: null },
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                }
            });

    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Office.js v1.1 supports the objects and members available to mail apps in office.js v1.0 the same way in read mode. In compose mode, office.js v1.1 offers new objects and members, and extends some existing objects and members to behave differently. Table 1 lists the objects and members available to mail apps in compose mode, including new and extended objects and members, and those that are unchanged from v1.0, and now work the same way in read and compose mode.

Note Note

While all existing objects and members continue to work in read mode, some existing objects and members now work in both read and compose modes, and new objects and members are available to mail apps in only compose mode.

Table 1. Objects and members available in compose mode

Object

Member

New or extended from v1.0

Notes

Appointment object

Extended

body property

New

Returns a Body object in only compose mode.

end property

Extended

In v1.1 compose mode, returns a Time object. (In read mode, no change from v1.0, returns a JavaScript Date object.)

location property

Extended

In v1.1 compose mode, returns a Location object. (In read mode, no change from v1.0, returns a string object.)

optionalAttendees property

Extended

In v1.1 compose mode, returns a Recipients object. (In read mode, no change from v1.0, returns an EmailAddressDetails object.)

requiredAttendees property

Extended

In v1.1 compose mode, returns a Recipients object. (In read mode, no change from v1.0, returns an EmailAddressDetails object.)

start property

Extended

In v1.1 compose mode, returns a Time object. (In read mode, no change from v1.0, returns a JavaScript Date object.)

subject property

Extended

In v1.1 compose mode, returns a Subject object. (In read mode, no change from v1.0, returns a string object.)

addFileAttachmentAsync method

New

Available in only compose mode.

addItemAttachmentAsync method

New

Available in only compose mode.

removeAttachmentAsync method

New

Available in only compose mode.

Body object

New

Available in only compose mode.

getTypeAsync method

New

Available in only compose mode.

prependAsync method

New

Available in only compose mode.

setSelectedDataAsync method

New

Available in only compose mode.

Context object

Extended

displayLanguage property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

mailbox property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

roamingSettings property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

CustomProperties object

Extended

get method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

remove method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

saveAsync method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

set method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

Item object

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

itemType property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

loadCustomPropertiesAsync method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

Location object

New

Available in only compose mode.

getAsync method

New

Available in only compose mode.

setAsync method

New

Available in only compose mode.

Mailbox object

Extended

diagnostics property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

item property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

userProfile property

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

convertToLocalClientTime method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

convertToUtcClientTime

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

displayAppointmentForm method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

displayMessageForm method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

getCallbackTokenAsync method

Extended

This method exists but is unsupported in compose forms. Do not use in compose mode.

getUserIdentityTokenAsync method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

makeEwsRequestAsync method

Extended

Same behavior in compose and read modes. (In read mode, no change from v1.0.)

Message object

Extended

bcc property

New

Returns a Recipients object. Available in only compose mode.

body property

New

Returns a Body object. Available in only compose mode.

cc property

Extended

In v1.1 compose mode, returns a Recipients object. (In read mode, no change from v1.0, returns an EmailAddressDetails object.)

conversationId property

Extended

In v1.1 compose mode, this property returns null for a new item. Changing the subject in a reply also changes the conversation ID. (In read mode, no change from v1.0.)

subject property

Extended

In v1.1 compose mode, returns a Subject object. (In read mode, no change from v1.0, returns a string object.)

to property

Extended

In v1.1 compose mode, returns a Recipients object. (In read mode, no change from v1.0, returns an EmailAddressDetails object.)

addFileAttachmentAsync method

New

Available in only compose mode.

addItemAttachmentAsync method

New

Available in only compose mode.

removeAttachmentAsync method

New

Available in only compose mode.

Recipients object

New

Available in only compose mode.

addAsync method

New

Available in only compose mode.

getAsync method

New

Available in only compose mode.

setAsync method

New

Available in only compose mode.

Subject object

New

Available in only compose mode.

getAsync method

New

Available in only compose mode.

setAsync method

New

Available in only compose mode.

Time object

New

Available in only compose mode.

getAsync method

New

Available in only compose mode.

setAsync method

New

Available in only compose mode.

Office.MailboxEnums.BodyType enumeration

New

Available in only compose mode.

Text

New

Value is "text". Available in only compose mode.

Html

New

Value is "html". Available in only compose mode.

If you use Visual Studio to create mail apps, download the Microsoft Office Developer Tools for Visual Studio 2013 - March 2014 Update to get the new and extended JavaScript API for Office.

As seen in Table 1, some members are available in only read or compose mode but not both, and some members return different types depending on the mode. If you use Visual Studio, you can use the following new methods to display the applicable Intellisense at design time for the message or appointment object passed as an input parameter:

  • Office.cast.item.toAppointmentCompose (item)

  • Office.cast.item.toAppointmentRead (item)

  • Office.cast.item.toAppointment (item)

  • Office.cast.item.toMessageCompose (item)

  • Office.cast.item.toMessageRead (item)

  • Office.cast.item.toMessage (item)

This set of methods support Intellisense for developing mail apps on only Visual Studio. They do not have any effect on other development tools. For more information, see the Office.cast.item property.

In v1.0 of the schema for app manifests, you do not explicitly identify the host applications of an app for Office. Instead you specify the capabilities, which represent the subset of features that the app works with and requires to add value to the intended hosts. In v1.1 of the schema, instead of specifying a capability, you specify a requirement set, and for a mail app, that's Mailbox. You must include a MinVersion attribute to identify the minimum version of office.js that your mail app requires and that the Exchange server and host application must support for the mail app to run. The following XML example shows how to specify the mailbox requirement set.

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

The attachment API and EWS callback tokens have been supported by Outlook Web App, OWA for Devices, Exchange 2013 and Exchange Online for a while, and are now also supported by the Outlook rich client in Office 2013 SP1.

If your mail app is to be activated in a read form, specifying at least the ReadItem level of permissions in the app manifest, you can use the attachment API (in the JavaScript API for Office), and Exchange Web Services (EWS) callback tokens to get attachments of a selected Outlook item in server-side code. Callback tokens allow server-side code of the mail app, or third-party web services, to use a EWS operation to actually get the specific attachments on that Exchange server. Because attachments may be large, and data in attachments is more likely to be stored or processed on the server side, using callback tokens allows more direct and efficient passing of the attachment data to the server than going first to the frame on the client and then back to the server. Figure 1 describes how a mail app requests and passes a callback token, together with the ID of specific attachments and URL of the EWS end point, to server-side code to let it retrieve those attachments from the Exchange server.

Figure 1. A mail app getting attachments from an Exchange server using callback tokens

Mail app gets attachments using callback token

The process of getting attachments on the Exchange server involves the following API members:

  • Mailbox.getCallbackTokenAsync method – mail app requests a callback token.

  • Item.attachments property – mail app gets attachment metadata such as attachment IDs.

  • Mailbox.ewsUrl property – mail app gets the URL of the EWS endpoint for the user’s mailbox.

  • GetAttachment operation – server-side code uses this EWS operation to get the actual attachments from the Exchange server.

Similar to the process for server-side app code to obtain attachments of an item from an Exchange server, a mail app can let its server-side code obtain all properties of a selected item including the item body. With ReadItem permissions, a mail app activated in a read form can get the item ID from the itemId property, EWS endpoint of the user’s mailbox from the ewsUrl property, and a callback token by calling the getCallbackTokenAsync method. The mail app can pass the item ID, EWS endpoint URL and callback token to its server-side code which can then access the EWS GetItem operation to get the entire user-selected item.

Mail apps can now run on a new native app, OWA for Android, that allows you to access Mail, People and Calendar items on Android smartphones. OWA for Android is the latest addition to OWA for Devices. If your Exchange account is on Office 365 for business or Exchange Online, and your Android smartphone is running Android 4.4 KitKat or later, install a pre-release version of OWA for Android. For more information about the features of OWA for Android, see OWA for Android now available on select devices. We welcome your feedback to help us improve this pre-release version.

The Outlook rich client, Outlook Web App and OWA for Devices are supported on displays with high DPI (for example, retina displays). You can use the HighResolutionIconUrl element and specify a URL to a high resolution icon in the app manifest to represent a compose app in the app selection pane. If you don’t provide a high resolution image, the app selection pane uses the image in the IconUrl element, if you specify one.

You can now create and list mail apps in the Office Store for purchase, similar to task pane and content apps. Only users with a valid app license can use a paid mail app (as opposed to free mail apps which don't require app licenses). Behind the scenes, Exchange Server stores a user’s license tokens in the user’s mailbox. When the user attempts to open a paid mail app, Exchange passes to Outlook the token as a query string parameter for the corresponding sourceLocation URL. When Outlook makes the HTTP request for the app home page, the mail app extracts the encoded license token and caches it. The mail app connects to the Office Store verification web service to validate the token.

If you plan to list a mail app for sale in the Office Store, you should include and test code that obtains an encoded license token as a query string from the sourceLocation URL, and caches the license token for verification later when you need to actually validate the app license. For more information, see Licensing apps for Office and SharePoint.

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

  2. Based on the available features, identify the scenarios for your mail app to support.

  3. See Choosing a version of the platform for your mail app for Outlook and Mail app features per version to verify the versions that offer the features that your scenarios need.

  4. If you're interested in creating a mail app that works in compose or read forms, continue with Create mail apps for compose forms in Outlook and Creating a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1).

  5. If you’re interested in extending an existing app to use compose features, continue with Create mail apps for compose forms in Outlook and Updating the manifest of a mail app from schema v1.0 to v1.1.

Show:
© 2014 Microsoft