Querying Properties in Custom Usage Events

This short post will demonstrate query syntax to display custom event properties in the App Insights Analytics page and display properties in multi-layered charts. I have demonstrated simple events and more complex ones with properties in past posts. If you implemented events with properties like in my last post then you probably noticed that those properties do not appear “out of the box” in the analytics reports.

This post:

  1. Provides a little background on why you might want to add properties, especially in the case of O365 sites or apps.
  2. Shows you how to use Custom Event properties in App Insights Analytics.

If you want to skip to the end, the key line in a query is this:

extend refine= tostring(customDimensions.refiner)

…where “refine” is a term that you invent to hold the propery values, and “refiner” is the label of the property that is in your custom event. Now you can work with the “refine” value just like any other in Analytics.

In my first example, I submitted the “clicked refiner” as the Event Name. Reporting was simple but this only provides me with one dimension of data- the thing that was clicked. This information is interesting and useful in the simplest cases, but I really need to know more about the context of the event to make the best decisions. For example, to add context to the Refiners example from previous posts I modified the custom event to be called Refinement and submitted the actual refiner value that was clicked as a property instead of as the Event name. Then I added some extra data to the event from User Profiles, also as properties, and did a little clicking. Now instead of gathering info about which refiners are popular, I also know which refiners are popular among users in specific Departments and with specific Titles.

The resulting table looks like this in Analytics:

…and yields a quick chart like this which tells me that the Refinements are in use, but not much else.

Important Note: The spaces in the property names which you can see above caused me headaches- keep things simple if you can and use labels without spaces.

Selecting “Chart” from the menu shows me that my informative properties are simply absent from the view since I have not told Analytics how to read them yet:

I started reading these pages on the query syntax some months back and I quickly went from being very impressed with the depth of query features in Application Insights to being slightly overwhelmed by the depth of the query features in Application Insights!

It was not so difficult though. After some reading, a little watching, a little trial and error, and a few conversations with more advanced users I quickly got to writing queries that allowed me to easily digest complicated event data laden with useful context from Office 365 User Profiles.

The starting query was very simple, show me custom events where the name of the event is Refinement.

As I hinted at the beginning, the only thing needed to query the custom event properties, is to tell Analytics that the property is something that can be queried, and to summarize the data on these values. The result is the much more readable table here:

Which is also two clicks (Chart->Doughnut), from looking like this:

Nice, but as I mentioned, a little context would be better. To get the other interesting data that mentioned in the first section, I just need to add more “extend” statements for the additional properties as shown here:

I clicked the “Split by” tab for a reason in this screen capture- you can see that I can now select the UserTitle as an additional dimension.

My chart gets very interesting when I select the UserTitle box. Especially because there is some trial-and-error data in my test tenant!

Only one of my test users actually had a Title in his User Profile at the time of this test, “Marketing Assistant”. While there is only one unique value here, the opportunity to add context to events is clear. Not only while developing a solution, but while developing a story, I can gather simple contextual usage data from an O365 solution and further target my story or solution to an audience like Marketing Assistants, Researchers in Sri Lanka, Developers in the Automotive Division in Sweden, etc.

Simple Feedback for Usage Analytics

Like my previous posts on Usage Analytics this topic appears regularly in my work. In the previous posts I described setting up App Insights for use in Office development and how to attach Custom Events to actions in SharePoint site elements so that we can easily take measurements (think Lean Startup) as we develop stories.

Sometimes though we do not have the benefit of a user action to confirm that a story was useful. For example, when we display information like today’s Special in the Cantina or the next public holiday. For these cases we can employ a simple feedback mechanism using the same back-end service. All that we need is a little HTML to display buttons but I have added a helper function to send event properties so that we can have more measurements in one instance and still tell the results apart.

Was this helpful?
YES NO
Yes, but not perfect.

You can style the table however you want- this one is much too large for most uses. The table code, without special Style, looks like this:

