Sharepoint 2013 : The Office JavaScript Object Model (part 2) - Functional Capabilities by Office Client,Mailbox-based Apps

Functional Capabilities by Office Client

A number of other functional capabilities are available in the API but these are so numerous that they will need to be left to your own discovery. http://dev.office.com has the full documentation for the Apps for Office JSOM. Table 1 identifies some of the more popular additional functional capabilities and shows how they map to the Office client applications.

TABLE 1: Functional Areas vs. App Support Summary

Mailbox-based Apps

Certainly as widely used by business professionals as Excel is for number crunching and Word is for authoring documents, a vast number of people exist whose days are built around communicating, scheduling, managing contacts, and ordering their day’s tasks with Outlook. Therefore, historically, Outlook has been one of the most targeted Office clients for third-party add-ins. Outlook tends to be a hub application in the business person’s day and a primary point of reference. Plus, if for some reason during the day a person doesn’t have access to his or her desktop, a web companion called Outlook Web Access is available as long as he or she has access to a browser and an Internet connection. This tight bond between business people and their Outlook is what makes it such a key new opportunity for landing your app for Office.

The MailApp for Office differs from the TaskPaneApp and the ContentApp in a couple of ways. First, it is not associated with a document, and second, it does not render in a task pane in Outlook nor on the surface of a mail item like the ContentApp does in a workbook. Rather, MailApps are activated in the Outlook, OWA, or Outlook mobile UI based upon activation rules defined in your app for Office manifest file. This declarative set of rules evaluates contextual content within an e-mail message or appointment item when it is opened. If the contextual content within the item matches one or more of the activation rules then the MailApp will be automatically activated and show in the UI. This differs from the document-based apps for Office that must be manually selected and inserted via the ribbon by the user. Lastly, another significant difference is that the manifest file is deployed to an Exchange server, App Catalog, rather than to SharePoint or a network share. Microsoft has pre-installed at least four mailbox-based apps to the Office 365 Exchange App Catalog for each tenancy. These Apps for Office — Action Items, Bing Maps, Suggested Meetings, and Unsubscribe — are found in the Exchange admin center under Organization ⇒ Apps. Although the Office 365 Exchange administrator can globally disable these apps for their tenancy, they cannot be uninstalled. However, given that they are available to users, they will automatically activate for a user when the activation rules are met within a mail item.

For a mailbox-based app, the activation rules act on contextual information within the mail item and provide the unique opportunity to build genuine productivity solutions for those who live in their Outlook. You can use several built-in, well-known entity types to activate a MailApp. These include URL, contact, task suggestion, meeting suggestion, phone number, address, and e-mail address. In your app manifest, using the Rule element, you would include the evaluation of one or more of these in the form of <Rule xsi:type="ItemHasKnownEntity" EntityType="Contact" />, for instance. You can further scope the activation rule by adding an additional attribute of RegExFilter where the rule will only activate if, say, the RegExFilter="ID". With this rule the intent is that you are only interested in identifying contacts from the state of Idaho. Hence, your MailApp would activate only when contact information contains an uppercase ID value. Although the well-known entity types will save you a ton of code writing, you will sometimes, of course, want a fully customized rule. Suppose you want to provide a convenient way for an Outlook user to interact with a back-end Line of Business (LoB) application or your Software as a Service (SaaS) application when the system sends an autogenerated e-mail to a stakeholder. In these situations you build your own rule using the ItemHasRegularExpressionMatch type. With this type you provide your own RegExValue to pattern match against the contextual information in the item body (whether HTML or plain text), subject, or sender’s SMTP address. This fully customized rule, as with any other rule, can then stand alone or be combined with other rules in a rule collection. You can combine the RuleCollection type using a Mode of And or Or with other rule collections to create complex rules. This flexibility in rule and rule collection construction provides you the ability to control precisely what needs to be in the mail or appointment item for your MailApp to activate. When a rule is not met, the MailApp will not show in the UI.

