RoamingSettings object (JavaScript API for Office)

apps for Office

Represents custom settings for a mail app that are stored in the user's mailbox as name/value pairs.

Last modified: March 04, 2015

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office".

Hosts:Outlook

App type: Mail

Available in requirement sets

Mailbox

Last changed in Mailbox

1.0

Applicable Outlook modes

Compose or read

See all support details

Office.context.roamingSettings

Methods

Name

Description

Introduced in:

get

Retrieves the specified setting.

Version 1.0

remove

Removes the specified setting.

Version 1.0

saveAsync

Saves the settings.

Version 1.0

set

Sets or creates the specified setting.

Version 1.0

The settings created by using the methods of the RoamingSettings object are saved per app and per user. That is, they are available only to the app that created them, and only from the user's mail box in which they are saved.

The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array.

The RoamingSettings object is automatically loaded as part of the Context object, and is available by calling the roamingSettings property of that object when the app is activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the user's mailbox.

The settings saved by using methods of the RoamingSettings object from a user's instance of a mail app are saved in the user's mailbox and are available only to that user's instance of the app. Mail apps also support the CustomProperties object, which lets you create a property bag stored with the current item. For more information, see Creating custom properties for a mail app.

A checkmark (√) in the following table indicates that this property is supported in the corresponding Outlook host application. An empty cell indicates that the Outlook host application doesn't support this property.

For more information about Office host application and server requirements, see Requirements for running apps for Office.

Supported hosts, by platform

Office for Windows desktop

Office for Windows RT

Office Online
(in browser)

OWA for Devices

Office for Mac

Outlook

√ (Read mode only)

Available in requirement sets

Mailbox

Minimum permission level

Restricted

App types

Mail

Library

Office.js

Namespace

Office

Version

Changes

1.0

Introduced

Show:
© 2015 Microsoft