Add new command get-pnpretentionlabel (#3459)

* Add new command get-pnpretentionlabel

* Added the Identity parameter and graph permissions

* Added    [RequiredMinimalApiPermissions("RecordsManagement.Read.All")] attribute

---------

Co-authored-by: Gautam Sheth <[email protected]>

documentation/Get-PnPRetentionLabel.md

@@ -0,0 +1,73 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPRetentionLabel.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPRetentionLabel
+---
+
+# Get-PnPRetentionLabel
+
+## SYNOPSIS
+Gets the Microsoft Purview retention labels that are within the tenant
+
+## SYNTAX
+
+```powershell
+Get-PnPRetentionLabel [-Identity <Guid>] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+This cmdlet allows retrieval of the available Microsoft Purview retention labels in the currently connected tenant. You can retrieve all the labels or a specific label.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPRetentionLabel
+```
+
+Returns all the Microsoft Purview retention labels that exist on the tenant
+
+### EXAMPLE 3
+```powershell
+Get-PnPRetentionLabel -Identity 58f77809-9738-5080-90f1-gh7afeba2995
+```
+
+Returns a specific Microsoft Purview retention label by its id
+
+## PARAMETERS
+
+### -Identity
+The Id of the Microsoft Purview retention label to retrieve
+
+```yaml
+Type: Guid
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Connection
+Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+[Microsoft Graph documentation](https://learn.microsoft.com/graph/api/informationprotectionpolicy-list-labels)

src/Commands/Model/Graph/Purview/RetentionDuration.cs

@@ -0,0 +1,17 @@
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.Purview
+{
+    public class RetentionDuration
+    {
+        /// <summary>
+        /// The type of the data.
+        /// </summary>
+        [JsonPropertyName("@odata.type")]
+        public string ODataType { get; set; } = "#microsoft.graph.security.retentionDurationInDays";
+        /// <summary>
+        /// Number of days.
+        /// </summary>
+        public int Days { get; set; }
+    }
+}

src/Commands/Model/Graph/Purview/RetentionLabel.cs

@@ -0,0 +1,118 @@
+using System;
+using System.Text.Json.Serialization;
+/// <summary>
+/// Describes the retention label that details how to Represents how customers can manage their data, including whether and for how long to retain or delete it."
+/// </summary>
+/// <seealso cref="https://learn.microsoft.com/en-gb/graph/api/resources/security-retentionlabel"/>
+namespace PnP.PowerShell.Commands.Model.Graph.Purview
+{
+    public class RetentionLabel
+    {
+        /// <summary>
+        /// The label ID is a globally unique identifier (GUID).
+        /// </summary>
+        public string Id { get; set; }
+
+        /// <summary>
+        /// The display name of the label.
+        /// </summary>
+        public string DisplayName { get; set; }
+
+        /// <summary>
+        /// Behavior during the retention period. Specifies how the behavior of a document with this label should be during the retention period. The possible values are: doNotRetain, retain, retainAsRecord, retainAsRegulatoryRecord, unknownFutureValue.
+        /// </summary>
+        public BehaviorDuringRetentionPeriod? BehaviorDuringRetentionPeriod { get; set; }
+
+        /// <summary>
+        /// Action after the retention period.Specifies the action to take on a document with this label applied during the retention period. The possible values are: none, delete, startDispositionReview, unknownFutureValue.
+        /// </summary>
+        public ActionAfterRetentionPeriod? ActionAfterRetentionPeriod { get; set; }
+
+        /// <summary>
+        /// Retention trigger information. Specifies whether the retention duration is calculated from the content creation date, labeled date, or last modification date. The possible values are: dateLabeled, dateCreated, dateModified, dateOfEvent, unknownFutureValue.
+        /// </summary>
+        public RetentionTrigger?  RetentionTrigger { get; set; }
+
+        /// <summary>
+        /// Retention duration information. Specifies the number of days to retain the content.
+        /// </summary>
+        [JsonPropertyName("retentionDuration")]
+        public RetentionDuration RetentionDuration { get; set; }
+
+        /// <summary>
+        /// Indicates if the label is in use.
+        /// </summary>
+        public bool? IsInUse { get; set; }
+
+        /// <summary>
+        /// Description for administrators.
+        /// </summary>
+        public string DescriptionForAdmins { get; set; }
+
+        /// <summary>
+        /// Description for users.
+        /// </summary>
+        public string DescriptionForUsers { get; set; }
+
+        /// <summary>
+        /// Information about the creator.
+        /// </summary>
+        [JsonPropertyName("createdBy")]
+        public IdentitySet CreatedBy { get; set; }
+
+        /// <summary>
+        /// Date and time when the label was created.
+        /// </summary>
+        public DateTimeOffset CreatedDateTime { get; set; }
+
+        /// <summary>
+        /// Information about the last modifier.
+        /// </summary>
+        [JsonPropertyName("lastModifiedBy")]
+        public IdentitySet LastModifiedBy { get; set; }
+
+        /// <summary>
+        /// Date and time when the label was last modified.
+        /// </summary>
+        public DateTimeOffset LastModifiedDateTime { get; set; }
+
+        /// <summary>
+        /// The label to be applied. Specifies the replacement label to be applied automatically after the retention period of the current label ends.
+        /// </summary>
+        public string LabelToBeApplied { get; set; }
+
+        /// <summary>
+        /// Default record behavior.Specifies the locked or unlocked state of a record label when it is created.The possible values are: startLocked, startUnlocked, unknownFutureValue.
+        /// </summary>
+        public DefaultRecordBehavior DefaultRecordBehavior { get; set; }
+    }
+
+    public enum BehaviorDuringRetentionPeriod
+    {
+        DoNotRetain,
+        Retain,
+        RetainAsRecord,
+        RetainAsRegulatoryRecord
+    }
+
+    public enum ActionAfterRetentionPeriod
+    {
+        None,
+        Delete,
+        StartDispositionReview
+    }
+
+    public enum RetentionTrigger
+    {
+        DateLabeled,
+        DateCreated,
+        DateModified,
+        DateOfEvent
+    }
+
+    public enum DefaultRecordBehavior
+    {
+        StartLocked,
+        StartUnlocked
+    }
+}

src/Commands/Purview/GetRetentionLabel.cs

@@ -0,0 +1,38 @@
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Utilities.REST;
+using System;
+using System.Collections.Generic;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.Purview
+{
+    [Cmdlet(VerbsCommon.Get, "PnPRetentionLabel")]
+    [OutputType(typeof(IEnumerable<Model.Graph.Purview.RetentionLabel>))]
+    [OutputType(typeof(Model.Graph.Purview.RetentionLabel))]
+    [RequiredMinimalApiPermissions("RecordsManagement.Read.All")]
+    public class GetAvailableRetentionLabel : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public Guid Identity;
+
+        protected override void ExecuteCmdlet()
+        {
+            string url;
+            url = "/beta/security/labels/retentionLabels";
+
+            if (ParameterSpecified(nameof(Identity)))
+            {
+                url += $"/{Identity}";
+
+                var labels = GraphHelper.GetAsync<Model.Graph.Purview.RetentionLabel>(Connection, url, AccessToken).GetAwaiter().GetResult();
+                WriteObject(labels, false);
+            }
+            else
+            {
+                var labels = GraphHelper.GetResultCollectionAsync<Model.Graph.Purview.RetentionLabel>(Connection, url, AccessToken).GetAwaiter().GetResult();
+                WriteObject(labels, true);
+            }
+        }
+    }
+}

src/Commands/Resources/GraphPermissions.json

@@ -2740,6 +2740,26 @@
         "consentDisplayName": "Read user sensitivity labels and label policies.",
         "value": "InformationProtectionPolicy.Read"
       },
+      {
+        "adminConsentDescription": "Allows the application to read any data from Records Management, such as configuration, labels, and policies on behalf of the signed-in user.",
+        "adminConsentDisplayName": "Read Records Management configuration, labels, and policies.",
+        "id": "07f995eb-fc67-4522-ad66-2b8ca8ea3efd",
+        "isEnabled": true,
+        "isAdmin": false,
+        "consentDescription": "Allows the application to read any data from Records Management, such as configuration, labels, and policies on behalf of the signed-in user.",
+        "consentDisplayName": "Read Records Management configuration, labels, and policies.",
+        "value": "RecordsManagement.Read.All"
+      },
+      {
+        "adminConsentDescription": "Allows the application to create, update and delete any data from Records Management, such as configuration, labels, and policies on behalf of the signed-in user.",
+        "adminConsentDisplayName": "Read and write Records Management configuration, labels, and policies",
+        "id": "f2833d75-a4e6-40ab-86d4-6dfe73c97605",
+        "isEnabled": true,
+        "isAdmin": false,
+        "consentDescription": "Allows the application to create, update and delete any data from Records Management, such as configuration, labels, and policies on behalf of the signed-in user.",
+        "consentDisplayName": "Read and write Records Management configuration, labels, and policies.",
+        "value": "RecordsManagement.ReadWrite.All"
+      },
       {
         "adminConsentDescription": "Allows the app to manage hybrid identity service configuration by creating, viewing, updating and deleting on-premises published resources, on-premises agents and agent groups, on behalf of the signed-in user.",
         "adminConsentDisplayName": "Manage on-premises published resources",