Step-by-Step: Build a SharePoint User Add-In with Azure App Insights

Microsoft engineer James Whitaker once argued that “data is the new oil”. This is very true when you want to get the most out of your Office 365 deployment; being able to analyze usage statistics, trends and application performance is invaluable. This kind of information allows managers and administrators to make essential changes and updates to SharePoint Online - important for the success of your platform.

So we’re not going to beat around the bush; the out-of-the-box analytics reports in SharePoint Online just don’t offer enough information and control. Luckily there is a solution, and that is Azure Application Insights. This is Microsoft’s answer to Google Analytics and allows website owners to track their websites and app developers to track their apps.

Azure Analytics are great, but they can be complex to get the most out of. So in today’s post, we’ll guide you through the process of signing up for Azure Application Insights and implementing custom tracking in SharePoint Online.

We will be particularly looking at tracking how people interact with list items and documents - i.e., which items are updated frequently, what are the most popular fields and tags, and which users are the most active.

Sign up for Azure Application Insights


Azure Application Insights is only available from the new Azure Preview Portal. The first requirement is obviously an active Azure subscription. Application Insights is free to try, see here for the complete pricing overview.

Go to this link to create a new Azure Application Insights application. A form appears, fill in the details as follows:

• Name: Choose something extremely exciting - e.g. “Office 365 Analyzer”
• Application Type: no options here, pick “Other (preview)”
• Resource Group: allows you to group Azure resources. I just created a new group.
• Subscription: Pick the subscription that should be billed (if you have more than one).
• Location: Nope. You cannot select a location. Central US it is.

Click “Create” and wait. When that’s ready, you should see the welcome screen:


Leave the page open - you’ll need to access it later.

Add a Remote Event Receiver to Track Updated Events


Now, let’s open Visual Studio! I’m using Visual Studio 2015, but it should work in older versions as well.

We start with an empty SharePoint Provider Hosted Add-in. Open Visual Studio, hit File -> New Project and select Visual C# (or Visual Basic if that’s how you roll) -> Office/SharePoint -> Apps -> App for SharePoint.

Please note that this will be renamed to add-in pretty soon. I’m trying to use the new name add-in where possible.

I’ve chosen “O365AnalyserApp” as the name.


In the subsequent screen, you need to enter the URL of your developer site.

Keep the default value for app type, “Provider Hosted App”. Click Next and log in to Office 365 if requested. Specify “SharePoint Online” as the target and click next.

On this screen you can choose between ASP.NET Web Forms and ASP.NET MVC. What you would choose here is based on experience and opinion. I’ve spent large periods of my existence doing Web Forms, but I’ve recently switched to MVC. Why? The integration with provider hosted apps is very good and will just make your life easier.

For example, when you create an app part, it automatically creates a controller.


So, select ASP.NET MVC and click next. Leave the authentication settings the same, use “Windows Azure Access Control Service”. And you’re done!

This may take a while, Microsoft has decided to let you start with a lot of goodies like jQuery, and a default controller showing SharePoint information.

Next, configure the required permissions in the AppManifest. Our add-in will require Manage Web permissions in the host web. Double click manifest.xml in the SharePoint project, and navigate to the permissions tab. Configure Scope = Web, Permission = Manage.


Set up Our Project


To be able to debug remote event receivers, you’ll need to take some additional steps. The manual on TechNet is excellent, so I won’t repeat that in detail. But, to sum it up:

1. Create an Azure Service Bus Namespace
2. Enable debugging via Microsoft Azure Service Bus in Visual Studio
3. Copy the connection string to Visual Studio

Next, we’re going to add the remote event receiver. As I said, a remote event receiver is in fact a web service. So, let’s add one now? Nope - we don’t need to. Open the properties of the SharePoint project and set Handle App Installed and Handle App Uninstalling to TRUE. Visual Studio will do the rest. Thanks Visual Studio.


