Last week we saw how we can retrieve entire email content in Read Mode of Outlook add-in using Exchange Web Services (EWS). This post talks about how we can integrate that information with SharePoint Online to work on workflows from inside Outlook environment.

The first step in the process is to create an application in the Azure AD instance linked to your SharePoint Online tenant. (Fyi, Microsoft provides a free trial of Azure for developers.)

We will navigate to our Active Directory inside Azure Management Portal and navigate to Applications tab. From there we click on “Add" button and select “Add an application my organization is developing”. Give it a name and select “Web Application” from the choices and hit next. Provide a Sign-On URL and App ID URI. The sign on URL in our case will be where you have hosted your Outlook web application. The App ID can be anything unique. Clicking on checkbox will create our application.

After your application is created, it will appear in the Applications list. Click on it and navigate to Configure tab. Here we will find few properties which are important for our application. Make a note of Client ID and generate an App Key either for 1 or 2 year. Also enter a Reply URL which is the URL where the Azure AD instance will navigate to provide the Authentication Token.

We will then need to click on “Add Application” and choose “Office 365 SharePoint Online” application. We will provide the application appropriate rights which in this case would be “Read and write items in lists in all site collections”. After you are done your application configuration will look something like this.

Now that we are done with all the configuration (whew!) we will go back to our code. In the web.config of our Outlook web application, we will add the following appSettings.

<add key="ida:AuthorizationUri" value="https://login.windows.net" />
<add key="ida:ClientID" value="ad039897-blablabla" />
<add key="ida:AppKey" value="supersecretappkey" />

The Client ID and AppKey that we have generated in previous steps need to populated here.

Next we will add code in our Home Controller to actually use this information to authenticate with Azure AD and use SharePoint Online APIs. As we will be already authenticated when we are inside OWA, the authentication process will be completely seamless to the end user.

Note: For best user experience, I suggest to keep the View of Home controller blank so that the authentication process is completely hidden from the end user.

private readonly string _clientId = ConfigurationManager.AppSettings["ida:ClientID"];
private readonly string _appKey = ConfigurationManager.AppSettings["ida:AppKey"];
private readonly string _authorizationUri = ConfigurationManager.AppSettings["ida:AuthorizationUri"];
private const string ServiceResourceId = "https://<tenant>.sharepoint.com";

public async Task<ActionResult> Index(string et, string code, string error, string error_description)
{
	if (error != null) return RedirectToAction("Error", new { error, error_description });

	var authContext = new AuthenticationContext(_authorizationUri + "/common", true);

	// Check if you received an authorization code, if not you need to sign in
	if (code == null)
	{
		// Get the authorization URL (https://login.windows.net/common/oauth2/authorize)
		var redirectUri = authContext.GetAuthorizationRequestURL(ServiceResourceId, _clientId, new Uri(Request.Url.AbsoluteUri.Split('?')[0]), UserIdentifier.AnyUser, string.Empty);

		return Redirect(redirectUri.ToString());
	}

	// If the code is empty, show the user the error page
	if (String.IsNullOrEmpty(code)) return RedirectToAction("Error", new { error = "AuthToken", error_description = "The authorization token was not retrieved." });

	// If a code is retrieved, the access token can be generated
	var clientCredentials = new ClientCredential(_clientId, _appKey);
	var authResult = await authContext.AcquireTokenByAuthorizationCodeAsync(code, new Uri(Request.Url.AbsoluteUri.Split('?')[0]), clientCredentials);
	return Redirect("/AppRead/Home/Home.html?auth=" + authResult.AccessToken);
}

Note how we are navigating to the Home.html page along with the Auth Token acquired by AAD. This token is then extracted and used for subsequent calls to work with SharePoint workflows.In this example, I have hardcoded the List name and item name as this is a POC. You can improve the code to dynamically fetch these values.

[ActionName("spQuery")]
public ApprovalApi.Models.ServiceResponse PostSPQuery(ServiceRequest request)
{
_request = request;
ApprovalApi.Models.ServiceResponse response = new Models.ServiceResponse();
ClientContext clientContext = new ClientContext("https://<tenant>.sharepoint.com/");
clientContext.AuthenticationMode = ClientAuthenticationMode.Anonymous;
clientContext.FormDigestHandlingEnabled = false;
clientContext.ExecutingWebRequest +=
	delegate(object oSender, WebRequestEventArgs webRequestEventArgs)
	{
		webRequestEventArgs.WebRequestExecutor.RequestHeaders["Authorization"] =
			"Bearer " + request.SPAuthToken;
	};
ListCollection lists = clientContext.Web.Lists;
List selectedList = clientContext.Web.Lists.GetByTitle("Tasks");
ListItem item = selectedList.GetItemById(2);
clientContext.Load<ListCollection>(lists);
clientContext.Load<List>(selectedList);
clientContext.Load(item);
clientContext.ExecuteQuery();
if (request.Approve)
{
	item["Completed"] = true;
	item["PercentComplete"] = 1;
	item["Status"] = "Approved";
	item["WorkflowOutcome"] = "Approved";
	response.isApproved = true;
}
else
{
	item["Completed"] = false;
	item["PercentComplete"] = 0;
	item["Status"] = "Rejected";
	item["WorkflowOutcome"] = "Rejected";
	response.isApproved = false;
}
item.Update();
clientContext.ExecuteQuery();
response.isError = false;
return response;
}

The UI of our Outlook web app will look something like this.

User can now click on Approve or Reject button from inside Outlook to deal with workflow tasks!

This was a quick look at how easy it is to integrate SharePoint and Office apps add-ins to improve the user experience. If you have any question or comment, please hit the comments section below.

As usual, the code is attached to this post.

ApprovalApp.zip

If you have been following Build 2015, you would know that Office apps and SharePoint apps have been renamed to Office add-ins and SharePoint add-ins respectively. You should also watch this excellent session available on Channel 9 in which the future of SharePoint and Office is discussed at length - Office Development Matters, and Here's Why...

If you have worked with SharePoint Approval workflow, you would know that once a new item is added you can have a functionality where a mail is triggered to the approver for his approval. A typical approval mail looks something like this:

The user is then expected to click on the link which opens the browser where he logs-in and approves/rejects the request. What if we can provide the user a better experience within the Outlook app itself! Here we are going to create an Outlook add-in which will read the email, extract the link and provide a UI for approval to the user. In this first part, we will see how our app will identify the email and read the contents of the mail.

We will begin with creating a task pane app for Outlook. We will call it ApprovalApp which will run in Read mode of an Outlook email.

We will start with defining something called Activation Rule which defines when an add-in will detect the proper mail and show its UI. Here we are going with a very simple Regex applied on the subject of the mail.

Next we will define a Web API which will host our service which will help in getting the mail content as well as working with the SharePoint workflow once the List item URL is extracted from the email body. To avoid cross-domain issue, we will keep both the Web API as well as Outlook add-in website within the same project.

The UI of our app looks something like this:

On click of "Get Mail Body" button, our app will call the Web API which will in turn authenticate with the EWS and return the mail item body. The code for making the Web API request is pretty simple.

function makeServiceRequest() {
    $.ajax({
        url: "/api/Approval",
        type: "POST",
        data: JSON.stringify(serviceRequest),
        contentType: "application/json",
        complete: responseComplete
    });
};

Now the main problem here is that in the current version of Office.js, you cannot access the mail body in Read Mode. To workaround this we have to use Exchange Web Services (EWS).

To authenticate with EWS, you do not have access to the user’s password. Instead Office.js provides a token via method getCallbackTokenAsync which can be used to authenticate with EWS. This is not very clearly documented anywhere and the following code will help you if you ever want to do the same thing.

function getMailBody() {
    Office.context.mailbox.getCallbackTokenAsync(authorizationTokenCallback);
};

function authorizationTokenCallback(asyncResult, userContext) {
    if (asyncResult.status == "succeeded") {
        serviceRequest.AuthToken = asyncResult.value;
        makeServiceRequest();
    }
    else {
        $('#taskUrl').text("Could not get callback token: " + asyncResult.error.message);
    }
}

This token can then be used in EWS Managed API to authenticate with Exchange and load the item body. The code taken in the authentication token passed by our app and uses OAuthCredentials to authenticate with Exchange. In the following code, we are also extracting the URLs from the email body via Regex.

Note: There are other simpler ways to extract URLs from email. The aim of this post is to show how we can access the entire email in Read mode.

public ApprovalApi.Models.ServiceResponse Post(ServiceRequest request)
        {
            ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2013);
            service.Credentials = new OAuthCredentials(request.AuthToken);
            service.Url = new Uri(request.EwsURL);
            Item item = Item.Bind(service, request.ItemId);
            if (item.Body != null)
            {
                Regex linkParser = new Regex(@"\b(?:https?://|www\.)\S+\b", RegexOptions.Compiled | RegexOptions.IgnoreCase);
                Match match = linkParser.Matches(item.Body.Text)[1];
                ApprovalApi.Models.ServiceResponse response = new Models.ServiceResponse();
                response.isError = false;
                response.url = match.Value;
                return response;
            }

            return null;
        }

