Last week, Microsoft started rolling out Delve to Office 365 customers. Delve is a cool new way to discover relevant information and connections across your work life. As cool as Delve is, I’m even more excited about the Office Graph that powers it. The Office Graph puts sophisticated machine learning on top of all the interactions you and your colleagues make with each other and content in Office 365. With the Office Graph you can identify information trending around people, content you have in common with others, and social connections that traverse organizational boundaries. Best of all, developers can leverage the Office Graph to create new and exciting scenarios that extend Office 365 like never before. In this post, I’ll illustrate some findings in developing my first Office Graph app. The video below illustrates some of the concepts of this post:
Also see Developing Apps against the Office Graph - Part 2
(Please visit the site to view this video)
| NOTE: The Office Graph “learns” through the “actions” of users (aka - “actors”) against other user or objects in Office 365 (ex: site, document, etc.). Actions may take time to show up in the Office Graph because it leverages SharePoint’s search and search analytics technologies. Additionally, the more actors and actions, the more you will get out of the Office Graph. It might take some work to achieve this in a demo or developer tenant of Office 365. As a point of reference, I spent a good part of a Saturday signing in/out of 25 test accounts to generate enough desired activity and waited another 6-12 hours to see that activity show up in the Office Graph. Happy waiting :) |
APIs and Graph Query Language (GQL)
I was extremely pleased to see detailed MSDN documentation accompany the release of Office Graph/Delve. Using GQL with the SharePoint Online Search REST API to query Office graph outlines the Graph Query Language (GQL) syntax and how to use it with the SharePoint Search APIs to query the Office Graph. The original “Marketecture” images for the Office Graph show a spider web of connections between people and content (see below).
In reality, this is exactly how the Office Graph and GQL work. People are “Actors” that perform activities/actions on other actors and objects. Ultimately, an activity/action generates a connection or “Edge”. When you query the Office Graph with GQL, you typically provide the Actor(s) and Action(s) and the Office Graph returns the Objects with “Edges” that match the actor/action criteria. Again, the Office Graph is queried through the standard SharePoint REST APIs for search, but with the additional GraphQuery syntax. Below are a few examples:
//Objects related to current user (ie - ME) //Objects related to actor 342 //Objects trending around current user (trending = action type 1020) //Objects related to current user and actor 342 //Objects recently viewed by current user and modified by actor 342 //People for whom the current worker works with //Objects related to actor 342 with 'Delve' in the title |
Notice that the use of ME or specific IDs in the ACTOR part of the queries and the numeric action type code for the connection. Actors and Actions can be combined in numerous ways to deliver interesting intersections in the Office Graph. Below is a comprehensive list of action types and their visibility scope.
| Action Type | Description | Visibility | ID |
|---|---|---|---|
| PersonalFeed | The actor’s personal feed as shown on their Home view in Delve. | Private | 1021 |
| Modified | Items that the actor has modified in the last three months. | Public | 1003 |
| OrgColleague | Everyone who reports to the same manager as the actor. | Public | 1015 |
| OrgDirect | The actor’s direct reports. | Public | 1014 |
| OrgManager | The person whom the actor reports to. | Public | 1013 |
| OrgSkipLevelManager | The actor’s skip-level manager. | Public | 1016 |
| WorkingWith | People whom the actor communicates or works with frequently. | Private | 1019 |
| TrendingAround | Items popular with people whom the actor works or communicates with frequently. | Public | 1020 |
| Viewed | Items viewed by the actor in the last three months. | Private | 1001 |
| WorkingWithPublic | A public version of the WorkingWith edge. | Public | 1033 |
The results returned from GQL queries are in a similar format as regular search queries against SharePoint’s REST APIs. However, GQL will add an additional “Edges” managed property that includes details about the action, the date of the action, and weight assigned by the ranking model. Below is an example of this property returned as part of the RelevantResult ResultTable of a Search API call.
<d:element m:type="SP.KeyValue"> <d:Key>Edges</d:Key> <d:Value>[{"ActorId":41391607,"ObjectId":151088624, "Properties":{"Action":1001,"Blob":[], "ObjectSource":1,"Time":"2014-08-19T13:46:29.0000000Z", "Weight":2}}] </d:Value> <d:ValueType>Edm.String</d:ValueType> </d:element> |
These Edge properties come into play when performing advanced GQL queries that specify a sort based on time (EdgeTime) or closeness (EdgeWeight). The sample below shows a search query to return people for whom the current user works with and sorted by closeness:
//People for whom the current worker works with sorted by closeness /_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(ME\, action\:1019),GraphRankingModel:{"features"\:[{"function"\:"EdgeWeight"}]}'&RankingModelId='0c77ded8-c3ef-466d-929d-905670ea1d72' |
One important note is that the Office 365 APIs do not currently support a search permission scope (I’m told it is coming). Until that exists, you will need to use the standard SharePoint app model to develop against the Office Graph.
Image Previews
One glimpse at Delve, and you immediately notice an attractively visual user interface. This isn’t your mama’s standard SharePoint search results. Visual previews accompany most Delve results without having to mouse/hover over anything. I could tell these visual previews would be a helpful in building my own applications against the Office Graph. After investigation, it appears that (at least for Office docs) a new layouts web handler generates on-demand previews based on some document parameters (very similar to dynamic image renditions). The getpreview.ashx handler accepts the Office document’s SiteID, WebID, UniqueID, and DocID to generate previews. All of these parameters can be retrieved as managed properties on a GCL query as is seen below and used in my app.
//make REST call to get items trending around the current user GraphQuery:ACTOR(ME\, action\:1020) |
//build an image preview based on uniqueid, siteid, webid, and docid o.pic = hostWebUrl + '/_layouts/15/getpreview.ashx?guidFile=' + o.uniqueId + '&guidSite=' + o.siteId + '&guidWeb=' + o.webId + '&docid=' + o.docId + '&ClientType=CodenameOsloWeb&size=small'; |
| DISCLAIMER: The getpreview.ashx handler is a undocumented discovery. Use it with caution as it is subject to change without notice until officially documented. |
The Final Product
For my first Office Graph app, I didn’t try to get too creative with GCL. Instead, I aimed at delivering an alternate/creative visual on top of some standard GCL queries. Specifically, I used d3.js to display Office Graph query results as animated bubbles sized by # of views. It’s a neat way to see the same results as Delve, but emphasized by popularity.
Final Thoughts
I hope this post helped spark your interest in the power of the Office Graph for developers. The Office Graph opens up a new world of intelligence in Office 365 that you can harness your applications. You can download the “Office Graph Bubbles” app I built for this post HERE.