Using PowerShell to obtain your Tenants Office365 Health Dashboard


Obtaining the Office 365 Health Status via script has become a lot easier now with the release of the Office 365 Service Communications API. An overview of the Office 365 Service Communications API and the methods can be found on MSDN at the following URL: http://msdn.microsoft.com/en-us/library/office/dn776043(v=office.15).aspx

Because the API is a standard JSON based web api we can leverage in-built functionality in PowerShell 4.0 to convert our request to/from JSON and invoke the API. The PowerShell commands i'll be using in this blog article are the ConvertTo-JSON (for converting our request to JSON format) and the Invoke-RestMethod (for invoking the API itself).

First off, we need to obtain our credentials which we will use for the initial registration.

$cred = get-credential

We now need to obtain our authentication cookie by calling the Register method with our Office 365 username and password. The Register method will return a cookie which can be used to authenticate subsequent requests for up to 2 days. Each additional method will return an updated Cookie, which extends the life of the cookie for another 48 hours.

The Service URL as per the MSDN documentation is "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/". The Method that we are calling to obtain the cookie is the Register method.. To call this method, we add the method name to the URL, so that it is "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/Register". We then invoke the web request with our username and password in JSON format. The method will return several properties, one of which is our RegistrationCookie. We need to store this cookie for future API requests.

$jsonPayload = (@{userName=$cred.username;password=$cred.GetNetworkCredential().password;} | convertto-json).tostring()

$cookie = (invoke-restmethod -contenttype "application/json" -method Post -uri "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/Register" -body $jsonPayload).RegistrationCookie

The cookie above can be stored as an alternative in storing your username & password credentials. You can use the cookie to authenticate to the API for future requests without having to call the Register method again. The cookie is only valid for 48-hours, but a new cookie is provided every time a method is ran on the API, theoretically making it possible never to have to use the actual Office 365 credentials more than once.

Now comes the fun part, we can call any of the methods with our cookie and obtain information from the dashboard. For this example, i'm going to use the GetEvents method to show all current Office 365 events. This method has a preferredEventTypes parameter which allows us to select which type of events to return. In this example, i'm going to use both the event types 0 and 1, which are for Service Incidents and Maintenance Events.

$jsonPayload = (@{lastCookie=$cookie;locale="en-US";preferredEventTypes=@(0,1)} | convertto-json).tostring()
$events = (invoke-restmethod -contenttype "application/json" -method Post -uri "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/GetEvents" -body $jsonPayload)

Now, let's inspect what's returned..

The "LastCookie" is updated with a fresh new cookie which we can use for future authentication requests. It is valid for another 2 days. This is what we can use for theoretically never having to re-run the Register method as this cookie can be used for future authentication.

The "Events" is a property array of the events returned, lets inspect:

Here we have the main request. In here we have entries for the start and end time of the event, messages, and status and title of the event. The "AffectedServiceHealthStatus" is another property, which includes the effected service name for the event. Below is an example of one of the events returned:

As you can see, polling the API is relatively easy to achieve with in-built commands for web API's in PowerShell 4.0. For full documentation on the Service API, visit MSDN: http://msdn.microsoft.com/en-us/library/office/dn776043(v=office.15).aspx


