Scripted Application of Data Governance Labels
Published Sep 05 2018 02:26 PM 11K Views
Microsoft

(Today's post comes from Robin Meure in Microsoft Premier Field Engineering - many thanks!)

 

How to apply Office 365 labels programmatically/scripted to a document library

 ADGLabel.jpg

While we had the ability to make labels available to certain (or all) sites from the Office 365 Security & Compliance Center and then apply a specific label to a document library like in the UI (as can been seen in the screenshot above), there was no way to set a default label onto a document library for each site (at least not in a scripted or programmatic way :)

 

Since the release of the March 2018 CSOM package, an API has been exposed to make this happen.

In short, the following methods have been exposed:

 

  • public method Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy.GetListComplianceTag
  • public method Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy.SetListComplianceTag
  • public method Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy.SetListComplianceTagWithMetaInfo

 

Here is how we can call it from PowerShell:

[Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy]::SetListComplianceTag($web.Context,$listUrl,$nameOfPolicy,$false,$false,$false)

 

The parameters of the methods are the following:

SetListComplianceTag

(

Microsoft.SharePoint.Client.ClientRuntimeContext context,

string listUrl,

string complianceTagValue,

bool blockDelete,

bool blockEdit,

bool syncToItems

)

 

ListUrl

Use the RootFolder.ServerRelativeUrl property of the List object to fetch this.

ComplianceTagValue

The title of the Label you want to apply on the document library

BlockDelete

Blocks the ability to delete the document

BlockEdit

Blocks the ability to edit the document

SyncToItems

Apply label to existing items in the library.

 

Next is a snippet to apply a label to a default library by either using the SharePointPnPPowerShellOnline module which can be found at PnP PowerShell repository or just 'vanilla' PowerShell CSOM. The most important thing is to remember that we need the right version of the CSOM library to be loaded. By default the PnPPowerShell, when being updated of course, will have the latest CSOM assemblies (as opposed to the SharePoint Online Management Shell).

 

############# Variables to be replaced ###############

#url of the web you want to apply the label on

$url = "https://tenant.sharepoint.com"

 

#name of the document library you want to apply the label on

$listName = "Documents"

 

#credentials being used to connect to the web

$credentials = Get-Credential

 

#title of the label you want to apply

#(it actually requires the title of the policy, as opposed to a Id/GUID..)

$nameOfPolicy ="Project documentation"

 

############# /Variables to be replaced ###############

 

############# PnP ###############

Connect-PnPOnline -Url $url

$web = Get-PnPWeb

$context = $web.Context

$list = Get-PnpList -Identity $listName -Web $web

############# /PnP ###############

 

############# Vanilla CSOM ###############

# Need at least 16.1.7521.1200 (March 2018 CSOM)

# Download the CSOM assemblies from https://www.nuget.org/packages/Microsoft.SharePointOnline.CSOM

Add-Type -Path "C:\Program Files\WindowsPowerShell\Modules\SharePointPnPPowerShellOnline\Microsoft.SharePoint.Client.dll"

Add-Type -Path "C:\Program Files\WindowsPowerShell\Modules\SharePointPnPPowerShellOnline\Microsoft.SharePoint.Client.Runtime.dll"

Add-Type -Path "C:\Program Files\WindowsPowerShell\Modules\SharePointPnPPowerShellOnline\Microsoft.Office.Client.Policy.dll"

 

$context = New-Object Microsoft.SharePoint.Client.ClientContext($url)

$context.Credentials =  New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($credentials.UserName, $credentials.Password)

$list = $context.Web.Lists.GetByTitle($listName)

$context.Load($list)

$context.Load($list.RootFolder)

$context.ExecuteQuery()

############# /Vanilla CSOM ###############

 

############ Main part of the script ############

 

# To get the Url of the list, we're fetching the RootFolder which contains the ServerRelativeUrl property

$listUrl = $list.RootFolder.ServerRelativeUrl

 

# Calling the method to SET the tag

[Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy]::SetListComplianceTag($context,$listUrl,$nameOfPolicy,$false,$false,$false)

 

#Call the executequery method on the Context to apply the change

$context.ExecuteQuery()

 

############ /Main part of the script ############

 

There you go!

2 Comments
Iron Contributor

This is great! When can we expect official documentation on docs.microsoft.com on this namespace? An article like this is great, but official documentation even better ;)

Deleted
Not applicable

Unfortunately, after coding an enterprise solution around this beware that it doesn't work. Using this API method has resulted in documents not appearing in the Disposition UI. Support call with Microsoft comment was that the Project Team have specifically said not to use this API and to only use the UI. When challenged I was told that UI wasn't cool for an enterprise and we wanted to set it for the users (i.e. via the API) they were definitive to not use the API and closed the call. Automation through headless scripting is perhaps my next step.

Version history
Last update:
‎Sep 05 2018 02:26 PM
Updated by: