(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
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!