- Overview
- Release Notes
- Requirements
- How to Get the Module
- Syntax
- Parameters
- Usage Examples
- Screenshots
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.
Go to Release Notes.
-
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.
Note: The PowerShell Gallery module is not being updated regularly. Go to OPTION 2: Installing from the Source instead.
The most convenient way to get this module is by installing from PowerShell Gallery.
Install-Module MS365HealthReportOr if you're deploying to Azure Automation, you can directly import from PowerShell gallery.
- Download or Clone the code.
- Extract the downloaded zip and/or go to the code folder.
- Run the
InstallMe.ps1script.
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>]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>]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>]| 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 $falseThe 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 $falseAs 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. |
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 = '[email protected]'
To = @('[email protected]')
LastUpdatedTime = (Get-Date).AddDays(-10)
Status = 'Ongoing'
}
New-MS365IncidentReport @reportSplatThis 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 = '[email protected]'
To = @('[email protected]')
StartFromLastRun = $true
Workload = @('Exchange Online','SharePoint Online')
Consolidate = $false
}
New-MS365IncidentReport @reportSplatImport-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
Sample run
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent