So you’ve created and published Retention Labels in Office 365 and now you want to apply labels by CSOM code. It’s not very well documented. The following (crude) code should help you get started applying labels to both individual items and to set as default for the whole library:
First some boilerplate initialization…
|
1 2 3 4 5 6 7 8 9 10 |
using Microsoft.SharePoint.Client.CompliancePolicy; ... var ctx = GetAppOnlyClientContext("https://mytenant.sharepoint.com/sites/myaswesomesite"); var rootWeb = ctx.Site.RootWeb; var list = rootWeb.Lists.GetByTitle("My List"); var listRootFolder = list.RootFolder; ctx.Load(rootWeb); ctx.Load(list); ctx.Load(listRootFolder); await ctx.ExecuteQueryAsync(); |
Get all labels available on the site:
|
1 2 3 4 5 6 7 8 |
var availableLabels = SPPolicyStoreProxy.GetAvailableTagsForSite(ctx, "https://mytenant.sharepoint.com/sites/myawesomesite"); await ctx.ExecuteQueryAsync(); Console.WriteLine("All available Retention Labels:"); foreach (var label in availableLabels) { Console.WriteLine("\t" + label.TagName); } |
Get the default label for a list:
|
1 2 3 4 5 6 |
var currentLabelApplied = SPPolicyStoreProxy.GetListComplianceTag(ctx, listRootFolder.ServerRelativeUrl); await ctx.ExecuteQueryAsync(); if(currentLabelApplied.Value != null) { Console.WriteLine("List Default Label: " + currentLabelApplied.Value.TagName); } |
Get labels for all items in a list:
|
1 2 3 4 5 6 7 |
for(var i=1; i<=list.ItemCount; i++) { var item = list.GetItemById(i); ctx.Load(item); await ctx.ExecuteQueryAsync(); Console.WriteLine($"Item '{item.FieldValues["Title"]}' has label '{item.FieldValues["_ComplianceTag"]}'"); } |
Write label to a list item:
|
1 2 3 4 5 6 |
var itemToLabel = list.GetItemById(1); ctx.Load(itemToLabel); await ctx.ExecuteQueryAsync(); itemToLabel.SetComplianceTag("My retention Label", false, false, false, false); itemToLabel.Update(); await ctx.ExecuteQueryAsync(); |
Set the default label for a list:
|
1 2 3 |
var applyToExistingItems = true; SPPolicyStoreProxy.SetListComplianceTag(ctx, listRootFolder.ServerRelativeUrl, "My Label", false, false, applyToExistingItems); await ctx.ExecuteQueryAsync(); |
SetComplianceTag and SetListComplianceTag have parameters (isTagPolicyHold, isTagPolicyRecord and isEventBasedTag) that are not documented what they actually do. Above I have set them to false. If you know what they do, please leave a comment!
hi Dan,
yes its frustrating, Microsoft’s documentation is severely lacking for those paramaters (isTagPolicyHold, isTagPolicyRecord etc…) I think they relate to if the item will be treated as an uneditable/undeletable “record” or not.
When I tested it I set those all to false.
question: so the problem I have is I use the REST API’ setComplianceTag() to clear a list item’s retention label (setting its value to “”), hoping that after/by 7 days hence it the auto-apply rules kick in (based on a keyword KQL query defined in the auto-apply policy)
but it seems like the auto apply doesn’t kick in in this scenario (I’ve waited more than 7 days). I would think clearing the retention label would negate any explicit precedence that the previous label would have had..that’s the only reason I could see it not auto applying the new label.
do you think if I used setCompliaceTagWithMeta() instead or if I set any of those parameters (isPolicyHold etc…) to true it would be any different?
any insight would be so greatly appreciated as I can’t afford to wait another 7 days to test it again
I’m afraid I don’t have any suggestions for you. I don’t see that you are doing anything wrong.
Hey. Interesting article. Thank. But I still do not understand if there is a tool how to create a new label and distribute it for certain sites or places?
You manage and distribute retention labels and policies in Office 365 Admin Center. It is quite difficult to grasp what to use and when though, so first read up on the different options. Microsoft’s documentation is a good start. I can also recommend Joanne C. Klein’s blog. She has written many good articles on this topic: https://joannecklein.com