Graph-based Service Communications API is now the Route to Service Health Data

In January 2021, I wrote about how to use the Office 365 Service Communications API to programmatically retrieve the service health information that’s available in the Microsoft 365 admin center (Figure 1).

At the time, the API used the manage.office.com endpoint. In December 2021, Microsoft deprecated the manage.office.com endpoint and introduced the Service Communications Graph API as the replacement. In this article, I explain how to use the API with Microsoft Graph PowerShell SDK cmdlets to retrieve service health information.

Retrieving Service Health Data

As shown in Figure 1, the active items Microsoft is working on are those that impact the service in some way, usually by removing the ability of users to do something. To find these items, run the Get-MgServiceAnnouncementIssue cmdlet and filter for items classified as advisory with a status of ‘serviceDegration’:

[array]$ServiceHealthItems = Get-MgServiceAnnouncementIssue -All `
    -Filter "classification eq 'Advisory' and status eq 'serviceDegradation'" | `
    Sort-Object {$_.LastModifiedDateTime -as [datetime]} -Descending

$ServiceHealthItems | Format-Table Id, Title, FeatureGroup, LastModifiedDateTime

If you don’t filter the service health items, the Get-MgServiceAnnouncementIssue cmdlet, including those where Microsoft resolved the issue (as with many SDK cmdlets, the All switch tells the cmdlet to fetch everything). This data reveals the areas where most issues occur. In my tenant, the 346 available issues broke down as follows:

$Data = Get-MgServiceAnnouncementIssue -All
$Data | Group-Object FeatureGroup -Noelement | Sort-Object Count -Descending | Format-Table Name, Count -AutoSize

Name                                    Count
----                                    -----
Teams Components                           80
Administration                             39
E-Mail and calendar access                 27
SharePoint Features                        25
Portal                                     23
Management and Provisioning                22
Microsoft Defender for Endpoint            21
Cloud App Security                         13
Viva Engage                                10

Another interesting grouping is by service:

$Data | Group-Object Service -Noelement | Sort-Object Count -Descending | Format-Table Name, Count -AutoSize

Name                                      Count
----                                      -----
Microsoft Teams                              80
Microsoft 365 suite                          64
Exchange Online                              60
Microsoft Defender XDR                       32
SharePoint Online                            30
Microsoft Defender for Cloud Apps            25
Microsoft Viva                               12
OneDrive for Business                         8

The start date for the oldest issue was March 1, 2023. The oldest last modified date for an issue was July 31, 2023. This suggests that Microsoft might keep about six months of service issue data online. Your mileage might vary.

Fetching Overall Service Health Data

Underneath the advisory items, the Microsoft 365 admin center displays an overview showing the health for individual services like Exchange Online, Teams, SharePoint Online, and so on. This information is accessible by running the Get-MgServiceAnnouncementHealthOverview cmdlet. In my tenant, this generates a list of 32 individual services, some of which (like Sway and Microsoft Managed Desktop), I’m not interested in. I therefore amend the output by filtering the services that I consider most important:

[array]$ImportantServices = "Exchange", "Teams", "SharePoint", "OrgLiveID", "Planner", "microsoftteams", "O365Client", "OneDriveForBusiness"
[array]$ImportantServiceStatus = Get-MgServiceAnnouncementHealthOverview | Where-Object {$_.Id -in $ImportantServices}
$ImportantServiceStatus | Sort-Object Service | Format-Table Service, Status -AutoSize

Service            Status
-------            ------
Exchange Online    serviceDegradation
Microsoft 365 apps serviceOperational
Microsoft Entra    serviceOperational
Microsoft Teams    serviceDegradation
Planner            serviceOperational
SharePoint Online  serviceDegradation

Using Service Health Data to Highlight Current Advisories

Many people will be perfectly happy to access service health information via the Microsoft 365 admin center. The advantage of using an API to retrieve the same information is that you can then use it in whatever way you think appropriate. As a working example to demonstrate what’s possible, I wrote a script that can run interactively or as an Azure Automation runbook using a managed identity.

The script retrieves the open service health advisories and creates an email with an HTML-format report containing the service data that is sent to nominated recipients (any mixture of mail-enabled objects, including individual mailboxes, distribution lists, and Microsoft 365 groups). The idea is to keep the recipients updated about progress with open issues that Microsoft is working on. Figure 2 shows an example email generated using the service advisories published in my tenant.

After it’s extracted, the report can be disseminated in other ways. For instance, you could publish it as a Teams channel message.

You can download the script from GitHub.

Disrupted Change

