Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

How to: Persist metadata for the same mailbox by using roaming settings

apps for Office

Learn how to store and access data that is specific to a mailbox and a mail app, and accessible on the supported form factors.

Last modified: February 27, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | 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

Unless otherwise specified, references to "Outlook" apply to the Outlook rich client, Outlook Web App, and OWA for Devices.

In this article
Roaming settings format
Loading roaming settings
Creating or assigning a setting
Removing a setting
Additional resources

A mail app can use the RoamingSettings object to save data that is specific to the user’s mailbox. This data is accessible by only that mail app. The data is stored on the Exchange Server for that mailbox, and is accessible in subsequent Outlook sessions on all the form factors that the mail app supports.

The data in a RoamingSettings object is stored as a serialized JavaScript Object Notation (JSON) string. The following is an example of the structure, assuming there are three defined roaming settings named app_setting_name_0, app_setting_name_1, and app_setting_name_2.

{
"app_setting_name_0":"app_setting_value_0",
"app_setting_name_1":"app_setting_value_1",
"app_setting_name_2":"app_setting_value_2"
}

A mail app typically loads roaming settings in the Office.initialize event handler. The following JavaScript code example shows how to load existing roaming settings and get the values of 2 settings, "customerName" and "customerBalance":

var _mailbox;
var _settings;
var _customerName;
var _customerBalance;

// The initialize function is required for all apps.
Office.initialize = function () {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run
        // and use the roaming settings.
    });
}

Continuing with the preceding example, the following JavaScript function, setAppSetting, shows how to use the RoamingSettings.set method to set a setting named cookie with today’s date, and persist the data by using the RoamingSettings.saveAsync method to save all the roaming settings back to the Exchange Server. The set method creates the setting if the setting does not already exist, and assigns the setting to the specified value. The saveAsync method saves roaming settings asynchronously. This code sample passes a callback method, saveMyAppSettingsCallback, to saveAsync. When the asynchronous call finishes, saveMyAppSettingsCallback is called by using one parameter, asyncResult. This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. You can use the optional userContext parameter to pass any state information from the asynchronous call to the callback function.

// Set an application setting.
function setAppSetting() {
    _settings.set("cookie", Date());
    _settings.saveAsync(saveMyAppSettingsCallback);
}

// Callback method after saving custom application roaming settings.
function saveMyAppSettingsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
}

Also extending the preceding examples, the following JavaScript function, removeAppSetting, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings back to the Exchange Server.

// Remove an application setting.
function removeAppSetting()
{
    _settings.remove("cookie");
    _settings.saveAsync(saveMyAppSettingsCallback);
}
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.