Export (0) Print
Expand All

Save item-specific metadata as custom properties

apps for Office

Learn about custom properties that allow you to store data about the message or appointment that the user is viewing or composing in Outlook.

Last modified: June 20, 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

In this article
Custom properties and MAPI-based properties
Using custom properties
Custom properties example
Additional resources

Note Note

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

The apps for Office platform lets you create a property bag to store data as strings for the item that the user is viewing or composing in Outlook. This property bag is accessible by only the mail app that created it, is stored for that item on the Exchange server, and can be retrieved when the item is reopened on any device supported by that app.

For example, if your mail app creates appointments from meeting suggestions in a message, you can use a custom property to track each of these appointments. This ensures that if the user opens the message again, your mail app does not offer to create the appointment a second time.

These app-specific, item-specific custom properties are represented in the JavaScript API for Office as CustomProperties, and can be accessed by using only the CustomProperties object. These properties are different from the custom, MAPI-based, UserProperties in the Outlook object model, and extended properties in Exchange Web Services (EWS). You cannot access CustomProperties by using the Outlook object model or EWS.

On the other hand, a mail app can get MAPI-based extended properties by using the EWS GetItem operation. Access GetItem on the server side by using a callback token, or on the client side by using the Mailbox.makeEwsRequestAsync method. In the GetItem request, specify the custom extended properties you need in a property set. A mail app can also use makeEwsRequestAsync and EWS CreateItem and UpdateItem operations to create and modify extended properties.

For more information about MAPI properties, Outlook UserProperties, EWS extended properties, using the callback token mechanism and makeEwsRequestAsync, see the Additional resources section.

Before you can use custom properties, you must load the property bag by calling the loadCustomPropertiesAsync method. If any custom properties are already set for the current item, they are loaded from the Exchanger server at this point. After you have created the property bag, you can use the set and get methods to add and retrieve custom properties. To save any changes that you make to the property bag, you must use the saveAsync method to persist the changes on the Exchange server.

The following table lists the objects and methods that you use with custom properties.

Object name

Method name and parameters

Description

Item (Appointment, Message, MeetingRequest)

loadCustomPropertiesAsync(callback, userContext)

Creates a property bag of custom properties and provides methods for working with the property bag. When the asynchronous call finishes, the method specified in the callback parameter is called by using one parameter, asyncResult, which contains the property bag in its value property. You can use the optional userContext parameter to pass state to the callback function.

CustomProperties

set(name, value)

Sets a property to a value. If the property does not exist, the property is created. If the property does exist, the existing value is replaced with the new value.

CustomProperties

get(name)

Gets a property value. The value can be of any type, but it is always returned in its string representation.

CustomProperties

remove(name)

Removes the custom property from the property bag.

CustomProperties

saveAsync(callback, userContext)

Saves the custom property bag on the Exchange server. Changes made with the set and remove methods are not persisted unless this method is called. When the asynchronous call finishes, the method specified in the callback parameter is called.

The following example shows a simplified set of methods for a mail app that uses custom properties. You can use this example as a starting point for your mail app that uses custom properties.

A mail app that uses this code retrieves any custom properties by calling the get method on the _customProps variable, as shown in the following example.

var property = _customProps.get("propertyName");

This example includes the following methods:

  • Office.initialize — Initializes the app and loads the custom property bag from the Exchange server.

  • customPropsCallback — Gets the custom property bag that is returned from the Exchange server and saves it for later use.

  • updateProperty — Sets or updates a specific property, and then saves the change to the Exchange server.

  • removeProperty — Removes a specific property from the property bag, and then saves the removal to the Exchange server.

/// <reference path="Scripts/Office.js" />
/// <reference path="Scripts/Outlook-15.js" />
/// <reference path="Scripts/MicrosoftAjax.js" />

var _mailbox;
var _customProps;

// The initialize function is required for all apps.
Office.initialize = function () {
    _mailbox = Office.context.mailbox;

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, further app-specific code can run.
        _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
}

function customPropsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
    else {
        _customProps = asyncResult.value;
    }
}

function updateProperty(name, value) {
    _customProps.set(name, value);
    _customProps.saveAsync(saveCallback);
}

function removeProperty(name) {
   _customProps.remove(name);
   _customProps.saveAsync(saveCallback);
}

function saveCallback() {
}
Show:
© 2014 Microsoft