From e0081293681f5041024098f7f6cab61fcf659eaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B6tz=20Jensen?= Date: Wed, 1 Jul 2020 11:59:47 +0200 Subject: [PATCH] Feature: Add support for search of data entities --- d365ce.integrations/d365ce.integrations.psd1 | 1 + .../functions/get-d365ceodataentity.ps1 | 227 ++++++++++++++ .../functions/Get-D365CeODataEntity.Tests.ps1 | 172 +++++++++++ docs/Add-D365CeODataConfig.md | 3 +- docs/Enable-D365CeException.md | 3 +- docs/Get-D365CeActiveODataConfig.md | 3 +- docs/Get-D365CeODataConfig.md | 3 +- docs/Get-D365CeODataEntity.md | 288 ++++++++++++++++++ docs/Get-D365CeODataEntityData.md | 3 +- docs/Get-D365CeODataEntityDataByKey.md | 3 +- docs/Import-D365CeODataEntity.md | 3 +- docs/Import-D365CeODataEntityBatchMode.md | 3 +- docs/Remove-D365CeODataEntity.md | 3 +- docs/Set-D365CeActiveODataConfig.md | 3 +- docs/Update-D365CeODataEntity.md | 3 +- 15 files changed, 699 insertions(+), 22 deletions(-) create mode 100644 d365ce.integrations/functions/get-d365ceodataentity.ps1 create mode 100644 d365ce.integrations/tests/functions/Get-D365CeODataEntity.Tests.ps1 create mode 100644 docs/Get-D365CeODataEntity.md diff --git a/d365ce.integrations/d365ce.integrations.psd1 b/d365ce.integrations/d365ce.integrations.psd1 index c1c3186..6df3e49 100644 --- a/d365ce.integrations/d365ce.integrations.psd1 +++ b/d365ce.integrations/d365ce.integrations.psd1 @@ -47,6 +47,7 @@ , 'Get-D365CeActiveODataConfig' , 'Get-D365CeODataConfig' + , 'Get-D365CeODataEntity' , 'Get-D365CeODataEntityData' , 'Get-D365CeODataEntityDataByKey' diff --git a/d365ce.integrations/functions/get-d365ceodataentity.ps1 b/d365ce.integrations/functions/get-d365ceodataentity.ps1 new file mode 100644 index 0000000..2653222 --- /dev/null +++ b/d365ce.integrations/functions/get-d365ceodataentity.ps1 @@ -0,0 +1,227 @@ + +<# + .SYNOPSIS + Get public OData Data Entity and their metadata + + + .DESCRIPTION + Get a list with all the available OData Data Entities,and their metadata, that are exposed through the OData endpoint of the Dynamics 365 Customer Engagement instance + + The cmdlet will search across the singular names for the Data Entities and across the collection names (plural) + + .PARAMETER EntityName + Name of the Data Entity you are searching for + + The parameter is Case Insensitive, to make it easier for the user to locate the correct Data Entity + + .PARAMETER EntityNameContains + Name of the Data Entity you are searching for, but instructing the cmdlet to use search logic + + Using this parameter enables you to supply only a portion of the name for the entity you are looking for, and still a valid result back + + The parameter is Case Insensitive, to make it easier for the user to locate the correct Data Entity + + .PARAMETER ODataQuery + Valid OData query string that you want to pass onto the D365 OData endpoint while retrieving data + + Important note: + If you are using -EntityName along with the -ODataQuery, you need to understand that the "$filter" query is already started. Then you need to start with -ODataQuery ' and XYZ eq XYZ', e.g. -ODataQuery ' and IsReadOnly eq false' + If you are using the -ODataQuery alone, you need to start the OData Query string correctly. -ODataQuery '$filter=IsReadOnly eq false' + + OData specific query options are: + $filter + $expand + $select + $orderby + $top + $skip + + Each option has different characteristics, which is well documented at: http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html + + .PARAMETER Tenant + Azure Active Directory (AAD) tenant id (Guid) that the D365CE environment is connected to, that you want to access through OData + + .PARAMETER Url + URL / URI for the D365CE environment you want to access through OData + + .PARAMETER ClientId + The ClientId obtained from the Azure Portal when you created a Registered Application + + .PARAMETER ClientSecret + The ClientSecret obtained from the Azure Portal when you created a Registered Application + + .PARAMETER EnableException + This parameters disables user-friendly warnings and enables the throwing of exceptions + This is less user friendly, but allows catching exceptions in calling scripts + + .PARAMETER RawOutput + Instructs the cmdlet to include the outer structure of the response received from OData endpoint + + The output will still be a PSCustomObject + + .PARAMETER OutNamesOnly + Instructs the cmdlet to only display the DataEntityName and the EntityName from the response received from OData endpoint + + DataEntityName is the (logical) name of the entity from a code perspective. + EntityName is the public OData endpoint name of the entity. + + .PARAMETER OutputAsJson + Instructs the cmdlet to convert the output to a Json string + + .EXAMPLE + PS C:\> Get-D365CeODataEntity -EntityName Account + + This will get Data Entities from the OData endpoint. + This will search for the Data Entities that are named "Account". + + .EXAMPLE + PS C:\> Get-D365CeODataEntity -EntityNameContains Account + + This will get Data Entities from the OData endpoint. + It will use the search string "Account" to search for any entity in their singular & plural name contains that search term. + + .EXAMPLE + PS C:\> Get-D365CeODataEntity -EntityNameContains Account -OutNamesOnly + + This will get Data Entities from the OData endpoint. + It will use the search string "Account" to search for any entity in their singular & plural name contains that search term. + It will only output the names for the entities and not all their metadata details. + + .EXAMPLE + PS C:\> Get-D365CeODataEntity -ODataQuery "`$filter=IsPrivate eq true" -OutNamesOnly + + This will get Data Entities from the OData endpoint. + It will utilize the OData Query capabilities to filter for Data Entities that are "IsPrivate = $true". + It will only output the names for the entities and not all their metadata details. + + .NOTES + The OData standard is using the $ (dollar sign) for many functions and features, which in PowerShell is normally used for variables. + + Whenever you want to use the different query options, you need to take the $ sign and single quotes into consideration. + + Example of an execution where I want the top 1 result only, from a specific legal entity / company. + This example is using single quotes, to help PowerShell not trying to convert the $ into a variable. + Because the OData standard is using single quotes as text qualifiers, we need to escape them with multiple single quotes. + + -ODataQuery '$top=1&$filter=dataAreaId eq ''Comp1''' + + Tags: OData, Data, Entity, Query + + Author: Mötz Jensen (@Splaxi) +#> +function Get-D365CeODataEntity { + [CmdletBinding(DefaultParameterSetName = "Default")] + [OutputType()] + param ( + + [Parameter(Mandatory = $false, ParameterSetName = "Default")] + [string] $EntityName, + + [Parameter(Mandatory = $true, ParameterSetName = "NameContains")] + [string] $EntityNameContains, + + [string] $ODataQuery, + + [Alias('$AADGuid')] + [string] $Tenant = $Script:ODataTenant, + + [Alias('URI')] + [string] $URL = $Script:ODataUrl, + + [string] $ClientId = $Script:ODataClientId, + + [string] $ClientSecret = $Script:ODataClientSecret, + + [switch] $EnableException, + + [switch] $RawOutput, + + [switch] $OutNamesOnly, + + [switch] $OutputAsJson + + ) + + + begin { + $bearerParms = @{ + Url = $Url + ClientId = $ClientId + ClientSecret = $ClientSecret + Tenant = $Tenant + } + + $bearer = New-BearerToken @bearerParms + + $headerParms = @{ + URL = $URL + BearerToken = $bearer + } + + $headers = New-AuthorizationHeaderBearerToken @headerParms + + $apiPath = Get-PSFConfigValue -FullName "d365ce.integrations.api.version" + [System.UriBuilder] $odataEndpoint = $URL + $odataEndpoint.Path = "$apiPath/EntityDefinitions" + } + + process { + if (Test-PSFFunctionInterrupt) { return } + + Invoke-TimeSignal -Start + + $odataEndpoint.Query = "" + + if (-not ([string]::IsNullOrEmpty($EntityName))) { + Write-PSFMessage -Level Verbose -Message "Building request for the Metadata OData endpoint for entity named: $EntityName." -Target $EntityName + + $searchEntityName = $EntityName + $odataEndpoint.Query = "`$filter=(LogicalName eq '$EntityName' or SchemaName eq '$EntityName' or LogicalCollectionName eq '$EntityName' or CollectionSchemaName eq '$EntityName' or EntitySetName eq '$EntityName')" + } + + if (-not ([string]::IsNullOrEmpty($ODataQuery))) { + $odataEndpoint.Query = $($odataEndpoint.Query + "$ODataQuery").Replace("?", "") + } + + try { + Write-PSFMessage -Level Verbose -Message "Executing http request against the Metadata OData endpoint." -Target $($odataEndpoint.Uri.AbsoluteUri) + $res = Invoke-RestMethod -Method Get -Uri $odataEndpoint.Uri.AbsoluteUri -Headers $headers -ContentType 'application/json' + + if (-not ([string]::IsNullOrEmpty($EntityNameContains))) { + Write-PSFMessage -Level Verbose -Message "Filtering the list of entities for entity that contains: $EntityNameContains." -Target $EntityNameContains + + $searchEntityName = $EntityNameContains + + $res.Value = $res.Value | Where-Object { $_.LogicalName -like "*$EntityNameContains*" ` + -or $_.SchemaName -like "*$EntityNameContains*" ` + -or $_.LogicalCollectionName -like "*$EntityNameContains*" ` + -or $_.CollectionSchemaName -like "*$EntityNameContains*" ` + -or $_.EntitySetName -like "*$EntityNameContains*" ` + } + } + + if (-not ($RawOutput)) { + $res = $res.Value | Sort-Object -Property SchemaName + + if ($OutNamesOnly) { + $res = $res | Select-PSFObject "SchemaName as EntityName", "CollectionSchemaName as CollectionSchemaName", "EntitySetName as EntitySetName" + } + } + + if ($OutputAsJson) { + $res | ConvertTo-Json -Depth 10 + } + else { + $res + } + } + catch { + $messageString = "Something went wrong while searching the Metadata OData endpoint for the entity: $searchEntityName" + Write-PSFMessage -Level Host -Message $messageString -Exception $PSItem.Exception -Target $entityName + Stop-PSFFunction -Message "Stopping because of errors." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -ErrorRecord $_ + return + } + + Invoke-TimeSignal -End + } +} \ No newline at end of file diff --git a/d365ce.integrations/tests/functions/Get-D365CeODataEntity.Tests.ps1 b/d365ce.integrations/tests/functions/Get-D365CeODataEntity.Tests.ps1 new file mode 100644 index 0000000..f73297e --- /dev/null +++ b/d365ce.integrations/tests/functions/Get-D365CeODataEntity.Tests.ps1 @@ -0,0 +1,172 @@ +Describe "Get-D365CeODataEntity 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 Get-D365CeODataEntity).ParameterSets.Name | Should -Be 'Default', 'NameContains' + } + + It 'Should have the expected parameter EntityName' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['EntityName'] + $parameter.Name | Should -Be 'EntityName' + $parameter.ParameterType.ToString() | Should -Be System.String + $parameter.IsDynamic | Should -Be $False + $parameter.ParameterSets.Keys | Should -Be 'Default' + $parameter.ParameterSets.Keys | Should -Contain 'Default' + $parameter.ParameterSets['Default'].IsMandatory | Should -Be $False + $parameter.ParameterSets['Default'].Position | Should -Be -2147483648 + $parameter.ParameterSets['Default'].ValueFromPipeline | Should -Be $False + $parameter.ParameterSets['Default'].ValueFromPipelineByPropertyName | Should -Be $False + $parameter.ParameterSets['Default'].ValueFromRemainingArguments | Should -Be $False + } + It 'Should have the expected parameter EntityNameContains' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['EntityNameContains'] + $parameter.Name | Should -Be 'EntityNameContains' + $parameter.ParameterType.ToString() | Should -Be System.String + $parameter.IsDynamic | Should -Be $False + $parameter.ParameterSets.Keys | Should -Be 'NameContains' + $parameter.ParameterSets.Keys | Should -Contain 'NameContains' + $parameter.ParameterSets['NameContains'].IsMandatory | Should -Be $True + $parameter.ParameterSets['NameContains'].Position | Should -Be -2147483648 + $parameter.ParameterSets['NameContains'].ValueFromPipeline | Should -Be $False + $parameter.ParameterSets['NameContains'].ValueFromPipelineByPropertyName | Should -Be $False + $parameter.ParameterSets['NameContains'].ValueFromRemainingArguments | Should -Be $False + } + It 'Should have the expected parameter ODataQuery' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['ODataQuery'] + $parameter.Name | Should -Be 'ODataQuery' + $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 $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 + } + It 'Should have the expected parameter Tenant' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['Tenant'] + $parameter.Name | Should -Be 'Tenant' + $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 $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 + } + It 'Should have the expected parameter URL' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['URL'] + $parameter.Name | Should -Be 'URL' + $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 $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 + } + It 'Should have the expected parameter ClientId' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['ClientId'] + $parameter.Name | Should -Be 'ClientId' + $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 $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 + } + It 'Should have the expected parameter ClientSecret' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['ClientSecret'] + $parameter.Name | Should -Be 'ClientSecret' + $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 $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 + } + It 'Should have the expected parameter EnableException' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['EnableException'] + $parameter.Name | Should -Be 'EnableException' + $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 + } + It 'Should have the expected parameter RawOutput' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['RawOutput'] + $parameter.Name | Should -Be 'RawOutput' + $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 + } + It 'Should have the expected parameter OutNamesOnly' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['OutNamesOnly'] + $parameter.Name | Should -Be 'OutNamesOnly' + $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 + } + It 'Should have the expected parameter OutputAsJson' { + $parameter = (Get-Command Get-D365CeODataEntity).Parameters['OutputAsJson'] + $parameter.Name | Should -Be 'OutputAsJson' + $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 Default" { + <# + Default - + Default -EntityName -ODataQuery -Tenant -URL -ClientId -ClientSecret -EnableException -RawOutput -OutNamesOnly -OutputAsJson + #> + } + Describe "Testing parameterset NameContains" { + <# + NameContains -EntityNameContains + NameContains -EntityNameContains -ODataQuery -Tenant -URL -ClientId -ClientSecret -EnableException -RawOutput -OutNamesOnly -OutputAsJson + #> + } + +} \ No newline at end of file diff --git a/docs/Add-D365CeODataConfig.md b/docs/Add-D365CeODataConfig.md index 3799eae..88dc484 100644 --- a/docs/Add-D365CeODataConfig.md +++ b/docs/Add-D365CeODataConfig.md @@ -157,8 +157,7 @@ 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). +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 diff --git a/docs/Enable-D365CeException.md b/docs/Enable-D365CeException.md index aa0242d..c2ea7c7 100644 --- a/docs/Enable-D365CeException.md +++ b/docs/Enable-D365CeException.md @@ -33,8 +33,7 @@ This will for the rest of the current PowerShell session make sure that exceptio ## PARAMETERS ### 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). +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 diff --git a/docs/Get-D365CeActiveODataConfig.md b/docs/Get-D365CeActiveODataConfig.md index 4ed3ed0..3582828 100644 --- a/docs/Get-D365CeActiveODataConfig.md +++ b/docs/Get-D365CeActiveODataConfig.md @@ -62,8 +62,7 @@ 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). +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 diff --git a/docs/Get-D365CeODataConfig.md b/docs/Get-D365CeODataConfig.md index 4675997..abfd2df 100644 --- a/docs/Get-D365CeODataConfig.md +++ b/docs/Get-D365CeODataConfig.md @@ -94,8 +94,7 @@ 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). +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 diff --git a/docs/Get-D365CeODataEntity.md b/docs/Get-D365CeODataEntity.md new file mode 100644 index 0000000..d69479b --- /dev/null +++ b/docs/Get-D365CeODataEntity.md @@ -0,0 +1,288 @@ +--- +external help file: d365ce.integrations-help.xml +Module Name: d365ce.integrations +online version: +schema: 2.0.0 +--- + +# Get-D365CeODataEntity + +## SYNOPSIS +Get public OData Data Entity and their metadata + +## SYNTAX + +### Default (Default) +``` +Get-D365CeODataEntity [-EntityName ] [-ODataQuery ] [-Tenant ] [-URL ] + [-ClientId ] [-ClientSecret ] [-EnableException] [-RawOutput] [-OutNamesOnly] [-OutputAsJson] + [] +``` + +### NameContains +``` +Get-D365CeODataEntity -EntityNameContains [-ODataQuery ] [-Tenant ] [-URL ] + [-ClientId ] [-ClientSecret ] [-EnableException] [-RawOutput] [-OutNamesOnly] [-OutputAsJson] + [] +``` + +## DESCRIPTION +Get a list with all the available OData Data Entities,and their metadata, that are exposed through the OData endpoint of the Dynamics 365 Customer Engagement instance + +The cmdlet will search across the singular names for the Data Entities and across the collection names (plural) + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-D365CeODataEntity -EntityName Account +``` + +This will get Data Entities from the OData endpoint. +This will search for the Data Entities that are named "Account". + +### EXAMPLE 2 +``` +Get-D365CeODataEntity -EntityNameContains Account +``` + +This will get Data Entities from the OData endpoint. +It will use the search string "Account" to search for any entity in their singular & plural name contains that search term. + +### EXAMPLE 3 +``` +Get-D365CeODataEntity -EntityNameContains Account -OutNamesOnly +``` + +This will get Data Entities from the OData endpoint. +It will use the search string "Account" to search for any entity in their singular & plural name contains that search term. +It will only output the names for the entities and not all their metadata details. + +### EXAMPLE 4 +``` +Get-D365CeODataEntity -ODataQuery "`$filter=IsPrivate eq true" -OutNamesOnly +``` + +This will get Data Entities from the OData endpoint. +It will utilize the OData Query capabilities to filter for Data Entities that are "IsPrivate = $true". +It will only output the names for the entities and not all their metadata details. + +## PARAMETERS + +### -EntityName +Name of the Data Entity you are searching for + +The parameter is Case Insensitive, to make it easier for the user to locate the correct Data Entity + +```yaml +Type: String +Parameter Sets: Default +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EntityNameContains +Name of the Data Entity you are searching for, but instructing the cmdlet to use search logic + +Using this parameter enables you to supply only a portion of the name for the entity you are looking for, and still a valid result back + +The parameter is Case Insensitive, to make it easier for the user to locate the correct Data Entity + +```yaml +Type: String +Parameter Sets: NameContains +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ODataQuery +Valid OData query string that you want to pass onto the D365 OData endpoint while retrieving data + +Important note: +If you are using -EntityName along with the -ODataQuery, you need to understand that the "$filter" query is already started. +Then you need to start with -ODataQuery ' and XYZ eq XYZ', e.g. +-ODataQuery ' and IsReadOnly eq false' +If you are using the -ODataQuery alone, you need to start the OData Query string correctly. +-ODataQuery '$filter=IsReadOnly eq false' + +OData specific query options are: +$filter +$expand +$select +$orderby +$top +$skip + +Each option has different characteristics, which is well documented at: http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tenant +Azure Active Directory (AAD) tenant id (Guid) that the D365CE environment is connected to, that you want to access through OData + +```yaml +Type: String +Parameter Sets: (All) +Aliases: $AADGuid + +Required: False +Position: Named +Default value: $Script:ODataTenant +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -URL +URL / URI for the D365CE environment you want to access through OData + +```yaml +Type: String +Parameter Sets: (All) +Aliases: URI + +Required: False +Position: Named +Default value: $Script:ODataUrl +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ClientId +The ClientId obtained from the Azure Portal when you created a Registered Application + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: $Script:ODataClientId +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ClientSecret +The ClientSecret obtained from the Azure Portal when you created a Registered Application + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: $Script:ODataClientSecret +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EnableException +This parameters disables user-friendly warnings and enables the throwing of exceptions +This is less user friendly, but allows catching exceptions in calling scripts + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RawOutput +Instructs the cmdlet to include the outer structure of the response received from OData endpoint + +The output will still be a PSCustomObject + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutNamesOnly +Instructs the cmdlet to only display the DataEntityName and the EntityName from the response received from OData endpoint + +DataEntityName is the (logical) name of the entity from a code perspective. +EntityName is the public OData endpoint name of the entity. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputAsJson +Instructs the cmdlet to convert the output to a Json string + +```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 +The OData standard is using the $ (dollar sign) for many functions and features, which in PowerShell is normally used for variables. + +Whenever you want to use the different query options, you need to take the $ sign and single quotes into consideration. + +Example of an execution where I want the top 1 result only, from a specific legal entity / company. +This example is using single quotes, to help PowerShell not trying to convert the $ into a variable. +Because the OData standard is using single quotes as text qualifiers, we need to escape them with multiple single quotes. + +-ODataQuery '$top=1&$filter=dataAreaId eq ''Comp1''' + +Tags: OData, Data, Entity, Query + +Author: M ¶tz Jensen (@Splaxi) + +## RELATED LINKS diff --git a/docs/Get-D365CeODataEntityData.md b/docs/Get-D365CeODataEntityData.md index 917b420..7cf82e3 100644 --- a/docs/Get-D365CeODataEntityData.md +++ b/docs/Get-D365CeODataEntityData.md @@ -213,8 +213,7 @@ 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). +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 diff --git a/docs/Get-D365CeODataEntityDataByKey.md b/docs/Get-D365CeODataEntityDataByKey.md index fbf4fe8..591cac9 100644 --- a/docs/Get-D365CeODataEntityDataByKey.md +++ b/docs/Get-D365CeODataEntityDataByKey.md @@ -199,8 +199,7 @@ 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). +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 diff --git a/docs/Import-D365CeODataEntity.md b/docs/Import-D365CeODataEntity.md index 426bfb4..64994dc 100644 --- a/docs/Import-D365CeODataEntity.md +++ b/docs/Import-D365CeODataEntity.md @@ -163,8 +163,7 @@ 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). +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 diff --git a/docs/Import-D365CeODataEntityBatchMode.md b/docs/Import-D365CeODataEntityBatchMode.md index 42513b8..6c6804c 100644 --- a/docs/Import-D365CeODataEntityBatchMode.md +++ b/docs/Import-D365CeODataEntityBatchMode.md @@ -181,8 +181,7 @@ 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). +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 diff --git a/docs/Remove-D365CeODataEntity.md b/docs/Remove-D365CeODataEntity.md index 3fc0e33..c93f44f 100644 --- a/docs/Remove-D365CeODataEntity.md +++ b/docs/Remove-D365CeODataEntity.md @@ -153,8 +153,7 @@ 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). +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 diff --git a/docs/Set-D365CeActiveODataConfig.md b/docs/Set-D365CeActiveODataConfig.md index f97afd2..5d12306 100644 --- a/docs/Set-D365CeActiveODataConfig.md +++ b/docs/Set-D365CeActiveODataConfig.md @@ -61,8 +61,7 @@ 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). +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 diff --git a/docs/Update-D365CeODataEntity.md b/docs/Update-D365CeODataEntity.md index 34addfc..cdbd9d5 100644 --- a/docs/Update-D365CeODataEntity.md +++ b/docs/Update-D365CeODataEntity.md @@ -186,8 +186,7 @@ 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). +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