CustomProperties.saveAsync method (JavaScript API for Office)

apps for Office

Saves item-specific custom properties to the Exchange Server 2013.

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". For details, see New name for apps for Office and SharePoint.

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

saveAsync(callback, userContext)

callback

The method to call when an asynchronous call is complete. Optional.

userContext

Any state data that is passed to the saveAsync method. Optional.

You must call the saveAsync method to persist any changes made with the set method or the remove method of the CustomProperties object. The saving action is asynchronous. When the asynchronous call finishes, the method specified in the callback parameter is called by using one parameter, asyncResult. You can use the optional userContext parameter to pass any state information to the callback function. The callback parameter is optional.

It’s a good practice to have your callback function check for and handle errors from saveAsync. In particular, a read app can be activated while the user is in a connected state in a read form, and subsequently the user becomes disconnected. If the app calls saveAsync while in the disconnected state, saveAsync would return an error. Your callback method should handle this error accordingly.

In this article, "Outlook" refers to Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), and Outlook Web App. "Outlook rich clients" refers to Outlook for Windows, Outlook for Mac and Outlook RT. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

The following JavaScript code sample shows how to asynchronously use the Item.loadCustomPropertiesAsync method to load custom properties that are specific to the current item in Microsoft Outlook, and the CustomProperties.saveAsync method to save these properties back to Exchange Server 2013. After loading the custom properties, the code sample uses the CustomProperties.get method to read the custom property myProp, the CustomProperties.set method to write the custom property otherProp, and then finally calls the saveAsync method to save the custom properties.

// The initialize function is required for all apps.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
    // After the DOM is loaded, app-specific code can run.
    var item = Office.context.mailbox.item;
    item.loadCustomPropertiesAsync(customPropsCallback);
    });
}
function customPropsCallback(asyncResult) {
    var customProps = asyncResult.value;
    var myProp = customProps.get("myProp");

    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed){
        write(asyncResult.error.message);
    }
    else {
        // Async call to save custom properties completed.
        // Proceed to do the appropriate for your app.
    }
}

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

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

ReadItem

App types

Mail

Library

Office.js

Namespace

Office

Version

Changes

1.0

Introduced

Show:
© 2015 Microsoft