<table style="width:100%;border:1px solid black;" bgcolor="#D3D3D3">
  <tr>
  <td colspan="2">Was this helpful?</td>
  </tr>
  <tr >
    <td style="width:50%;border:1px solid #999999;" onclick="UsageEvent({NewPanel:'yes'}); this.style.backgroundColor = '#cce5cc';">YES</td> 
    <td style="width:50%;border:1px solid #999999;" onclick="UsageEvent({NewPanel:'no'}); this.style.backgroundColor = '#cce5cc';">NO</td>
  <tr>
    <td colspan="2" onclick="UsageEvent({NewPanel:'other'}); this.style.backgroundColor = '#cce5cc';">Yes, but not perfect.</td>
  </tr>
</table>

Note that the onclick action is a function. The input is a JSON containing a property name and value.  The UsageEvent function looks like this:

function UsageEvent (eventProperties) {
appInsights.trackEvent("Feedback",eventProperties);
}

For this example I moved away from the simple “Your Event Here” model as previously described because I might want to track lots of different events, some “Feedback” events and others that are various types of Actions. The “properties” model allows me have a handful of top-level entries, like “Feedback” which can be sorted or charted separately in the App Insights console based on their properties.

Make Better Decisions with Usage Analytics Part 2

Earlier this month I demonstrated how to plug Azure Application Insights logic into an Office 365 or SharePoint Master Page to track common usage events. This gets you very basic, but still critical, information about usage on your site such as the number of views per page, session length, entry and exit pages, and info about the client. This is useful, but only a slight improvement over native SharePoint and Office 365 reporting.  Further, most of the time I am looking for something more specific, for example, which refiners or refinement panels are used on my Search Result page.
There is a limited amount of real estate on the results page and while it is common to add refiners for everything that seems relevant, or even to target refinement panels to audiences, I still want to know whether or not users actually use the refiner that I just added. Usage analytics can steer efforts when you have no other insights, or augment first-hand data like user surveys or interviews with concrete numbers.
For example, your Test users may report that they spend as much time working with Presentations as they do with Spreadsheets, but if you want to improve the rendering for both content types and you know that users browsing data filter by “Excel” twice as often as they filter by “PowerPoint” you might prioritize the work on the Excel experience over PowerPoint for the short-term.  Besides, it never hurts to have a good quantitative reason for prioritization in the absence of other reasons.

Even Dilbert is aware of this problem- but you don’t have to take the pill, just have a good answer.

In the last post we got started with four quick steps:

1. Create an Azure Application Insights (AI) instance
2. Acquire the Javascript for sending events to your AI instance
3. Insert Javascript into Master Page for your site
4. Use the new “AI Master Page”

…and I mentioned that you could add one simple statement to create a custom event:

appInsights.trackEvent(“Your Event Here”);

Today, we will add this one simple statement to a refinement template in Office 365 to gather feedback on refiner usage by repeating steps 3 and 4 with Display Templates for refinement.

Note: this post assumes that you are working in a site collections where you have already updated the Master Page like we covered in the last post.

If you have never edited a Display Template before, then you might want to review here first.

To get started like we did with the Master Page, download the Default Filter template from your Filter gallery.

Filters folder in the Master Page Gallery
Filters folder in the Master Page Gallery

I also highlighted the Search folder as a reminder that your filter templates are not in the same folder as item Display Templates. The file we edit here is Filter_Default.html.

Open it for editing and change the title and filename to something meaningful. On line 266 you should see a div tag for refinement items. Note that it already features an onclick event which fires some JavaScript. We can add our statement in the same tag but we need to encode the quotes in our statement so as to not confuse the browser.

Replace the onclick statement in the tag with this one:

onclick="_#= aOnClick =#_ appInsights.trackEvent(&quot;Refine by _#=ctx.RefinementControl.propertyName=#_ &quot;);"

In the “your event here” part of the statement we have added a context property(ctx), propertyName, which will provide the name of the Managed Property which was refined on.

Save the template, upload, and publish it as we did with the Master Page in part 1.  Again, as with the Master Page we need to utilize our new template on a page which displays refiners, like the standard results page for your Search Center. You can either change the template for the desired property refiner to use your new one, or add a new refiner using the new template.  You can choose the template that is used for each property when you edit the Refinement webpart on your page.

Select a Refiner Template from the list
Select a Template

Save your changes to the webpart, then the page,then publish, and watch your new metrics start rolling in.

