diff --git a/documentation/Get-PnPRetentionLabel.md b/documentation/Get-PnPRetentionLabel.md new file mode 100644 index 000000000..eaff541bc --- /dev/null +++ b/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 ] [-Connection ] +``` + +## 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) \ 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..e1d0f1d01 --- /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..b712d56c9 --- /dev/null +++ b/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))] + [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(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",