Finding and fixing incorrectly applied Purview retention labels

Introduction

Microsoft 365 Purview allows you to create and publish retention labels that you can apply to data in SharePoint, OneDrive, Teams and Exchange. These labels ensure that data is retained for a required period of time. They define if content should be locked as a record in the meantime and if it should be deleted after the retention period has ended. This is especially useful for data that is not actively used, but still needs to be kept for legal or compliance reasons. In this blog post series I dive a little deeper into how to programmatically manage Purview retention labels and apply them to SharePoint content.

Series overview

• Part 1: Managing and applying Purview retention labels using code
• Part 2: Working with Purview event-based retention using code
• Part 3: Finding and fixing incorrectly applied Purview retention labels (this blog)
• Part 4: Implications of applying Purview retention labels to folders
• Part 5: Automating Purview data retention using Azure Functions

Table of contents

• Introduction
• How to mess up retention
• Discovering applied retention settings
• Finding and fixing incorrectly applied labels
• Conclusion

How to mess up retention

In the previous blog post I showed you how to apply retention labels to SharePoint content using code. I also showed you how to use the SetComplianceTag method in CSOM and the REST API to apply a retention label to a file. Using this method with the wrong parameters is NOT supported and the entire series of methods will therefore be deprecated by Microsoft in the near future. The reason for this is that the method allows to override the settings of the Purview label that’s being applied when using the wrong parameters. The only supported route to use the method is to first retrieve the Retention label, and to map the properties of the label when applying the label.

Read this blog post for a lengthier explanation of this.

If you do this wrong, you can end up in a big compliance mess. To demonstrate this I created a simple retention label with no record settings:

You see, just a label, nothing fancy. Next, I used it to label a file using the SetComplianceTag method, but I used all the wrong values, and this is what happened:

The file is now a record, even if the retention label is no record-type label. That is the reason you should steer clear of these methods if possible. If you really need to use this method, make sure you retrieve the correct values first!

Discovering applied retention settings

Fortunately, there is a way to check what retention settings where used when applying a label. You can use the ComplianceInfo property of a list item to see if the retention label is applied correctly. The ComplianceInfo property is available in the SharePoint REST API, and in CSOM:

Using the REST API, I can use the following URL:

https://contoso.sharepoint.com/sites/my-site/_api/web/lists('<some-guid>')/items(1)/ComplianceInfo

Using this URL, I can see the following result for my incorrectly applied retention label:

{
    odata.metadata: "https://contoso.sharepoint.com/sites/Sales/_api/$metadata#SP.ListItemComplianceInfo",
    ComplianceTag: "Just a label",
    TagPolicyEventBased: false,
    TagPolicyHold: true,
    TagPolicyRecord: true
}

As you can see the output contains almost every property that you can use on the SetComplianceTag method. The only property that’s missing is the TagSuperLock that would indicate that it is a regulatory record. But then again, this already gives us something to work with.

Using CSOM, I can get there as follows:

var list = clientContext.Web.GetListByTitle("Documents");
var listItem = list.GetItemById(1);
clientContext.Load(listItem, l => l.ComplianceInfo);
clientContext.ExecuteQuery();

Finding and fixing incorrectly applied labels

Now that we know how to check what retention settings where used, we can use this to find incorrectly applied labels. The following script uses the CLI for Microsoft 365 to get a list of Purview Retention Labels and searches the tenant to find items that label has been applied to. It then checks to see if the retention settings where correctly applied. If not, it will reapply the label.

# Get a list of labels from Purview
$labels = m365 purview retentionlabel list | ConvertFrom-Json

foreach ($label in $labels) {

    # Get a list of items across your tenant that have the label applied
    $labelledItems = m365 spo search --queryText 'ComplianceTag="$($label.displayName)"' --selectProperties "ListItemId,ListId,SPSiteUrl,Path" --allResults | ConvertFrom-Json

    Write-Host "Looking through $($labelledItems.Count) items..." -ForegroundColor Yellow

    if ($labelledItems.Count -gt 0) {

        # Get the label settings from the site of the first search result
        $siteLabel = @(m365 spo web retentionlabel list --webUrl $labelledItems[0].SPSiteUrl --query "[?TagName == '$($label.displayName)']" | ConvertFrom-Json)[0]         

        foreach ($item in $labelledItems) {

            # Get the retention settings from the ComplianceInfo property of the item
            $complianceInfo = m365 request --url "$($item.SPSiteUrl)/_api/web/lists(guid'$($item.ListId)')/items($($item.ListItemId))/ComplianceInfo" | ConvertFrom-Json

            # Compare the rention settings to the Purview label settings
            if ($complianceInfo.TagPolicyHold -ne $siteLabel.BlockDelete -or $complianceInfo.TagPolicyRecord -ne $siteLabel.BlockEdit) {
                Write-Host "Item is not labelled correctly: $($item.Path)" -ForegroundColor Red
                
                # Reapply the retention label on the item
                m365 spo listitem retentionlabel ensure --webUrl $item.SPSiteUrl --listId $item.ListId --listItemId $item.ListItemId --name $label.displayName
            }
        }
    }
}    

Important to note is that this command may influence the retention period of the labeled items. This would happen if your retention period has been configured to start based on the date the item was labelled. It’s essentially reapplying the label, and therefore restarting the retention period. This may not be desirable in your situation, so make sure you understand the implications of this script before you run it.

Also: this script might take a long time, as it’s quering every item that’s been labelled. But if you suspect that you have incorrectly applied labels, this is a good way to find them.

Conclusion

In this blog post I showed you how to find incorrectly applied retention labels. We saw how to use the ComplianceInfo property to check what retention settings where used when applying the label. I hope this helps you to keep your tenant in compliance!

Happy coding!

Sources

• CLI for Microsoft 365 - Getting started
• CLI for Microsoft 365 - listing purview retention labels
• CLI for Microsoft 365 - searching SharePoint
• CLI for Microsoft 365 - executing specific web requests
• CLI for Microsoft 365 - listing available retention labels on a site
• CLI for Microsoft 365 - applying retention labels