So, You Want to Build an Office Mail App

  • Article

Facebook, Twitter, Yammer, Pinterest, and all the other social media outlets have an amazing aptitude for communication, but the one comprehensive and reliable communication channel is still email. Email is the start and end of every business's day--and sometimes into the wee hours of the morning.

Mail apps for Office are an integration of what we are already chained to and the capability to empower email to be more insightful. They can give an old application a new interface to grow.

Office AMS 2.0

In the recent release of Office AMS 2.0, we added a simple mail app for picking up YouTube video urls from an email and present them in the Outlook interface in both the web and desktop clients. It is located in the [OfficeAMS] \Samples\Core.MailApps folder.

OfficeAMS-FolderStructure

Office Mail Apps AppManifest.xml

Visual Studio will structure your application into 2 parts: the Office application manifests and the web applications that support them. You can have multiple Mail App manifests in one Office App project, but for the purpose of this release, only one is included.

OfficeAMS-MailApp-ProjectStructure

When you double-click the app Core.YouTubeApp, you will be presented with the deployment properties interface. It has tabs for:

  • General – Details about the app
  • Read Form – What scenarios cause the app to become available when the reading pane is visible
  • Compose Form – What scenarios cause the app to become available when the compose pane is visible
  • App Domains – What site URLs are available to be opened from your app when making cross-domain calls

The AppManifest.xml file describes the app to the Office client application. You can modify the same features available in the tabbed experience in XML directly. The XML for the YouTube app is as follows:

 <OfficeApp xmlns="https://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
   <Id>e1c173ce-6df8-479e-86c1-59fa33774441</Id>
   <Version>1.0.0.0</Version>
   <ProviderName>Contoso</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <DisplayName DefaultValue="YouTube" />
   <Description DefaultValue="YouTube video player"/>
   <Capabilities>
     <Capability Name="Mailbox" />
   </Capabilities>
   <DesktopSettings>
     <SourceLocation DefaultValue="~remoteAppUrl/AppRead/YouTube/YouTube.html" />
     <RequestedHeight>350</RequestedHeight>
   </DesktopSettings>
   <Permissions>ReadItem</Permissions>
   <Rule xsi:type="RuleCollection" Mode="Or">
     <Rule xsi:type="ItemIs" ItemType="Message"/>
     <Rule xsi:type="ItemHasKnownEntity" EntityType="Url" IgnoreCase="true" FilterName="YouTubeVideos" RegExFilter="youtube\.com\/watch" />
   </Rule>
   <DisableEntityHighlighting>false</DisableEntityHighlighting>
 </OfficeApp>

General Tab

The general tab has basic settings for your app. You can set the Display Name (which appears on the apps tab in the Reading Pane), set the version, list the provider, provide a description and icon, and you can set permissions. You can see it in the image below.

In the Office AMS sample, we’re only going to be reading the email and not modifying the email or modifying the user’s mailbox in any manner. Read more about permissions here.

image

Read Form Tab

The Read Form tab specifies what items cause the app to be activated. It allows you to create rules based on regular expressions which may or may not already exist. Any or All of the scenarios must match (depending on the top-level rule) in order for the app to be activated. The Office API will automatically detect all URLs, email addresses, phone numbers and some other items, but you can further filter these with your own regular expressions.

In the YouTube scenario, we’re looking for the presence of a youtube.com/watch address. If this regular expression matches in the message or subject, the app will appear in the Reading Pane in Outlook or Outlook Web Access. Note that the Filter name has been set. This enables us to find the items by name during runtime.

The Source Location points to the web address your app will point to once the app is activated.

OfficeAMS-MailApps-ReadForm

The only drawbacks with the filters, right now, manifest themselves when using the Item is appointment filter. If you are trying to use the location as a filter (maybe trying to find a PIN code for teleconference calls, you may have issues. Forwarded meeting invites do not appear as appointments, they are considered a “message”, so you may not see your app activated with just “appointment”. It’s worth experimenting with, though.

The Web Application

The YouTube application is very simple. The web site hosts a basic HTML page with no server-side code. We could easily implement server-side code here to perform operations such as OAuth authorizations, dynamic views of content, or event write a data entry application; however, in this simple example we will find all of the YouTube entries in the email message and put them into a nice viewing window in Outlook.

The web application has a folder already configured with an AppRead folder for the Read Form view. There is nothing special with the name, just ensure that the name matches what is in the AppManifest when it is published and consumed by your Outlook client in the Source Location attribute (currently ~remoteAppUrl/AppRead/YouTube/YouTube.html):

image

Script Me Some YouTube Videos!

The YouTube.js script is very simple.

  1. Get the item from the Office.context.mailbox.item object hierarchy.
  2. Call item.getFilteredEntitiesByName("YouTubeVideos") which will provide all the entities that are picked up by the interface. In the sample, I wrote the code to point to the item.getEntities() because there is a separate regular expression filter on the URL, anyways. The separate regular expression is to find the ID of the YouTube video for use in the youtube.com/embed url which is used to display the video.
  3. Provide the video ID to individual tabs for use when the tab is clicked.
  4. Upon click, set the event to replace the contents of the video frame with the embedded player path for YouTube and provide a link to the video.

Deployment

The deployment is a very simple process as well.

  1. Deploy the app to a web host. This could be your own web host running on an Apache server or Windows server. Or, Windows Azure can be your web host (remember that you get 10 web sites for free).
  2. Find a location to host the AppManifest.xml file. Upon building the project, I copy the Core.YouTubeApp.xml to a folder within the web site called Apps and set the ~remoteAppUrl to whatever the actual site URL is. This is actually done by a file called UpdateAppUrl.ps1 stored in the Core.MailApps directory and is run from the Mail App project. You can update the UpdateAppUrl.ps1 file with your actual domain address.
  3. If your administrator allows it, from within the Outlook Web Access site you can add the app directly as a trusted app by pointing directly to the appmanifest URL.
  4. You can also submit this app as an Office store app.

There you have it, a simple YouTube app. Now, I want to see one in the store and one for Channel 9.