From 2005779c8803a758640536689348f6ec257c5415 Mon Sep 17 00:00:00 2001 From: reshmee011 Date: Mon, 2 Oct 2023 22:57:07 +0100 Subject: [PATCH 1/3] Add new command get-pnpretentionlabel --- documentation/Get-PnPRetentionLabel.md | 50 ++++++++ .../Model/Graph/Purview/RetentionDuration.cs | 17 +++ .../Model/Graph/Purview/RetentionLabel.cs | 118 ++++++++++++++++++ src/Commands/Purview/GetRetentionLabel.cs | 25 ++++ 4 files changed, 210 insertions(+) create mode 100644 documentation/Get-PnPRetentionLabel.md create mode 100644 src/Commands/Model/Graph/Purview/RetentionDuration.cs create mode 100644 src/Commands/Model/Graph/Purview/RetentionLabel.cs create mode 100644 src/Commands/Purview/GetRetentionLabel.cs diff --git a/documentation/Get-PnPRetentionLabel.md b/documentation/Get-PnPRetentionLabel.md new file mode 100644 index 000000000..51f0da2a5 --- /dev/null +++ b/documentation/Get-PnPRetentionLabel.md @@ -0,0 +1,50 @@ +--- +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 [-Connection ] +``` + +## DESCRIPTION +This cmdlet allows retrieval of the available Microsoft Purview retention labels in the currently connected tenant. + +## EXAMPLES + +### EXAMPLE 1 +```powershell +Get-PnPRetentionLabel +``` + +Returns all the Microsoft Purview retention labels that exist on the tenant + +### -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) \ No newline at end of file diff --git a/src/Commands/Model/Graph/Purview/RetentionDuration.cs b/src/Commands/Model/Graph/Purview/RetentionDuration.cs new file mode 100644 index 000000000..86ac0c07b --- /dev/null +++ b/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 + { + /// + /// The type of the data. + /// + [JsonPropertyName("@odata.type")] + public string ODataType { get; set; } = "#microsoft.graph.security.retentionDurationInDays"; + /// + /// Number of days. + /// + public int days { get; set; } + } +} diff --git a/src/Commands/Model/Graph/Purview/RetentionLabel.cs b/src/Commands/Model/Graph/Purview/RetentionLabel.cs new file mode 100644 index 000000000..122a66d5e --- /dev/null +++ b/src/Commands/Model/Graph/Purview/RetentionLabel.cs @@ -0,0 +1,118 @@ +using System; +using System.Text.Json.Serialization; +/// +/// 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." +/// +/// +namespace PnP.PowerShell.Commands.Model.Graph.Purview +{ + public class RetentionLabel + { + /// + /// The label ID is a globally unique identifier (GUID). + /// + public string Id { get; set; } + + /// + /// The display name of the label. + /// + public string DisplayName { get; set; } + + /// + /// 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. + /// + public BehaviorDuringRetentionPeriod? BehaviorDuringRetentionPeriod { get; set; } + + /// + /// 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. + /// + public ActionAfterRetentionPeriod? ActionAfterRetentionPeriod { get; set; } + + /// + /// 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. + /// + public RetentionTrigger? RetentionTrigger { get; set; } + + /// + /// Retention duration information. Specifies the number of days to retain the content. + /// + [JsonPropertyName("retentionDuration")] + public RetentionDuration RetentionDuration { get; set; } + + /// + /// Indicates if the label is in use. + /// + public bool? IsInUse { get; set; } + + /// + /// Description for administrators. + /// + public string DescriptionForAdmins { get; set; } + + /// + /// Description for users. + /// + public string DescriptionForUsers { get; set; } + + /// + /// Information about the creator. + /// + [JsonPropertyName("createdBy")] + public IdentitySet CreatedBy { get; set; } + + /// + /// Date and time when the label was created. + /// + public DateTimeOffset CreatedDateTime { get; set; } + + /// + /// Information about the last modifier. + /// + [JsonPropertyName("lastModifiedBy")] + public IdentitySet LastModifiedBy { get; set; } + + /// + /// Date and time when the label was last modified. + /// + public DateTimeOffset LastModifiedDateTime { get; set; } + + /// + /// The label to be applied. Specifies the replacement label to be applied automatically after the retention period of the current label ends. + /// + public string LabelToBeApplied { get; set; } + + /// + /// Default record behavior.Specifies the locked or unlocked state of a record label when it is created.The possible values are: startLocked, startUnlocked, unknownFutureValue. + /// + 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 + } +} diff --git a/src/Commands/Purview/GetRetentionLabel.cs b/src/Commands/Purview/GetRetentionLabel.cs new file mode 100644 index 000000000..d5fe8b5e6 --- /dev/null +++ b/src/Commands/Purview/GetRetentionLabel.cs @@ -0,0 +1,25 @@ +using PnP.PowerShell.Commands.Base; +using PnP.PowerShell.Commands.Base.PipeBinds; +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))] + [OutputType(typeof(Model.Graph.Purview.RetentionLabel))] + public class GetAvailableRetentionLabel : PnPGraphCmdlet + { + protected override void ExecuteCmdlet() + { + string url; + + url = "/beta/security/labels/retentionLabels"; + + var labels = GraphHelper.GetResultCollectionAsync(Connection, url, AccessToken).GetAwaiter().GetResult(); + WriteObject(labels, true); + } + } +} \ No newline at end of file From df679d0a5f6dbd3f9512cebc538d8f0b7a5ac12d Mon Sep 17 00:00:00 2001 From: reshmee011 Date: Wed, 4 Oct 2023 10:47:24 +0100 Subject: [PATCH 2/3] Added the Identity parameter and graph permissions --- documentation/Get-PnPRetentionLabel.md | 27 +++++++++++++++++-- .../Model/Graph/Purview/RetentionDuration.cs | 2 +- src/Commands/Purview/GetRetentionLabel.cs | 18 ++++++++++--- src/Commands/Resources/GraphPermissions.json | 20 ++++++++++++++ 4 files changed, 61 insertions(+), 6 deletions(-) diff --git a/documentation/Get-PnPRetentionLabel.md b/documentation/Get-PnPRetentionLabel.md index 51f0da2a5..eaff541bc 100644 --- a/documentation/Get-PnPRetentionLabel.md +++ b/documentation/Get-PnPRetentionLabel.md @@ -15,11 +15,11 @@ Gets the Microsoft Purview retention labels that are within the tenant ## SYNTAX ```powershell -Get-PnPRetentionLabel [-Connection ] +Get-PnPRetentionLabel [-Identity ] [-Connection ] ``` ## DESCRIPTION -This cmdlet allows retrieval of the available Microsoft Purview retention labels in the currently connected tenant. +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 @@ -30,6 +30,29 @@ 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. diff --git a/src/Commands/Model/Graph/Purview/RetentionDuration.cs b/src/Commands/Model/Graph/Purview/RetentionDuration.cs index 86ac0c07b..e1d0f1d01 100644 --- a/src/Commands/Model/Graph/Purview/RetentionDuration.cs +++ b/src/Commands/Model/Graph/Purview/RetentionDuration.cs @@ -12,6 +12,6 @@ public class RetentionDuration /// /// Number of days. /// - public int days { get; set; } + public int Days { get; set; } } } diff --git a/src/Commands/Purview/GetRetentionLabel.cs b/src/Commands/Purview/GetRetentionLabel.cs index d5fe8b5e6..1a34a21fc 100644 --- a/src/Commands/Purview/GetRetentionLabel.cs +++ b/src/Commands/Purview/GetRetentionLabel.cs @@ -12,14 +12,26 @@ namespace PnP.PowerShell.Commands.Purview [OutputType(typeof(Model.Graph.Purview.RetentionLabel))] public class GetAvailableRetentionLabel : PnPGraphCmdlet { + [Parameter(Mandatory = false)] + public Guid Identity; + protected override void ExecuteCmdlet() { string url; - - url = "/beta/security/labels/retentionLabels"; - + url = "/beta/security/labels/retentionLabels"; + + if (ParameterSpecified(nameof(Identity))) + { + url += $"/{Identity}"; + + var labels = GraphHelper.GetAsync(Connection, url, AccessToken).GetAwaiter().GetResult(); + WriteObject(labels, false); + } + else + { var labels = GraphHelper.GetResultCollectionAsync(Connection, url, AccessToken).GetAwaiter().GetResult(); WriteObject(labels, true); + } } } } \ No newline at end of file diff --git a/src/Commands/Resources/GraphPermissions.json b/src/Commands/Resources/GraphPermissions.json index f50ce6fb3..b6d4bc1cf 100644 --- a/src/Commands/Resources/GraphPermissions.json +++ b/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", From 3c24d8a76fcf20d9e8f6fc4ec1901fbb1b77ed44 Mon Sep 17 00:00:00 2001 From: reshmee011 Date: Thu, 5 Oct 2023 09:22:21 +0100 Subject: [PATCH 3/3] Added [RequiredMinimalApiPermissions("RecordsManagement.Read.All")] attribute --- src/Commands/Purview/GetRetentionLabel.cs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/Commands/Purview/GetRetentionLabel.cs b/src/Commands/Purview/GetRetentionLabel.cs index 1a34a21fc..b712d56c9 100644 --- a/src/Commands/Purview/GetRetentionLabel.cs +++ b/src/Commands/Purview/GetRetentionLabel.cs @@ -1,5 +1,5 @@ -using PnP.PowerShell.Commands.Base; -using PnP.PowerShell.Commands.Base.PipeBinds; +using PnP.PowerShell.Commands.Attributes; +using PnP.PowerShell.Commands.Base; using PnP.PowerShell.Commands.Utilities.REST; using System; using System.Collections.Generic; @@ -10,6 +10,7 @@ namespace PnP.PowerShell.Commands.Purview [Cmdlet(VerbsCommon.Get, "PnPRetentionLabel")] [OutputType(typeof(IEnumerable))] [OutputType(typeof(Model.Graph.Purview.RetentionLabel))] + [RequiredMinimalApiPermissions("RecordsManagement.Read.All")] public class GetAvailableRetentionLabel : PnPGraphCmdlet { [Parameter(Mandatory = false)]