Table of Contents
Beta API Can Create and List a Viva Engage Community
Message center notification MC701523 (24 December 2023, Microsoft 365 roadmap item 178311) marks the start of Graph API support for Viva Engage with a beta Community API to create and list Viva Engage communities. The API is limited to modern Viva Engage (Yammer) networks. All new networks are modern. The key point is that modern networks use Microsoft 365 groups to manage community membership.
This step marks the initial Graph API support for Viva Engage. Yammer has long had its own APIs but embracing the Graph is an inevitable part of integrating with the wider Microsoft 365 ecosystem (Graph support for Viva Engage activity data is already available). For whatever reason, the old Yammer engineering group resisted integration with Microsoft 365 for many years following the 2012 acquisition. That tactic didn’t work well in terms of driving Yammer use. Fortunately, Microsoft saw sense some years ago and began down the path to transition Yammer to Viva Engage in 2022.
PowerShell Code to Create a New Viva Engage Community
Creating a new Viva Engage community is simple. The API supports both delegated and application permissions. To make things easy, I used an interactive session with the Microsoft Graph PowerShell SDK. These commands:
- Connects to the Graph SDK endpoint with the necessary scope (permission).
- Defines the URI for the Communities endpoint.
- Creates a hash table containing the parameters for the new community.
- Converts the hash table to a JSON-format variable.
- Posts to the Communities endpoint using the JSON variable as the request body.
Connect-MgGraph -Scopes Community.ReadWrite.All -NoWelcome
$Uri = "https://graph.microsoft.com/beta/employeeExperience/communities"
$VivaCommunityParameters = @{
"displayName" = "Viva Engage Technical Discussions"
"description" = "A community where everyone gets together to discuss the technology that drives Viva Engage and its communities."
"privacy" = "Public"
}
$VivaCommunityBody = $VivaCommunityParameters | ConvertTo-Json
Invoke-MgGraphRequest -Uri $Uri -Method POST -Body $VivaCommunityBody -StatusCodeVariable "Status"
Figure 1 shows the new community as it appears in the Viva Engage web app.
Because Viva Engage communities depend on Microsoft 365 groups to manage their membership, creating a community also creates a Microsoft 365 group with a single owner and single member (the signed-in account). The current version of the API doesn’t support specifying a different account as the owner or additional members in the request body. This issue is easily addressed by running the New-MgGroupOwnerByRef and New-MgGroupMember cmdlets after creating the community. See this article for more information.
The API does not support creating a community using an existing group. You can only create a new community with a new group.
Points About Creating a Community
Specifying the StatusCodeVariable parameter when running the POST request with Invoke-MgGraph to create a new community returns a status value in a variable with the name of the passed string (in this case, $Status). A 202 value means that the request successfully created the community.
The unfortunate thing is that the value returned doesn’t include the Viva Engage identifier used with the Get method to retrieve details of the new community. The Viva Engage (Yammer) identifier is not the same as the Entra ID group identifier. Instead, it’s a Base64 value like eyJfdHlwZSI6Ikdyb3VwIiwiaWQiOiI4MzIxMjc1In0 (equating to {“_type”:”Group”,”id”:”8321275″}). The Get method requires the identifier to fetch details of a community and doesn’t support fetching details of all communities. That seems like an oversight that Microsoft should fix before the API attains general availability.
Another bug is that if you specify “public” (lowercase p) in the parameters, the API sets the new community to be private. You must set the value to be “Public” if you want to create a public community.
Interaction with Microsoft 365 Groups
The new API can create a group but it cannot update group properties (like its photo) or group membership. Most group properties are still controlled by Yammer APIs and are inaccessible through the Graph. In addition, you’ll find that most attempts to update group settings like the access type (public or private) using the Set-UnifiedGroup or Update-MgGroup cmdlets fail.
However, you can run the Add-UnifiedGroupLinks to populate the new community with owners and members. Here’s an example of adding four members to a community:
$GroupId = (Get-UnifiedGroup -Filter {displayName -eq 'Viva Engage Technical Discussions'}).ExternalDirectoryObjectId
[array]$Members = "Lotte.Vetler", "James.Ryan", "Chris.Bishop", "Andy.Ruth"
A Start Along the Road to Fully Embracing the Graph
All beta APIs tend to exhibit imperfections and bits that are incomplete. Being able to create new Viva Engage communities using the Graph is a good step forward but it’s only the start of the transition from the old Yammer APIs. We look forward to seeing more progress on this point in the future.
Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.