Windows Vista
Windows 7
Windows Azure
Windows Server
Windows Phone
Windows Server

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

8/17/2014 4:34:42 AM

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.

TRY IT OUT: Using the Office JSOM for Mailbox-based Apps (Explore MailApp.zip)

In this exercise you work with the fundamentals of MailApps using a complex rule in the manifest file, retrieving information from the mail item, and displaying the information in a web page for the user to see. Because MailApps deploy to the Exchange App Catalog, you will deploy it to your Office 365 developer tenancy Exchange Server. Just follow these steps:

1. Run Visual Studio 2012 as Administrator. Select New Project.

2. In the New Project dialog, expand the Templates ⇒ Visual C# ⇒ Office/SharePoint ⇒ Apps nodes. Select App for Office 2013 and provide the Name: ExploreMailApp. Click OK.

3. In the Create App for Office dialog, select Mail app in. Click Finish.

4. The ExploreMailApp.html file should be displayed by default. If it’s not, open it from the Pages folder and replace the entire <body>...</body> contents with the following:
<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>
<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>
5. Open the ExploreMailApp.xml manifest file and replace the entire <Rule>...</Rule> rule collection node with the following:
  <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 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"
6. Open the JavaScript file and replace the entire contents with the following:
Office.initialize = function () {
$(document).ready(function () {
var userProfile = Office.context.mailbox.userProfile;

var item = Office.context.mailbox.item;

//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

// 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

// 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

7. Before you run this, click on the ExploreMailApp node in the Solution Explorer and view the Properties. Notice that the Start Action is set to start using Microsoft Outlook Web Access. You could set the Start Action to Microsoft Outlook, but using OWA is best for testing to avoid any impact on your current Outlook configuration.

8. Press F5 to start debugging. (Internet Explorer must have script debugging enabled for the app to run.) Visual Studio immediately prompts you for your mailbox credentials. Enter your Office 365 developer subscription in the form of YourO365UserName@YourO365DeveloperDomain.onmicrosoft.com and the password for the account. If you choose the Remember my e-mail option, you won’t be bothered by Visual Studio any longer with this prompt, but if you ever want the prompt back to possibly deploy to another mailbox, then delete this e-mail address from the E-mail Address property for the ExploreMailApp node.

9. After your browser opens, log in to Office 365 using the same account and password from step 8.

10. Because you might not have any e-mail items already in your mailbox that will fire the activation rules you’re using, create and send a new e-mail to your Office 365 account with each of the following on a separate line in the e-mail body exactly as they are shown here:
a. http://bing.com
b. Joe Doe, 1234 SW East ST, Boise, ID, 88763
c. Jon Doe, 624 West South ST, Sturgis, SD, 55557
d. INVOICE# 000768, Invoice# 023457, invoice# 009888, invoice# 987

11. When you receive the e-mail, click on it. In the location above the body where MailApps render, you’ll see a tab labeled ExploreMailApp. Click on this tab to see your MailApp in action.

How It Works
Take a look at the all-important activation rule. It is called a complex activation rule, but that doesn’t necessarily mean it’s complicated to create one. With this rule you simply want your MailApp to activate when the mail item is either a message or appointment and has any well-known contact or URL entity types or a regular expression custom pattern match for invoices. To do this you can see that you nest two Mode="Or" rule collections inside a Mode="And" rule collection node. To simplify how to conceptualize this, see the following structure.
<Rule xsi:type="RuleCollection" Mode="And"> (this is the overarching AND)
<Rule xsi:type="RuleCollection" Mode="Or"> (the OR for Message/Appointment)
<Rule xsi:type="RuleCollection" Mode="Or"> (the OR for well-known Entities/RegEx)
Additionally, the rule is an example of how to set a filter on a well-known entity to only select contacts that have an address in the state of Idaho. This filter is provided a name so the resulting set can be interrogated directly via code. The syntax for this rule is:
<Rule xsi:type="ItemHasKnownEntity" EntityType="Contact" RegExFilter="ID" FilterName="state" IgnoreCase="false" />
Lastly, the complex rule has a custom regular expression to pattern-match for a text-based literal, ignoring letter case, in combination with any six-digit value. This is to simulate how easily you can surface information to the user that might be sourced from back-end LoB or SaaS systems. Consider this: the invoices could actually be links in the MailApp to directly access the LoB system, or you could call out to back-end web services using the invoice numbers, aggregate data from a variety of sources, and construct an information-rich web page for display in the MailApp. Lots of possibilities here!

Nothing is special about the html file; it’s just a place to display the goodies available to you in the mail item.

The code in JavaScript is pretty straightforward and shows how to access some of the properties on the user profile and item objects. What’s more interesting is how you get the information of interest out of the well-known entities and the matches for the custom regular expression rule.

The pattern first used is to retrieve all the well-known entities that have been processed by calling the item.getEntities() method. An important point here is that although you don’t have an activation rule based on some of these well-known entities, Outlook is still finding all of them. Therefore, you can use this method to retrieve them, see whether any contain data, and process the data any way you like. In this case you are only interested in checking the well-known URL entity. Once retrieved, the array is traversed and any URL present is constructed as a hyperlink and written to the web page.
The contacts are retrieved directly using the item.getFilteredEntitiesByName("state") method by passing in the string value of "state" to match the FilterName specifically used in the rule. This way you process only the contacts that matched the RegExFilter="ID" on the rule.
Finally, you use the item.getRegExMatches() method to get all the invoice numbers found in the mail item that matched your custom regular expression.

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.

Other -----------------
- SQL Server 2012 : Understanding Latches and Spinlocks (part 3) - Latching Example - With Latching
- SQL Server 2012 : Understanding Latches and Spinlocks (part 2) - Latching Example - Without Latching
- SQL Server 2012 : Understanding Latches and Spinlocks (part 1) - Latching Example
- SQL Server 2012 : Latches and Spinlocks - Symptoms (part 2) - Measuring Latch Contention, Measuring Spinlock Contention , Contention Indicators
- SQL Server 2012 : Latches and Spinlocks - Symptoms (part 1) - Recognizing Symptoms
- Integrating SharePoint 2013 with the Office Applications (part 10) - Microsoft Outlook - Lists and Libraries
- Integrating SharePoint 2013 with the Office Applications (part 9) - Microsoft InfoPath - Customizing the Document Information Panel and List Forms
- Integrating SharePoint 2013 with the Office Applications (part 8) - Microsoft InfoPath -Deploying a Form Via Central Administration, Rendering a Form Using the InfoPath Form Web Part
- Integrating SharePoint 2013 with the Office Applications (part 7) - Microsoft Access - Access Services
- Integrating SharePoint 2013 with the Office Applications (part 6) - Microsoft Access
Top 10 video Game
-   Call Of Duty: Black Ops III [PS4/XOne/PC] Zombies - Shadows of Evil Trailer
-   No Time To Explain [XOne/PC] Multiplayer Trailer
-   Bierzerkers [PC] Early Access Trailer
-   Downward [PC] Kickstarter Trailer
-   Grip [PS4/PC] Trailer
-   Hitman [PS4/XOne/PC] Debut Trailer
-   Gears of War: Ultimate Edition [XOne] Recreating the Cinematics Trailer
-   Gravity Falls: Legend of the Gnome Gemulets [3DS] Debut Trailer
-   Street Fighter V [PS4/PC] Ken Trailer
-   Doctor Who | Series 9 Teaser Trailer
-   Transformers: Devastation | Gameplay Trailer (SDCC 2015)
-   Tom Clancy's Rainbow Six Siege | Inside Rainbow #3 – The GIGN Unit
-   Final Fantasy XIV: A Realm Reborn 'Alexander' Video
-   SirVival Trailer
-   Blood Bowl II [PS4/XOne/PC] Overview Trailer
Popular tags
Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Biztalk Exchange Server Microsoft LynC Server Microsoft Dynamic Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 windows Phone 7 windows Phone 8
programming4us programming4us
Popular keywords
HOW TO Swimlane in Visio Visio sort key Pen and Touch Creating groups in Windows Server Raid in Windows Server Exchange 2010 maintenance Exchange server mail enabled groups Debugging Tools Collaborating
programming4us programming4us
PS4 game trailer XBox One game trailer
WiiU game trailer 3ds game trailer
Trailer game
Natural Miscarriage
Windows Vista
Windows 7
Windows Azure
Windows Server
Game Trailer