How to Report Team Archive and Restore Events

Let Administrators Know When Team Archive and Restore Events Happen

Earlier this week, I discussed the topic of archiving teams at the end of their lifecycle and the challenges which result if the archived teams include shared or private channels. The inevitable question which arises is how administrators can know when team owners (or administrators) archive teams. It’s a reasonable question because if administrators know what’s happening within a tenant, they can take proactive steps to head off potential issues when necessary.

Look Into the Audit Log

My normal go-to place for information about Microsoft 365 workloads is to look in the “unified” audit log to see if Teams captures audit records when someone archives or restores a team.

Teams captures audit records for archive and restore events, but it doesn’t create dedicated events for these operations. Instead, Teams captures events using the generic TeamSettingChanged operation, which is used for other actions such as updating the name of a team. Given the fundamental nature of archiving a team, it’s surprising that Teams doesn’t consider it important enough to create audit events using specific events for the two operations, like TeamArchive or TeamRestore.

Searching the audit log for TeamSettingChanged operations is simple. After finding the audit records, the next step is to extract the JSON payload from the AuditData property and then process the records for archive operations. To differentiate between team archive and restore actions, the audit events store values in the NewValue property. If it’s True, the audit record is for an archive action. If it’s False, the action restores a team. The code handles these conditions.

[array]$Records = (Search-UnifiedAuditLog -Operations TeamSettingChanged -StartDate $StartDate -EndDate $EndDate -ResultSize 5000)
ForEach ($Rec in $Records) {
      $AuditData = ConvertFrom-Json $Rec.Auditdata
      If ($AuditData.Name -eq "Team is archived") {  # It's an archival team setting record
        Switch ($AuditData.NewValue) {
         "False"  { $Action = "Restored team" }
         "True" { $Action = "Archived team" }
        } #end switch

Retrieve Channel Information

As described in the article, it’s important to know if an archived team includes private or shared channels, so we need some code to retrieve this information. The display name of the archived or restored team is in the audit record, so the Get-Team cmdlet can retrieve the team’s group identifier and Get-TeamChannel can then retrieve the channel data. For the purpose of the script, I am only interested in the count of the different types of channel, but it would be easy to output the channel names if required.

Write-Host "Checking channels for" $AuditData.TeamName
         $TeamId = (Get-Team -DisplayName $AuditData.TeamName).GroupId
         If ($TeamId) {
            [array]$TeamChannels = Get-TeamChannel -GroupId $TeamId
            [array]$StandardChannels = $TeamChannels | ? {$_.Membershiptype -eq "Standard"}
            [array]$SharedChannels = $TeamChannels | ? {$_.Membershiptype -eq "Shared"}
            [array]$PrivateChannels = $TeamChannels | ? {$_.Membershiptype -eq "Private"}
            $ChannelStatus = "OK" }
         Else {
            $ChannelStatus = "Team might be deleted" }

Output the Audit Data

Afterwards, it’s a matter of reporting the results of scanning the audit records and outputting the data. The script creates a CSV file and pipes the data to the Out-GridView cmdlet (Figure 1) to make it easy to browse the audit data.

The example code for the script I used to create the report is available from GitHub.

If you want to distribute the report in other ways, you could:

• Format the content in HTML and send it via email (see this article for details).
• Create the report in a SharePoint document library (the basics of how to do this is explained here; the scenario is a script running in a Azure Automation runbook but the technique of using PnP cmdlets is the same in “regular” PowerShell).
• Post the report to a Teams channel or post a link to it in a message card created in a Teams channel using the inbound webhook connector. See this article for more information.

Possible Improvements

It would be easier if Teams generated specific audit records whenever a team archive or restore action occurs, but at least the data is available when you go looking for it. Another improvement Microsoft could make is to include the group identifier in the audit record as this is needed to retrieve information about the team using cmdlets from the Teams or Microsoft Graph PowerShell SDK modules, or indeed with a Graph query. I’m not holding my breath that any changes will happen though!

---

Learn more about how the Office 365 applications really work on an ongoing basis by subscribing to the Office 365 for IT Pros eBook. Our monthly updates keep subscribers informed about what’s important across the Office 365 ecosystem.