Configuring default Office 365 Labels using PowerShell

Office 365 Labels over Information Management Policies?

Office 365 labels are starting to get quite prolific across the stack now and I’m starting to see better uses for them over SharePoint Retention policies. If you’re not familiar with Office 365 labels, my MVP colleague Joanne Klein has a great blog post from last year that provides a great overview of the experience that you can read here. Whilst you still can’t trigger a retention off of a custom field with Labels, there’s still some value in using them for simple retention policies and for triggering DLP actions. As part of a DMS project that I’m working on, we needed to apply a default label to a number of libraries across SharePoint Online to ensure that content was automatically tagged with that label when uploaded or created.

This is quite simple through the UI by selecting the “Apply Label to items in this list or library” in the list settings. This displays the following dialogue that displays a list of all labels that have been published to that location. Whichever one is selected will automatically be applied to items created or uploaded to the library. You can also use the tick box to retrospectively apply the label to items that currently exist in the library, but be warned, this will automatically apply the label’s retention policy next time the timer job runs, and any items that are past retention will be removed!



There’s a few things that don’t quite work for me at this point for more advanced scenarios, the key one being the ability to choose a default label per content type for a start as it’s a much better way of attributing different retention policies across an information architecture and the second is of course the fact that labels can currently only trigger retention based on one of three dates, the Created Date, Modified Date and the Label Date (e.g. the date the label was applied).  I think we’re going to see a lot of development around this over the next 12 to 18 months however, so I don’t think we’re stuck with this for long!

Applying this through script

In my scenario though, the basic default label actually worked really well for a large number of libraries in the solution I was building.. and when I say large number, I’m talking around 2000 libraries, so you can imagine that we didn’t want to have to visit each of these libraries in turn to configure the policy. I did some investigation and had a discussion with a number of other MVPs and we all came to the same conclusion that whilst the option was there in the schema and available on the ListItem object, the equivalent List object property wasn’t exposed through CSOM to enable this to be configured by code.

I posted my woes onto the Microsoft Tech Community site and highlighted the post to a few people in the MS SharePoint world to see if I could get some comment. Mikael Svenson who had been looking at the issue with me also raised a User Voice (which is absolutely one of the best ways of getting Microsoft’s attention these days on requests for features!) and at that point I decided to return to the fall back approach of using an IE session controlled by PowerShell to screen scrape and re-create the clicks that a user would do, through script. Not my favourite approach, but it does work!

Whilst I was doing this though, Mikael sent me a message to say that there was a new release of the CSOM code and it included the ability to set this label through the List object. I took a look, and tested it and sure enough, setting this label became very easy indeed! So massive Kudos to Microsoft Engineering for turning this around so quickly.

To have a play with this, you’ll need the latest CSOM binaries (You really should be using NUGET to keep these up to date too!), you’ll need the version MIcrosoft.SharePointOnline.CSOM.16.1.7521.1200 at least and you’ll need to load the Microsoft.Office.Client.Policy.dll into your script.

Once you have a context object, you can get a list of the tags that are currently published to the site using:


This returns a collection of labels (Object ComplianceTag) that are available, if you have a reference to the Root Folder object of a library, you can query it to find out what the current label setting is:

$CurrentLabelApplied = [Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy]::GetListComplianceTag($SPOContext,$docLibRoot.ServerRelativeUrl)

This returns a single label object of type ComplianceTag.

To set the compliance tag on the library, you just need the TagName of the require ComplianceTag.

[Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy]::SetListComplianceTag($SPOContext,$docLibRoot.ServerRelativeUrl,"Default Label Tag Name",$false, $false,$false)

A nice simple command with a couple of arguments, the most of which are self explanatory, apart from the last three which relate to making the tag deletable or editable but also appear to have no effect at all. Unfortunately there’s no documentation just yet on these, but I’ll update this post as and when it appears.




