Feature: Support linking of Enterprise Policy between Dataverse and A…

d365bap.tools/d365bap.tools.psd1

@@ -54,7 +54,10 @@
 		, 'Get-BapEnvironmentApplicationUser'
 
 		, 'Get-BapEnvironmentD365App'
+
+		, 'Get-BapEnvironmentLinkEnterprisePolicy'
 
+		, 'Get-BapEnvironmentSecurityRole'
 		, 'Get-BapEnvironmentSolution'
 
 		, 'Get-BapEnvironmentUser'
@@ -63,6 +66,7 @@
 
 		, 'Invoke-BapEnvironmentInstallD365App'
 
+		, 'Set-BapEnvironmentLinkEnterprisePolicy'
 		, 'Set-BapEnvironmentVirtualEntity'
 
 		, 'Update-BapEnvironmentVirtualEntityMetadata'

d365bap.tools/functions/Get-BapEnvironment.ps1

@@ -11,6 +11,8 @@
     .PARAMETER EnvironmentId
         The id of the environment that you want to work against
         
+        Default value is "*" - which translates into all available environments
+        
     .PARAMETER AsExcelOutput
         Instruct the cmdlet to output all details directly to an Excel file
         

d365bap.tools/functions/Get-BapEnvironmentLinkEnterprisePolicy.ps1

@@ -0,0 +1,109 @@
+
+<#
+    .SYNOPSIS
+        Get Enterprise Policy
+        
+    .DESCRIPTION
+        Get all registered Enterprise Policies from a Dataverse environment and its linked status
+        
+    .PARAMETER EnvironmentId
+        The id of the environment that you want to work against
+        
+    .PARAMETER AsExcelOutput
+        Instruct the cmdlet to output all details directly to an Excel file
+        
+        This makes it easier to deep dive into all the details returned from the API, and makes it possible for the user to persist the current state
+        
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentLinkEnterprisePolicy -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6
+        
+        This will get all Enterprise Policy informations from the Dataverse environment.
+        
+        Sample output:
+        PpacEnvId   : eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6
+        PpacEnvName : new-test
+        Type        : identity
+        policyId    : d3e06308-e287-42bb-ad6d-a588ef77d6e8
+        location    : europe
+        id          : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-01/providers/Microsoft.PowerPlatfor
+        m/enterprisePolicies/EnterprisePolicy-Dataverse
+        systemId    : /regions/europe/providers/Microsoft.PowerPlatform/enterprisePolicies/d3e06308-e287-42bb-ad6d-a588ef77d6e8
+        linkStatus  : Linked
+        
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentLinkEnterprisePolicy -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -AsExcelOutput
+        
+        This will get all Enterprise Policy informations from the Dataverse environment.
+        Will output all details into an Excel file, that will auto open on your machine.
+        
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Get-BapEnvironmentLinkEnterprisePolicy {
+    [CmdletBinding()]
+    [OutputType('System.Object[]')]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $EnvironmentId,
+
+        [switch] $AsExcelOutput
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $tokenBap = Get-AzAccessToken -ResourceUrl "https://service.powerapps.com/"
+        $headers = @{
+            "Authorization" = "Bearer $($tokenBap.Token)"
+        }
+    }
+
+    process {
+        $body = [PsCustomObject]@{
+            "SystemId" = $EnterprisePolicyResourceId
+        } | ConvertTo-Json
+
+        # 2019-10-01
+        $uriLinkEnterprisePolicy = "https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/environments/$EnvironmentId`?api-version=2024-05-01"
+
+        $resObj = Invoke-RestMethod -Method Get -Uri $uriLinkEnterprisePolicy -Headers $headers -Body $body -ContentType "application/json"
+
+        $resCol = @(
+            if ($null -ne $resObj.properties.enterprisePolicies) {
+                foreach ($prop in $resObj.properties.enterprisePolicies.psobject.Properties) {
+                    $enterprisePolicyObj = [ordered]@{
+                        PpacEnvId   = $envObj.PpacEnvId
+                        PpacEnvName = $envObj.PpacEnvName
+                        Type        = $prop.Name
+                    }
+
+                    foreach ($innerProp in $prop.Value.psobject.properties) {
+                        $enterprisePolicyObj."$($innerProp.Name)" = $innerProp.Value
+                    }
+
+                    ([PSCustomObject]$enterprisePolicyObj) | Select-PSFObject -TypeName "D365Bap.Tools.Environment.EnterprisePolicy"
+                }
+            }
+        )
+
+        if ($AsExcelOutput) {
+            $resCol | Export-Excel
+            return
+        }
+
+        $resCol
+    }
+
+    end {
+
+    }
+}

d365bap.tools/functions/Get-BapEnvironmentSecurityRole.ps1