Changing the details of an API is always disruptive. It’s not just the new endpoint. It’s also the way that the API returns data. Everything must be checked and verified. At least now the Service Communications API is part of the Microsoft Graph. As such, the level of change should be minimal in the future and we have the added benefit of PowerShell cmdlets to work with.

Learn how to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.

Microsoft 365 Notifications User Counts Come from the Graph

Message center notification MC315739 (January 18, roadmap item 83946) brings news of a big change for the information included in notifications. Soon, along with the text describing new features or changes to existing Microsoft 365 features, notifications will include service usage data relevant to the change. Deployment starts for targeted release tenants in mid-January and should be complete worldwide for all tenants by mid-February.

Let’s take the change announced in MC302456 as an example. This notification describes how users can maintain their guest accounts in other tenants from Teams. To help administrators understand how many people will be affected by the change, the service communications API queries the Microsoft Graph reports API to retrieve the monthly active user data for Teams and reports this information in the notification.

Figure 1 shows a mock-up included in MC315739 to illustrate how Microsoft 365 notifications highlight user data. On the left, you see a notification for a change affecting multiple workloads together with the usage data for each workload (Outlook is really Exchange Online, but obviously non-Outlook clients can connect to Exchange Online mailboxes). On the right, you see a notification for Kaizala, which doesn’t store its usage data in the Microsoft Graph, so it’s impossible to display this information.

Editorial comment: The need for Kaizala is possibly now much reduced by the general availability of the Teams Walkie-Talkie feature.

The Problem with Microsoft Graph Usage Data

The Microsoft Graph reports API allows access to usage data about some Microsoft 365 services. Coverage is good for base workloads (SharePoint Online, Exchange Online, Teams, and OneDrive for Business) and not so good elsewhere (Planner, Stream, Forms, Whiteboard, etc.). Nevertheless, the usage data is detailed enough to build a picture of user activity over the last ninety days. If you’d like to know how to use the API with PowerShell, consider running the User Activity Analysis script to see how to make calls against the reports API and the kind of data the API returns. For example, this code creates a query to retrieve Teams activity data for users over the last 30 days. Data returned by the reports API is always a few days behind the actual date.

$TeamsUserReportsURI = "https://graph.microsoft.com/v1.0/reports/getTeamsUserActivityUserDetail(period='D30')"

[array]$TeamsUserData = (Invoke-RestMethod -Uri $TeamsUserReportsURI -Headers $Headers -Method Get -ContentType "application/json") -Replace "...Report Refresh Date", "Report Refresh Date" | ConvertFrom-Csv

The data returned by the API is in an array. Here’s the item in the area for an account:

Report Refresh Date        : 2022-01-16
User Principal Name        : Jane.Smith@office365itpros.org
Last Activity Date         : 2022-01-15
Is Deleted                 : False
Deleted Date               :
Assigned Products          : POWER BI (FREE)+ENTERPRISE MOBILITY + SECURITY E5+BUSINESS APPS (FREE)+MICROSOFT POWER AUTOMATE FREE+MICROSOFT VIVA TOPICS+MICROSOFT DEFENDER FOR CLOUD APPS – APP GOVERNANCE+OFFICE 365 E5 WITHOUT AUDIO CONFERENCING
Team Chat Message Count    : 58
Private Chat Message Count : 14
Call Count                 : 1
Meeting Count              : 5
Has Other Action           : No
Report Period              : 30

The data looks good and is useful. However, some workloads (like Teams) return data for both tenant and guest accounts, so the numbers reported in message center notifications will reflect that data. You might be concerned about how a change will affect guest users, but I hazard a guess that most tenant administrators will focus on the effect on tenant users.

Another issue (acknowledged in MC315739) is the non-specific nature of the report. Usage across all clients and all features is included into one workload figure. For instance, a change affecting Microsoft Lists in SharePoint Online and OneDrive for Business might affect just the five people who create and manage Lists, but the notification will say that the change affects everyone who has used SharePoint Online or OneDrive for Business in the last month. You won’t know either if a change is specific to a client platform, like Android or iOS.

Counting all and sundry who use a workload isn’t such a big problem for new features. It is more important for updated features and becomes even more critical when Microsoft deprecates some functionality. You then want to know precisely who is affected, or at least, how many are affected.

Another aspect of an all-up number is that it doesn’t take account of multi-geo deployments. You’ll know that some people in the organization might need to be informed about a change, but not their location.

Still a Good Change

