Merge pull request #4457 from reshmee011/unlockrecord

New cmdlet to update retention label on file

Author: KoenZomers

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)

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

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 <FilePipeBind> -RecordLocked <Boolean> [-Connection <PnPConnection>]
+```
+
+### Set a retention label on a file
+```powershell
+Set-PnPFileRetentionLabel -Identity <FilePipeBind> -RetentionLabel <String> [-Connection <PnPConnection>]
+```
+
+## 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)

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<FileRetentionLabel>(requestUrl, httpContent);
+                WriteObject(results, true);
+            }
+        }
+    }
+}