Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

Save item-specific metadata as custom properties in Outlook

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: April 01, 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

In this article
Using custom properties
Custom properties example
Additional resources

Note Note

Unless otherwise specified, references to "Outlook" apply to the Outlook rich client, 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 stored on the Exchange server and can be retrieved when the item is reopened. Each mail app can access only its own property bag.

For example, if you create a mail app that creates an appointment from a meeting suggestion in a message, you can use custom properties to store the fact that the meeting was created. This ensures that if the message is opened again, your mail app does not offer to create the appointment again.

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() {
}

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.