Even with the caveats listed above, including user data in Microsoft 365 notifications is still a good change. If you see a notification where a low number of users will experience an impact, you can probably spend less time preparing for that change and more on changes affecting large user populations. The availability of data through Graph APIs limit what the developers can do to slice and dice usage data to make it more precise and informative. This will probably happen over time. In the interim, take the user information presented in Microsoft 365 notifications as a starting point to help you understand the likely impact of individual changes on users. Use this data in conjunction with your knowledge of the tenant and how people work within the organization, and the monthly active user data for affected workloads will be helpful. Taken as an exact guide, it won’t be.

I guess I might have to update my script to extract and report information from message center notifications to accommodate this change…

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.

Microsoft 365 Privacy Messages in Case of Data Compromise

Microsoft posts notifications to the message center in the Microsoft 365 admin center to inform tenant administrators about a variety of different updates made to its service. MC272885 posted on Jul 24, 2021, has the title Attachments for messages with Data Privacy Tag, which might leave you scratching your head to understand what Microsoft means. At first glance, the combination of attachments and messages points to email and tag could mean a sensitivity or retention label. But that’s not what it means.

Reading the detail reveals that Microsoft is introducing a new tag for service update messages. Let’s explore what this means.

Tagging Service Messages

When Microsoft publishes a service update message, it applies tags to help tenant administrators understand the importance and potential impact of the change (Figure 1).

The tags shown in the message center include:

• Admin Impact: The change impacts the management of some aspect of the tenant. For example, a new API is available. MC272885 (described here) is deemed a change with administrator impact.
• Feature Update: Microsoft has changed the way a feature works. For example, MC264095 describes how the default setting for guest access in Teams changes from off to on.
• Major Update: The change described is considered major. For example, the retirement of Skype for Business Online on July 31 (MC266078) is obviously a big change in Office 365. Other updates tagged as major are debatable, but you can consider this tag to be a way for Microsoft to highlight important changes. Note: Unlike the other tags, this tag is marked by setting the IsMajorChange property of a message to $True.
• New Feature: A new feature is on its way for an app. For example, MC230680 describes the introduction of reactions in Teams meetings. Microsoft often misses the date for feature introductions and republishes the update, which is what happened on MC230680 on June 30 when they published new dates for availability of the feature in the GCC and DOD clouds.
• Retirement: Microsoft is removing a feature from the service. Skype for Business Online is an example, so is the final removal of Site mailboxes (MC266256). Not many shed tears when site mailboxes shuffled off into the great byte wastebasket.
• User Impact: Many changes impact users in some way. For example, MC271629 advises administrators that Project Moca is moving its spaces to the OWA calendar.
• Updated Message: This tag does not appear in the Microsoft 365 admin center. It’s used to flag service messages which have been updated since the original publication. This is usually due when Microsoft needs to clarify the meaning of the text.

Many updates have multiple tags. For instance, MC264095 has the major update, feature update, and user impact tags.

Analyzing Service Update Tags

Using the Graph API for Service Communications, we can fetch the messages currently available in the Microsoft 365 admin center to see what tags are in use. As you’ll recall, this API spans both incidents (outages) reported in the admin center and service updates. I took the example script I created for service updates and used some of the code to pull all update messages into an array.

$Uri = "https://graph.microsoft.com/beta/admin/serviceAnnouncement/messages"
[array]$Messages = Get-GraphData -AccessToken $Token -Uri $uri

I then used some simple code to analyze the tags placed on each message.

$TagAdmin = 0; $TagUpdate = 0; $TagMajor = 0; $TagNew = 0; $TagRetirement = 0; $TagUser = 0; $TagUpdatedMessage = 0; $TagDataPrivacy = 0
ForEach ($Message in $Messages) {
    ForEach ($Tag in $Message.Tags) {
      Switch ($Tag) 
        {
        "Admin impact"    {$TagAdmin++}
        "Feature update"  {$TagUpdate++}
        "New feature"     {$TagNew++}
        "Retirement"      {$TagRetirement++}
        "User impact"     {$TagUser++}
        "Updated message" {$TagUpdatedMessage++}
        "Data privacy"    {$TagDataPrivacy++}
       } # End Switch
    }  # End Foreach tag
   If ($Message.IsMajorChange -eq $True) {$TagMajor++}
} # End ForEach message 
Write-Host "Admin impact messages:  " $TagAdmin
Write-Host "Feature update messages:" $TagUpdate
Write-Host "Major update messages:  " $TagMajor
Write-Host "New feature messages:   " $TagNew
Write-Host "Retirement messages:    " $TagRetirement
Write-Host "User impact messages:   " $TagUser
Write-Host "Updated messages:       " $TagUpdatedMessage
Write-Host "Data privacy messages:  " $TagDataPrivacy

