«

May 16

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!

 

SNAGHTML51f9590

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:

[Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy]::GetAvailableTagsForSite($SPOContext,$SPOContext.Url)
$SPOContext.ExecuteQuery()

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)
$SPOContext.ExecuteQuery()

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)
$SPOContext.ExecuteQuery()

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.

 

Paul.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*