Tips to develop a great mail app for Office

Article
10/16/2013

This article shares tips for developing mail apps in time zone conversion, secure (https) data transmission, tablet/smartphone support, roaming settings to track persistent data, and the non-interchangeable custom properties in the Outlook object model and in the apps for Office platform.

Mail apps are one of the three basic types of apps for Office. Mail apps display next to the currently viewed Outlook items: email message, meeting request, meeting response, meeting cancellation, or appointment. In this blog post, we share tips to help you develop great mail apps.

Display local time

Sometimes you might need to display time-related information in a mail app. For example, the mail sender and recipient are not always in the same time zone. For a better user experience, you might need to convert the sender’s local time to the recipient's local time. Here we propose one method that gets the recipient’s local time zone from the server.

 private string FormatDate(DateTime dateTime)
{
  string date = "";
  dateTime = 
    TimeZoneInfo.ConvertTimeToUtc(
      dateTime
    ).AddHours(Convert.ToInt32(this.TimeZone));
  date = dateTime.ToString("M/d/yyyy H:mm");
  return date;
}

The code is run on an IIS server. dateTime, that represents the sender’s local time, is from a third-party server, but is represented in the local server’s time zone when we get it. this .TimeZone is the mail recipient’s time zone that the server got from the client. dateTime is converted to UTC time first, then the offset of the recipient’s local time zone is added. The returned date is the time in the recipient’s local time zone.

Conversion occurs on the server because the client only needs a date string. The code asks the client to pass the time zone information to the server and let the server convert. After the conversion, the date string is embedded in an HTML page and passed to the client.

To get the recipient’s local time from the client, the JavaScript API method Mailbox.convertToLocalClientTime is recommended. Using date values in mail apps provides an example to show how developers can handle time zone conversion from the client.

Source file location must be a secure URL

The apps for Office platform requires that all source files are hosted on secure (HTTPS) sites. If a mail app communicates with third-party APIs, when receiving an HTTP URL, the URL address cannot be passed directly to the mail app. That is, the source location in the manifest file can’t be assigned to a less-secure (HTTP) URL. Instead, the mail app requires secure (HTTPS) URLs. For the HTTP URL from third part APIs, we must extract data and then pass the data to the mail app through a secure (HTTPS) URL.

In particular, in the app manifest, regardless of whether we’re specifying a URL of a source HTML file (SourceLocation URL) for a mail app running on a desktop, tablet, or smartphone, the URL must be in secure (HTTPS) format. Apps for Office XML manifest overview provides a sample mail app for Office manifest. Creating a manifest for a mail app for Outlook describes four basic steps for creating a manifest for a mail app for Outlook and illustrates the process with an example manifest.

Mail apps support tablets and smartphones

Mail apps are not only for desktops; mail apps also support tablets and smartphones. Creating a manifest for a mail app for Outlook describes four basic steps for creating a manifest for a mail app for Outlook, and shows the process with an example manifest. In particular, the sample manifest file contains codes for tablets and smartphones.

Define settings for a mail app to run on tablets

To run a mail app on a tablet, use the TabletSettings element, and its child elements SourceLocation and RequestedHeight. For example, configure the tablet settings by adding the following code to the XML manifest file.

 <TabletSettings>
  <SourceLocation DefaultValue="https://tablet_URL_address/MyApp.html" />
  <RequestedHeight>350</RequestedHeight>
</TabletSettings>

Here DefaultValue specifies a secure (HTTPS) URL to the mail app source file to be used when the app is running on a tablet; RequestedHeight (350) is the height of the app pane that displays this mail app on a tablet.

Define settings for a mail app to run on smartphones

To run a mail app on a smartphone, use the PhoneSettings element and its child element SourceLocation.

 <PhoneSettings>
  <SourceLocation DefaultValue="https://phone_URL_address/MyApp.html" />
</PhoneSettings>

Here DefaultValue specifies a secure (HTTPS) URL to the mail app source file to be used when the app is running on a smartphone.

