functions/Remove-JS7CompletedOrder.ps1

function Remove-JS7CompletedOrder
{
<#
.SYNOPSIS
Removes an order that completed a workflow either with a cancelled or finished state
 
.DESCRIPTION
Orders in a worklfow by default are automatically removed upon completion. However, it is possible
to cause orders to remain in a workflow after completion. Such orders are either in a cancelled state
or in a finished state.
 
The cmdlet causes orders to be removed after completion.
 
The following REST Web Service API resources are used:
 
* /orders/remove_when_terminated
 
.PARAMETER OrderId
Specifies the identification of an order.
 
.PARAMETER AuditComment
Specifies a free text that indicates the reason for the current intervention,
e.g. "business requirement", "maintenance window" etc.
 
The Audit Comment is visible from the Audit Log view of the JOC Cockpit.
This argument is not mandatory, however, JOC Cockpit can be configured
to enforce Audit Log comments for any interventions.
 
.PARAMETER AuditTimeSpent
Specifies the duration in minutes that the current intervention required.
 
This information is shown in the Audit Log view. It can be useful when integrated
with a ticket system that logs the time spent on interventions with JS7.
 
.PARAMETER AuditTicketLink
Specifies a URL to a ticket system that keeps track of any interventions performed for JS7.
 
This information is shown in the Audit Log view of JOC Cockpit.
It can be useful when integrated with a ticket system that logs interventions with JS7.
 
.INPUTS
This cmdlet accepts pipelined order objects that are e.g. returned from the Get-JS7Order cmdlet.
 
.OUTPUTS
This cmdlet returns an array of order objects.
 
.EXAMPLE
Remove-JS7CompletedOrder -OrderId "#2021-01-19#T086350577-ap27"
 
Causes the indicated order to be removed upon completion of its workflow.
 
.LINK
about_JS7
 
#>

[cmdletbinding(SupportsShouldProcess)]
param
(
    [Parameter(Mandatory=$True,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)]
    [string] $OrderId,
    [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)]
    [string] $AuditComment,
    [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)]
    [int] $AuditTimeSpent,
    [Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelinebyPropertyName=$True)]
    [Uri] $AuditTicketLink
)
    Begin
    {
        Approve-JS7Command $MyInvocation.MyCommand
        $stopWatch = Start-JS7StopWatch

        if ( !$AuditComment -and ( $AuditTimeSpent -or $AuditTicketLink ) )
        {
            throw "$($MyInvocation.MyCommand.Name): Audit Log comment required, use parameter -AuditComment if one of the parameters -AuditTimeSpent or -AuditTicketLink is used"
        }

        $orderIds = @()
    }

    Process
    {
        $orderIds += $OrderId
    }

    End
    {
        if ( $orderIds.count )
        {
            $body = New-Object PSObject
            Add-Member -Membertype NoteProperty -Name 'controllerId' -value $script:jsWebService.ControllerId -InputObject $body
            Add-Member -Membertype NoteProperty -Name 'orderIds' -value $orderIds -InputObject $body

            if ( $AuditComment -or $AuditTimeSpent -or $AuditTicketLink )
            {
                $objAuditLog = New-Object PSObject
                Add-Member -Membertype NoteProperty -Name 'comment' -value $AuditComment -InputObject $objAuditLog

                if ( $AuditTimeSpent )
                {
                    Add-Member -Membertype NoteProperty -Name 'timeSpent' -value $AuditTimeSpent -InputObject $objAuditLog
                }

                if ( $AuditTicketLink )
                {
                    Add-Member -Membertype NoteProperty -Name 'ticketLink' -value $AuditTicketLink -InputObject $objAuditLog
                }

                Add-Member -Membertype NoteProperty -Name 'auditLog' -value $objAuditLog -InputObject $body
            }

            if ( $PSCmdlet.ShouldProcess( $Path, '/orders/remove_when_terminated' ) )
            {
                [string] $requestBody = $body | ConvertTo-Json -Depth 100
                $response = Invoke-JS7WebRequest -Path '/orders/remove_when_terminated' -Body $requestBody

                if ( $response.StatusCode -eq 200 )
                {
                    $ok = ( $response.Content | ConvertFrom-JSON ).ok

                    if ( !$ok )
                    {
                        throw "could not remove completed orders: $($response.message)"
                    }
                } else {
                    throw ( $response | Format-List -Force | Out-String )
                }
            }

            Write-Verbose ".. $($MyInvocation.MyCommand.Name): $($orderIds.count) completed orders removed"
        }

        Trace-JS7StopWatch -CommandName $MyInvocation.MyCommand.Name -StopWatch $stopWatch
        Update-JS7Session
    }
}