Public/Schedules/Add-JIMScheduleStep.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Add-JIMScheduleStep { <# .SYNOPSIS Adds a step to a Schedule in JIM. .DESCRIPTION Adds a new step to an existing Schedule. Steps define the tasks that execute when the schedule runs. Steps can run sequentially or in parallel. .PARAMETER ScheduleId The unique identifier (GUID) of the Schedule to add the step to. .PARAMETER StepType The type of step: - RunProfile: Execute a Connected System Run Profile .PARAMETER ConnectedSystemId For RunProfile steps: The ID of the Connected System. .PARAMETER ConnectedSystemName For RunProfile steps: The name of the Connected System. .PARAMETER RunProfileId For RunProfile steps: The ID of the Run Profile to execute. .PARAMETER RunProfileName For RunProfile steps: The name of the Run Profile to execute. .PARAMETER Parallel If specified, runs this step in parallel with the previous step. Otherwise, waits for the previous step to complete. .PARAMETER OnFailure What the step does to the Schedule when it fails: - FollowSchedule (the default): whatever the Schedule is set to do (its OnStepFailure) - Stop: stop the Schedule, even if the Schedule is set to continue - Continue: carry on with the remaining steps, even if the Schedule is set to stop Cannot be used with -ContinueOnFailure. .PARAMETER ContinueOnFailure Shorthand for -OnFailure Continue: the Schedule carries on if this step fails, whatever the Schedule is set to do. Cannot be used with -OnFailure. .PARAMETER ChangeReason An optional reason for the change, recorded against this Schedule's change history. .PARAMETER PassThru If specified, returns the updated Schedule object. .OUTPUTS If -PassThru is specified, returns the updated Schedule object. .EXAMPLE Add-JIMScheduleStep -ScheduleId "12345678-..." -StepType RunProfile -ConnectedSystemId 1 -RunProfileId 1 Adds a Run Profile step to the schedule. .EXAMPLE Add-JIMScheduleStep -ScheduleId "12345678-..." -StepType RunProfile -ConnectedSystemName "HR System" -RunProfileName "Delta Import" -PassThru Adds a step using names instead of IDs. .EXAMPLE $schedule = Get-JIMSchedule -Name "Delta Sync" Add-JIMScheduleStep -ScheduleId $schedule.id -StepType RunProfile -ConnectedSystemName "HR" -RunProfileName "Import" Add-JIMScheduleStep -ScheduleId $schedule.id -StepType RunProfile -ConnectedSystemName "Badge" -RunProfileName "Import" -Parallel Adds two import steps that run in parallel. .EXAMPLE Add-JIMScheduleStep -ScheduleId "12345678-..." -StepType RunProfile -ConnectedSystemName "Active Directory" -RunProfileName "Export" -OnFailure Stop Adds an export step that stops the Schedule if it fails, even when the Schedule is set to continue. .LINK Get-JIMSchedule New-JIMSchedule Remove-JIMScheduleStep Set-JIMScheduleStep #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium', DefaultParameterSetName = 'ById')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [Alias('Id')] [guid]$ScheduleId, [Parameter(Mandatory)] [ValidateSet('RunProfile')] [string]$StepType, [Parameter(Mandatory, ParameterSetName = 'ById')] [int]$ConnectedSystemId, [Parameter(Mandatory, ParameterSetName = 'ByName')] [string]$ConnectedSystemName, [Parameter(Mandatory, ParameterSetName = 'ById')] [int]$RunProfileId, [Parameter(Mandatory, ParameterSetName = 'ByName')] [string]$RunProfileName, [switch]$Parallel, [Parameter()] [ValidateSet('FollowSchedule', 'Stop', 'Continue')] [string]$OnFailure, [switch]$ContinueOnFailure, [Parameter()] [ValidateNotNullOrEmpty()] [string]$ChangeReason, [switch]$PassThru ) process { # -ContinueOnFailure is shorthand for -OnFailure Continue; both at once is ambiguous (which wins?), so refuse it # before anything is sent rather than silently preferring one. if ($PSBoundParameters.ContainsKey('OnFailure') -and $PSBoundParameters.ContainsKey('ContinueOnFailure')) { $PSCmdlet.ThrowTerminatingError([System.Management.Automation.ErrorRecord]::new( [System.ArgumentException]::new('Specify either -OnFailure or -ContinueOnFailure, not both. -ContinueOnFailure is shorthand for -OnFailure Continue.'), 'ConflictingFailureParameters', [System.Management.Automation.ErrorCategory]::InvalidArgument, $null)) } $newStepOnFailure = if ($PSBoundParameters.ContainsKey('OnFailure')) { $OnFailure } elseif ($ContinueOnFailure) { 'Continue' } else { 'FollowSchedule' } # Check connection first 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 } # Resolve names to IDs if using ByName parameter set if ($PSCmdlet.ParameterSetName -eq 'ByName') { try { $cs = Resolve-JIMConnectedSystem -Name $ConnectedSystemName $ConnectedSystemId = $cs.id $runProfiles = Invoke-JIMApi -Endpoint "/api/v1/synchronisation/connected-systems/$ConnectedSystemId/run-profiles" $runProfile = $runProfiles | Where-Object { $_.name -eq $RunProfileName } if (-not $runProfile) { Write-Error "Run Profile '$RunProfileName' not found for Connected System '$ConnectedSystemName'" return } $RunProfileId = $runProfile.id } catch { Write-Error "Failed to resolve names: $_" return } } if ($PSCmdlet.ShouldProcess($ScheduleId, "Add Schedule Step")) { Write-Verbose "Adding step to Schedule: $ScheduleId" try { # Get existing schedule with steps $schedule = Invoke-JIMApi -Endpoint "/api/v1/schedules/$ScheduleId" if (-not $schedule) { Write-Error "Schedule not found: $ScheduleId" return } # Determine step index $existingSteps = if ($schedule.steps) { $schedule.steps } else { @() } $maxStepIndex = if ($existingSteps.Count -gt 0) { ($existingSteps | Measure-Object -Property stepIndex -Maximum).Maximum } else { -1 } # If parallel, use same step index as previous; otherwise increment $newStepIndex = if ($Parallel -and $maxStepIndex -ge 0) { $maxStepIndex } else { $maxStepIndex + 1 } # Build the new step. Enum values must be sent as names, not numbers: the API # rejects numeric enum values on request DTOs (#1060). The failure setting goes as # onFailure, never continueOnFailure, so no legacy mapping applies (#1787). $newStep = @{ stepIndex = [int]$newStepIndex stepType = $StepType executionMode = if ($Parallel) { 'ParallelWithPrevious' } else { 'Sequential' } onFailure = $newStepOnFailure connectedSystemId = [int]$ConnectedSystemId runProfileId = [int]$RunProfileId } # Send the existing steps back as they are, their ids and failure settings included # (ConvertTo-JIMScheduleStepRequest), so adding a step changes no other step. $convertedSteps = @() foreach ($step in $existingSteps) { $convertedSteps += ConvertTo-JIMScheduleStepRequest -Step $step } # Build update body with existing steps plus new one $allSteps = $convertedSteps + @($newStep) $body = @{ name = $schedule.name description = $schedule.description triggerType = $schedule.triggerType patternType = $schedule.patternType isEnabled = $schedule.isEnabled daysOfWeek = $schedule.daysOfWeek runTimes = $schedule.runTimes intervalValue = $schedule.intervalValue intervalUnit = $schedule.intervalUnit intervalWindowStart = $schedule.intervalWindowStart intervalWindowEnd = $schedule.intervalWindowEnd cronExpression = $schedule.cronExpression steps = $allSteps } if ($PSBoundParameters.ContainsKey('ChangeReason')) { $body.changeReason = $ChangeReason } $result = Invoke-JIMApi -Endpoint "/api/v1/schedules/$ScheduleId" -Method 'PUT' -Body $body Write-Verbose "Added step to Schedule: $ScheduleId" if ($PassThru) { Invoke-JIMApi -Endpoint "/api/v1/schedules/$ScheduleId" } } catch { Write-Error "Failed to add Schedule step: $_" } } } } |