Office Graph API and Cortana - Chapter 1: Introduction to the Office Graph
French version / Version française
Preface
This article shows how to use the programming interface (API of Office Graph). In this series of 3 articles, we will show how, within a mobile application, integrate the Office Graph. We will achieve this in a Windows Phone 8.1 application, known as «Store App » (and not Silverlight). We will show how to manage authentication (with ADAL), consumption of its graph of company by web services, as well as the programming interface of Cortana, to run our application thanks to voice !
You can DOWNLOAD THE SOURCE CODE in the joined ZIP file, available at the end of each chapter.
This article is published to the TechDays 2015, which will take place from 10 to 12 January 2015 to the Palais des Congrès de Paris. This year I would have the chance to co-animate the session dedicated to Office Graph with Alexandre Cipriani and Stéphane Palluet. Enjoy many of our session for this example and many more.
Chapter 1: Introduction to the Graph Office (this article)
Chapter 2: How to make queries by code to the Office Graph?
Chapter 3: Integration with Cortana
Introduction
If you have recently followed the news around Office 365, you'll probably not missed the release of a new feature for a few months: Delve, and the Office Graph. Delve is a web interface based on the principles of 'machine learning', 'social graph' or semantic search. It allows to be able to render to the user a visualization of all its professional activity in its various forms. For example, we can see at a glance all popular documents around itself, the documents that we have recently consulted, modified or created documents or visit recently by one or more colleagues, etc. etc. The social graph is integrated with the human dimension of the Organization, we can easily identify and prioritize documents from his network of close, as his manager, his team, etc.
This fabric of social information is called the Office Graph. The Office Graph is the computer representation of all social signals around us. These 'signals' are sent by applications when different types of actions are performed, such as the creation, modification, consultation, etc. of a document, a presentation, a video, a discussion, etc.
It is also important to remember that this system of datamining, is present in Office 365 to serve a better service to the user. This means that the Graph Office fully respects the privacy of the user in many ways:
- We cannot see in the Office Graph that the information to which we have access. Security is fully implemented, we can see that information which have shared us through SharePoint sites, OneDrive, Office Video, Yammer, etc.
- This service is not used for advertising purposes
- This service fully fits in the Office 365 contractual constraints in terms of compliance & privacy
About Delve
Delve is the first App to use the Office Graph. It is a graphical interface to consume Web its graph of company.Delve is available from the "Apps Launcher" Office 365 menu:
Delve User Interface is very successful, the information is clearly accessible by a system of dynamic tiles to preview documents, see the number of views, to identify the site of origin, etc. Delve can display us a few clicks all our documents, all our readings, all information of our colleagues or our network. We can even find free mode of the terms within the social graph.
Office Graph
The Office Graph has a programming interface that enables third-party applications to communicate with him.This allows applications that could exploit its potential.
We can imagine several types of integration, as for example:
- Post or find the latest documents from the user to assist in an Intranet application or desktop
- Display information "profiled" in a collaborative site, an Intranet site or a mobile application
- Display information of his manager or his team for a project within a project space management application
- Interact by sending signals from a third-party application
- etc. etc.
The potential of this kind of interaction is huge. We can imagine in the future a design of the collaborative spaces of large organizations which will automatically know to focus on the user and his work experience.
The Office Graph official documentation is available on MSDN at the following address:
The Office Graph API is available today in Preview version and allows you to:
- Make queries on the graph using the REST protocol (close to existing methods for searching SharePoint 2013)
- Use GQL (Graph Query Language) to interact with the graph and refine the results
Current 2015, the capabilities of the API will be improved for example to feed the graph into signals.
How to query the Office Graph?
To query the graph, simply send HTTP requests to the address « /_api/search/query » on your Office 365 tenant SharePoint url. For example:
https://<tenant_address>/_api/search/query?Querytext='*'&SelectProperties='DocId'
The web service will return the results of your query in XML or JSON format.
In fact, the Office Graph rests entirely on the SharePoint 2013 search service and its web services. The REST interface to use SharePoint 2013 search engine is documented on MSDN at the following address:
https://msdn.microsoft.com/fr-fr/library/office/jj163876%28v=office.15%29.aspx
Queries can contain several types of search parameters, such as for example:
Parameter |
Description |
QueryText |
Free text search. For example: Querytext='*' |
QueryTemplate |
A template query with rules and predefined filters. For example: QueryTemplate='(FileExtension%3Adoc%20OR%20FileExtension%3Adocx)' In this example the filter rule is (in version not url encoded): (FileExtension:doc OR FileExtension:docx) |
SelectProperties |
The properties of the objects you want to return from the query. For example: SelectProperties='Author,AuthorOwsUser,ContentClass' |
SourceId |
To specify a source of the SharePoint search engine result. For example to target only the basis of SharePoint user profiles: SourceId='b09a7990-05ea-4af9-81ef-edfab16c4e31' |
RankingModelId |
A model for the existing classification of the SharePoint Search Engine (example: people, or popular, etc.) For example: RankingModelId='0c77ded8-c3ef-466d-929d-905670ea1d72' |
SortList |
The sorting model For example: SortList='LastModifiedTime%3Adescending' |
RowLimit |
The number of results to return For example: RowLimit=36 |
StartRow |
Where to start the results (for pagination) For example: StartRow=0 |
EnableQueryRules |
To use or not the query rules added by the SharePoint Administrator |
ProcessBestBets |
To use or not best bets |
ProcessPersonalFavorites |
To use or not user's favorites |
Etc. |
|
In addition to the traditional parameters of SharePoint Search, the specificity of the Office Graph is that we can query it through a 'Protocol' for actor/action. It simply allows to get the results of the graph for such or such actors (people) and for some actions, such as changing, reading, etc.
Simply add the Properties parameter in the query and specify its query on the graph with the syntax GraphQuery:…
In the query, we can specify actors and apply filters to get actions related to this actor, with the following syntax:
ACTOR(<ActorId> [, filter])
The parameters are constructed with the following members:
- Actors, which can be an identifier integer designating a user, or 'ME' to refer to the current user;
- Actions, which are from a list of available identifiers and used to refine its queries;
- Operators AND or OR that allow conditions between actions and actors
The list of available actions is as follows:
| Action | Description |
ID |
PersonalFeed |
View personal user like on the homepagein Delve. |
1021 |
Modified |
What actor has changed during the past three months. |
1003 |
OrgColleague |
Anyone who has the same manager as the actor. |
1015 |
OrgDirect |
Direct report employees of the actor. |
1014 |
OrgManager |
The manager of the actor. |
1013 |
OrgSkipLevelManager |
Colleagues sharing the same manager |
1016 |
WorkingWith |
Persons with whom the actor communicates or shares frequently |
1019 |
TrendingAround |
The most popular elements of the persons with whom the actor communicates regularly. |
1020 |
Viewed |
Items displayed by the actor in the past three months.. |
1001 |
WorkingWithPublic |
The public version of WorkingWith . |
1033 |
For example, to display its last 10 items related from our graph, we can make the following query:
https://<tenant_address>/_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(ME)'
This query will return the following XML result by default:
From this principle, can make queries with multiple forms. Some examples of queries on the Office Graph illustrating the principle of operators and parameters:
10 items that you have recently modified:
10 elements recently modified by the person with ID 2962:
10 items that you have recently changed or displayed:
10 items that you have modified on August 15, 2014:
10 items that you have modified on August 15, 2014:
30 items that you have recently modified sorted by date descending modified:
10 items that you have recently posted, and that the user width ID '2962' has recently changed:
Example: find our team PowerPoint presentations
Let's take an example. Try to find all presentations that have been recently modified by our colleagues. We do the following query to find the members of his team, by filtering on the the source query for the basis of SharePoint profiles:
This query will return a list of the players of your team with their identifiers (DocId), that correspond to their actor within the graph IDs:
From this list of actors, we can examine the graph to find recent presentations PowerPoint (ppt or pptx) amended recently by the team:
Office Graph returns a list of PowerPoint files published recently by my network of colleagues:
You have all understood about the Office Graph and the graph query process? Perfect! Now you are ready to understand how to use the Office Graph in a .net application, and specifically a Windows Phone application.
Go to the 2nd chapter of this article to read more:
Chapter 2: How to make queries by code to the Office Graph?