Office.RoamingSettings interface
The settings created by using the methods of the RoamingSettings object are saved per add-in and per user. That is, they are available only to the add-in that created them, and only from the user's mailbox in which they are saved.
While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings shouldn't be considered secure storage. They can be accessed by Exchange Web Services or Extended MAPI. They shouldn't be used to store sensitive information, such as user credentials or security tokens.
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 accessible via the roamingSettings property in the Office.context namespace.
To learn more about RoamingSettings, see Get and set add-in metadata for an Outlook add-in.
Remarks
Important:
The
RoamingSettingsobject is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it's only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane (or item in the case of UI-less add-ins) is closed and reopened.When set and saved through Outlook on Windows (new or classic) or on Mac, these settings are reflected in Outlook on the web only after a browser refresh.
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Methods
| get(name) | Retrieves the specified setting. |
| remove(name) | Removes the specified setting. |
| save |
Saves the settings. Any settings previously saved by an add-in are loaded when it's initialized, so during the lifetime of the session you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they're available the next time the add-in is used, use the |
| set(name, value) | Sets or creates the specified setting. The A maximum of 32KB is available for the settings of each add-in. An error with code 9057 is thrown when that size limit is exceeded. Any changes made to settings using the |
Method Details
get(name)
Retrieves the specified setting.
get(name: string): any;Parameters
- name
-
string
The case-sensitive name of the setting to retrieve.
Returns
any
Type: String | Number | Boolean | Object | Array
Remarks
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);
remove(name)
Removes the specified setting.
remove(name: string): void;Parameters
- name
-
string
The case-sensitive name of the setting to remove.
Returns
void
Remarks
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
saveAsync(callback)
Saves the settings.
Any settings previously saved by an add-in are loaded when it's initialized, so during the lifetime of the session you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they're available the next time the add-in is used, use the saveAsync method.
saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
if (result.status !== Office.AsyncResultStatus.Succeeded) {
console.error(`Action failed with message ${result.error.message}`);
} else {
console.log(`Settings saved with status: ${result.status}`);
}
});
set(name, value)
Sets or creates the specified setting.
The set method creates a new setting of the specified name if it doesn't already exist, or sets an existing setting of the specified name. The value is stored in the document as the serialized JSON representation of its data type.
A maximum of 32KB is available for the settings of each add-in. An error with code 9057 is thrown when that size limit is exceeded.
Any changes made to settings using the set method will not be saved to the server until the saveAsync method is called.
set(name: string, value: any): void;Parameters
- name
-
string
The case-sensitive name of the setting to set or create.
- value
-
any
Specifies the value to be stored.
Returns
void
Remarks
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);
Office Add-ins