MS365HealthReport

• Overview
• Release Notes
• Requirements
• How to Get the Module
  • OPTION 1: Installing from PowerShell Gallery
  • OPTION 2: Download from GitHub
• Syntax
  • Parameter Set 1: Authenticate using Client Secret
  • Parameter Set 2: Authenticate using Client Certificate
  • Parameter Set 3: Authenticate using Client Certificate Thumbprint
• Parameters
• Usage Examples
  • Example 1: Getting the Open Issues Updated Within the Last 10 Days
  • Example 2: Getting All Exchange and SharePoint Issues Updated Since the Last Run
  • Example 3: Send Notification to a Teams Channel
• Screenshots

Overview

Retrieve the Microsoft 365 Service Health status and send the email report using Microsoft Graph API.

Important: As of December 17, 2021, Microsoft has deprecated the Office 365 Service Communications API, which caused the previous version of this module (v1.4.2) to stop working. This new version now uses only Microsoft Graph API. Please refer to the new set of required API permissions in the Requirements section.

Release Notes

Go to Release Notes.

Requirements

• A registered Azure AD (OAuth) App with the following settings:

  • Application Name: MS365HealthReport
  • API: Microsoft Graph
    • Permission Type: Application
    • Permission(s): Mail.Send, ServiceHealth.Read.All, ServiceMessage.Read.All, Teamwork.Migrate.All

  
  API Permissions

• Windows PowerShell 5.1 or PowerShell 7.1+ on a Windows or Linux host (not tested with PowerShell on macOS).

• The MSAL.PS PowerShell Module must be installed on the computer where you will be running this script. The minimum version required is 4.16.0.4.

• A valid mailbox used for sending the report. A shared mailbox (no license) is recommended.

How to Get the Module

Note: The PowerShell Gallery module is not being updated regularly. Go to OPTION 2: Installing from the Source instead.

OPTION 1: Installing from PowerShell Gallery

The most convenient way to get this module is by installing from PowerShell Gallery.

Install-Module MS365HealthReport

Or if you're deploying to Azure Automation, you can directly import from PowerShell gallery.

OPTION 2: Download from GitHub

• Download or Clone the code.
• Extract the downloaded zip and/or go to the code folder.
• Run the InstallMe.ps1 script.

Syntax

Parameter Set 1: Authenticate using Client Secret

New-MS365IncidentReport
-ClientID <guid>
-ClientSecret <string>
-TenantID <string>
[-OrganizationName <string>]
[-StartFromLastRun]
[-LastUpdatedTime <datetime>]
[-Workload <string[]>]
[-Status <string>]
[-SendEmail]
[-From <string>]
[-To <string[]>]
[-CC <string[]>]
[-Bcc <string[]>]
[-WriteReportToDisk <bool>]
[-Consolidate <bool>]
[<CommonParameters>]

Parameter Set 2: Authenticate using Client Certificate

New-MS365IncidentReport
-ClientID <guid>
-ClientCertificate <X509Certificate2>
-TenantID <string>
[-OrganizationName <string>]
[-StartFromLastRun]
[-LastUpdatedTime <datetime>]
[-Workload <string[]>]
[-Status <string>]
[-SendEmail]
[-From <string>]
[-To <string[]>]
[-CC <string[]>]
[-Bcc <string[]>]
[-WriteReportToDisk <bool>]
[-Consolidate <bool>]
[<CommonParameters>]

Parameter Set 3: Authenticate using Client Certificate Thumbprint

New-MS365IncidentReport
-ClientID <guid>
-ClientCertificateThumbprint <string>
-TenantID <string>
[-OrganizationName <string>]
[-StartFromLastRun]
[-LastUpdatedTime <datetime>]
[-Workload <string[]>]
[-Status <string>]
[-SendEmail]
[-From <string>]
[-To <string[]>]
[-CC <string[]>]
[-Bcc <string[]>]
[-WriteReportToDisk <bool>]
[-Consolidate <bool>]
[<CommonParameters>]

Parameters

