Public/Exchange/Get-JIMPendingExchangeChange.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Get-JIMPendingExchangeChange { <# .SYNOPSIS Gets the Exchange queue: the recipient changes JIM has queued for Exchange, and where each one stands. .DESCRIPTION Lists the changes exports have queued for Exchange: one row per account, naming its Connected System and Metaverse Object. A change leaves the queue once Exchange has it; its outcome stays on its Activity. A change stands in one of six states: - Queued: waiting for its first attempt. The Exchange delivery lane picks it up within seconds. - Delivering: Exchange is applying it now. - Retrying: an attempt failed in a way that may clear by itself (Exchange unreachable, the account not yet visible to Exchange). NextRetryAt says when the next attempt falls due. - Parked: Exchange refused it, JIM lacks the permissions to make it, or 24 hours of retries failed. JIM has stopped trying; FailureMessage gives Exchange's own words. Retry it with Resume-JIMPendingExchangeChange once the cause is fixed. - Refused: JIM refused the declared state before asking Exchange, for example a recipient type that does not fit the object. It holds until what is declared for the account changes. - NotMade: it would change an existing recipient's type, which JIM does not do. It holds until what is declared for the account changes. An Exchange change cannot be cancelled. To stop or correct one, change what is declared for the account (its source data or the Attribute Flow); the newer state replaces the queued change. .PARAMETER ConnectedSystemId Only changes for this Connected System. .PARAMETER State Only changes in this state. Held changes wait, unattempted, because their Connected System does not manage Exchange recipients now; they are delivered once it does again. .PARAMETER FailureKind Only changes whose last attempt failed this way. .PARAMETER MetaverseObjectId Only this Metaverse Object's changes. .PARAMETER ConnectedSystemObjectId Only this account's change. The queue holds at most one per account. .PARAMETER Search Free-text search over the Metaverse Object and Connected System names. .PARAMETER SortBy The column to sort by; queued when omitted. .PARAMETER SortDirection The sort direction; ascending when omitted. .PARAMETER Page The page of changes to return. .PARAMETER PageSize How many changes to return per page. .PARAMETER All Returns every page. Stops after 1,000 pages with a warning unless -Force is given. .PARAMETER Force Fetches beyond the -All page ceiling. .PARAMETER Summary Returns the queue's counts by state instead of its changes. .OUTPUTS One object per queued change, or with -Summary one object of counts. .EXAMPLE Get-JIMPendingExchangeChange -Summary Reports how many changes stand in each state, and how many wait on a person. The quickest way to find out whether Exchange needs attention. .EXAMPLE Get-JIMPendingExchangeChange -State Parked | Select-Object MetaverseObjectDisplayName, ConnectedSystemName, FailureKind, FailureMessage Lists the changes JIM has stopped trying, with Exchange's reason for each: the ones a person has to deal with. .EXAMPLE Get-JIMPendingExchangeChange -State Parked -All | Group-Object FailureKind | Select-Object Name, Count Shows what is behind the parked changes, which is usually one cause (missing permissions, say) rather than many. .EXAMPLE Get-JIMConnectedSystem -Name "Panoply AD" | Get-JIMPendingExchangeChange -All Lists every queued change for one Connected System, following pagination. .LINK Resume-JIMPendingExchangeChange #> [CmdletBinding(DefaultParameterSetName = 'List')] [OutputType('JIM.PendingExchangeChangeResponse', ParameterSetName = 'List')] [OutputType('JIM.PendingExchangeChangeResponse', ParameterSetName = 'ListAll')] [OutputType('JIM.ExchangeQueueSummary', ParameterSetName = 'Summary')] param( # Aliased so a Connected System piped in binds by its Id. The noun here is the queued change, not the Connected # System, so -ConnectedSystemId is spelt out in every example. [Parameter(ParameterSetName = 'List', ValueFromPipelineByPropertyName)] [Parameter(ParameterSetName = 'ListAll', ValueFromPipelineByPropertyName)] [Alias('Id')] [int]$ConnectedSystemId, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [ValidateSet('Queued', 'Held', 'Delivering', 'Retrying', 'Parked', 'Refused', 'NotMade')] [string]$State, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [ValidateSet('ObjectNotFound', 'Refused', 'InsufficientPermissions', 'AuthenticationFailed', 'Unreachable')] [string]$FailureKind, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [guid]$MetaverseObjectId, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [guid]$ConnectedSystemObjectId, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [string]$Search, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [ValidateSet('queued', 'identity', 'system', 'attempts', 'nextAttempt', 'lastAttempt')] [string]$SortBy, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [ValidateSet('asc', 'desc')] [string]$SortDirection, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, [int]::MaxValue)] [int]$Page = 1, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ListAll')] [ValidateRange(1, 100)] [int]$PageSize = 50, [Parameter(Mandatory, ParameterSetName = 'ListAll')] [switch]$All, [Parameter(ParameterSetName = 'ListAll')] [switch]$Force, [Parameter(Mandatory, ParameterSetName = 'Summary')] [switch]$Summary ) process { if (-not $script:JIMConnection) { Write-Error "You are not connected to JIM. Run Connect-JIM -Url <your JIM URL> to authenticate, then try again." return } if ($PSCmdlet.ParameterSetName -eq 'Summary') { Write-Verbose "Getting the Exchange queue summary" Invoke-JIMApi -Endpoint '/api/v1/exchange/queue/summary' return } # Built once and reused across pages, so an auto-paginating fetch cannot drift from the first page's filters. $criteria = @() if ($PSBoundParameters.ContainsKey('ConnectedSystemId')) { $criteria += "connectedSystemId=$ConnectedSystemId" } if ($State) { $criteria += "state=$State" } if ($FailureKind) { $criteria += "failureKind=$FailureKind" } if ($PSBoundParameters.ContainsKey('MetaverseObjectId')) { $criteria += "metaverseObjectId=$MetaverseObjectId" } if ($PSBoundParameters.ContainsKey('ConnectedSystemObjectId')) { $criteria += "connectedSystemObjectId=$ConnectedSystemObjectId" } if ($Search) { $criteria += "search=$([System.Uri]::EscapeDataString($Search))" } if ($SortBy) { $criteria += "sortBy=$SortBy" } if ($SortDirection) { $criteria += "sortDirection=$SortDirection" } $criteriaSuffix = if ($criteria.Count -gt 0) { '&' + ($criteria -join '&') } else { '' } if ($All) { Write-Verbose "Getting every queued Exchange change" $pageRequest = { param($p) Invoke-JIMApi -Endpoint "/api/v1/exchange/queue?page=$p&pageSize=$PageSize$criteriaSuffix" } Invoke-JIMPagedFetch -PageRequest $pageRequest -CmdletName 'Get-JIMPendingExchangeChange' -PageSize $PageSize -Force:$Force ` -ItemNoun 'queued Exchange changes' -NarrowHint 'narrow the query with -ConnectedSystemId, -State or -Search' return } Write-Verbose "Getting queued Exchange changes (Page: $Page, PageSize: $PageSize)" $response = Invoke-JIMApi -Endpoint "/api/v1/exchange/queue?page=$Page&pageSize=$PageSize$criteriaSuffix" foreach ($item in $response.items) { $item } } } |