Wednesday, November 8, 2023

Integrate with Announcements in Viva Connections using the Microsoft Graph API

In the constantly evolving Microsoft 365 world, there's always something new to explore. One of the latest additions to catch our attention is the Announcements feature in Viva Connections. This feature introduces publishing capabilities to Viva Connections, enhancing communication within organizations by allowing communicators to share targeted, time-sensitive updates and information with their team members. In this post, I share with you my findings about how to extend Viva Connections Announcements using the Microsoft Graph API.

Anatomy of Announcements 

First things first, behind the scenes Announcements is not a common list in SharePoint, but a document library that can be accessed directly via Viva Connections or in SharePoint via the following URL: {SiteUrl}/_layouts/15/announcements.aspx. Communicators can use this area to create, manage, and share announcements to keep their team informed. Technically, an announcement is stored in XML format as an .aspx page.

Key properties for announcements:

  • Audience Targeting: When creating an announcement, audience targeting is essential and mandatory. You can target up to 10 audiences, which can be Microsoft Entra ID security groups or Microsoft 365 groups. This ensures that your message reaches the right people.
  • End date and time: Setting an end date and time for your announcement is mandatory. You can schedule it to remain visible for up to two weeks from the original publishing date.
  • Message: The message is where you convey the details. Maximum of 250 characters.
  • Title: Each announcement must have a title but keep it concise as you're limited to 60 characters.
  • Schedule to send later: If timing is crucial, you can schedule your announcement to send later. Scheduling is available only in half-hour increments, so plan accordingly.

Accessing Announcements

The most recent announcement takes the spotlight in Viva Connections. The next four announcements are accessible through a carousel format. If you want to view all announcements, a "See all" button opens a modal dialog listing all announcements in descending order.

Announcements in Viva Connections

Extending Announcements 

Microsoft Viva Connections has had so far limited extensibility options, primarily related to Dashboard cards (aka. adaptive card extensions). However, the landscape is changing with the introduction of new Viva Connections features such as Announcements and Company Links. These features leverage the SharePoint infrastructure, opening the door to a wider range of integration scenarios. Now, you can integrate with SharePoint to enhance the Viva Connections experience.

Extending via the Microsoft Graph API

At the time of this written, Microsoft hasn’t introduced a dedicated API set to integrate with Announcements in Viva Connections. However, you can use the driveItem API to seamlessly integrate with the Announcements library in SharePoint. The following examples show the requests I used to create a new announcement in Viva Connections.

Downloading an announcement

I first ran a GET request to download an existing announcement from the Announcements library.

This is what the response object looks like:

Uploading an announcement

You can upload announcements in the form of .aspx pages to the Announcements library. For this example, I updated the XML content of the previous response before uploading the new announcement to the Announcements library.

The previous request creates a new announcement in the Announcements library; however, the announcement isn’t yet visible in Viva Connections. To ensure your announcement appears in Viva Connections, remember to publish the page. Note that you'll need to check out the .aspx page before you can proceed with checking it in and publishing it.

Checking out the .aspx page (announcement)

Checking in and publishing the .aspx page (announcement)

Exploring deeper with internal APIs

For those who enjoy taking a deeper look at internal APIs, I found an endpoint that returns announcements the signed-in user has dismissed. 

The EmployeeExperience path in this endpoint already exists in Microsoft Graph. I’m curious whether Microsoft plans to extend the employeeExperience resource in the future to expose other Viva APIs publicly 🤔

API integration considerations

While Announcements in Viva Connections offer powerful communication capabilities, it's worth noting that Microsoft doesn't provide dedicated Viva Connections APIs for seamless integration. To work with Announcements, you have to rely on SharePoint operations. However, this approach can be risky, as Microsoft can change the structure of the Announcements library without prior notice. Announcements are saved in XML format on .aspx pages and relying on this XML structure can be challenging because Microsoft can alter it at any time. This represents a challenge for building production-ready integrations, especially considering the ever-changing landscape of Microsoft 365.

In conclusion, Announcements in Viva Connections are a valuable tool for enhancing communication within your organization. Communicators have an additional instrument with support for audience targeting that they can use to increase their reach. As a developer or ISV, understanding the extensibility options and the potential challenges can help you make the most of this feature and potentially extend Microsoft’s services.

See also

Thanks for reading,