Create and manage Viva Engage communities with the Microsoft Graph API

Microsoft continues to expand its services and bring more functionalities into Microsoft Graph. The latest addition is the introduction of an API set for Viva Engage. I’m extremely positive about this recent development, as it introduces support for interacting with Viva Engage (formerly known as Yammer) via Microsoft Graph; laying a solid foundation for future enhancements to this API set and allowing developers to benefit from all Microsoft Graph features, including authentication and throttling management. This blog posts introduces the new Viva Engage API in Microsoft Graph and related scenarios.

Anatomy of a Viva Engage community

Each Viva Engage community is linked to a Microsoft 365 group; however, the ID of the associated group isn’t the same as the ID of the related community. This close relationship enables developers to expand the management scenarios on a community by operating at group level. When changes are applied to the associated group, they automatically reflect in the related community. This allows for more extensive scenarios that go beyond the capabilities supported in the Viva Engage API. For more information on the Viva Engage and Microsoft 365 group relationship, see Viva Engage and Microsoft 365 groups.

The Viva Engage API in Microsoft Graph

The Viva Engage API in Microsoft Graph supports three scenarios that allow developers to:

• Create a community
• Monitor the creation of a community
• Access a community

The current API set is limited to creating and getting communities and it doesn’t support all CRUD operations. For consistency with similar API sets such as the team and group, I hope that the Viva Engage team will extend this API set with the following additional operations on the community resource in the short term: List, Update, and Delete community.

You can only use the Viva Engage API on Viva Engage networks in native mode, which has been the default for all new Viva Engage tenants since 2020. For more information on native mode, see Overview of Viva Engage in Native Mode for Microsoft 365.

Creating a community

The Create operation on the community resource triggers an async operation for the creation of a Viva Engage community. This is a similar approach used also for the creation of Microsoft Teams teams. 

You can create communities using delegated and application permissions. When you create a community using delegated permissions, you’re automatically defined as a community owner. When you create a community using application permissions, you have to specify a community owner in the request body.

The following example shows a request for creating a community using application permission. Note that the response body contains an Operation-Location header with a link that allows you to monitor the async operation.

For more details, see Create community.

Monitoring the creation of a community

Use the link in the Operation-Location header to poll for status update on the creation operation. Monitor the response body of the following request for a status update that indicates whether the creation operation is still running, failed, or succeeded.

For more details, see Get engagementAsyncOperation.

Accessing a community

Retrieve a newly created or already existing Viva Engage community via the Get operation on the community resource. The following example shows an example of a request that returns a community object in the response body.

For more details, see Get community.

You can also access the following two relationships to get more information about a community:

• group: Returns the Microsoft 365 group associated with the community. For example, https://graph.microsoft.com/beta/employeeExperience/communities/eyJfdHlwZSI6Ikdyb3VwIiwiaWQiOiI4MzIxMjc1In0/group
• owners: Returns the administrators of the community. For example, https://graph.microsoft.com/beta/employeeExperience/communities/eyJfdHlwZSI6Ikdyb3VwIiwiaWQiOiI4MzIxMjc1In0/owners

Integrating with Viva Engage communities via the Microsoft 365 group API

As mentioned previously, every Viva Engage community is associated with a Microsoft 365 group. Operations ran on the associated group, automatically apply to the related community. This section explains five scenarios that you can implement in a Viva Engage community via the Microsoft 365 group API. For more scenarios, see Viva Engage and Microsoft 365 groups.

Adding and removing members from a community

Use the Add members API on the associated group to update the members of the related community. Likewise, you can use the Remove members API to remove the members from the related community.

Adding and removing an admin from a community 

Use the Add owners API on the associated group to add admins to the related community. Likewise, you can use the Remove owners API to remove the admins from the related community.

Renaming a community

Use the Update group API on the associated group to update the displayName property of the related community.

Conclusion

I’m positive about the new Viva Engage API support for two main reasons:

• Microsoft Viva has been around since 2021. Initially, the extensibility options for Viva apps were limited but now Microsoft continues to expose more and more API sets that enable developers to integrate and extend the services of Viva apps such as Viva Learning, Viva Goals, and now Viva Engage.
  
• I spent part of my career managing and developing provisioning engines. It was awkward to use the Yammer REST API to create Yammer groups while the provision of teams and groups happened via the Microsoft Graph API. Independent software vendors (ISVs) provisioning Viva Engage communities can finally benefit from a unified approach for creating collaboration spaces and communities.

I’ll keep a close eye on the development of the Viva Engage API and look forward to seeing more Viva apps available for integration via Microsoft Graph.

Thanks for reading,

Jarbas