From an app model perspective, you still have a manifest file and you write your mailbox-based app using your favorite web technologies and host the app on any server you like. From a JSOM perspective you still use the Office JSOM but you use the Office.context.mailbox object. From the mailbox object you can get information relating to the specific message or appointment item and access a limited set of profile information about the user. For more advanced scenarios you can call back into Exchange using Exchange Web Services (EWS) where you can create new e-mail messages and appointments to provide a more deeply integrated mailbox-based app for Office. For now, in the following Try It Out, you can explore well-known entities, rules and rule collections, and regular expressions for customized pattern matching.

<body>
    <div id="Content">
        <h4>Display some of what's available to developers:</h4>
        User Profile name: <span id="displayName"></span>
        <br />
        User Profile time zone: <span id="timeZone"></span>
        <br />
        Email item Subject: <span id="subject"></span>
        <br />
        Email item From: <span id="from"></span>
        <br />
        Email item To: <span id="to"></span>
       <table>
           <tr><td>Urls</td><td id="urls" /></tr>
           <tr><td>Contact Names and Addresses</td><td id="contactNames" /></tr>
           <tr><td>Invoices</td><td id="regexInvoices" /></tr>
       </table>     
    </div>
</body>

  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemIs" ItemType="Message" />
      <Rule xsi:type="ItemIs" ItemType="Appointment" />
    </Rule>
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemHasKnownEntity" EntityType="Contact" 
RegExFilter="ID" FilterName="state" IgnoreCase="false" />
      <Rule xsi:type="ItemHasKnownEntity" EntityType="Url" />
      <Rule xsi:type="ItemHasRegularExpressionMatch"
      PropertyName="BodyAsHTML" IgnoreCase="true"
      RegExName="Invoices"
      RegExValue="\bINVOICE#\s*([0-9][0-9][0-9][0-9][0-9][0-9])+\b"/>
    </Rule>
  </Rule>

Office.initialize = function () {
    $(document).ready(function () {
        var userProfile = Office.context.mailbox.userProfile;
        $('#displayName').text(userProfile.displayName);
        $('#timeZone').text(userProfile.timeZone);
 
        var item = Office.context.mailbox.item;
        $('#subject').text(item.normalizedSubject);
        $('#from').text(item.from.displayName);
        $('#to').text(item.to[0].displayName);
 
        //Get all the well-known entities to show this pattern and use for URLs.
        var myEntities = item.getEntities();
 
        // Build an array of Urls using the Urls entity.
        var myUrls = myEntities.urls;
        // Loop over the myUrls array.
        var myString = "";
        for (i = 0; i < myUrls.length; i++) {
            myString += "<a href='" + myUrls[i] + "'>" + myUrls[i] 
+ "</a>" + " <br />";
        }
        // Write the Contacts found to the web page
        $('#urls').html(myString);
 
        // Build an array of Contacts by directly accessing the filtered entity 
        // by name.
        var myContacts = item.getFilteredEntitiesByName("state")
        // Loop over the myContacts array.
        myString = "";
        for (i = 0; i < myContacts.length; i++) {
            myString += 
                   myContacts[i].personName + ", " + myContacts[i].addresses 
+ " <br />";
        }
        // Write the Contacts found to the web page
        $('#contactNames').html(myString);
 
        // Handle invoices from RegEx matches
        var myInvoices = item.getRegExMatches();
        //Loop over the myInvoices collection.
        myString = "";
        for (var i in myInvoices.Invoices) {
            myString += myInvoices.Invoices[i] + ", ";
        }
        // Write the invoices found to the web page
        $('#regexInvoices').text(myString);
 
    });
};

<Rule xsi:type="RuleCollection" Mode="And"> (this is the overarching AND)
 <Rule xsi:type="RuleCollection" Mode="Or"> (the OR for Message/Appointment)
...
 </Rule>
 <Rule xsi:type="RuleCollection" Mode="Or"> (the OR for well-known Entities/RegEx)
...
 </Rule>
</Rule>

This Try It Out is not at all exhaustive of the many different ways you can interact with mail and appointment items in a MailApp, but hopefully it pulls together enough of the concepts and code to get you rolling. Mailbox-based apps can provide a convenient vector for engaging a user for interaction with your back-end systems. These can be great companion apps for your SaaS or LoB systems because they render everywhere, whether within Outlook on the rich client, OWA, or Outlook mobile.