Skip to comment form

    • Joris on Tue 5 Jun 18 at 4:24 pm
    • Reply

    Hi Paul, after looking into it for nearly 4hours I found your website.
    Nice to see there is a way to do this through powershell. I also need to do it
    for several sites (already on creation). The only thing is that I don’t get the reference
    set to the document library. Can you assist with a code snippet of this working for
    the document library?

    Will the command also check the box “Apply label to existing…”?

    1. Hi Joris,

      The reference to the Document library is gained just using either get-pnplist or the equivalent CSOM, they return the same thing.

      $DocLib = get-pnplist -identity “Documents”

      Then the root folder is simply

      $DocLibRoot = $DocLib.RootFolder

      As to the “apply to existing”, no the PowerShell currently doesn’t do that as far as I can see.

    • Dan Cecil on Mon 11 Jun 18 at 4:34 pm
    • Reply

    Great post, thanks for this. I found that when calling ‘SetComplianceTag’ the last three boolean parameters can be read from the compliance tag returned from one of the Get commands: $tag.BlockDelete, $tag.BlockEdit, $tag.IsEventTag

    You’re right though, it isn’t documented but this seemed to make sense to me, and it worked!

    1. Thanks for the Update Dan. I found out the first two, but the last “IsEventTag” I couldn’t see. Interestingly they still don’t appear to do anything, the Delete and Edit certainly don’t seem to do what they suggest.

      • Sam on Wed 3 Oct 18 at 10:15 am
      • Reply

      Thanks for the info. I can confirm that GetAvailableTagsForSite gives you the settings for those flags. So are you saying that that

      BlockDelete = isTagPolicyHold
      BlockEdit = isTagPolicyRecord
      IsEventTag = isEventBasedTag

      The last one is obvious but the other two, not so much. I would be much more comfortable just setting the label and letting the system figure out what policy and properties should be applied but it seems to be that those flags are required.

      The above flags are what is defined by the SetComplianceTag documentation at the time of writing.

      On a slightly unrelated note, does anyone know what the SetComplianceTagWithMetaInfo method does?

      1. Thanks Sam,

        It looks like they’ve updated the documentation, but there’s still no clear detail as to what those flags are for. As far as my testing went it didn’t seem to matter whether or not the label applied was a record policy or not.

    • jay on Wed 18 Jul 18 at 2:19 pm
    • Reply


    I use powershell all the time and I`m unfamiliar with CSOM – You have a tutorial on how exactly I download CSOM with nugget ect?


      That shows you how to use Nuget with PowerShell and the install package you need for CSOM can be found here:

    • Giuliano on Tue 5 Mar 19 at 5:00 pm
    • Reply

    Hi Paul,

    what kind of privileges are required? is the SharePoint Administrator required by using CSOM?

    1. Hi Giuliano,

      As far as I can see, you just need to be a site collection admin to be able to access the tag collection for the site collection. You shouldn’t need to be a SharePoint administrator (But I haven’t tested that as my account is an SP admin!). In fact in theory, you should only need permission to be able to edit the lists and libraries on the site as these people would be able to set the label drop down.


    • Ankush Jain on Thu 4 Apr 19 at 1:47 pm
    • Reply


    How can i apply label to a single listitem ?
    It is throuwing exception that “Invalid data has been used to update the list item. The field you are trying to update may be read only.”

    1. This technique only allows the library to be updated with the default label. Take a look at the Joanne Klein post that I’ve linked in other responses to use Rest to set this.

    • Damien Bird on Wed 22 May 19 at 12:26 pm
    • Reply

    Do you know if and how this can be applied to individual folders in a doc lib vs the whole doc lib?

    I.e. Shared Documents\
    Folder A (1 year Retention Label)
    Folder B (2 year)
    Folder C (5 year) etc…?

    Thanks in advance – Damien

    1. Sadly no, this can only be applied to the entire library. Location based labelling would be great, but I think we’re not likely to see that as the push from MS is for you to use AIP auto labelling.

    • MS on Wed 26 Jun 19 at 7:48 am
    • Reply


    Can you please advise on a way to be able to apply different tags to individual items in a library?

    1. Apologies for the late reply on this one! WordPress didn’t alert me to comments!

      This technique was all about setting the default setting for the library which you can now do in PowerShell using the PNP Cmdlets. – Sets the Label for the list or library (Basically it wraps up the Object Model calls I show above, into the PowerShel cmdlet..

      Unfortunately, I don’t believe there is one yet to set the compliance label on a single document, however Joanne Klein has an article on how to do it from flow, so you could do the same Rest call from PowerShell using invoke-RestRequest.

    • Taranjeet on Tue 24 Sep 19 at 11:13 am
    • Reply

    How can we set the retention label using PNP.JS or Rest API ?

    1. You can use the Rest API, I’m not sure about PNP.JS.. Take a look at Fellow MVP Joanne Kleins blog on doing this form Flow.

    • Evan Economopoulos on Sun 1 Mar 20 at 11:21 am
    • Reply

    hi Paul,

    I really wish Microsoft had clearer documentation on the setComplianceTag method….so the problem I have is I use the REST API 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 to assign it a different label as per the policy

    trouble is after waiting the 7 days the auto apply rule/policy didn’t apply its label..

    I think clearing the label in this manner is treated as an “explicit” assignment (even though there is no label?) and thus the auto apply didn’t do its thing thing its “implicit”

    do you think I would have any luck if I used setComplianceTagWithMeta instead (what is the difference exactly do you know?) or any other idea? Or perhaps I can query the KQL policy keyword query itself and assign go from there…



    1. I must admit my first thought is that it’s treating this as an implicit application of a label, much like a user removing a default applied label which would prevent the re-application of said label.

      As for the SetComplianceTagWithMeta, I’ve not used it, but I suspect the behaviour would be the same as the Implicit/Explicit rules are baked into the label engine itself.


    • Evan Economopoulos on Tue 3 Mar 20 at 1:50 pm
    • Reply

    thanks again Paul,
    thanks for the clarification, last question would you know anything about the SetComplianceTagWithExplicitMetasUpdate method either CSOM or REST API version which are the same…the ComplianceFlags parameter, I think it might be whats called the “Label Setting” if in your List you show that column.

    I noticed that “Label Setting” column has no value to start when a list item is first created in a list or doc lib, but when a label is applied it seems to get a value ranging from 0 to 3. Others have thought it my be an ENUM relating to the Explicit/Implicit but it all seems so cryptic and the Microsoft documentation is left wanting.

    Also using SetComplianceTageWithExplicitMetasUpdate might be problematic as one person thinks its an internal method not meant for use…what are your thoughts?

Leave a Reply

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.