Office 365 Groups, also known as Unified Groups, provide users with the ability to communicate via email, share files, and collaborate with tools such as OneNote, Teams and Planner.

Although administrators do have some controls that can be applied to the management of Groups, out of the box it is possible for end users to create, modify, and delete their own Groups. For organizations where that freedom is preferred, it’s still a good idea to keep an eye on the state of Groups in your tenant in case of misuse.

Get-O365GroupReport.ps1 is a PowerShell script for administrators to generate reports about the Groups in their Office 365 tenant. The script stores information about the Groups that were found in a tenant, and uses that information to determine which groups are new, modified, or deleted since the last report was generated.

get-o365groupreport-sample-report

To install the script:

  1. Download the latest release from the TechNet Script Gallery or from GitHub.
  2. Unzip the files to a folder on the workstation or server where you want to run the script.
  3. Rename Get-O365GroupReport.xml.sample to Get-O365GroupReport.xml
  4. Edit Get-O365GroupReport.xml with appropriate email settings for your environment. If you exclude the SMTP server, the script will send the report email to the first MX record for the domain of the To address.
  5. Run the script using the usage examples below.

You can customize the behavior of the script by editing settings in the Get-O365GroupReport.xml file.

  • HistoryItemsToKeep: defines the number of previous UnifiedGroups.xml files that will be preserved in the \history folder. The default is 10. History files might be useful to you for manual comparisons.
  • EmailOnlyIfChanges: defines whether to send the email report if there are no new, modified, or deleted groups detected. The default is 1, which means the email report will not send if there’s no changes. If you prefer to receive the report every time, change the value to 0.

This script can make use of the following functions:

By adding those functions to your PowerShell profile you can streamline the running of Get-O365GroupReport.ps1. Without those functions, you’ll need to run the script from an existing PowerShell session that is connected to Exchange Online, or you’ll be prompted for credentials to connect to Exchange Online.

Run the script in a PowerShell console.

.\Get-O365GroupReport.ps1

Run the script, using a stored credential to connect to Exchange Online.

.\Get-O365GroupReport.ps1 -UseCredential admin@tenantname.onmicrosoft.com

Run the script with verbose output.

.\Get-O365GroupReport.ps1 -Verbose

Run the script with manual SMTP settings that override the Get-O365GroupReport.xml configuration.

.\Get-O365GroupReport.ps1 -MailFrom reports@contoso.com -MailTo you@contoso.com -MailSubject "Your custom subject" -SmtpServer mail.contoso.com

Questions and feedback are welcome in the comments below. If you encounter a bug please let use know in the comments, or by raising an issue on GitHub.

About the Author

Chris Brown

Chris is a solution architect living in Melbourne, Australia, specializing in Office 365, Amazon/Microsoft public cloud, identity management, and security.

Comments

  1. Alex

    Caitlin has a reason. I havent received the email.

  2. Caitlin

    How long does this typically take to run? The command ran successfully but I haven’t received the email with the summary.

  3. Vinod

    As Usual one of the best script for O365 Group Inventory.
    Thanks a lot Paul.

Leave a Reply