Now that we have the entire email body and also the item URL, in the next part we will look at how we can use this information to bring SharePoint functionality within Outlook.

Stay tuned!

P.S. – You can find the source code attached with this post below.

ApprovalApp.zip

1. Install Node.js on your system.
2. Install Vorlon on your install by the following command in NPM - "npm i -g vorlon"
3. Run Vorlon by command - "vorlon".

IE 8 allows “postMessage” method. We take advantage of this method to communicate between the host page and the cross origin page that is loaded in an IFrame in the host page.

The cross origin page which is loaded in the IFrame, attaches itself to the “onmessage” event and begins listening for incoming messages.

When the cross domain page receives any message, it parses the message and then performs the requested operation. It will then send back response to host page through “postMessage” method.

If there are multiple concurrent requests, the host page needs to figure out the request-response mapping. For this, we declare a global counter in the page called messageIndex. Each message that the host page sends to the IFrame contains certain parameters as properties:

1. URL – The URL where the request needs to be sent for processing
2. Type – GET/POST/PUT/DELETE
3. Content Type – text/json etc.
4. Payload Data
5. Message ID – The globally incrementing counter (messageIndex).

The cross domain page would process the request and send back the response which will contain the following properties:

1. Result
2. Message ID

At the host page, we again attach to the “onmessage” event and receive and process the data accordingly.

The cross origin page can decide whether to allow request coming from any origin or can check the origin of the incoming request and allow/reject the call.

We all, however, do agree that Open XML is a pretty neat way to manipulate Office documents. It offers nearly all the advantages and even more as compared to Interop solutions. In this post I am going to show you a way in which you can get the full power of Open XML SDK while using Word Apps.

The new Office API provides a way to get the entire document without any user interaction. The method getFileAsync provides a way to get the document either as plain text or in OOXML format. Getting data as plain text is simple and we don’t like doing simple things. Hence we will get data in OOXML format which is returned as byte array.

One thing to note here is that the getFileAsync method allows transfer only up to 4 MB of data but that should be sufficient for most purposes. 

Now that we have the byte array, notice that Office API also provides a handy method to convert it to Base-64 encoded string which we can then POST to any service of our choosing.

function GetDocument() {
 $('#Loading').show();
 var documentText = null;
 Office.context.document.getFileAsync("compressed", function (result) {
 if (result.status == "succeeded") {
 //Get the file
 var myFile = result.value;
 myFile.getSliceAsync(0, function (resultSlice) {
 if (result.status == "succeeded") { 
//We got the file slice. Now we will encode the data and post to a service
 documentText = OSF.OUtil.encodeBase64(resultSlice.value.data);
 $.ajax({
 type: "POST",
 url: "../DocumentService.svc/ParseDocument",
 data: JSON.stringify(documentText),
 contentType: "application/json; charset=utf-8",
 dataType: "json",
 success: function (data) {
 $('#Loading').hide();
 $('#Content').show();
 $('#Content').append(data);
 },
 failure: function () {
 $('#Content').append("Sorry an error occurred!");
 }
 });
 }
 });
 myFile.closeAsync();
 }
 });
 }

For this example, we are also going to create a secured REST-ful WCF service which will have a single method called as ParseDocument accepting a string parameter. We will creatively name this service as DocumentService.svc.

Now we will POST our document which we got earlier as a Base-64 encoded string to this service. At the service side, we will extract byte array from the string. From this byte-array we can easily create an Open XML WordProcessingDocument object. Having a document object opens up a world of possibilities for us to manipulate the document. In this example I am just returning the document’s contents in HTML format back to the app but you can be more imaginative than that.

public string ParseDocumentData(string openXml)
 {
 byte[] byteArray = Convert.FromBase64String(openXml);
 using (var memoryStream = new MemoryStream())
 {
 memoryStream.Write(byteArray, 0, byteArray.Length); 
//We got our document on server. Yay!
 using (var wordDoc = WordprocessingDocument.Open(memoryStream, true))
 {
 var settings = new HtmlConverterSettings()
 {
 PageTitle = "Document Analysis"
 };
 
 XElement html = HtmlConverter.ConvertToHtml(wordDoc, settings);
 return html.ToString();
 }
 }
 }

 Demo Solution

So next time if someone asks you if we can use Open XML with the new Word API, you know what to say!

P.S. - I have attached the working solution. You will need to launch Visual Studio as administrator to run the sample.

OpenXMLDemo.zip