Not so tough, but this only tells me what properties were filtered on, not which items were clicked as I promised earlier.
The event logic is already in the right place to capture which item was clicked. To get the actual item we only need to change the variable that gets stuffed into the event. Replace the ctx.RefinementControl.propertyName variable with refinementName, like this:
("Refine by _#=refinementName=#_ ")
…and you will log exactly the item that was clicked such as Excel, PowerPoint, etc, and your reports will start to look like this one:

Chart of Custom Events
Custom Events

Make better decisions with Usage Analytics in O365 and SharePoint

If you have worked with me for more than a day then you have probably heard me talk about feedback loops and the necessity of analytics to assist in prioritizing UX work.  I am passionate about using data to support investment and there are really simple ways to get started, even with “inside the firewall” SharePoint sites.
Why is this important?  It is important because you probably have a limited budget for making improvements and you would like to invest those limited resources in the places where the opportunity to improve productivity is the greatest.


Most SharePoint site templates provide some basic reports around page views, and certain ones, like catalogs, also provide popularity reports for catalog items.  What is not there out of the box, is a way to review other activities such as, when a search refiner is clicked, when an object is hovered-over, if someone clicks on those shortcuts you added in a Content webpart, or whether or not the average visitor hops around on the site or stays on one page.

I cannot cover every option in a short post, but today I will get you started by demonstrating how to get Azure Application Insights into your SharePoint site to collect more comprehensive data than just page views.
The process is simple:
1. Create an Azure Application Insights (AI) instance
2. Acquire the Javascript for sending events to your AI instance
3. Insert Javascript into Master Page for your site
4. Use the new “AI Master Page”

That is all.  From the moment the new Masterpage is utilized you will start seeing core session and page view data in your Azure Portal.   I take for granted that if you are interested in analytics for your SharePoint sites that you are already familiar with Masterpages and their function, but I still explain the update process here in case you need a guide.  To complete this exercise you also need to have an Azure account to create an AAI instance, but the basic tier is free and most intranets will not generate enough events to get you out of the “free” tier.  Do not have an account?  Sign-up is free at: https://azure.microsoft.com.

1. Create an Azure Application Insights (AI) instance

Click to create a new Application Insights instance at https://portal.azure.com and fill in the necessary info about resource group and application type- I used ASP.Net here.  The blades expand as clicked so I numbered the image below for clarity.

2. Acquire the Javascript for sending events to your AI instance

When the instance is created, you should see info like this in the AI instance landing page indicating that there is no data yet.

Select “Page views” as above when the service is new and AI will produce a block of code for you which both enables Application Insights on a page, and submits a View event to AI.  The snippet will look like this:

The instrumentation key is unique for every instance.  Note the final statement in the block which actually logs the View event:
appInsights.trackPageView();
When this script is loaded, you can add custom events with only one more statement:
appInsights.trackEvent(“Your Event Here”);
What custom events should you make and where should they go?  That is the high-value question.  More on this subject in my next post.

3. Insert Javascript into Masterpage for your site

Navigate to your masterpage gallery and download a copy of the masterpage which you would like to add the event logic to.  In this example I downloaded the standard “seattle.html” Master Page.  Add the Javascript snippet as the last item inside the Body tag, save with a new meaningful name, upload, and publish.

4. Use the new “AAI Masterpage”

Finally, from the Site Master Page Settings screen select your new Master Page.  If you did not publish the new page in the last step, your new Master Page will not appear in the dropdown.

Once the master page is set, all Page Views in the site will be logged in Application Insights and you will start seeing data like this in your portal:

O365 Site Views in Azure Application Insights

You get a lot more than just Page Views from Application Insights but I will let you explore until I have time to create another post outlining how to use Custom Events in standard templates- it is easier than the name might lead you to believe.  Keep in mind that while it great to have core usage data, the value is in how you use it.

Around the San Francisco Bay

Some years ago I was enduring the usual NorCal bashing while  visiting friends in SoCal.  “San Francisco is dangerous, I can’t find anything, it’s cold, there aren’t enough frozen yogurt stands,” etc.  I assured my friends that they just “weren’t doing it right” and worked up a quick list of places to visit and generally advised them on how to just have great day or days in SF.  Over the years, I kept editing and sharing the list and eventually converted most of the items on the list into points on this map.  Since then, I hear it has been shared extensively.  Let me know if you have any feedback on it.

map of Bay Area