@@ -0,0 +1,113 @@
+
+<#
+    .SYNOPSIS
+        Get Security Roles from environment
+        
+    .DESCRIPTION
+        Get Security Roles from the Dataverse environment
+        
+    .PARAMETER EnvironmentId
+        The id of the environment that you want to work against
+        
+    .PARAMETER Name
+        Name of the Security Role that you want to work against
+        
+        Supports wildcard search
+        
+        Default value is "*" - which translates into all available Security Roles
+        
+    .PARAMETER AsExcelOutput
+        Instruct the cmdlet to output all details directly to an Excel file
+        
+        This makes it easier to deep dive into all the details returned from the API, and makes it possible for the user to persist the current state
+        
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSecurityRole -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6
+        
+        This will list all Security Roles from the Dataverse environment.
+        
+        Sample output:
+        Id                                   Name                           ModifiedOn
+        --                                   ----                           ----------
+        5a8c8098-b933-eb11-a813-000d3a8e7ded (Deprecated) Marketing Realti… 03/02/2023 10.11.13
+        1cbf96a1-b933-eb11-a813-000d3a8e7ded (Deprecated) Marketing Realti… 03/02/2023 10.11.14
+        d364ba1c-1bfb-eb11-94f0-0022482381ee Accounts Payable Admin         17/08/2023 07.06.15
+        
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSecurityRole -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -Name "Environment*"
+        
+        This will list all Security Roles, which matches the "Environment*" pattern, from the Dataverse environment.
+        
+        Sample output:
+        Id                                   Name                           ModifiedOn
+        --                                   ----                           ----------
+        d58407f2-48d5-e711-a82c-000d3a37c848 Environment Maker              15/06/2024 21.12.56
+        
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSecurityRole -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -AsExcelOutput
+        
+        This will list all Security Roles from the Dataverse environment.
+        Will output all details into an Excel file, that will auto open on your machine.
+        
+    .NOTES
+        General notes
+#>
+function Get-BapEnvironmentSecurityRole {
+    [CmdletBinding()]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $EnvironmentId,
+
+        [string] $Name = "*",
+
+        [switch] $AsExcelOutput
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $baseUri = $envObj.LinkedMetaPpacEnvUri
+        $tokenWebApi = Get-AzAccessToken -ResourceUrl $baseUri
+        $headersWebApi = @{
+            "Authorization" = "Bearer $($tokenWebApi.Token)"
+        }
+    }
+
+    process {
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $resRoles = Invoke-RestMethod -Method Get -Uri $($baseUri + '/api/data/v9.2/roles') -Headers $headersWebApi
+
+        $resCol = @(
+            foreach ($roleObj in  $($resRoles.value | Sort-Object -Property name)) {
+                if (-not ($roleObj.Name -like $Name)) { continue }
+
+                $roleObj | Select-PSFObject -TypeName "D365Bap.Tools.Role" -ExcludeProperty "@odata.etag" -Property "roleid as Id", *
+            }
+        )
+
+        if (-not $IncludeAppIds) {
+            $resCol = $resCol | Where-Object applicationid -eq $null
+        }
+
+        if ($AsExcelOutput) {
+            $resCol | Export-Excel
+            return
+        }
+
+        $resCol
+    }
+
+    end {
+
+    }
+}

d365bap.tools/functions/Invoke-BapEnvironmentInstallD365App.ps1

@@ -72,6 +72,32 @@
         Succeeded 02/03/2024 13.42.07 02/03/2024 13.44.48                     5c80df7f-d89e-42bd-abeb-98e577ae49f4
         Succeeded 02/03/2024 13.42.09 02/03/2024 13.48.26                     6885e0f4-639f-4ebc-b21e-49ce5d5e920d
         
+    .EXAMPLE
+        PS C:\> $apps = @(Get-BapEnvironmentD365App -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -InstallState Installed -UpdatesOnly)
+        PS C:\> Invoke-BapEnvironmentInstallD365App -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -PackageId $apps.PackageId
+        
+        This will find all D365 Apps that has a pending update available.
+        It will gather the Ids into an array.
+        It will run the cmdlet and have it get the status of the installation progress until all D365 Apps have been fully installed.
+        
+        Sample output (Install initialized):
+        status  createdDateTime     lastActionDateTime  error statusMessage operationId
+        ------  ---------------     ------------------  ----- ------------- -----------
+        Running 02/03/2024 13.42.07 02/03/2024 13.42.16                     5c80df7f-d89e-42bd-abeb-98e577ae49f4
+        Running 02/03/2024 13.42.09 02/03/2024 13.42.12                     6885e0f4-639f-4ebc-b21e-49ce5d5e920d
+        
+        Sample output (Partly succeeded installation):
+        status    createdDateTime     lastActionDateTime  error statusMessage operationId
+        ------    ---------------     ------------------  ----- ------------- -----------
+        Succeeded 02/03/2024 13.42.07 02/03/2024 13.44.48                     5c80df7f-d89e-42bd-abeb-98e577ae49f4
+        Running   02/03/2024 13.42.09 02/03/2024 13.45.55                     6885e0f4-639f-4ebc-b21e-49ce5d5e920d
+        
+        Sample output (Completely succeeded installation):
+        status    createdDateTime     lastActionDateTime  error statusMessage operationId
+        ------    ---------------     ------------------  ----- ------------- -----------
+        Succeeded 02/03/2024 13.42.07 02/03/2024 13.44.48                     5c80df7f-d89e-42bd-abeb-98e577ae49f4
+        Succeeded 02/03/2024 13.42.09 02/03/2024 13.48.26                     6885e0f4-639f-4ebc-b21e-49ce5d5e920d
+        
     .NOTES
         Author: Mötz Jensen (@Splaxi)
 #>
