diff --git a/CHANGELOG.md b/CHANGELOG.md index e2bdc67b8..ffe4cf70d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). - Added `Get-PnPFileRetentionLabel` cmdlet to fetch the file retention labels. [#4603](https://github.com/pnp/powershell/pull/4603) - Added `Get/Set/Remove-PnPUserProfilePhoto` cmdlets to download, upload or remove the profile photo of the specified user. - Added `New/Get/Remove/Update-PnPTodoList` cmdlets to manage Todo lists. +- Added `Set-PnPFileRetentionLabel` which allows setting a retention label on a file in SharePoint or locking/unlocking it. [#4457](https://github.com/pnp/powershell/pull/4457) - Added `Get-PnPFileCheckedOut` cmdlet to retrieve all files that are currently checked out in a library [#4682](https://github.com/pnp/powershell/pull/4682) - Added `Get-PnPTenantPronounsSetting` and `Set-PnPTenantPronounsSetting` cmdlets to manage the availability of using pronouns in the organization [#4660](https://github.com/pnp/powershell/pull/4660) - Added `HidePeopleWhoHaveListsOpen` parameter to `Set-PnPSite` cmdlet to hide people who simultaneously have lists open [#4699](https://github.com/pnp/powershell/pull/4699) diff --git a/documentation/Get-PnPFileRetentionLabel.md b/documentation/Get-PnPFileRetentionLabel.md index c4fbcef6a..e0f43f50e 100644 --- a/documentation/Get-PnPFileRetentionLabel.md +++ b/documentation/Get-PnPFileRetentionLabel.md @@ -35,8 +35,6 @@ This example retrieves the retention label information for the file at the speci Get-PnPFileRetentionLabel -Url "/sites/Marketing/Shared Documents/Report.pptx" ``` -This example retrieves the retention label information for the file at the specified URL. - ## PARAMETERS ### -Url diff --git a/documentation/Set-PnPFileRetentionLabel.md b/documentation/Set-PnPFileRetentionLabel.md new file mode 100644 index 000000000..4713e2368 --- /dev/null +++ b/documentation/Set-PnPFileRetentionLabel.md @@ -0,0 +1,106 @@ +--- +Module Name: PnP.PowerShell +schema: 2.0.0 +applicable: SharePoint Online +online version: https://pnp.github.io/powershell/cmdlets/Set-PnPFileRetentionLabel.html +external help file: PnP.PowerShell.dll-Help.xml +title: Set-PnPFileRetentionLabel +--- + +# Set-PnPFileRetentionLabel + +## SYNOPSIS + +**Required Permissions** + + * Microsoft Graph API : One of Files.Read.All, Sites.Read.All, Files.ReadWrite.All, Sites.ReadWrite.All + +Allows setting a retention label on a file in SharePoint or locking/unlocking it. + +## SYNTAX + +### Lock or unlock a file +```powershell +Set-PnPFileRetentionLabel -Identity -RecordLocked [-Connection ] +``` + +### Set a retention label on a file +```powershell +Set-PnPFileRetentionLabel -Identity -RetentionLabel [-Connection ] +``` + +## DESCRIPTION + +The Set-PnPFileRetentionLabel cmdlet updates the retention label information or locks/unlocks a file in SharePoint using Microsoft Graph. It takes a URL as input, decodes it, and specifically encodes the '+' character if it is part of the filename. + +## EXAMPLES + +### Example 1 +```powershell +Set-PnPFileRetentionLabel -Url "/sites/Marketing/Shared Documents/Report.pptx" -RecordLocked $true +``` + +This example locks the file at the specified URL. + +### Example 2 +```powershell +Set-PnPFileRetentionLabel -Identity "/sites/Marketing/Shared Documents/Report.pptx" -RetentionLabel "Finance" +``` + +This example updates the retention label information for the file at the specified URL. + +### Example 3 +```powershell +Set-PnPFileRetentionLabel -Identity "/sites/Marketing/Shared Documents/Report.pptx" -RetentionLabel "" +``` + +This example removes the retention label information from the file at the specified URL. + +## PARAMETERS + +### -Identity +Specifies the server relative URL, File instance, listitem instance or Id of the file for which to set the retention label information or change the locking state. + +```yaml +Type: FilePipeBind +Parameter Sets: (All) + +Required: True +Position: Named +Default value: None +Accept pipeline input: True +Accept wildcard characters: False +``` + +### -RecordLocked +Specifies whether to lock or unlock the file. If omitted, the file is not locked or unlocked. + +```yaml +Type: Boolean +Parameter Sets: Lock or unlock a file +Required: True +Position: Named +Default value: None +Accept pipeline input: True +Accept wildcard characters: False +``` + +### -RetentionLabel +Specifies the retention label to apply to the file. Provide an empty string or $null to remove the existing label. + +```yaml +Type: String +Parameter Sets: Set a retention label on a file +Required: True +Position: Named +Default value: None +Accept pipeline input: True +Accept wildcard characters: False +``` + +## RELATED LINKS + +[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp) +[Setting a retention label through Microsoft Graph](https://learn.microsoft.com/graph/api/driveitem-setretentionlabel) +[Removing a retention label through Microsoft Graph](https://learn.microsoft.com/graph/api/driveitem-removeretentionlabel) +[Locking or unlocking a file through Microsoft Graph](https://learn.microsoft.com/graph/api/driveitem-lockorunlockrecord) \ No newline at end of file diff --git a/src/Commands/Files/SetFileRetentionLabel.cs b/src/Commands/Files/SetFileRetentionLabel.cs new file mode 100644 index 000000000..7033898fe --- /dev/null +++ b/src/Commands/Files/SetFileRetentionLabel.cs @@ -0,0 +1,81 @@ +using Microsoft.SharePoint.Client; +using PnP.Framework.Utilities; +using PnP.PowerShell.Commands.Attributes; +using PnP.PowerShell.Commands.Base; +using PnP.PowerShell.Commands.Base.PipeBinds; +using PnP.PowerShell.Commands.Model.Graph.Purview; +using System; +using System.Management.Automation; +using System.Net.Http; +using System.Text; +using System.Text.Json; + +namespace PnP.PowerShell.Commands.Files +{ + [Cmdlet(VerbsCommon.Set, "PnPFileRetentionLabel", DefaultParameterSetName = ParameterSet_LOCKUNLOCK)] + [RequiredApiDelegatedOrApplicationPermissions("graph/Files.Read.All")] + [RequiredApiDelegatedOrApplicationPermissions("graph/Sites.Read.All")] + [RequiredApiDelegatedOrApplicationPermissions("graph/Files.ReadWrite.All")] + [RequiredApiDelegatedOrApplicationPermissions("graph/Sites.ReadWrite.All")] + [OutputType(typeof(FileRetentionLabel))] + public class SetFileRetentionLabel : PnPGraphCmdlet + { + private const string ParameterSet_LOCKUNLOCK = "Lock or unlock a file"; + private const string ParameterSet_SETLABEL = "Set a retention label on a file"; + + [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)] + public FilePipeBind Identity; + + [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SETLABEL)] + public string RetentionLabel = string.Empty; + + [Parameter(Mandatory = true, ParameterSetName = ParameterSet_LOCKUNLOCK)] + public bool? RecordLocked; + + protected override void ExecuteCmdlet() + { + var file = Identity.GetFile(ClientContext); + file.EnsureProperties(f => f.VroomDriveID, f => f.VroomItemID); + + var requestUrl = $"v1.0/drives/{file.VroomDriveID}/items/{file.VroomItemID}/retentionLabel"; + + object payload = null; + + switch(ParameterSetName) + { + case ParameterSet_LOCKUNLOCK: + payload = new + { + retentionSettings = new + { + isRecordLocked = RecordLocked + } + }; + break; + case ParameterSet_SETLABEL: + if (string.IsNullOrEmpty(RetentionLabel)) + { + WriteVerbose("Removing retention label"); + RequestHelper.Delete(requestUrl); + } + else + { + WriteVerbose($"Setting retention label to '{RetentionLabel}'"); + payload = new + { + name = RetentionLabel + }; + } + break; + } + + if (payload != null) + { + var jsonPayload = JsonSerializer.Serialize(payload); + var httpContent = new StringContent(jsonPayload, Encoding.UTF8, "application/json"); + var results = RequestHelper.Patch(requestUrl, httpContent); + WriteObject(results, true); + } + } + } +}