Office 2013 – Custom Properties in Mail Apps

From a web developer’s perspective, Office 2013 has brought about some very interesting possibilities. Take, for example, Mail Apps.

Mail Apps are HTML & Javascript applications that run inside Outlook 2013 — both on Office 365 and on the traditional desktop client. Prior to Office 2013, getting any type of custom functionality into Outlook required a plugin — cumbersome for developers and users alike. Mail Apps reduce this complexity significantly – with the help of Microsoft’s new app store, both development and installation are now much simpler.

I was intrigued by the concept of Mail Apps when the Developer Preview first launch and spent some time seeing what I could achieve — as a jQuery fan, I always welcome the opportunity to solve problems with jQuery that may or may not have actually needed it.

There are, it seems, some annoying limitations with what you can do — say goodbye to the window object, for example — but also some serious potential.

One particular element of Mail Apps that shows a lot of potential is the Custom Properties feature – data stored on the Exchange server that are associated with items.  The process for working with them is pretty simple – make a call to the server to pull in custom properties, get or set as needed, and asynchronously save them back to the server. It’s a simple idea, but a potent one. It’s not just local storage the same data is available no matter where you view the mail item.

As an example of how to use custom properties in a Mail App, here’s a potential requirement – tracking task status in an email. There are, of course, plenty of task-status tracking options out there, including one offered by Outlook itself (though it’s pretty simplistic) but most are fairly dedicated to the concept. What if we just want to keep track of a task within an email, and maybe jot down some notes about it?

As it turns out, a Mail App is a great fit for this scenario. The app’s flow is pretty simple:

  1. When the app loads, retrieve the custom properties for the item
  2. Render the data, and track any updates the user makes
  3. Save the changes back to the server

Normally, steps #1 and #3 would represent a serious hassle in a web app. Fortunately Office 2013 takes care of data persistence for us entirely we load and we save, and that’s about it. No need to write a backend or paste in SOAP envelopes.

This pretty much just leaves us with the display side of things -to start with, maintaining a ‘view-model’ that can be saved back to the server or loaded when necessary:

(Note: I won’t show all of the code within this post — see the full code for the actual source)    

var TASK_PROGRESS = "TaskProgress";
var TASK_NOTES = "TaskNotes";

var viewModel =
taskComments: [],
//progress: between 0 and 100

renderTaskDetails: function()
$("#taskProgressBar").width(this.taskProgress * 5);

  • "+el+"
  • ");
    setProgress: function(p)
    this.taskProgress = p;
    addComment: function(text)
    saveTaskDetails: function()
    _CustomProps.saveAsync(function() {

    Saved changes.

    setTimeout(function() { $("#message_log").empty(); },1500);

    This task model has two parts: a progress percentage, between 0 and 100, and an array of strings. Simple enough.

    Note the ‘saveTaskDetails’ function. _CustomProps, a variable that holds the custom properties for the item (see full code)

    The next step is is to populate the view model:

    function onInitializeComplete() {
    // Load custom properties for the current item.

    function myLoadAllCustomPropertiesCallback(obj)
    _CustomProps = obj.value;

    var taskProgress;
    var taskComments;

    if (_CustomProps.get(TASK_PROGRESS))
    taskProgress = _CustomProps.get("TaskProgress");
    viewModel.taskProgress = taskProgress;

    if (_CustomProps.get(TASK_NOTES))
    taskComments = _CustomProps.get("TaskNotes");
    viewModel.taskComments = taskComments;


    The onInitializeComplete method is called within the Office.Initialize method – the _Item.loadCustomPropertiesAsync() call will retrieve custom properties associated with the item.

    This is pretty much the only code required to make a Mail App using custom properties — of course, there’s plenty of display logic I haven’t shown here, but it’s nothing spectacular.

    Here’s a shot of the app in action, callous disregard of padding and all:


    In summary – Mail Apps are cool. Custom properties offer a lot of potential, and hopefully Office 2013 enables you all to create some really cool solutions.

    Here’s the full source:

    Phone: 312-602-4000
    222 W. Adams
    Chicago, IL 60606
    Show Buttons
    Share On Facebook
    Share On Twitter
    Share on LinkedIn
    Hide Buttons