@@ -111,6 +137,7 @@ function Invoke-BapEnvironmentInstallD365App {
 
         [System.Collections.Generic.List[System.Object]] $arrInstallStarted = @()
         [System.Collections.Generic.List[System.Object]] $arrStatus = @()
+        [System.Collections.Generic.List[System.Object]] $arrFailedStarts = @()
 
         $headersPowerApi."Content-Type" = "application/json;charset=utf-8"
 
@@ -124,11 +151,24 @@ function Invoke-BapEnvironmentInstallD365App {
             }
 
             $body = $appToBeInstalled | ConvertTo-Json
-            $resIntall = Invoke-RestMethod -Method Post -Uri "https://api.powerplatform.com/appmanagement/environments/$EnvironmentId/applicationPackages/$($appToBeInstalled.uniqueName)/install?api-version=2022-03-01-preview" -Headers $headersPowerApi -Body $body
 
-            $arrInstallStarted.Add($resIntall)
+            try {
+                $resIntall = Invoke-RestMethod -Method Post -Uri "https://api.powerplatform.com/appmanagement/environments/$EnvironmentId/applicationPackages/$($appToBeInstalled.uniqueName)/install?api-version=2022-03-01-preview" -Headers $headersPowerApi -Body $body
+
+                $arrInstallStarted.Add($resIntall)
+            }
+            catch {
+                $arrFailedStarts.Add($appToBeInstalled)
+            }
         }
 
+        if ($arrFailedStarts.Count -gt 0) {
+            $messageString = "The following packages <c='em'>failed to start</c>:"
+            Write-PSFMessage -Level Host -Message $messageString
+
+            $arrFailedStarts.ToArray()
+        }
+
         do {
             $tokenPowerApi = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com/"
             $headersPowerApi = @{

d365bap.tools/functions/Set-BapEnvironmentLinkEnterprisePolicy.ps1

@@ -0,0 +1,71 @@
+
+<#
+    .SYNOPSIS
+        Set the link between Dataverse and the Enterprise Policy
+        
+    .DESCRIPTION
+        To enable managed identity between Dataverse and Azure resources, you will need to work with the Enterprise Policy concept
+        
+        It needs to be linked, based on the SystemId of the Enterprise Policy (Azure) and the Dataverse environment (Id)
+        
+    .PARAMETER EnvironmentId
+        The id of the environment that you want to work against
+        
+    .PARAMETER EnterprisePolicyResourceId
+        The (system) id of the Enterprise Policy that you want to link to your Dataverse environment
+        
+    .EXAMPLE
+        PS C:\> Set-BapEnvironmentLinkEnterprisePolicy -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -EnterprisePolicyResourceId '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-01/providers/Microsoft.PowerPlatform/enterprisePolicies/EnterprisePolicy-Dataverse'
+        
+        This will link the Dataverse Environment to the Enterprise Policy.
+        The Environment is 'eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6'.
+        The EnterprisePolicy is '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-01/providers/Microsoft.PowerPlatform/enterprisePolicies/EnterprisePolicy-Dataverse'
+        
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Set-BapEnvironmentLinkEnterprisePolicy {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
+    [CmdletBinding()]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $EnvironmentId,
+
+        [parameter (mandatory = $true)]
+        [Alias('SystemId')]
+        [string] $EnterprisePolicyResourceId
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $tokenBap = Get-AzAccessToken -ResourceUrl "https://service.powerapps.com/"
+        $headers = @{
+            "Authorization" = "Bearer $($tokenBap.Token)"
+        }
+    }
+
+    process {
+        $body = [PsCustomObject]@{
+            "SystemId" = $EnterprisePolicyResourceId
+        } | ConvertTo-Json
+
+        # 2019-10-01
+        $uriLinkEnterprisePolicy = "https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/environments/$EnvironmentId/enterprisePolicies/Identity/link?api-version=2023-06-01"
+
+        Invoke-RestMethod -Method Post -Uri $uriLinkEnterprisePolicy -Headers $headers -Body $body -ContentType "application/json" > $null
+    }
+
+    end {
+
+    }
+}