With the new Groups API we can extend the capabilities of Office 365 Groups to facilitate collaboration even further. And while getting started with the API is easy, there are two things that aren’t obvious right from the start.

Groups - it’s for collaboration

A while ago Microsoft released Groups as a part of Office 365. Being a combination of Azure AD, Exchange Online and SharePoint Online, Groups are a new way to facilitate lightweight collaboration in organizations. Comparing to Team Sites, Groups focus less on document management and more on communication and collaboration and provide groups of users with an access to discussions, calendars, documents and easy note taking - all from a single place.

Office 365 Groups are still relatively new and there are many ideas how they could be improved. Aside from those ideas, Microsoft provided us with an API that we can use to build custom solutions on top of Office 365 Groups.

Office 365 Groups API

The API that allows us to interact with Office 365 Groups is available as a part of the new Office 365 Unified API. Although this API is still in beta it already provides us with rich capabilities, such as CORS support for building rich client-side solutions, not to mention the functionality to interact with the different workloads within Office 365.

The Office 365 Groups API allows us to easily interact with Groups and the data stored within. Thanks to the documentation provided on dev.office.com you will be able to quickly get started, but once you do the odds are high that you will stumble upon two things that are not super obvious right from the beginning.

Getting deep links to Group’s resources

When building solutions on top of Office 365 Groups you might want to provide your users with direct links to access conversations, calendar or documents. While it doesn’t seem like anything extraordinary, currently the API doesn’t provide you with a way to get these links. Instead you would need to construct them yourself.

If you want to link to conversations for example you would need to link to:

https://outlook.office365.com/owa/#path=/group/mygroup@contoso.onmicrosoft.com/mail

The link to the Group’s calendar is similar:

https://outlook.office365.com/owa/#path=/group/mygroup@contoso.onmicrosoft.com/calendar

Linking to Group’s documents is different and requires you to get a hold of the user’s tenant name and the Group ID in order to build the link, which is:

https://contoso.sharepoint.com/_layouts/groupstatus.aspx?id=14cb9281-5d0c-4bfa-99da-1eef714c2d2b&target=documents

Even though these links work, your users might experience an inconvenience when using the direct links to conversations and calendars.

Outlook on the web is a Single Page Application that uses the URL hash to keep track of the path to the current view, such as Inbox, your personal calendar or conversations of a specific Group. Unfortunately if you are not authenticated in Outlook on the web, the first time you access a deep link in Outlook on the web you will be redirected to the Office 365 login page. Once you login you will end up in your personal Inbox rather than in the location designated by the deep link you used initially. Using the same link for the second time takes you to the right place, but by that time you already left the application and you would first need to get back to it to click on the link again.

Showing Group’s picture

One of the important elements of Groups are their pictures. Pictures enhance Groups’ identities and help users distinguish the different Groups within their organization. When building solutions on top of Office 365 Groups it is therefore essential to maintain that consistent user experience and include Group picture next to its name.

Following the documentation on dev.office.com you will find out that in order to retrieve Group’s picture you have to perform a GET request to the following URL, where contoso.onmicrosoft.com is the name of your tenant and the GUID is the ID of the Group for which you want to retrieve the picture:

https://graph.microsoft.com/beta/contoso.onmicrosoft.com/groups/01d360b6-2487-43f2-b968-180754ef4c7e/GroupPhoto/$value

What you get back are the binary contents of the Group’s picture. What the documentation doesn’t mention however is what you are supposed to do with it. Using the URL mentioned above with an img tag is not an option since it requires authentication information to be provided in the Authorization header. So there is something else that you have to do in order to display the Group’s picture in your application, but what?

There is more to a blob than meets the eye

Getting the contents of the Group’s image seems straightforward. After all, how hard can executing a GET request be. Unfortunately if you don’t do this correctly, you will spend a lot of time wondering why your image doesn’t show in your application, not knowing that its contents, that you have just retrieved, are invalid.

Assuming you’re using AngularJS in your application, when retrieving Group’s picture using an HTTP request, you need to extend your request with the responseType: ‘blob’ request header:

$http({
  url: 'https://graph.microsoft.com/beta/contoso.onmicrosoft.com/groups/01d360b6-2487-43f2-b968-180754ef4c7e/GroupPhoto/$value',
  method: 'GET',
  responseType: 'blob'
}).success(function (image) {
  // process
}).error(function (err) {
  // error
});

This will instruct AngularJS to treat the response of that request as binary data and deal with it accordingly.

From blob to image

Once you have properly retrieved the binary contents of the Group’s picture, the next step is to display them in your web application. In contrary to base64-encoded images you cannot pass the binary image contents directly to HTML. Instead you have to instruct your browser to create an object first to which you then can refer:

$http({
  url: 'https://graph.microsoft.com/beta/contoso.onmicrosoft.com/groups/01d360b6-2487-43f2-b968-180754ef4c7e/GroupPhoto/$value',
  method: 'GET',
  responseType: 'blob'
}).success(function (image) {
  var url = window.URL || window.webkitURL;
  var blobUrl = url.createObjectURL(image);
  // return blobUrl
}).error(function (err) {
  // error
});

After retrieving the image’s binary contents we first need to create an object that we can refer to out of it. This is done using the URL.createObjectURL function. Unfortunately it’s implemented differently in WebKit browsers so before calling this function you first need to get the right version of it depending on the web browser that the user is working with.

Calling the createObjectURL function returns a URL to the blob, such as: blob:http%3A//yourapplication/GUID. This URL can be then set as the value of the img src attribute in order to have the image displayed in your web application.

The screenshot above shows an application that we have built at Mavention and which simplifies accessing Groups. We will be releasing it shortly so stay tuned for updates.

Summary

Groups are a new way to facilitate lightweight collaboration in organizations using Office 365. Using the new Office 365 Unified APIs you can extend Groups’ capabilities even further. Although the API is currently in beta, it already provides rich functionality. The documentation provided on dev.office.com helps you get started but it doesn’t mention how to provide deep links to Groups’ resources or display Group’s picture in your web application - both of which require some additional effort.