From 30f1cc0ee68e97395835daa7ec9699d4293df986 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B6tz=20Jensen?= Date: Sun, 3 Mar 2024 09:48:15 +0100 Subject: [PATCH] Feature: Implement Confirm-BapEnvironmentIntegration.ps1 --- d365bap.tools/d365bap.tools.psd1 | 4 + .../Confirm-BapEnvironmentIntegration.ps1 | 88 +++++++++++++++++ ...onfirm-BapEnvironmentIntegration.Tests.ps1 | 49 ++++++++++ d365bap.tools/xml/d365bap.tools.Format.ps1xml | 40 ++++++++ docs/Confirm-BapEnvironmentIntegration.md | 94 +++++++++++++++++++ docs/Get-BapEnvironment.md | 1 + docs/Get-BapEnvironmentApplicationUser.md | 1 + docs/Get-BapEnvironmentD365App.md | 1 + 8 files changed, 278 insertions(+) create mode 100644 d365bap.tools/functions/Confirm-BapEnvironmentIntegration.ps1 create mode 100644 d365bap.tools/tests/functions/Confirm-BapEnvironmentIntegration.Tests.ps1 create mode 100644 docs/Confirm-BapEnvironmentIntegration.md diff --git a/d365bap.tools/d365bap.tools.psd1 b/d365bap.tools/d365bap.tools.psd1 index aeb86c8..ae9f86b 100644 --- a/d365bap.tools/d365bap.tools.psd1 +++ b/d365bap.tools/d365bap.tools.psd1 @@ -45,12 +45,16 @@ 'Compare-BapEnvironmentD365App' , 'Compare-BapEnvironmentUser' + , 'Confirm-BapEnvironmentIntegration' + , 'Get-BapEnvironment' , 'Get-BapEnvironmentApplicationUser' , 'Get-BapEnvironmentD365App' , 'Get-BapEnvironmentUser' + + , 'Get-BapEnvironmentVirtualEntity' , 'Invoke-BapEnvironmentInstallD365App' ) diff --git a/d365bap.tools/functions/Confirm-BapEnvironmentIntegration.ps1 b/d365bap.tools/functions/Confirm-BapEnvironmentIntegration.ps1 new file mode 100644 index 0000000..bed50e0 --- /dev/null +++ b/d365bap.tools/functions/Confirm-BapEnvironmentIntegration.ps1 @@ -0,0 +1,88 @@ + +<# + .SYNOPSIS + Test the integration status + + .DESCRIPTION + Invokes the validation of the PowerPlatform integration, from the Dataverse perspective + + If it returns an output, the Dataverse is fully connected to the D365FO environment + + .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:\> Confirm-BapEnvironmentIntegration -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 + + This will invoke the validation from the Dataverse environment. + It will only output details if the environment is fully connected and working. + + Sample output: + LinkedAppLcsEnvId LinkedAppLcsEnvUri IsUnifiedDatabase TenantId + ----------------- ------------------ ----------------- -------- + 0e52661c-0225-4621-b1b4-804712cf6d9a https://new-test.sandbox.operations.eu.dynamics.c… False 8ccb796b-37b… + + .EXAMPLE + PS C:\> Confirm-BapEnvironmentIntegration -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -AsExcelOutput + + This will invoke the validation from the Dataverse environment. + It will only output details if the environment is fully connected and working. + Will output all details into an Excel file, that will auto open on your machine. + + The excel file will be empty if the integration isn't working. + + .NOTES + Author: Mötz Jensen (@Splaxi) +#> +function Confirm-BapEnvironmentIntegration { + [CmdletBinding()] + 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: $EnvironmentId didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the Get-BapEnvironment 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 { + $resValidate = Invoke-RestMethod -Method Get -Uri $($baseUri + '/api/data/v9.2/RetrieveFinanceAndOperationsIntegrationDetails') -Headers $headersWebApi + + $temp = $resValidate | Select-PSFObject -TypeName "D365Bap.Tools.Environment.Integration" -ExcludeProperty "@odata.context" -Property "Id as LinkedAppLcsEnvId", + "Url as LinkedAppLcsEnvUri", + * + + if ($AsExcelOutput) { + $temp | Export-Excel + return + } + + $temp + } + + end { + + } +} \ No newline at end of file diff --git a/d365bap.tools/tests/functions/Confirm-BapEnvironmentIntegration.Tests.ps1 b/d365bap.tools/tests/functions/Confirm-BapEnvironmentIntegration.Tests.ps1 new file mode 100644 index 0000000..9f542b5 --- /dev/null +++ b/d365bap.tools/tests/functions/Confirm-BapEnvironmentIntegration.Tests.ps1 @@ -0,0 +1,49 @@ +Describe "Confirm-BapEnvironmentIntegration Unit Tests" -Tag "Unit" { + BeforeAll { + # Place here all things needed to prepare for the tests + } + AfterAll { + # Here is where all the cleanup tasks go + } + + Describe "Ensuring unchanged command signature" { + It "should have the expected parameter sets" { + (Get-Command Confirm-BapEnvironmentIntegration).ParameterSets.Name | Should -Be '__AllParameterSets' + } + + It 'Should have the expected parameter EnvironmentId' { + $parameter = (Get-Command Confirm-BapEnvironmentIntegration).Parameters['EnvironmentId'] + $parameter.Name | Should -Be 'EnvironmentId' + $parameter.ParameterType.ToString() | Should -Be System.String + $parameter.IsDynamic | Should -Be $False + $parameter.ParameterSets.Keys | Should -Be '__AllParameterSets' + $parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets' + $parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $True + $parameter.ParameterSets['__AllParameterSets'].Position | Should -Be 0 + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False + } + It 'Should have the expected parameter AsExcelOutput' { + $parameter = (Get-Command Confirm-BapEnvironmentIntegration).Parameters['AsExcelOutput'] + $parameter.Name | Should -Be 'AsExcelOutput' + $parameter.ParameterType.ToString() | Should -Be System.Management.Automation.SwitchParameter + $parameter.IsDynamic | Should -Be $False + $parameter.ParameterSets.Keys | Should -Be '__AllParameterSets' + $parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets' + $parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648 + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False + } + } + + Describe "Testing parameterset __AllParameterSets" { + <# + __AllParameterSets -EnvironmentId + __AllParameterSets -EnvironmentId -AsExcelOutput + #> + } + +} \ No newline at end of file diff --git a/d365bap.tools/xml/d365bap.tools.Format.ps1xml b/d365bap.tools/xml/d365bap.tools.Format.ps1xml index 4e79f9b..3e2630f 100644 --- a/d365bap.tools/xml/d365bap.tools.Format.ps1xml +++ b/d365bap.tools/xml/d365bap.tools.Format.ps1xml @@ -309,5 +309,45 @@ + + D365Bap.Tools.Environment.Integration + + D365Bap.Tools.Environment.Integration + + + + + 36 + + + 50 + + + 17 + + + 36 + + + + + + + LinkedAppLcsEnvId + + + LinkedAppLcsEnvUri + + + IsUnifiedDatabase + + + TenantId + + + + + + \ No newline at end of file diff --git a/docs/Confirm-BapEnvironmentIntegration.md b/docs/Confirm-BapEnvironmentIntegration.md new file mode 100644 index 0000000..42290a4 --- /dev/null +++ b/docs/Confirm-BapEnvironmentIntegration.md @@ -0,0 +1,94 @@ +--- +external help file: d365bap.tools-help.xml +Module Name: d365bap.tools +online version: +schema: 2.0.0 +--- + +# Confirm-BapEnvironmentIntegration + +## SYNOPSIS +Test the integration status + +## SYNTAX + +``` +Confirm-BapEnvironmentIntegration [-EnvironmentId] [-AsExcelOutput] [] +``` + +## DESCRIPTION +Invokes the validation of the PowerPlatform integration, from the Dataverse perspective + +If it returns an output, the Dataverse is fully connected to the D365FO environment + +## EXAMPLES + +### EXAMPLE 1 +``` +Confirm-BapEnvironmentIntegration -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 +``` + +This will invoke the validation from the Dataverse environment. +It will only output details if the environment is fully connected and working. + +Sample output: +LinkedAppLcsEnvId LinkedAppLcsEnvUri IsUnifiedDatabase TenantId +----------------- ------------------ ----------------- -------- +0e52661c-0225-4621-b1b4-804712cf6d9a https://new-test.sandbox.operations.eu.dynamics.c… False 8ccb796b-37b… + +### EXAMPLE 2 +``` +Confirm-BapEnvironmentIntegration -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -AsExcelOutput +``` + +This will invoke the validation from the Dataverse environment. +It will only output details if the environment is fully connected and working. +Will output all details into an Excel file, that will auto open on your machine. + +The excel file will be empty if the integration isn't working. + +## PARAMETERS + +### -EnvironmentId +The id of the environment that you want to work against + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -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 + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +Author: Mötz Jensen (@Splaxi) + +## RELATED LINKS diff --git a/docs/Get-BapEnvironment.md b/docs/Get-BapEnvironment.md index 85fb4a8..f9378e3 100644 --- a/docs/Get-BapEnvironment.md +++ b/docs/Get-BapEnvironment.md @@ -99,6 +99,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS +### System.Object[] ## NOTES Author: Mötz Jensen (@Splaxi) diff --git a/docs/Get-BapEnvironmentApplicationUser.md b/docs/Get-BapEnvironmentApplicationUser.md index e9eab88..30fff45 100644 --- a/docs/Get-BapEnvironmentApplicationUser.md +++ b/docs/Get-BapEnvironmentApplicationUser.md @@ -89,6 +89,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS +### System.Object[] ## NOTES Author: Mötz Jensen (@Splaxi) diff --git a/docs/Get-BapEnvironmentD365App.md b/docs/Get-BapEnvironmentD365App.md index 8cbcfc8..dd8d68a 100644 --- a/docs/Get-BapEnvironmentD365App.md +++ b/docs/Get-BapEnvironmentD365App.md @@ -246,6 +246,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS +### System.Object[] ## NOTES Author: Mötz Jensen (@Splaxi)