Comments (20)

  1. Hi Duncan,

    The best way to look at this API is that it lists the current incidents, and those incidents have a service category. If there are no incidents for your category, then that particular service category could be considered healthy.

    I hope that makes sense.

  2. Very useful article. Thank you.

  3. Chen V says:

    Good Article. I installed Office 365 admin in my Windows mobile to check health status as and when required.

  4. Duncan Hepple says:

    Thanks for this. Am I right in thinking that if there isn’t a Service Incident or Maintenance Event within the past month for a particular service, then there will be no "AffectedServiceHealthStatus" field for that service? I’m trying to adapt your good
    work into a Python script that we can pull into Nagios – but I imagine that if Lync Online has no issues for a month then the "AffectedServiceHealthStatus" data for this Service will disappear until there is another incident?

    Wouldn’t it be good if there was a GetStatus task that could just give us the live status of each O365 service?

  5. Duncan Hepple says:

    This didn’t occur to me – thanks for your advice.

  6. Dns says:

    Hi,

    What does Status value in AffectedServiceHealthStatus means and what are the possible value?

    AffectedServiceHealthStatus : {@{InternalName=SharePoint; ServiceFeatureStatus=System.Object[]; ServiceName=SharePoint

    Online; Status=2}}

    I can not find any information about this in the API documentations….

  7. Duncan Hepple says:

    Hi DNS,

    I have come to the conclusion that the values are:

    5 is No Issues
    4 is Investigating
    3 is Extended Recovery
    2 is Restoring Service
    1 is Degraded

    I have found this out by checking the text description in the O365 Portal of recent service incidents.

    Cheers,

    Duncan

  8. lee says:

    Anyone have a script to create an alert if the services are something other than No issue?

  9. Akos says:

    Hi,

    Thanks for the article it was very useful.
    I have tried to reuse the cookie, but for some reason after two days, it does not valid any more and need to run the registration again. Is it something I am missing? Have you tried to reuse the cookie?

    Thanks,
    Akos

  10. Duncan Hepple says:

    Akos – I just get a new cookie every time. I run the registration and then the event/status pull as part of the same check (that runs every 5 minutes)

  11. Duncan Hepple says:

    So this appears to have broken? I’m not getting any "Exchange Online" or "SharePoint Online" alerts in this feed anymore. They don’t seem to have been renamed either..

    Cheers

  12. Akos – Every time you run a method, a new cookie is generated. That cookie is valid for another 48 hours. I suggest storing this cookie in a text file. So providing that you’re running a method atleast once every 48 hours, and storing and re-using the
    last cookie, you won’t need to re-authenticate.

  13. Lee McG says:

    Why dont Microsoft create more intuitive cmdlets for direct service status querying?

  14. Duncan Hepple says:

    Looks like the goal posts have moved with this method.. I’m not getting accurate statuses for services through this endpoint anymore (compared with O365 dashboard). Are we now supposed to be using this?
    https://msdn.microsoft.com/EN-US/library/office/dn707386.aspx

  15. Dr Sylvester Benson says:

    GET YOUR PROBLEM SOLVE TODAY WITH MY PROFESSION IN ANY SPIRITUAL SPELL OR ANY KIND OF PHYSICAL BATTLE THAT NEED, MY NAME IS DR SYLVESTER AND THIS IS MY EMAIL FOR CONTACT (stbenson391@gmail.com) OR YOU CAN FOLLOW HIM UP ON FACEBOOK BY MY NAME (SYLVESTER E BENSON)
    ON FACEBOOK OR CALL ME ON MY MOBILE NUMBER +2348136090988, AM ALWAYS AVAILABLE TO RENDER YOU HELP WITH EXPERIENCE OF 32 YEARS IN SPELL CASTING AND HERBAL MEDICURE TO CURE ANY KIND OF DISEASE THAT YOU MAY HAVE, CONTACT ME ON ANY KIND OF ISSUES.

  16. User_123 says:

    Hi,
    Can you please provide me with the steps after ‘$events.Events | get-member’ to fetch the service heath status.

  17. Duncan Hepple says:

    Try $events.Evens.AffectedServiceHealthStatus | select ServiceName, Status

    This would probably give you lots of duplicates, so you’d have to pipe it through something like "Get-Unique". We use a similar check in Bash and use the Linux binary "uniq" to strip the duplicates

  18. John says:

    Would it kill you to publish a working demonstration PowerShell script?

  19. Inn VNix Ginner says:

    Thanks for your contribution

  20. John says:

    For those struggling look here for a working example.
    https://gist.github.com/alexinnes/0b6983c75e30ea7f5e99

Skip to main content