Office Graph goes CRUD
Note: This is a roadmap discussion, so what we end up releasing may be different. We have chosen to share this early though, so that you can prepare for what is coming and ramp up on new features. This blog is not the official documentation, but merely an excerpt of our talk given at //Build/. You can follow the development of the Office graph API via the documentation which we plan to update as the API progresses.
Hi,
This week at //Build/ Microsoft made a number of great announcements (my unfiltered opinion, obviously), especially around Windows 10, Azure and HoloLens. In the middle of this, we also showed a little bit of what is coming with Office Graph going forward. In his keynote, Satya showed sales opportunities from Salesforce going into the Office Graph and showing up in Delve. And my colleague Jon Meling and I had a roadmap session called Building solutions with Office Graph where we explained and showed some upcoming features that we will take a look at in this posting. The highlight is that the Office Graph will be opened up not just for queries, but for Apps and solutions to create, read, update and delete contents stored in the graph and thus be an integrated part of the Office fabric.
Baseline
Let us first quickly go through what is out in the market today with the Office Graph and Delve. If you are familiar with that you may safely skip this section and go straight to the new features of the Office Graph.
Delve
Delve is a new tool in Office 365. You will find it in the top menu together with Mail, Calendar, OneDrive for Business, Sites etc. However, it is a little special since it combines data from all the other workloads to help the user stay in the know, find what she needs and discover and learn about new people in her organization. All this is made possible because Delve uses the Office Graph.
One of the main features of Delve is collaboratively organizing content using boards.
Ashok Kuppusamy, Cem Aykan and Fredrik Holm will go through more of the upcoming features of Delve in a talk at Ignite called Office Delve and Office Graph Vision and Roadmap.
Office Graph
Office Graph is an intelligent fabric that applies machine learning to map the connections between people, content and interactions across Office 365. With the Office Graph we're breaking down the silos by linking entities together and organizing knowledge across all your work. The Office Graph connects you to all your colleagues and documents; the things that matter to you. This happens while you continue to work with your information and colleagues in the tools that you prefer: Outlook, Office rich clients, Office web clients, Skype, Yammer, SharePoint, OneDrive for Business and more.
Office Graph simply connects the dots in the enterprise, across all workloads, and adds semantics and insights to the relationships, making this available to all tools and apps in the Office 365 suite.
Current APIs and extension points
Delve is a web solution so if you do F12 in your browser and check out the network traffic you will see all the calls that go across the wire. Here, you will notice that most of the features in Delve are built up with the following sequence after a user action:
- Run one or more searches to get the right data (documents, people, boards)
- This uses the SharePoint search endpoint, with the graph extensions and the Graph Query Language. This is documented here as a preview API.
- Log the user action (as a "signal")
- This is not documented, nor supported. If you still use it you risk messing up your Office 365 tenant's data, as what goes in here is used to among other things calculate the Delve home page for each user.
- Retrieve images for the documents and/or people to show in the UX.
- Again, this is not documented nor supported, but it is less risky to use due to fewer side effects in the Office Graph.
Office Graph going forward
Let's look at what is on our roadmap for the Office Graph. The good news for developers is that we are moving from a more or less read-only graph to a graph that support Create, Read, Update and Delete operations. YES! Developers will not only be able to read, but also add, change and delete; provided the user and/or tenant admin gives the Developer (or App) the consent to do so.
In addition, the Office Graph will not only work with pre-defined types of data but also allow you to enrich it with new entities and insights.
APIs
Microsoft announced a new Unified API for Office 365 this week. The new Unified API provides access to all Office 365 APIs including the Office Graph through one single API surface. With the new Unified API you can now create powerful solutions on top of Office 365, while utilizing the power of the graph. In the figure above we've placed "Your App" side-by-side with built-in workloads to show that you are able to create just as nice experiences as e.g. Delve using the new APIs.
The Unified API federates entities across multiple data sources, providing one unified view of all of Office 365. This hides authentication differences from the users and provides a coherent developer experience.
The Office Graph exposes a graph data model, through a REST/OData-based API that you can connect directly to or use through the Unified API. The entities available through the API may be mastered in the graph, or be proxy objects for data in other systems (Azure, Dropbox, Google Drive etc.). In both cases, the API allows you to connect objects with one another in the graph.
The Office Graph is a strongly typed API, so a User is a User and a Document is a Document. This provides for a consistent way of working with data, and different applications can interoperate through a well-defined shared data model.
Types of data
The Office Graph will contain different types of data, similar to what is already released with Delve and more. There will be conversations from Outlook and Yammer, different types of files from SharePoint and OneDrive for Business, Users and groups from Azure Active Directory and events and tasks from Outlook and Project.
ActionNodes and RelationshipNodes are new concepts. An ActionNode represents some action taken by a user (similar to what we called signals in the past) while a RelationshipNode is any kind of relationship between entities in the graph.
Modeling concepts
The modeling concepts in the Office Graph starts out with a node. A node represents some entity with a stable ID, such as a user or document. The node has basic properties and navigation properties. A navigation property is an edge or pointer to another node. It has a type but no properties.
A node may have multiple extensions (or views), each with a different set of properties describing some other aspect of the entity.
In this case, User, Employee, File and Document are extensions.
We also have a special type of nodes we call Action nodes. An action node has some properties that describe the action taken as well as the actor and the object or objects(s) in question. It can also have additional properties and edges that give more context such as the app used to take the action and similar.
The Office Graph also can contain Relationship nodes. This is how we represent n-ary relationships and relationships with properties.
REST and OData
We've chosen to expose that data in the Office Graph through REST/OData as shown on this slide. Imagine a subset of the graph with relationships from users to entities they have liked.
To get all Like actions by a particular user, you can get the LikeAction collection where each LikeAction refers to the object the user liked. 
To get the liked object, add $expand to the URL. This will inline it.
Since all of this is well-defined JSON the server provides a $metadata document that returns all the available object types and their properties. We plan to provide client-side SDKs for situations where using REST directly is not so convenient.
Combining search and graph traversal
The graph will support graph-traversal such as finding items I've modified.
GET /me/Actions/Modified
This returns the list of items (documents, slide decks) etc. that I have worked on.
It will also be possible to combine this with full-text searches that we are used to from traditional search engines. For example, entities with "Windows" in the title is a typical full-text search. This will only match entities (documents, users, emails etc.) that have that word in the title field.
OData supports $filter, $expand and $search operations that we use to combine search, graph traversal, and result ranking. Thus, to combine the traversal and the full-text search we end up with something like this:
GET /me/Actions/Modified
?$search=Title:windows
Extension points
This figure shows the main extension points for Delve and the Office Graph.
The graph contains Data from Office 365, but you can add your own data to the graph. An example of this could be documents stored in some content management system. The type of data to be stored can also easily be customized. This could be done by enriching existing data or defining completely new data entity types. Office Graph will come with strong analytics that for example calculates who you are working with and what items are trending around you. These analyses can be customized or extended to support the needs of your apps and your data. Notifications will be available that trigger various conditions in the graph. Actions can also be added, allowing actions in other systems to be reasoned over by the Office Graph, and referenced entities to be shown in applications that leverage the Office Graph, e.g. Delve.
It will also be possible to customize what appears in Delve and how it is displayed.
Connector models
We understand that a modern workplace is fragmented. Companies are using a number of different services to get their work done. People can use Office 365 for email and storing documents and then they might be using all kinds of other line of business data for other purposes. We plan to open up the Office Graph through extensibility, as we want to enable our customers to place rich or shallow representations inside the Office Graph, and potentially also have it appear in Delve.
Currently, we see three different approaches for Office Graph's extensibility. First Microsoft plans to set up service(s) that targets the Office Graph. Our main goal here is to make the process for the end user simple. Then, we think there will be a set of external services that will implement the hooks needed to push content and activities directly to the Office Graph API. The last model is where a 3rd party stands up a service themselves to get data and signals into the Office Graph.
Licensing
While we're not yet ready to disclose pricing and licensing details, we do think it's important to note that we're planning to monetize some of the advanced capabilities of the Office Graph. Stay tuned for more details over the coming months.
Final words
Please remember that this is a roadmap posting. By the time we release something, concepts and implementation may have changed completely. We've still chosen to share this as early as possible to give partners, customers, ISVs and developers in general time to ramp up and consider the new opportunities new features in the Office Graph will provide.
Thanks a lot to Jon Meling for creating a lot of this material related to connectors and getting external data into the graph. If you watch the recording of our Build session you will see some demos in there with external content as well as some code examples of using the graph and adding your own extensions.