Enhancement: Refactor the Set-PnPListItem commandlet to use the 'SetComplianceTagOnBulkItems' endpoint for applying retention labels

[martinlingstuyl]

The Set-PnPListItem commandlet currently uses the SetComplianceTag endpoint for applying Retention Labels.
However, this method will be deprecated in the near future. This is because of a concern on the boolean parameters that can be used with the endpoints. (See my blog for more information.

We should refactor this command to use the newer SetComplianceTagOnBulkItems endpoint. This endpoint does not have the same problems.

An extra reason to switch to using this endpoint is that this endpoint allows you to apply Unpublished retention labels. Which means you can have retention labels that are NOT visible to end users, but usable by automation, which is a real good scenario.

Implementation

This newer endpoint can be used through CSOM or the REST API. The endpoint can be called as follows:

POST <site_url>/_api/SP_CompliancePolicy_SPPolicyStoreProxy_SetComplianceTagOnBulkItems
Authorization: "Bearer <accessToken>"
Content-Type: "application/json"

{
    "listUrl": "<list_absolute_url>",
    "complianceTagValue": "Retain 10 years",
    "itemIds": [1,2,3,4,5]
}

or using CSOM:

using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.CompliancePolicy;

//...

var result = SPPolicyStoreProxy.SetComplianceTagOnBulkItems(clientContext, new[] { 1,2,3 }, "https://contoso.sharepoint.com/sites/sales/Lists/TestList", "Some Label");
clientContext.ExecuteQueryRetry();

The endpoint returns a 200 response with an "odata.null": true. If a list item cannot be found, it will be returned. The endpoint will also throw an error if the label cannot be found.

An important thing to note is that you'll need the absolute URL of the list, which means we might need to execute an HTTP request to get at it.

[gautamdsheth]

Hi @martinlingstuyl , just came across this page:

https://learn.microsoft.com/en-us/sharepoint/dev/apis/csom-methods-for-applying-retention-labels

Looks like it is available via CSOM now, but was not able to find a way , any idea about it ?

[martinlingstuyl]

Ah nice @gautamdsheth!! Totally missed that. It must have been right after I worked with it extensively. On what entity did you try it? I am currently on holidays. Will try it right after!

Have you tried with the CompliancePolicy namespace?

var policyStore = new SPPolicyStore(clientContext, web);  

[martinlingstuyl]

Found it, @gautamdsheth:

using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.CompliancePolicy;

//...

var result = SPPolicyStoreProxy.SetComplianceTagOnBulkItems(clientContext, new[] { 1,2,3 }, "https://contoso.sharepoint.com/sites/sales/Lists/TestList", "Some Label");
clientContext.ExecuteQueryRetry();

[gautamdsheth]

@martinlingstuyl - have merged the refactored code. Works fine at my end, will be available in tomorrow's nightly as well as next major version.

Let me know if you run into any issues :)

[martinlingstuyl]

Very nice @gautamdsheth!! 💖

[Lonewalker25]

@gautamdsheth , is there a way to do bulk date on all items in the library without specifying the item IDs?

Thanks!

[martinlingstuyl]

Bulk update the retention labels of an entire library, is that what you mean @Lonewalker25?

There is not, unless you would use default labels. Checkout my blog post on if you want to know more, there's also a section on default labels.

https://www.blimped.nl/managing-and-applying-purview-retention-labels-using-code/

However, be advised: using default labels may have license implications.

[Lonewalker25]

@martinlingstuyl
I did read your blog prior last post and found your blog is the only place that talked about this feature from extensive Google searches. So thank you again for that, really saving my day here. 😊

I do not know about the license implications but I'm sure I will once I run into it.

I read the blog again and I think this should be the section you referred to

POST <site_url>/_api/web/lists(guid'<list_guid>')/items(<item_id>)/SetComplianceTag()
Authorization: "Bearer <accessToken>"
Content-Type: "application/json"

{
    "complianceTag": "Retain 10 years",
    "isTagPolicyHold": true,
    "isTagPolicyRecord": true,
    "isEventBasedTag": false,
    "isTagSuperLock": false,
    "isUnlockedAsDefault": false
}

I use Power Automate to run this. I understand applying tags needs time. However, I am finding that this action is more of a hit-or-miss. I have a few test libraries in a site, I have witnessed this so far:

• A library with less than 5 items, can take up to 10mins to update
• A library with 30 items, takes up 2 mins to update
• Sometimes, all items in a library get updated to the new tag and at other times, only 90% of items are updated with new tags. (tried to run the flow multiple times)
  Although the first 2 issues do not bother me, the last one is a show-stopper. Do you have any idea why this is happening?
  

[martinlingstuyl]

Hi @Lonewalker25, In your answer you're referring to SetComplianceTag, but in the picture I see you're using the correct one: SP_CompliancePolicy_SPPolicyStoreProxy_SetListComplianceTag.

As far as I can see you're using it in the correct way. I haven't used the method extensively myself, but as far as I know I never ran into what your describing. The default label should be applied and synced. However, these are of course internal microsoft processes that we have no influence or control over. It might just be that some issues are holding them back.

I fear you'd need to contact Microsoft Support for that. it may be they can identity the issue and fix it on their side.

If you don't have the time to wait for Microsoft you could of course also automate it yourself using SetComplianceTagOnBulkItems. Maybe that's even the better road, depending on the scenario that you're automating.

Default labels are really only the good solution if you want to apply a retention label on the entire container, so that (while people are still working in a library) all new items will receive the retention label as well.

Another scenario would be that all the files in a library need to be archived and people will no longer work there. In that case I think I'd not use Default labels, but just automate it myself.