How to Retrieve Information About Microsoft 365 Service Incidents

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.