Parameter	Notes
ClientID	This is the Client ID / Application ID of the registered Azure AD App.
ClientSecret	The client secret key associated with the registered Azure AD App.
ClientCertificate	If you uploaded a client certificate to the registered Azure AD App, you can use it instead of the client secret to authenticate. To use this, you need to get the X509Certificate2 object fromt certificate store. eg. $certificate = Get-Item Cert:\CurrentUser\My\<certificate>
ClientCertificateThumbprint	If you uploaded a client certificate to the registered Azure AD App, you can use it instead of the client secret to authenticate. To use this, you only need to specify the certificate thumbprint. The script will automatically get the certificate from the personal certificate store.
OrganizationName	The organization name you want to appear in the alerts/reports. This is not retrieved from Azure automatically to keep minimum API permissions.
StartFromLastRun	Using this, the module gets the last run time from the history file. Then, only the incidents that were updated after the retrieved timestamp is reported. This is not recommended to use if you're running the module in Azure Automation. History file - %userprofile%\<tenant>\runHistory.csv
LastUpdatedTime	Use this if you want to limit the period of the report to include only the incidents that were updated after this time. This parameter overrides the StartFromLastRun switch.
Workload	By default, all workloads are reported. If you want to limit the report to specific workloads only, specify the workload names here. NOTE: Workload names are case-sensitive. If you want to get all the list of exact workload names that are available in your tenant, use the Get-MS365HealthOverview -Token <access token> command included in this module, or view them using the Service Health dashboard on the Admin Centre.
Status	New in v2. Filters the query result based on status. Valid values are: Ongoing - for current open issues only. Closed - for returning only resolved issues. If you do not use this parameter, all (Ongoing and Closed) will be returned.
SendEmail	Use this switch parameter to indicate that you want to send the report by email.
From	This is the sender address. The mailbox must be valid. You can use a Shared Mailbox that has no license for this. Also, this is required if you enabled -SendEmail
To	This is the To recipient addresses. Required if you used -SendEmail.
Cc	This is the CC recipient addresses. This is optional.
Bcc	This is the CC recipient addresses. This is optional.
WriteReportToDisk	By default, the reports are saved to disk. If you don't want to save to disk, or if you're running this in Azure Automation, you can set this parameter to $false The default output folder is $($env:USERPROFILE)\$($ModuleInfo.Name)\$($TenantID).
Consolidate	Boolean parameter. If set to $true (default), the alerts are consolidated and sent in one email. If set to $false, each alert is sent separately.
SendTeams	Boolean parameter. If set $true, the notification will be sent to the Teams Webhook URL. The default value is $false As of version 2.1.5, the only Teams notification option is consolidated (default).
TeamsWebHookURL	The array of Teams Webhook URL to send the notification. Refer to Create Incoming Webhooks.

Usage Examples

Example 1: Getting the Open Issues Updated Within the Last 10 Days

This example gets all open issues updated within the last 10 days.

Import-Module MS365HealthReport
$reportSplat = @{
    OrganizationName = 'Organization Name Here'
    ClientID = 'Client ID here'
    ClientSecret = 'Client Secret here'
    TenantID = 'Tenant ID here'
    SendEmail = $true
    From = 'sender@domain.com'
    To = @('to@domain.com')
    LastUpdatedTime = (Get-Date).AddDays(-10)
    Status = 'Ongoing'
}

New-MS365IncidentReport @reportSplat

Example 2: Getting All Exchange and SharePoint Issues Updated Since the Last Run

This example gets the last run time from the history file and only return the updates after that time.

Each alert is sent separately because the Consolidate parameter is set to $false.

Import-Module MS365HealthReport

$reportSplat = @{
    OrganizationName = 'Organization Name Here'
    ClientID = 'Client ID here'
    ClientSecret = 'Client Secret here'
    TenantID = 'Tenant ID here'
    SendEmail = $true
    From = 'sender@domain.com'
    To = @('to@domain.com')
    StartFromLastRun = $true
    Workload = @('Exchange Online','SharePoint Online')
    Consolidate = $false
}

New-MS365IncidentReport @reportSplat

Example 3: Send Notification to a Teams Channel

Import-Module MS365HealthReport

$reportSplat = @{
    OrganizationName = 'Organization Name Here'
    ClientID = 'Client ID here'
    ClientSecret = 'Client Secret here'
    TenantID = 'Tenant ID here'
    StartFromLastRun = $true
    Workload = @('Exchange Online','SharePoint Online')
    SendTeams = $true
    TeamsWebHookURL = @('https://contoso.webhook.office.com/webhookb2/340e8862...')
}

New-MS365IncidentReport @reportSplat

Screenshots

Sample run