Admin impact messages:   165
Feature update messages: 65
Major update messages:   76
New feature messages:    119
Retirement messages:     31
User impact messages:    191
Updated messages:        96
Data privacy messages    0

The total count of messages was 266. You can see that:

• The most popular tag is user impact (191) followed by admin impact (165).
• There’s a surprising number of retirement messages (31).
• Many updates are issued (96).

Your mileage might vary because Microsoft issues service updates to tenants based on the feature set licensed by the tenant.

What’s Changing

Microsoft is introducing a new Data Privacy tag to indicate messages which need administrator attention because they potentially impact sensitive data. The change is due to roll out by the end of July.

Microsoft says that messages might also contain one or more downloadable attachments (if multiple, the attachments are in a zip file) to help administrators “gain additional insight into the described scenario.” For instance, an attachment might be a PowerShell script to report data or users affected by a service update.

Only accounts holding the Global administrator and Privacy reader roles can access the downloadable attachments.

It’s hard to be certain about how Microsoft will use the new Data Privacy tag and what kind of service update messages they will tag. I guess we will see when some messages appear with the tag (none are found in the messages in my tenant) and the kind of attachments available for the messages.

So much change, all the time. It’s a challenge to stay abreast of all the updates Microsoft makes across Office 365. Subscribe to the Office 365 for IT Pros eBook to receive monthly insights into what’s happening.

Programmatic Access to Service Incidents

A reader asked if an easy way exists for programmatic access to information about Microsoft 365 incidents. To set context, several standard methods are available for tenant administrators to learn about an incident concerning a Microsoft 365 application. The Service Health dashboard in the Microsoft 365 admin center lists ongoing incidents and their status (Figure 1).

Incidents are also available through the Microsoft 365 admin mobile app (Figure 2). The app is available for iOS and Android.

Administrators can choose to receive notifications for incidents affecting their tenant in Outlook for Windows. Finally, nominated individuals can receive email about incidents (Figure 3) with the understanding that if problems can components which prevent email being sent. And sometimes email arrives to announce the end of an incident before you know that an incident happened. To configure the email addresses (up to 2) to receive notifications, access Preferences in the Service Health dashboard and choose the types of events and workloads you want to receive email about.

Microsoft targets communications about incidents to the affected tenants, but if you don’t want to rely on the standard methods, you can keep a close eye on Twitter accounts like Microsoft 365 status to get a heartbeat across the entire infrastructure.

ISV Monitoring

An alternative is to invest in third-party monitoring products, which usually deploy probes and other artificial transactions to establish what’s working well and where problems might be about to break. ISVs active in this space earn their bread by detecting problems before Microsoft makes formal announcements that an incident is active. They also concentrate on your organization and the workloads most important to your users.

DIY Service Monitoring

To return to the original question, programmatic access to the same information used by the Microsoft 365 admin center is available through the REST-based Office 365 Service Communications API. You can use this API to check for and display information about incidents in whatever interface you choose, such as a dashboard which includes Microsoft 365 and other services. The API supports access to historical status of incidents, current workload status, and messages, which include informational messages in addition to those about incidents.

Note: Microsoft will deprecate the Office 365 Service Communications API on December 17, 2021. You should transition your code to the Microsoft Graph Service Health and Communications API. See this article for details.

The basic approach used with Microsoft 365 REST-based APIs is followed (see this post for more information):

• Register an app with Azure AD. Note the app identifier and secret.
• Assign the permission to access service information to the app. This is the ServiceHealth.Read permission for the Office 365 Management APIs.
• Use the tenant identifier, app identifier, and app token to get an OAuth access token.
• Use the access token to authenticate the call to get service incidents.
• Parse and display the service incidents as required.

Here’s an example in PowerShell. At this point we assume that a suitable access token has been obtained and included in the $Headers variable. The commands retrieve the current messages and filter them for incidents with a status of “Service degradation.” We then loop through the incidents to find any with recent updates (within the last 30 minutes, as dictated by the $Minutes variable) and write out anything we find:

# Fetch information from Service Communications API
Write-Host "Fetching Microsoft 365 Message Center Notifications..."
$MessageCenterURI = "https://manage.office.com/api/v1.0/$($tenantid)/ServiceComms/Messages"
$ServiceData = (Invoke-RestMethod -Uri $MessageCenterURI -Headers $Headers -Method Get -ContentType "application/json") 
$ServiceData = $ServiceData.Value | ?{$_.MessageType -eq "Incident" -and $_.Status -eq "Service degradation"}

