[New-Commandlet Get-PnPDeletedFlow] to list all the deleted Power Automate flows (#4396)

Co-authored-by: Gautam Sheth <gautamdsheth@outlook.com>

Author: NishkalankBezawada

documentation/Get-PnPDeletedFlow.md

@@ -0,0 +1,107 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPDeletedFlow.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPDeletedFlow
+---
+  
+# Get-PnPDeletedFlow
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Azure: management.azure.com
+
+**Information**
+
+* To use this command, you must be a Global or Power Platform administrator.
+
+**Note**
+
+* A Power Automate flow is soft-deleted when:
+* It's a non-solution flow.
+* It's been deleted less than 21 days ago.
+
+Returns all soft-deleted Power Automate flows within an environment
+
+## SYNTAX
+
+### All (Default)
+```powershell
+Get-PnPDeletedFlow [-Environment <PowerAutomateEnvironmentPipeBind>] [-Connection <PnPConnection>] [-Verbose]
+```
+
+
+## DESCRIPTION
+This cmdlet returns Deleted Power Automate Flows meeting the specified criteria.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Get-PnPDeletedFlow
+```
+Returns all the deleted flows in the default Power Platform environment belonging to any user
+
+### Example 2
+```powershell
+Get-PnPPowerPlatformEnvironment -Identity "MyOrganization (default)" | Get-PnPDeletedFlow
+```
+Returns all the deleted  flows for a given Power Platform environment belonging to the any user
+
+
+## PARAMETERS
+
+### -Environment
+The name of the Power Platform environment or an Environment object to retrieve the available flows for.
+
+```yaml
+Type: PowerAutomateEnvironmentPipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: The default environment
+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)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+
+### -Verbose
+When provided, additional debug statements will be shown while executing the cmdlet.
+
+```yaml
+Type: SwitchParameter
+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)

src/Commands/Model/PowerPlatform/PowerAutomate/DeletedFlow.cs

@@ -0,0 +1,33 @@
+using System;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.PowerPlatform.PowerAutomate
+{
+    /// <summary>
+    /// Contains information on one Microsoft Power Automate Flow
+    /// </summary>
+    public class DeletedFlow
+    {
+        /// <summary>
+        /// Name of the Flow as its Flow GUID
+        /// </summary>
+        public string Name { get; set;}
+
+        /// <summary>
+        /// The friendly name of the Flow as can be seen through flow.microsoft.com
+        /// </summary>
+        public string DisplayName { get; set; }
+
+        /// <summary>
+        /// Date and time at which this Flow has last been modified
+        /// </summary>
+        public DateTime? LastModifiedTime { get; set; }
+
+        public DeletedFlow(string name, string displayName, DateTime? lastModifiedTime)
+        {
+            Name = name;
+            DisplayName = displayName;
+            LastModifiedTime = lastModifiedTime;
+        }
+    }
+}

src/Commands/PowerPlatform/PowerAutomate/GetDeletedFlow.cs

@@ -0,0 +1,62 @@
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Utilities.REST;
+using System;
+using System.Linq;
+using System.Management.Automation;
+using PnP.PowerShell.Commands.Enums;
+using PnP.PowerShell.Commands.Utilities;
+using PnP.PowerShell.Commands.Model.PowerPlatform.PowerAutomate;
+
+namespace PnP.PowerShell.Commands.PowerPlatform.PowerAutomate
+{
+    [Cmdlet(VerbsCommon.Get, "PnPDeletedFlow", DefaultParameterSetName = ParameterSet_ALL)]
+    public class GetDeletedFlow : PnPAzureManagementApiCmdlet
+    {
+        private const string ParameterSet_ALL = "All";
+
+        [Parameter(Mandatory = false, ValueFromPipeline = true, ParameterSetName = ParameterSet_ALL)]
+        public PowerPlatformEnvironmentPipeBind Environment;
+
+        protected override void ExecuteCmdlet()
+        {
+            string environmentName = null;
+            string baseUrl = PowerPlatformUtility.GetPowerAutomateEndpoint(Connection.AzureEnvironment);
+            if (ParameterSpecified(nameof(Environment)))
+            {
+                environmentName = Environment.GetName();
+
+                WriteVerbose($"Using environment as provided '{environmentName}'");
+            }
+            else
+            {
+                var environments = GraphHelper.GetResultCollection<Model.PowerPlatform.Environment.Environment>(this, Connection,  baseUrl + "/providers/Microsoft.ProcessSimple/environments?api-version=2016-11-01", AccessToken);
+                environmentName = environments.FirstOrDefault(e => e.Properties.IsDefault.HasValue && e.Properties.IsDefault == true)?.Name;
+
+                if(string.IsNullOrEmpty(environmentName))
+                {
+                    throw new Exception($"No default environment found, please pass in a specific environment name using the {nameof(Environment)} parameter");
+                }
+
+                WriteVerbose($"Using default environment as retrieved '{environmentName}'");
+            }
+
+
+            WriteVerbose($"Retrieving all Power Automate Flows within environment '{environmentName}'");
+
+            var flowUrl = $"{baseUrl}/providers/Microsoft.ProcessSimple/scopes/admin/environments/{environmentName}/v2/flows?api-version=2016-11-01&include=softDeletedFlows";
+            var results = GraphHelper.GetResultCollection<Model.PowerPlatform.PowerAutomate.Flow>(this, Connection, flowUrl, AccessToken);
+
+            var deletedFlowList = results
+                .Where(flow => flow.Properties.StateRaw == "Deleted")
+                .Select(flow => new Model.PowerPlatform.PowerAutomate.DeletedFlow(
+                    flow.Name,
+                    flow.Properties.DisplayName,
+                    flow.Properties.LastModifiedTime
+                ))
+                .ToList();
+            WriteObject(deletedFlowList, true);
+
+        }
+    }
+}