functions/Get-JS7Calendar.ps1
|
function Get-JS7Calendar { <# .SYNOPSIS Returns calendars from the JOC Cockpit inventory .DESCRIPTION Calendars are selected from the JOC Cockpit inventory * by path and name of a calendar, * by the folder of the calendar location including sub-folders, * by a regular expression that is used to filter calendar names. Resulting calendars can be forwarded to other cmdlets for pipelined bulk operations. The following REST Web Service API resources are used: * /calendars .PARAMETER CalendarPath Optionally specifies the path and name of a calendar that should be returned. One of the parameters -Folder, -CalendarPath or -RegularExpression has to be specified if no pipelined calendar objects are provided. .PARAMETER Folder Optionally specifies the folder for which calendars should be returned. One of the parameters -Folder, -CalendarPath or -RegularExpression has to be specified if no pipelined calendar objects are provided. .PARAMETER Recursive Specifies that all sub-folders should be looked up if the -Folder parameter is used. By default no sub-folders will be searched for calendars. .PARAMETER RegularExpression Specifies that a regular expession is applied to the calendar name to filter results. .PARAMETER Compact Specifies that fewer attributes of calendars are returned. .PARAMETER WorkingDays Specifies that only calendars for working days should be returned. Such calendars specify days for which orders should be executed with a JS7 Controller. Only one of the parameters -WorkingDays or -NonWorkingDays can be used. .PARAMETER NonWorkingDays Specifies that only calendars for non-working days should be returned. Such calendars specify days for which no orders should be executed with a JS7 Controller. Only one of the parameters -WorkingDays or -NonWorkingDays can be used. .OUTPUTS This cmdlet returns an array of calendar objects. .EXAMPLE $calendars = Get-JS7Calendar Returns all calendars available with the JOC Cockpit inventory. .EXAMPLE $calendars = Get-JS7Calendar -Folder /some_folder -Recursive Returns all calendars that are configured with the folder "/some_folder" including any sub-folders. .EXAMPLE $calendar = Get-JS7Calendar -CalendarPath /BusinessDays Returns the calendar that is stored with the path "/BusinessDays". .EXAMPLE $calendars = Get-JS7Calendar -WorkingDays Returns the calendars that define working days only. .LINK about_JS7 #> [cmdletbinding()] param ( [Parameter(Mandatory=$False,ValueFromPipeline=$True,ValueFromPipelinebyPropertyName=$True)] [string] $CalendarPath, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string] $Folder = '/', [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$False)] [switch] $Recursive, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [string] $RegularExpression, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $Compact, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $WorkingDays, [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)] [switch] $NonWorkingDays ) Begin { Approve-JS7Command $MyInvocation.MyCommand $stopWatch = Start-JS7StopWatch if ( $WorkingDays -and $NonWorkingDays ) { throw "$($MyInvocation.MyCommand.Name): only one of the parameters -WorkingDays or -NonWorkingDays can be used" } $returnCalendars = @() $calendarPaths = @() $folders = @() $type = $null } Process { Write-Debug ".. $($MyInvocation.MyCommand.Name): parameter Folder=$Folder, CalendarPath=$CalendarPath" if ( $CalendarPath.endsWith( '/') ) { throw "$($MyInvocation.MyCommand.Name): the -CalendarPath parameter has to specify the folder and name of a calendar" } if ( $CalendarPath -and !$CalendarPath.startsWith( '/') ) { $CalendarPath = '/' + $CalendarPath } if ( !$Folder -and !$CalendarPath -and !$RegularExpression ) { throw "$($MyInvocation.MyCommand.Name): no folder, no calendar or regular expression is specified, use -Folder or -CalendarPath or -RegularExpression" } if ( $Folder -and $Folder -ne '/' -and $CalendarPath ) { throw "$($MyInvocation.MyCommand.Name): only on of the parameterrs -CalendarPath or -Folder can be used" } if ( $Folder -and $Folder -ne '/' ) { if ( !$Folder.StartsWith( '/' ) ) { $Folder = '/' + $Folder } if ( $Folder.EndsWith( '/' ) ) { $Folder = $Folder.Substring( 0, $Folder.Length-1 ) } } if ( $Folder -eq '/' -and !$WorkflowPath -and !$RegularExpression -and !$Recursive ) { $Recursive = $True } if ( $WorkingDays ) { $type = 'WORKINGDAYSCALENDAR' } if ( $NonWorkingDays ) { $type = 'NONWORKINGDAYSCALENDAR' } if ( $CalendarPath ) { $calendarPaths += $CalendarPath } elseif ( $Folder ) { $objFolder = New-Object PSObject Add-Member -Membertype NoteProperty -Name 'folder' -value $Folder -InputObject $objFolder Add-Member -Membertype NoteProperty -Name 'recursive' -value ($Recursive -eq $True) -InputObject $objFolder $folders += $objFolder } } End { if ( $calendarPaths.count -or $folders.count ) { $body = New-Object PSObject if ( $Compact ) { Add-Member -Membertype NoteProperty -Name 'compact' -value $True -InputObject $body } if ( $calendarPaths.count ) { Add-Member -Membertype NoteProperty -Name 'calendars' -value $calendarPaths -InputObject $body } if ( $folders.count ) { Add-Member -Membertype NoteProperty -Name 'folders' -value $folders -InputObject $body } if ( $type ) { Add-Member -Membertype NoteProperty -Name 'type' -value $type -InputObject $body } if ( $RegularExpression ) { Add-Member -Membertype NoteProperty -Name 'regex' -value $RegularExpression -InputObject $body } [string] $requestBody = $body | ConvertTo-Json -Depth 100 $response = Invoke-JS7WebRequest -Path '/calendars' -Body $requestBody if ( $response.StatusCode -eq 200 ) { $returnCalendars = ( $response.Content | ConvertFrom-JSON ).calendars } else { throw ( $response | Format-List -Force | Out-String ) } $returnCalendars | Select-Object -Property ` @{name='calendarPath'; expression={$_.path}}, ` from, ` id, ` includes, ` name, ` path, ` title, ` to, ` type } if ( $returnCalendars.count ) { Write-Verbose ".. $($MyInvocation.MyCommand.Name): $($returnCalendars.count) calendars found" } else { Write-Verbose ".. $($MyInvocation.MyCommand.Name): no calendars found" } Trace-JS7StopWatch -CommandName $MyInvocation.MyCommand.Name -StopWatch $stopWatch Update-JS7Session } } |