Programmatically Follow or Unfollow a Delve Board with the REST API

In one of my previous posts, we saw how you can programmatically add a document to a Delve Board with the REST API. This is a follow up post to that in which we will see how to Follow or Unfollow a Delve board with the REST API. If you haven't already seen the previous article, I suggest you take a look at it because it explains how Delve works under the hood and how you can integrate Delve into your custom Office 365 solutions.

Please bear in mind that since Delve utilizes search internally, you will have to wait for a search crawl to take place in Office 365 before you can see results of the REST operation.

I have used JavaScript and the jQuery.ajax function to make calls to the Signals API. But you can use a variety of other options which support REST.

So without much further ado, here is the code to follow or unfollow a board in Delve:

Get all Office 365 Video Channels, Groups and Delve Boards with REST

Office 365 has introduced 3 new portals recently: Videos, Groups and Delve. Behind the scenes, the architecture of Videos and Groups is such that each Video channel is a site collection and so is each Group. For Delve boards, each board is saved as a Tag and when you add a document to a board, the document is tagged with the name of the board.

If you are working on a solution for Office 365 and want to integrate Videos, Groups or Delve, here is how you can get a list of all of them using the SharePoint REST API:

1) Get all Office 365 Video Channels with REST API:

https://siteurl.sharepoint.com/_api/search/query?querytext='contentclass:sts_site WebTemplate:POINTPUBLISHINGTOPIC'&SelectProperties='WebTemplate,Title,Path'&rowlimit=50

2) Get all Office 365 Groups with REST API:

https://siteurl.sharepoint.com/_api/search/query?querytext='contentclass:sts_site WebTemplate:Group'&SelectProperties='WebTemplate,Title,Path'&rowlimit=50

3) Get all Delve Boards with REST API:

https://siteurl.sharepoint.com/_api/search/query?querytext='(Path:"TAG://PUBLIC/?NAME=*")'&Properties='IncludeExternalContent:true'&selectproperties='Path,Title'&rowlimit=50

Programmatically add a document to a Delve Board with REST

Microsoft recently launched the Boards feature in Delve, with which you can create Pinterest like boards and add content to them. You can add documents from your SharePoint sites as well as OneDrive for Business sites.  Here is a great introduction to the functionality: http://blogs.office.com/2015/01/07/introducing-boards-office-delve-new-way-organize-share-work/ 
I have been playing around a bit with this feature and have some interesting things to share. So Lets have a look at how this has been implemented under the hood.

1) The same Signals API which I have blogged about here is used in boards. AJAX requests are sent to the /_api/signalstore/signals endpoint when any operations are made in Delve (eg. add document to board)

2) Boards are internally referred to as "Tags". So when you add a document to a board, it gets "Tagged" with the name of the board. More on this later.

3) There seem to be 2 components in play. When you add a document to board, there is an "immediate" add in the front-end as well as a normal add when the incremental crawl adds the document in the Search Index. The front-end immediately  shows the user  that the document is added to a board. This is a very good solution as otherwise the user would have to wait till the incremental crawl has taken place.

Let us have a look at the API now. All the API is doing is adding/removing documents to boards and following/unfollowing boards. Unlike my previous post about modifying relationship signals in the Office Graph, with this API you will not be interfering with your Office Graph relationships so I think you can safely use this API in your solutions.  Now lets take a look at what actually happens under the hood:

There is a new button introduced in the document card. So when you click on "Add to Board" and select a board from the dropdown,  here is the JSON which is sent to the Signals API: 

(click to zoom)

Basically, it has 2 Important pieces of data: 

1) The document gets tagged with the name of the board. This tag is then used by Delve to search and get all documents belonging to a certain board. This is done by the first object with ActionType:Tag and Item Id as the absolute url of the document.

2) The current user is made to follow the Tag (which is the board name) so that it shows up on the left hand side in Delve. This is done by the second object with ActionType: Follow and Item Id: ‘Path=”TAG://PUBLIC/?NAME=MY+TEST+BOARD”  where the name of the board I selected was "My Test Board"

If you want to reproduce this exact behavior in your solution, here is the sample code you can start with. Please be aware that that this code only tags the document with the board name so that it is added to the search index and follows the board so that it appears in your boards in Delve. This does not do the front-end add to the board. So you will have to wait for an incremental crawl to run in Office 365 for the document to get added to the board and show up in Delve. I have observed this can take anywhere from 5 to 30 minutes. 

