In earlier posts we went over the Office 365 development platform and proposed an example application to demonstrate how we can leverage its resources and Azure Active Directory using the Graph API.
In the previous post we looked under the hood at securing our web application and API with Azure Active Directory, and using the Graph API to find users, check calendars and send email notifications.
In the final installment of this series, we’ll take a closer look at the Outlook Add-in for this application.
Office 365 Add-ins
As we’ve seen, the Graph API makes it easy to integrate Office 365 resources and functionality into your own applications. Add-ins allow you to pull external resources and services directly into Office applications like Outlook, Word, PowerPoint and Excel.
Office 365 Add-ins are implemented as independently hosted web applications that are hosted within Office applications (both the web-based versions or native applications). This means:
- You can write Add-ins with whatever web technology stack you prefer. There are a fair number of Office development samples written using Node.JS, for example.
- You can host your add-in in any manner that you see fit, without worrying about adversely affecting your enterprise’s Office 365 services.
Work Item Outlook Add-in
With Outlook Add-ins you can integrate functionality related to emails directly into the main view pane or a ribbon command. For our example application, we use an Add-in to integrate a form into the view pane of a work item notification email that lets the user update the work item without leaving Outlook to switch to the work item web application:
Our Outlook Add-in is a simple AngularJS application that loads a work item from our Web API endpoint and data-binds it to a form. To avoid unnecessary clutter, we only want to display the “Work Item Form” add-in link in emails that are actually related to a work item. Following the example of this sample add-in, we can do this using an activation rule in our add-in manifest. In this case we’ll use a regular expression rule to find URLs in the message body that partially match a work item resource endpoint:
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemHasRegularExpressionMatch" PropertyName="BodyAsHTML" RegExName="WorkItemUrl" RegExValue="https://[a-zA-Z0-9-._:]*/api/workitems/\d+"/>
</Rule>
This also makes the regular expression matches named “WorkItemUrl” available to us in our work item add-in JavaScript, which we can use to easily locate the actual URL for the work item resource in the email content and use it to get the item in a REST call. For example:
var workItemUrls = Office.context.mailbox.item.getRegExMatches().WorkItemUrl;
if (workItemUrls && workItemUrls.length) {
vm.url = workItemUrls[0];
dataService.getWorkItem(vm.url)
.then(function (workItem) {
vm.workItem = workItem;
});
}
Authenticating with Azure Active Directory Credentials
We secured our web API by requiring Azure Active Directory credentials for our Office 365 domain, so our Outlook Add-in must authenticate when making API calls to get and update work items.
This is accomplished using the Active Directory Authentication Library (ADAL) for JavaScript. Since we’re using AngularJS, we can also use the Angular library for ADAL for easy integration. Our ADAL configuration code looks like this:
(function () {
'use strict';
var officeAddin = angular.module('officeAddin');
officeAddin.config(['$httpProvider', 'adalAuthenticationServiceProvider', adalConfigurator]);
function adalConfigurator($httpProvider, adalProvider) {
var adalConfig = {
// your Azure Active Directory tenant
tenant: 'mytenant.onmicrosoft.com',
// client ID of your app in Azure Active Directory
clientId: '00000000-0000-0000-0000-000000000000',
endpoints: {},
cacheLocation: 'localStorage', // enable this for IE, as sessionStorage does not work for localhost.
};
adalProvider.init(adalConfig, $httpProvider);
}
})();
Since the user is already logged into Outlook with their credentials, there is no need to log in a second time. All AJAX calls made from our Add-in will now include a bearer token from those credentials for authentication.
Add-in Deployment
Office 365 Add-ins are deployed via an XML manifest file that includes details like the URI for the Add-in, and for Outlook Add-ins (as we saw a moment ago) the activation rule.
To deploy an Add-in, you log into the of the Office 365 portal and navigate to the Admin section. From there you can go to the Exchange Admin Center, then Add-ins. You can then add it by browsing to a local manifest file or providing a URL that points to it. Once added, you can configure if the Add-in is enabled by default for users, and whether it is optional or mandatory:
Much More than Office
Office 365 lets you work with familiar Office applications anywhere, anytime, on any device. But it’s much more than that.
With the Graph API you can programmatically interact with Office 365 resources like users, contacts, calendars, mail and files, opening the door to integrating these resources in enterprise applications and enhancing how users interact with Office, all with relative ease. It’s a web API, so it is platform independent.
Office 365 Add-ins allow you to easily build and deploy useful resources and functionality right into the Office applications. Since they are written as web applications you can leverage the development expertise you already have and host using the cloud or on-premises infrastructure that suits your needs.
The use of Azure Active Directory for identification services in Office 365 means that all user activities and API calls are secure – but it also means you have a secure single-source of authentication and authorization that can be used for enterprise applications as well.
These capabilities open up new and exciting possibilities to remove the seams between Office applications, resources and data and those of the enterprise.
Further Reading from our Office 365 Series:
Office 365 as a Development Platform
Matter Center on the Office 365 Platform
