Use Audit Events to Track Down Retention Label Assignments

A reader of my article about how to write a PowerShell script to report files and folders in a SharePoint Online document library observed that while the report details the retention labels assigned to items, it doesn’t say who assigned the labels. This is absolutely true, and it’s because SharePoint Online doesn’t note details of the last retention label assignment (date, user, etc.) in the information available through the Files Graph API. If the data isn’t available, it cannot be included in a report.

But retention label assignment is an auditable action. Details of assignments are captured by SharePoint Online and ingested into the unified audit log roughly 30 minutes after someone assigns a retention label to an item.

Searching for Retention Label Assignments

It’s easy to search the audit log for the logged events (the “TagApplied” operation is used here; the ComplianceSettingChanged could also be used) and report that information. Here’s some simple code to find the relevant audit events:

[array]$Records = Search-UnifiedAuditLog -Operations TagApplied -StartDate $StartDate -EndDate $EndDate -Formatted -SessionCommand ReturnLargeSet -ResultSize 5000

If ($Records.Count -eq 0) {
    Write-Output "No TagApplied events found in the last 30 days"
    Break
}   Else {
    # Get rid of duplicates
    $Records = $Records | Sort-Object Identity -Unique
    Write-Output ("Processing {0} retention label assignment events..." -f $Records.Count)
}

If the search is likely to return more than 5,000 events, it’s probably best to use the Graph AuditLogQuery API to perform an asynchronous search. Background searches can find hundreds of thousands of audit records if necessary.

The search finds assignment events when labels are applied manually by a user or automatically by an auto-label policy. In many careful scans of the audit log, I cannot find any events captured when files are uploaded to a document library and receive the default retention label configured for that library. The documentation says that events are triggered when retention labels are applied manually or automatically to a document but perhaps default retention labels are omitted.

Parsing the Audit Records

After finding relevant events, the next step is to remove any duplicates and sort the set by date.

$Records = $Records | Sort-Object Identity -Unique
$Records = $Records | Sort-Object {$_.CreationDate -as [datetime]} -Descending

The code then loops through the set to extract details and create a report. The name of the retention label and details of the file such as its name and host site and folder are in the AuditData structure, which must be converted from JSON to a PowerShell object to allow easy extraction of the properties.

The next issue is to find out who assigned the retention label. This is simple when users assign retention labels manually because the audit record stores the user principal name in the UserIds property. It’s less straightforward when auto-label policies are involved because the UserIds property contain the GUID of the retention policy rule that caused the label assignment to occur.

To translate the rule GUID back to a policy name, we need to find the GUID of the policy (because that’s how the rule links to its policy) and then extract the policy name. The code to resolve the rule GUID is not difficult, but it depends on being able to lookup the registered compliance policy rules and policies in the tenant. I use hash tables for this purpose and populate the tables with the Get-RetentionCompliancePolicy and Get-RetentionComplianceRule cmdlets.

Two GUIDs couldn’t be resolved by this method. I assume these represent background processes run by SharePoint Online to apply policies, so I declared the GUIDs in an array:

[array]$SharePointAutoLabelId = 'eba15bfd-c28e-4433-a20e-0278888c5825', 'a405a596-28e7-43c6-8ac7-76e0fc13ee0f'

If the GUIDs are found in audit records, the code reports them as “SharePoint Auto Label process.” One of the two GUIDs (‘eba15bfd-c28e-4433-a20e-0278888c5825’) is involved with the application of retention labels for document versions for cloudy attachments captured by a special policy, so I think it’s reasonable to assume that the other GUID represents some other form of background processing. Figure 1 shows some sample output.

You can download the full script from the Office 365 for IT Pros GitHub repository.

Chasing Default Retention Label Assignments

Although using the audit log to answer the question about who assigned retention labels to files is reasonably accurate, I’m unhappy to find that default retention label assignments aren’t audited. Or at least, I can’t find the right audit event to report. I’ve asked Microsoft about the issue and hopefully they can clarify what’s going on.

Need some assistance to write and manage PowerShell scripts for Microsoft 365? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.