Now the thing about RT API is that it is rate limited – 10000 calls per day, 10 calls per second. This initially seemed fairly high number to me. So the initial version of my app didn’t implement any kind of caching mechanism. My app pretty soon got somewhat popular. After getting some good reviews, I started getting bad reviews about the app not working\crashing. I looked at the RT Developer dashboard and noticed that I was frequently going over my quota limit. To quickly workaround this I started caching the RT API responses on user’s machine; refreshing data from the API only when a time period of 24 hours has been crossed. In hindsight, I should have done this in the initial version of app itself.

Caching stabilized things for a while. But as the app popularity grew, I was again back to hitting my quota limits. I needed some kind of middle tier service which cushions the number of requests to RT API and most importantly, I needed to do it quickly. Enter Azure Mobile Services (AMS)!

I had known and played with Azure Mobile Services for quite a while then. But what pushed me into selecting it was when I had a chance to attend a session on it by Josh Twist (@joshtwist). I was amazed at the simplicity and power it provided and the rapid improvements and features that were added to it. I knew it was in good hands.

I am not going to list down all the cool features that AMS provides – Push Notifications for Windows, iOS, and Android, OAuth Authentication for Facebook, Twitter, Google, and Windows are just a few. AMS also provides a way to do some operation whenever an attempt is made to insert, update, delete or read a record from a table. These operations are written in JavaScript and because AMS fully supports Node.js you can easily make HTTP requests (require ('request') ;) and take full advantage of its power. All this code is written in the browser window itself so we don’t need any editor for writing code.

Writing code in Azure Mobile Service browser window

In my situation to reduce the number of calls to RT API, my app now calls AMS instead. AMS in turn checks whether it already has the requested data in tables else makes a call to RT API and stores the data back in table for future requests and also return the data back to the client – all this code written in JavaScript! This mechanism coupled with the caching at user’s machine level means that I remain well with in my quota limits. Problem solved.

To make things even simpler, AMS provides an SDK for Windows Store apps (apart from SDKs for other platforms). They also provide a sample app showing how to use the SDK. In fact the whole operation to migrate my app to use AMS was so easy and smooth that I was able to finish the process in a day, testing included!

If you are developing a mobile app for any platform, I highly recommend considering Azure Mobile Services for any kind of network communication. You won’t be disappointed.

1. Office Store - We can publish your app to the Office Store from where it is easily available to millions of Office subscribers.
2. SharePoint App Catalog  - If the app needs to be used within an organization, we can publish the app to the organization App Catalog running on SharePoint 2013.
3. Network Share - We just publish the app to a network location accessible to our target audience.

Next we have to specify where we want to host our app (local machine in this example). Note that specifying the location does not actually host the app at the mentioned location but just packages the app so as to use that location when deploying.

Click next to see a summary and hit Finish. This will package our app and open it in Windows Explorer.

The following is the structure of the package prepared by Visual Studio.

There are many files of interest here- first being the Web.zip file. The zip file contains all the DLLs and dependencies necessary to host our app in IIS.

Next there is a handy deployment file (deploy.cmd) which will help in deploying the app to IIS by using Web Deploy.

The next file of interest is the SetParameters.xml file.This file contains parameters that are passed to Web Deploy when we use the deploy.cmd file to install the package. We can change the values of parameters present in this file as needed.

To deploy the package to IIS, open Command Prompt in admin mode and run deploy.cmd file with following switches -

1. /t - Trial Mode -  By specifying this flag, Web Deploy would check all scenarios which will be encountered when the deployment takes place but does not actually make any changes. It just generates a log file similar to what would be generated when actually deploying the app. After we are satisfied with the log files and settings, we can change the flag to /y to begin the actual deployment.
2. /y - Yes or Update Mode  - Web Deploy performs the deployment and displays a log of what it does.

Now that our app is deployed to IIS, we copy the manifest file present in "OfficeAppManifests" folder and place it on a network location. Next open Office application -> Trust Center -> Trust Center Settings -> Trusted App Catalogs.

Here specify the Catalog Url as the network path where we have placed the manifest file and check "Show in Menu" option.

That's it. Our app is published. We can go to Insert App option and see our app present in the Shared Folder category.

Limitations

There are certain limitations when publishing Office apps this way.

1. Apps published to a network location cannot use Office Licensing service to license the apps.
2. Apps cannot be used by general public and is only limited to people having access to the network location.
3. App developer cannot monetize this app as it does not use Office Store.

Conclusion

In my next blog post, we will see how publishing to Office Store solves these limitations of using a network share by using the Office Licensing service.