Roaming settings

Often, a mail app must store user-specific data, such as user preferences, to provide a custom experience. Mail apps can use the RoamingSettings object to save data specific to the user's mailbox on the Exchange server, so that the mail app can access the data in subsequent sessions on any device that the mail app supports.

RoamingSettings are saved per app and per user. That is, they are available only to the app that creates them and only from the user's mailbox in which they are saved.

The RoamingSettings object is loaded as part of the Context object, and is available by calling the roamingSettings property of that object when the app is activated.

To save data that is specific to an item in the mailbox, use the CustomProperties object instead. See the section Different platforms, different types of custom properties for more information.

How to use the roaming setting

This section describes how to create, assign, get, and remove a roaming setting.

Create or assign a setting

The following JavaScript function setAppSetting shows how to use the RoamingSettings.set method to set a setting named PropertyKey with a value PropertyValue, and persist the data by using the RoamingSettings.saveAsync method to save the roaming settings back to the Exchange server.

 /**
*Set an application setting.
*/
function setAppSetting(IsEULAAccepted) {
  MyApp.settings.set("PropertyKey", "PropertyValue");
  MyApp.settings.saveAsync(saveMyAppSettingsCallback);
}

/**
*Callback method after saving roaming settings.
*/
function saveMyAppSettingsCallback(AsyncResult) {
  if (AsyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  // Do something here.
}

The property key of a setting is a string, and the property value can be a string, a number, a Boolean value, null, an object, or an array.

Get a setting

The following JavaScript function getAppSetting shows how to use the RoamingSettings.get method to get the value of the setting PropertyKey.

 // Use the Office.context.roamingSettings.get method to get the value of the
// "PropertyKey" property by name.
function getAppSetting() {
  if (Office.context.roamingSettings.get("PropertyKey ")) {
    var propertyValue = Office.context.roamingSettings.get("PropertyKey ");
    // Do something with PropertyValue.
  }
}

Remove a setting

The following JavaScript function removeAppSetting shows how to use the RoamingSettings.remove method to remove the PropertyKey property and save the settings for the current item back to the Exchange server.

 // Remove a setting from an item.
// Remove the setting named PropertyKey and then save.
function removeAppSetting() {
  Office.context.roamingSettings.remove("PropertyKey");
  Office.context.roamingSettings.saveAsync(saveMyAppSettingsCallback);
}

How to: Persist data for the same mailbox by using roaming settings describes how to store and access data that is specific to a mailbox and a mail app, and that is accessible on the supported form factors.

Different platforms, different types of custom properties

In the Outlook object model (OM), users and add-ins can create and manage custom properties for an Outlook item by using the UserProperties object. In the JavaScript API for Office, mail apps can create and manage a different kind of custom properties for Outlook items using the Custom properties object. However, these two custom properties are different and not interchangeable. That is, we can’t get one type of custom properties from another.

For example, the following table lists the different methods for the two totally different custom properties.

Action	Method (Outlook OM)	Method (apps for Office)
Create a new custom property	Add	Set and then saveAsync
Retrieve a custom property	Item	Get
Search a custom property	Find	Get
Remove a custom property	Remove (Outlook)	Remove (apps for Office) and then saveAsync

Table 1. Different methods for Outlook custom properties and app for Office custom properties

Properties Overview describes Outlook OM properties and Properties (Outlook) discusses properties-related actions like creating/deleting a property and getting/setting the value of a property. How to: Persist data for the same item in a mailbox using custom properties in Outlook describes how a mail app uses custom properties to store data that is specific to an Outlook item in the user’s mailbox on, and access the data subsequently on the supported Outlook clients and form factors.

References

Attribute

This article was written by ecoSystem team intern Meiling Liu and content developer Tony Liu. Content developer Angela Chu-Hatoun, program manager Andrew Salamatov, and SDE Yihua Cao provided valuable feedback.