Back to blog

Guest Blog: Office 365 Health Monitoring with PowerShell

Feb 22, 2016 by contrib-mattmcnabb

Do you manage an Office 365 tenant? Would you like to script automatic email alerts so that you can be informed on any incident that is affecting your tenant in real-time?

If the answer is yes to both of these questions, then it is likely that you’ll be interested in a new module published to my PowerShell Gallery. The Office 365 Message Center currently lacks email alerting on incidents but using this module, you will be able to script this automatic alerting. This means you can stay informed on any incidents that affect your environment, and, ultimately, make your life easier, and your boss happy!

The O365ServiceCommunications module can be used to retrieve messages regarding your tenant health status, incident closure, and general information about planned downtime or new features. You could even drop the event data returned into a SQL database, and generate reports that track the health of your Office 365 tenant. Sounds useful? Here’s how to get started.

Before you begin:

This module uses the Office 365 Service Communications REST API and you’ll need to be a global administrator for your tenant, or a delegated partner administrator in order to authenticate to the service.

Installing the O365ServiceCommunications module

To get started with the O365ServiceCommunications module, first, you’ll need to install the module. If you have PowerShell version 5.0 or have updated version 4.0 with the latest features you can install the module using PowerShellGet by running this command:

Find-Module O365ServiceCommunications | Install-Module

If you don’t have PowerShellGet you can install the module by downloading directly from the Github project site. Click on “Download ZIP” and then once the download has completed, right-click the ZIP file and select “Unblock.” Now extract the contents of the ZIP archive to a directory in your PowerShell module path (e.g. %Program Files%\WindowsPowerShell\Modules).

Once the module is installed, you can make its commands available like this:
Import-Module O365ServiceCommunications

Authenticating

Before you can retrieve events from your tenant, you’ll need to sign in to the REST API. Create a credential object first:

$MyCred = Get-Credential

And then pass that credential to the New-SCSession command:

$MySession = New-SCSession -Credential $MyCred

Keep note, I assigned the output of the New-SCSession command to the $MySession variable, make sure you do this too – you’ll use this later when you make subsequent calls to the API to retrieve service events.

Getting service info

The next command you’ll want to take a look at is Get-SCServiceInfo. This command will return data about the services that are available in your tenant – in other words, information that may have service incidents or maintenance messages.

Get-SCServiceInfo -SCSession $MySession

Here you can see that the $MySession variable is passed in to the command. This sends along your authentication token to grant you access to the retrieve information from the REST API. Depending on the subscriptions you’ve purchased you’ll see something like this:

Office 365 Health Monitoring with PowerShell 1

Getting events

Get-SCEvent is the real core of the O365ServiceCommunications module. It retrieves information for service incidents, maintenance announcements, and general messages about things like new features or items of concern for supporting your tenant. These are the same messages that you can see by going to the Message Center in your Office 365 administrative portal. You can run this just like the previous command – just pass in the session object:

Get-SCEvent -SCSession $MySession
By default, this will return only information about incidents:

Office 365 Health Monitoring with PowerShell 2

To get other event types you can specify the -EventTypes parameter. This takes one or more of three arguments: Incident, Maintenance, and Message.

How to use it

I have included a sample script in version 1.1 of the O365ServiceCommunications module that demonstrates how to generate an email alert when there are current service incidents that affect your tenant. It gathers data about the events and builds HTML tables that are then added to the body of an email message to be sent out to recipients of your choice:

Office 365 Health Monitoring with PowerShell 3

This sample script should serve as a good jumping-off point for learning how to consume the data from this module.

For partners

If you’re a delegated partner administrator of an Office 365 tenant, you can use the partner equivalent commands: Get-SCTenantServiceInfo and Get-SCTenantEvent. In this case you’ll also need to specify the -Domains parameter with the domain name of the partner tenant you’d like to gather information for. You can still use the New-SCSession command to authenticate to the service first.

That covers getting started with the O365ServiceCommunications PowerShell module. I think this is a great addition to any Office 365 management tool, but give it a try and see for yourself!

My original post, as well as other content on PowerShell and DevOps, can be found here.