Exploring the Office 365 Groups API

Office 365 Groups are rolling out across the service. This compelling, collaborative structure has the potential to grow rapidly in every organization, regardless of the size. With its Office 365 foundation, there is a rich API for accessing information in the service. (Although, some of the pieces are in beta at the moment.) This article and accompanying sample program hope to shed some light on the Groups API.​

W​hat is an Office 365 Group?

To best describe Office 365 Groups and their purpose, I thought it best to use Microsoft’s own words:

Collaborating with colleagues can be challenging. When teams are working on a project together, there can be a lot to keep track of. Emails and meetings in Outlook, conversations and calls in Skype for Business and documents to store and share in SharePoint and OneDrive for Business. Office 365 groups enables teams to come together and get work done, by establishing a single hub (managed in Azure active directory), and a single set of permissions across all these Office 365 apps, so teams can simplify collaboration and increase productivity. Office 365 groups also allows collaboration in OneNote, Power BI and Dynamics CRM. When a user joins the group, they immediately gain access to all of the work of the team and project.​​​​​​​​

What is a Group Resource?

In​ the API, a group resource “represents an Azure Active Directory Group. While this sounds quite simple, in actuality it means many different things. In the directory a group object can be used in access control lists (security), for distributing email (Exchange), a dynamic collection of users (Dynamic Groups in Azure AD Premium), and a group object can represent a plan in the Planner application. Understanding the purpose of a group resource in the directory can be quite maddening. Many different properties and relationships must be reviewed to make an accurate classification.

To aid i​​​n the review of properties and relationships of a group resource, I’ve created a web application named the Office 365 Groups Explorer. This application is available for all to run against their own tenant at https://office365groupsexplorer.azurewebsites.net/. The application source code is available at https://github.com/pschaeflein/Office365-Groups-Explorer​.

Companion Web Application

The companion web application lists all groups in the user’s tenant, along with all the properties. For step-by-step instructions to create a similar application, complete the lab in the Training Content repository produced by the Office Developer team on GitHub: Deep Dive into the Microsoft Graph for Office 365 Groups. Since those steps are available, this article will not focus on app registration nor the mechanics of the REST endpoint. Rather, it will discuss the resources, properties and relationships in the API. This information, combined with the official documentation should help in the creation of your custom applications that leverage the Groups resources.

The application home page is shown in Figure 1.


Figure 1 - Companion Application home page​

Resources

The Groups API consists of a few primary resources:

  • Group
  • Conversation
  • Thread
  • Post
  • Event
  • Drive / DriveItem (Files)
  • Notes
  • Plan

There is a relationship between the Group resources and each of the other resources. However, the relations only apply to Office 365 groups, not security or distribution groups.

Groups​​

The group type can be determined by inspecting a few properties. In Figure 2, two groups are shown using the sample application. The "groupTypes", "mailEnabled" and "securityEnabled" properties indicate that the "Sales Team" group is a distribution group and the “Dynamic Demo” group is a security group.​​


Figure 2- Group details, highlighting mailEnabled and securityEnabled properties​

Curiously, there is a groupTypes property, that is defined as a collection. In both groups shown, the property is empty. However, for a group created using the Offfice 365 Groups interface, the groupTypes property contains a single value of "Unified." This can be seen in Figure 3.​


Figure 3 - Group details, highlighting groupTypes property​

​Since the "groupTypes" property is set for Office 365 Groups, we can use it to find all groups in the organization. Unfortunately, using the "groupTypes" property in an OData $filter parameter does not work. Another point to consider – the application must have permission to Read Directory data to get the groupTypes property to be returned.​

Conversation / Thread

The ​conversation resource is a container for threads that occur in the group. (There is quite a bit of overlap between the Conversation resource and the Thread resource. I suspect that differences will emerge once Skype and Yammer conversations get added to the Group paradigm.) Threads are created in the web interface, via email to the Group inbox, and automatically in response to events. In Figure 4, the conversations are shown in the web interface as well as the results of the API call. We can see that two conversations pertain to calendar events in the group.


Figure 4 - Group Conversations in the web interface as the sample application

Po​​st

Posts most closely align with messages in an email context. Although, posts in Office 365 Groups need not be an email message – they can be added via the API or the web interface. A view of a thread containing two posts is in Figure 5. Figure 5 - Posts in a conversation thread​


Figure 5 - Posts in a conversation thread

Although it is not shown in the companion application, Posts have a "body" property that contains the actual message in the post. The "body" property is actually a compound type, also specifying the content type (text, html) of the content.

Events​

The Event resource represents an entry on the group calendar. These entries resemble meeting invites, with a collection of attendees and a location. In Figure 6, two events are shown that were created by Garth. Notice the attendee list includes the Group object.​


Figure 6 - Listing of Events in a group

Drive / DriveItem (Files)

Files in a group are stored in the Group’s OneDrive. In practice, this means that the files are stored in a SharePoint document library. Figure 7 illustrates the storage of files in Office 365 and the related DriveItem resources. The endpoint is a bit more complex than just /drive, as the folder structure must be included. (However, the addressing of the Group Drive resource is the same as the addressing for user’s Drive resources.) The DriveItem resource does not include the file contents. The file contents are accessed via a separate call to the address returned in the "webUrl" property.


Figure 7 - Group files shown in sample application and Office 365 web interface

​​Notes / Plan

Office 365 groups also contain a group notebook. The notebook is actually a OneNote notebook and the API for accessing that resource is part of the /beta namespace at the moment.

Office 365 Planner leverages the Group construct for storing its Plans and members. Group Plans are also in the /beta namespace, as planner is still rolling out to tenants and is not 100% available.​

Summary

​​The Office 365 Groups application offers tremendous benefits to teams. It API allows developers to integrate their applications with the group information. This article provides an introduction to the various resources in the API and the companion web application allows for discovering the information available in your tenants. The companion web application is available to run against any tenant at https://office365groupsexplorer.azurewebsites.net/. The application source code is available at https://github.com/pschaeflein/Office365-Groups-Explorer.