functions/Get-JS7FileTransferHistory.ps1
|
function Get-JS7FileTransferHistory { <# .SYNOPSIS Returns the history of file transfers performed with YADE .DESCRIPTION File transfer history information is returned for file transfers performed with YADE from a JS7 workflow. File transfers can be selected by YADE profile, file name, history status etc. The history information returned includes start time, end time, status etc. of a file transfer. File transfers can include any number of files. For information about individual files the Get-JS7FileTransferHistoryFile cmdlet can be used. This cmdlet can be used for pipelining to return information about individual files like this: $files = Get-JS7FileTransferHistory -RelativeDateFrom -1w -Successful | Get-JS7FileTransferHistoryFile The following REST Web Service API resources are used: * /yade/transfers .PARAMETER ControllerId Optionally limits file transfer history items to workflows that have been executed which the indicated Controller. .PARAMETER Operation Optionally limits file transfer history items to the ones using one or more of the following operations: * COPY * MOVE * GETLIST * RENAME A number of operations can be specified by use of a comma, for example: -Operation COPY,MOVE. .PARAMETER Profile Optionally limits file transfer history items to the ones using the indicated YADE file transfer profile. This parameter accepts any number of profiles separated by a comma. .PARAMETER Source Optionally specifies the host and port that act as the source of a file transfer to limit the file transfer history items returned. Depending on the source protocol in use this can be the localhost for a local source or the host configured with a file transfer fragment that is used as the source. A source is specified by the hostname and optionally a port that are separated by a colon, for example: -Source some_host:22. This parameter accepts any number of sources separated by a comma. .PARAMETER Target Optionally specifies the host and port that act as the target of a file transfer to limit the file transfer history items returned. Depending on the target protocol in use this can be the localhost for a local target or the host configured with a file transfer fragment that is used as the target. A target is specified by the hostname and optionally a port that are separated by a colon, for example: -Target some_host:22. This parameter accepts any number of targets separated by a comma. .PARAMETER SourceFile Optionally specifies the name of a source file to limit the file transfer history items returned. This parameter accepts any number of source file names separated by a comma. .PARAMETER TargetFile Optionally specifies the name of a target file to limit the file transfer history items returned. This parameter accepts any number of target file names separated by a comma. .PARAMETER DateFrom Specifies the date starting from which file transfer history items should be returned. Consider that a UTC date has to be provided. Default: Beginning of the current day as a UTC date .PARAMETER DateTo Specifies the date until which file transfer history items should be returned. Consider that a UTC date has to be provided. Default: End of the current day as a UTC date .PARAMETER RelativeDateFrom Specifies a relative date starting from which file transfer history items should be returned, for example: * -1s, -2s: one second ago, two seconds ago * -1m, -2m: one minute ago, two minutes ago * -1h, -2h: one hour ago, two hours ago * -1d, -2d: one day ago, two days ago * -1w, -2w: one week ago, two weeks ago * -1M, -2M: one month ago, two months ago * -1y, -2y: one year ago, two years ago Optionally a time offset can be specified, e.g. -1d+02:00, as otherwise midnight UTC is assumed. Alternatively a timezone offset can be added, e.g. by using -1d+TZ. This is calculated by the cmdlet for the timezone that is specified with the -Timezone parameter. This parameter takes precedence over the -DateFrom parameter. .PARAMETER RelativeDateTo Specifies a relative date until which file transfer history items should be returned, for example: * -1s, -2s: one second ago, two seconds ago * -1m, -2m: one minute ago, two minutes ago * -1h, -2h: one hour ago, two hours ago * -1d, -2d: one day ago, two days ago * -1w, -2w: one week ago, two weeks ago * -1M, -2M: one month ago, two months ago * -1y, -2y: one year ago, two years ago Optionally a time offset can be specified, e.g. -1d+02:00, as otherwise midnight UTC is assumed. Alternatively a timezone offset can be added, e.g. by using -1d+TZ. This is calculated by the cmdlet for the timezone that is specified with the -Timezone parameter. This parameter takes precedence over the -DateFrom parameter. .PARAMETER Timezone Specifies the timezone to which dates should be converted available from the file transfer history. A timezone can be specified like this: Get-JS7FileTransferHistory -Timezone (Get-Timezone -Id 'GMT Standard Time') All dates in JS7 are UTC and can be converted e.g. to the local time zone like this: Get-JS7FileTransferHistory -Timezone (Get-Timezone) Default: Dates are returned in UTC. .PARAMETER Limit Specifies the max. number of history items for file transfers to be returned. The default value is 10000, for an unlimited number of items the value -1 can be specified. .PARAMETER Compact Specifies the a smaller subset of properties to be returned with the file transfer history items. .PARAMETER Successful Returns history items for successfully completed file transfers. .PARAMETER Failed Returns history items for failed file transfers. .PARAMETER InProgress Specifies that history items for running file transfers should be returned. .OUTPUTS This cmdlet returns an array of file transfer history items. .EXAMPLE $items = Get-JS7FileTransferHistory Returns today's file transfer history from any workflows. .EXAMPLE $items = Get-JS7FileTransferHistory -Profile copy_to_remote,move_to_remote Returns today's file transfers that have been performed by use of the indicated YADE profiles. .EXAMPLE $items = Get-JS7FileTransferHistory -Timezone (Get-Timezone) Returns today's file transfers with dates being converted to the local timezone. .EXAMPLE $items = Get-JS7FileTransferHistory -Timezone (Get-Timezone -Id 'GMT Standard Time') Returns today's file transfers with dates being converted to the GMT timezone. .EXAMPLE $items = Get-JS7FileTransferHistory -Successful -DateFrom "2020-08-11 14:00:00Z" Returns the file transfer history for successfully completed orders that started after the specified UTC date and time. .EXAMPLE $items = Get-JS7FileTransferHistory -Failed -DateFrom (Get-Date -Hour 0 -Minute 0 -Second 0).AddDays(-7).ToUniversalTime() Returns the file transfer history for any failed orders for the last seven days. .EXAMPLE $items = Get-JS7FileTransferHistory -RelativeDateFrom -7d Returns the file transfer history for the last seven days. The history is reported starting from midnight UTC. .EXAMPLE $items = Get-JS7FileTransferHistory -RelativeDateFrom -7d+01:00 Returns the file transfer history for the last seven days. The history is reported starting from 1 hour after midnight UTC. .EXAMPLE $items = Get-JS7FileTransferHistory -RelativeDateFrom -7d+TZ Returns the file transfer history for the last seven days. The history is reported starting from midnight in the same timezone that is used with the -Timezone parameter. .EXAMPLE $items = Get-JS7FileTransferHistory -RelativeDateFrom -1w Returns the file transfer history for the last week. .LINK about_JS7 #> [cmdletbinding()] param ( [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string] $ControllerId, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [ValidateSet('COPY','MOVE','GETLIST','RENAME',IgnoreCase = $False)] [string[]] $Operation, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string[]] $Profile, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string[]] $Source, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string[]] $Target, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string[]] $SourceFile, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string[]] $TargetFile, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [DateTime] $DateFrom = (Get-Date (Get-Date).ToUniversalTime() -Format 'yyyy-MM-dd'), [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [DateTime] $DateTo, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string] $RelativeDateFrom, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string] $RelativeDateTo, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [TimeZoneInfo] $Timezone = (Get-Timezone -Id 'UTC'), [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [int] $Limit, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $Compact, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $Successful, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $Failed, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $InProgress ) Begin { Approve-JS7Command $MyInvocation.MyCommand $stopWatch = Start-JS7StopWatch $operations = @() $profiles = @() $states = @() $sources = @() $targets = @() $sourceFiles = @() $targetFiles = @() } Process { Write-Debug ".. $($MyInvocation.MyCommand.Name):" if ( $Successful ) { $states += 'SUCCESSFUL' } if ( $Failed ) { $states += 'FAILED' } if ( $InProgress ) { $states += 'INCOMPLETE' } if ( $Operation ) { $operations += $Operation } if ( $Profile ) { $profiles += $Profile } if ( $Source ) { $sources += $Source } if ( $Target ) { $targets += $Target } if ( $SourceFile ) { $sourcesFiles += $SourceFile } if ( $TargetFile ) { $targetFiles += $TargetFile } } End { # PowerShell/.NET does not create date output in the target timezone but with the local timezone only, let's work around this: $timezoneOffsetPrefix = if ( $Timezone.BaseUtcOffset.toString().startsWith( '-' ) ) { '-' } else { '+' } $timezoneOffsetHours = [Math]::Abs($Timezone.BaseUtcOffset.hours) if ( $Timezone.SupportsDaylightSavingTime -and $Timezone.IsDaylightSavingTime( (Get-Date) ) ) { $timezoneOffsetHours += 1 } [string] $timezoneOffset = "$($timezoneOffsetPrefix)$($timezoneOffsetHours.ToString().PadLeft( 2, '0' )):$($Timezone.BaseUtcOffset.Minutes.ToString().PadLeft( 2, '0' ))" $body = New-Object PSObject if ( $ControllerId ) { Add-Member -Membertype NoteProperty -Name 'controllerId' -value $ControllerId -InputObject $body } else { Add-Member -Membertype NoteProperty -Name 'controllerId' -value $script:jsWebService.ControllerId -InputObject $body } if ( $operations ) { Add-Member -Membertype NoteProperty -Name 'operations' -value $operations -InputObject $body } if ( $profiles ) { Add-Member -Membertype NoteProperty -Name 'profiles' -value $profiles -InputObject $body } if ( $sources ) { $objSources = @() foreach( $sourceItem in $sources ) { $objSource = New-Object PSObject $matchinfo = ( $sourceItem | Select-String -Pattern '^(.*)\:([0-9]+)$' ) if ( $matchInfo -and $matchInfo.Matches -and $matchInfo.Matches.Groups.count ) { Add-Member -Membertype NoteProperty -Name 'host' -value $matchInfo.Matches.Groups[1] -InputObject $objSource if ( $matchInfo.Matches.Groups.count -eq 3 ) { Add-Member -Membertype NoteProperty -Name 'protocol' -value $matchInfo.Matches.Groups[1] -InputObject $objSource } } else { Add-Member -Membertype NoteProperty -Name 'host' -value $source -InputObject $objSource } $objSources += $objSource } Add-Member -Membertype NoteProperty -Name 'sources' -value $objSources -InputObject $body } if ( $targets ) { $objTargets = @() foreach( $targetItem in $targets ) { $objTarget = New-Object PSObject $matchinfo = ( $targetItem | Select-String -Pattern '^(.*)\:([0-9]+)$' ) if ( $matchInfo -and $matchInfo.Matches -and $matchInfo.Matches.Groups.count ) { Add-Member -Membertype NoteProperty -Name 'host' -value $matchInfo.Matches.Groups[1] -InputObject $objTarget if ( $matchInfo.Matches.Groups.count -eq 3 ) { Add-Member -Membertype NoteProperty -Name 'protocol' -value $matchInfo.Matches.Groups[1] -InputObject $objTarget } } else { Add-Member -Membertype NoteProperty -Name 'host' -value $target -InputObject $objTarget } $objTargets += $objTarget } Add-Member -Membertype NoteProperty -Name 'sources' -value $objSources -InputObject $body } if ( $sourceFiles ) { Add-Member -Membertype NoteProperty -Name 'sourceFiles' -value $sourceFiles -InputObject $body } if ( $targetFiles ) { Add-Member -Membertype NoteProperty -Name 'targetFiles' -value $targetFiles -InputObject $body } if ( $DateFrom -or $RelativeDateFrom ) { if ( $RelativeDateFrom ) { if ( $RelativeDateFrom.endsWith( '+TZ' ) ) { $RelativeDateFrom = $RelativeDateFrom.Substring( 0, $RelativeDateFrom.length-3 ) + $timezoneOffset } Add-Member -Membertype NoteProperty -Name 'dateFrom' -value $RelativeDateFrom -InputObject $body } else { Add-Member -Membertype NoteProperty -Name 'dateFrom' -value ( Get-Date (Get-Date $DateFrom).ToUniversalTime() -Format 'u').Replace(' ', 'T') -InputObject $body } } if ( $DateTo -or $RelativeDateTo ) { if ( $RelativeDateTo ) { if ( $RelativeDateTo.endsWith( '+TZ' ) ) { $RelativeDateTo = $RelativeDateTo.Substring( 0, $RelativeDateTo.length-3 ) + $timezoneOffset } Add-Member -Membertype NoteProperty -Name 'dateTo' -value $RelativeDateTo -InputObject $body } else { Add-Member -Membertype NoteProperty -Name 'dateTo' -value ( Get-Date (Get-Date $DateTo).ToUniversalTime() -Format 'u').Replace(' ', 'T') -InputObject $body } } if ( $states ) { Add-Member -Membertype NoteProperty -Name 'states' -value $states -InputObject $body } if ( $Limit ) { Add-Member -Membertype NoteProperty -Name 'limit' -value $Limit -InputObject $body } if ( $Compact ) { Add-Member -Membertype NoteProperty -Name 'compact' -value ($Compact -eq $True) -InputObject $body } [string] $requestBody = $body | ConvertTo-Json -Depth 100 $response = Invoke-JS7WebRequest -Path '/yade/transfers' -Body $requestBody if ( $response.StatusCode -eq 200 ) { $returnItems = ( $response.Content | ConvertFrom-Json ).transfers } else { throw ( $response | Format-List -Force | Out-String ) } if ( $Timezone.Id -eq 'UTC' ) { $returnItems } else { $returnItems | Select-Object -Property ` controllerId, ` id, ` historyId, ` orderId, ` workflowPath, ` job, ` jobPosition, ` _operation, ` error, ` numOfFiles, ` source, ` target, ` state, ` @{name='start'; expression={ ( [System.TimeZoneInfo]::ConvertTimeFromUtc( [datetime]::SpecifyKind( [datetime] "$($_.start)".Substring(0, 19), 'UTC'), $Timezone ) ).ToString("yyyy-MM-dd HH:mm:ss") + $timezoneOffset }}, ` @{name='end'; expression={ ( [System.TimeZoneInfo]::ConvertTimeFromUtc( [datetime]::SpecifyKind( [datetime] "$($_.end)".Substring(0, 19), 'UTC'), $Timezone ) ).ToString("yyyy-MM-dd HH:mm:ss") + $timezoneOffset }}, ` @{name='surveyDate'; expression={ ( [System.TimeZoneInfo]::ConvertTimeFromUtc( [datetime]::SpecifyKind( [datetime] "$($_.surveyDate)".SubString(0, 19), 'UTC'), $($Timezone) ) ).ToString("yyyy-MM-dd HH:mm:ss") + $timezoneOffset }} } if ( $returnItems.count ) { Write-Verbose ".. $($MyInvocation.MyCommand.Name): $($returnItems.count) items found" } else { Write-Verbose ".. $($MyInvocation.MyCommand.Name): no items found" } Trace-JS7StopWatch -CommandName $MyInvocation.MyCommand.Name -StopWatch $stopWatch Update-JS7Session } } |