Get and set app metadata for a mail app in Outlook

apps for Office

Learn about loading and storing custom data that only your mail app can access - through roaming settings for a mailbox, or through custom properties for an item in a mailbox.

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

Note Note

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

In this article
Custom data per mailbox: roaming settings
Custom data per item in a mailbox: custom properties
In this section
Additional resources

You can specify data specific to a user’s Exchange mailbox using the RoamingSettings object. Examples of such data include the user’s personal data and preferences. Your mail app can access roaming settings when it roams on any device it’s designed to run on (desktop, tablet, or smartphone).

The following code sample shows how to load the RoamingSettings object by accessing the Office.context.roamingSettings property. It also shows how to get and set specific settings. Getting and setting occur to the in-memory copies of those settings for the current Outlook session. You should explicitly save all the roaming settings to the Exchange Server so that they will be available the next time the user opens your mail app, on the same or any other supported device. For more details, see How to: Persist metadata for the same mailbox by using roaming settings.

Office.initialize = function () {
    // Load roaming settings from the server.
    var settings = Office.context.roamingSettings;
    var customerName;

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get a roaming setting.
        customerName = settings.get("customerName");

        // Set a roaming setting.
        settings.set("LastAccess", Date());

        // Save all roaming settings for the mailbox
        // to the server so that they will be available
        // in the next session.
        settings.saveAsync(saveSettingsCallback);
    });
}

// Callback function from saving roaming settings.
function saveSettingsCallback(asyncResult) {
}

You can also specify data specific to an item in an Exchange mailbox using the CustomProperties object. For example, your mail app can categorize certain messages and note the category using a custom property "messageCategory".

The following code sample shows how to load the CustomProperties object by calling the asynchronous method Office.context.mailbox.item.loadCustomPropertiesAsync. It also shows how to get and set specific properties. Similar to roaming settings, getting and setting occur to the in-memory copies of the properties for the current Outlook session. To make sure these custom properties will be available in the next session, save all the custom properties to the Exchange Server. For more details, see Save item-specific metadata as custom properties and How to: Persist metadata for the same Outlook item in a mailbox using custom properties.

Office.initialize = function () {
    var mailbox = Office.context.mailbox;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Load custom data for the item that the
        // user has selected in user's mailbox.
        mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
    else {
        // Successfully loaded custom properties,
        // can get them from the asyncResult argument.
        var customProps = asyncResult.value;

        // Get individual custom property.
        var myProp = customProps.get("myProp");

        // Set individual custom property.
        customProps.set("otherProp", "value");

        // Save all custom properties to server.
        customProps.saveAsync(savePropsCallback);
    }
}

// Callback function from saving custom properties.
function savePropsCallback(asyncResult) {
}
Show:
© 2014 Microsoft