Here is the code:


The document will get added to the board:

Hope you enjoyed this post. I have plans to follow this up with some code samples which show how to remove documents from boards, unfollow boards and some other new functionality. Thanks for reading.

Writing signals into the Office Graph and Delve

Say you are developing a custom solution in SharePoint Online and you want to integrate data from the Office Graph in it. The method of reading data from the Office Graph is pretty straightforward and I have documented it in my previous post: http://www.vrdmn.com/2014/09/exploring-office-graph-and-graph-query.html

But what if you actually want to send behavior data to the Office Graph? You have a custom link to a User Profile or a document in your solution and when the user clicks the link, you want to send a "Clicked" signal to the Office Graph. If  a User Profile link of a user is clicked, you want to send a signal to increase the "closeness" of the current user to that user.

You want the user's interactions in your solution to affect the data that is stored in the Office Graph.

It is actually possible to push signals into the Office Graph from your custom application. There is actually an endpoint  _api/signalstore/signals to which you can send your custom signals.

Some things to note before we go ahead:

1) This API is not yet documented and might change in the future. It is not recommended for production solutions just as yet. 

2) This API is also throttled at a certain stage to avoid malicious use to provide false data to the Office Graph.

3) It takes about 24 hours for Delve to reflect your changes.

To see how this is done, you can open up Delve in your browser and press F12 to bring up the Developer Tools. When you navigate in various areas of Delve, you can see all the signals which are sent to the Office Graph as a result of your actions. For example, when you click a document, you can see the following request is sent:

(click to zoom)

Each signal is made of 3 properties. The Action, the Actor and the Item.

1) Actor: This is always the current user as you cannot send signals on behalf of other users.

2) Item: This is the object against which the signal is performed. This can be a document url in case of a document or it can be the login name of a user if the object is a user.

3) Action: This is the action e.g. Clicked, Shown or Elevate which is used to affect the relationship between the Actor and the Item.

I have put together couple of code samples which could be used as a base in sending custom signals to the Office Graph. These samples work right off the bat but they can be further customized by setting properties to modify the Office Graph behavior. You can find the full list of properties in your Developer Tools.

1) Send a document "Clicked" signal. This will tell the Office Graph that the current user has clicked a particular document. The Office Graph will take into account this action when calculating the closeness of the current user to this document.



2) Elevate a user with respect to the current user. This will increase the closeness and edge weight of the specified user with respect to the current user:



Hope this API will get documented soon. There is a lot of potential here for building custom solutions on top of the Office Graph and Delve.

Exploring Office Graph and the Graph Query Language

So you must have heard about the Office Delve launch recently. I have been trying out my hands at the Office Graph which powers Delve and the Graph Query Language which can be used to get data from the Office Graph. To get a comprehensive idea of how it all works, follow these links:

Developing Apps against the Office Graph - Part 1
http://blogs.msdn.com/b/richard_dizeregas_blog/archive/2014/09/15/developing-apps-against-the-office-graph.aspx

Developing Apps against the Office Graph – Part 2
http://blogs.msdn.com/b/richard_dizeregas_blog/archive/2014/09/17/developing-apps-against-the-office-graph-part-2.aspx

Using Graph Query Language (GQL) with the SharePoint Online Search REST API to query Office graph:
http://msdn.microsoft.com/en-us/library/office/dn783218(v=office.15).aspx

So basically we can say that the Graph Query Language can be used to filter normal search queries to return content which is highly relevant to the user. I think the most important thing about the GQL is the EdgeWeight property which can be used to return content sorted by it's "closeness" to the user. This 'magic' property will also return a relevance score of how close the object (content) is to the actor (user).

For example, if  I make a query to get all the people with whom the current user closely works with, the person who will have the highest relevance score will be the person with whom the current user works with most closely. The next person will have a slightly lesser relevance score and so on. This will also be true for other queries such as documents which are most relevant to the current user. This data can be very useful and can be used in a variety of scenarios.

Here is an example of a query to get the users with whom the current user works closely. I have modified the code from Richard diZerega's blog which is linked above.