$Now = Get-Date
ForEach ($Incident in $ServiceData) {    
   $TimeSince = ($Now - ([datetime]$Incident.LastUpdatedTime)) 
   If ($TimeSince.TotalMinutes -le $Minutes) {  
      If ($Incident.EndTime -eq $Null) { $IncidentColor = "Red" }
      Else { $IncidentColor = "Yellow" } 
   $Title = "[" + $Incident.WorkloadDisplayName + "] " + $Incident.Title + " (" + $Incident.Severity + ")"
   Write-Host ""
   Write-Host "Microsoft 365 Incident" $Incident.Id
   Write-Host $Title -foregroundcolor $IncidentColor 
   Write-Host "Start time:       " (Get-Date $Incident.StartTime)
   Write-Host "Last Updated:     " (Get-Date $Incident.LastUpdatedTime)
   Write-Host "Current minutes:  " $TimeSince.TotalMinutes.ToString().Split(".")[0]
   Write-Host ""
   Write-Host "Incident Details"
   Write-Host "----------------"
   $Incident.Messages.MessageText
    } 
}

Figure 4 shows what the output looks like for an incident.

Obviously, there’s lots that you could do to refine and prettify the output to make it work the way you’d like it to look (here’s an example of how to post service incident information to a Teams channel). The same approach will work with any language which supports REST APIs.

Knowing the ins and outs of Office 365 administration includes understanding how to extend the basic functionality. We cover this kind of stuff in detail in the Office 365 for IT Pros eBook. Subscribe and stay up to date as things change.

Another Way for Tenant Administrators to Know When Incidents HappenI

MC211619 was one of the Office 365 notifications that passed me by without making much of an impression. Announced on June 16, it’s about a new right-hand notification panel in Outlook for Windows (click to run, aka Microsoft 365 enterprise apps). The panel appears when an incident happens that affects tenant users and the idea is that administrators get a heads-up before users start to complain that something isn’t working. The update is associated with Microsoft 365 roadmap item 58085.

One reason why I didn’t pay much attention to this change is that relatively few incidents have recently happened that affect my tenant. I guess I’ve been luck. Although incidents occur all the time inside Office 365, the sheer scale of the service and the way that tenants receive service from a network of datacenters mean that some tenants never notice problems while others experience issues.

The Outlook Notifications Panel Opens

Last night, Outlook (version 2006, build 13001.20384) opened the notification panel for the first time to display details of a problem with OneDrive. As you can see in Figure 1, notifications also include when problems are resolved. As it happens, the two incidents are related (navigation in the browser clients for SharePoint Online and OneDrive for Business). Clicking the See more link under a notification opens the Service health section of the Microsoft 365 admin center to display details of the problem.

I’m not sure how quickly Outlook removes notifications. The service health dashboard shows both problems as resolved at 9:37pm UTC on July 14 while the notifications remain visible some 36 hours later.

Outlook Help Includes Admin Notifications

The notification panel is designed to open automatically, which is what I saw. You can check for incidents at any time by going to Outlook’s help section (Figure 2).

Disabling Incident Notifications

If you don’t want to see incident notifications, you can disable their display in Outlook Options. Go to Advanced and scroll to the bottom to reveal the checkbox to disable incident notifications intended for administrators (Figure 3).

Outlook Build 2009 or later also includes the option to turn off notifications (Figure 4).

Microsoft doesn’t define what users Outlook considers to be an administrator. It seems like the panel is available to any account holding a role which allows them to access service health data, such as global administrators and global readers. This would make sense as these roles can access details of advisories and incidents in the Microsoft 365 admin center. I don’t believe that it works for accounts holding other roles like SharePoint administrator or Teams administrator.

Service Notifications by Email

You can configure service health dashboard preferences in the Microsoft 365 admin center to have incident notification sent by email to up to two users. Oddly, I didn’t receive notifications for the incidents flagged by Outlook, even though I’d chosen to receive emails for incidents and advisories related to SharePoint Online and OneDrive for Business. As I assume both Outlook and the admin center use the same service communications API to know when new incidents occur, it’s hard to explain why this happened. Maybe it’s just another small disconnect in the cloud.

Uncertain Need for the Feature

I’m unconvinced that a need existed for Outlook to surface incident reports to administrators. There’s already many ways to find out when problems exist, including the email mentioned above, using a third-party monitoring product, or building your own solution using the API. Besides, users let you know faster than any probe when things aren’t working, and your favorite social media feed will highlight problems when they are widespread across Office 365.

Overall, it seems like Outlook could focus on other areas of functionality like the top items in Outlook user voice instead of admin notifications, but hey, what would I know…

Need more information about how to run an Office 365 tenant? We have a few ideas in the Office 365 for IT Pros eBook…