Thumbnail Finding and fixing incorrectly applied Purview retention labels

Finding and fixing incorrectly applied Purview retention labels

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.

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.

Note: Using the SetComplianceTag method with the wrong parameters is NOT supported and the entire series of methods will therefore be deprecated by Microsoft in the near future.

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:

just-a-label

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:

just-a-label-applied

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!

Important: Steer clear of the SetComplianceTag methods if you can. If you really need to use this method, make sure you retrieve the correct values first!

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();

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
            }
        }
    }
}    
Note: To use this script successfully on your entire tenant you would have to sign in using an application identity. If you just use 'm365 login' with your own account it will only find items in the sites you have access to.

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.

Keep in mind: This command may influence the retention period of the labeled items when the 'labelled-date' is used to define the retention period.

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!


purview retention sharepoint cli-microsoft365
Support me by sharing this

More

More blogs

Working with Purview event-based retention using code
Working with Purview event-based retention using code

Do you want to retain data for a period of time after a certain event has happened? It is called event-based retention and this is how you use it from code.

Read more
Managing and applying Purview retention labels using code
Managing and applying Purview retention labels using code

An overview of the different ways you can manage and apply Microsoft 365 Purview retention labels in SharePoint using code.

Read more
Automating Purview data retention using Azure Functions
Automating Purview data retention using Azure Functions

An example of how to automatically apply Purview retention labels using Azure Functions.

Read more

Thanks

Thanks for reading

Thanks for reading my blog, I hope you got what you came for. Blogs of others have been super important during my work. This site is me returning the favor. If you read anything you do not understand because I failed to clarify it enough, please drop me a post using my socials or the contact form.


Warm regards,
Martin

Microsoft MVP | Microsoft 365 Architect

Microsoft MVP horizontal