Next, I’m going to reuse some code of the Core Event Receivers sample. I’m copying the RemoteEventReceiverManager class to my project, and then copying the contents of the AppEventReceiver. The example code adds a remote event receiver to the host web in a newly created list, for the ItemAdded event. We are interested in the ItemUpdated event.

To do so, replace:


with:


Next, add a method to RemoteEventReceiverManager which will do the actual magic and submits events to Azure Analytics. Abracadabra!

Call this method ItemUpdatedEventHandler with the following signature:


Next, we need to add the proper NuGet package to our solution to be able to communicate with Application Insights. Add the following package to the Web project:


There are multiple NuGet packages available, for web sites, Windows apps, Windows Phone apps and so on. I’m using this package for .NET web applications, because it also measures the website of the provider hosted app automatically. This comes in handy when you are using this in the future. Alternatively, you could use the Core package only, as in this article.

We can now implement our ItemUpdated event handler. First, copy the Instrumentation Key from the Application Insights Dashboard:


… and add it in a tag <InstrumentationKey>key-here</InstrumentationKey> to the ApplicationInsights.config

Then add the following code to the ItemUpdatedEventHandler:


… and in the ProcessEvent add the following case-statement to the switch:

Let's Test It!


Let’s hit F5. Visual Studio will do its magic by creating an app package and upload it to SharePoint. The first time I did this, I switched to another window, and was waiting and waiting for the add-in to deploy, but nothing seemed to happen. Then I minimized some windows, and noticed a pop up asking me to trust the app. Every time you deploy an app, you need to trust it:


After the app is installed, a browser window should open with the provider hosted website. We’re not using this, so navigate to your host web (i.e. the developer site). Go to All Site Contents; and verify the app and a new list are there.


To verify it’s working, add a breakpoint to: RemoteEventReceiver.ItemUpdatedEventHandler.

Click on the “Remote Event Receiver Jobs” and add an item. Next, open the item again, and save it again to fire the ItemUpdated event.


The breakpoint should now hit, and it should add the event to Application Insights.


Note the custom data we are capturing too. You can, for example, track events for this list item by clicking the ellipsis menu next to ListItemId, and click Search.


You can also use this data in custom reports - to, for example, track popular values for certain properties.

It should also show analytics data when you are browsing through the ASP.NET website (i.e. data about server requests, server response time, etc.). But we are mainly interested in the custom events.

When you stop debugging, and want to test again, delete the custom list “Remote Event Receiver Jobs” first to make sure you start fresh.

What about the Added Event?


Currently, the event receiver only fires when an item is updated, not when it’s added. This can be implemented very easily. The methods are still there to handle the item added event, the only thing to do is to attach the ItemAdded event handler to the list.

Next, the RemoteEventReceiver.HandleItemAdded should be implemented similar to the implementation of HandleItemUpdated, but now with a different event type.

Inject JavaScript with a Provider Hosted Add-In


You can also inject JavaScript into the host web to keep track of page views and the flow of users. To do so, we need to add JavaScript to our host web. There are multiple ways of doing this. Changing the Masterpage is probably the easiest, but that’s advised against. As we already have a provider hosted add-in, you can use this add-in to inject JavaScript as well by adding a user custom action to the host web. You can follow this example to do this. You’ll also need the piece of JavaScript from Azure Application Insights.

Combined with the remote event receiver you can, for example, track which pages users are editing data on, as there may be different pages. You can also track users to see how they arrived at those pages.

If Data Is the New Oil, Get Digging


I have shown you how you can create awesome analytics applications by combining remote event receivers with Azure Application Insights. This will give you data about which users are the most active, which metadata and which list items / documents are the most popular when it comes to editing metadata.

Combined with tracking page views and user flow, you gain even more invaluable knowledge about the usage of Office 365. And it does not stop here. You can also track when an item is deleted, when subsites are added, or when lists are created. The options, and insights, are endless.

Continue reading...