Run Scripts Remotely

The following PowerShell script for an app handling demonstrates the usage of multiple exit codes (10, 11, 12) and reboot code 100.

<# Demonstrates: - Exit codes for success/failure - Reboot code usage - App conflict handling #>

$ErrorActionPreference = "Stop"

$PkgName = "Example Application"
$RebootExitCode = 100

# Demo values:
# None
# Force Close
# Reboot
$ApplicationRestartBehavior = "Reboot"

$ConflictApps = @(
    @{ ProcessName = "notepad"; AppName = "Notepad" },
    @{ ProcessName = "winword"; AppName = "Microsoft Word" },
    @{ ProcessName = "excel"; AppName = "Microsoft Excel" }
)

function Get-RunningConflictApps {
    $runningApps = @()

    foreach ($app in $ConflictApps) {
        $process = Get-Process -Name $app.ProcessName -ErrorAction SilentlyContinue
        if ($process) {
            $runningApps += $app
        }
    }

    return $runningApps
}

function Stop-WithExitCode {
    param(
        [int]$Code,
        [string]$Message
    )

    if ($Code -eq 0) {
        Write-Host $Message
    }
    else {
        Write-Error $Message
    }

    exit $Code
}

function Handle-ConflictingApps {
    param($RunningApps)

    $appNames = ($RunningApps.AppName | Select-Object -Unique) -join ", "

    switch ($ApplicationRestartBehavior) {
        "None" {
            Stop-WithExitCode `
                -Code 12 `
                -Message "Installation of $PkgName cannot continue. Please close: $appNames"
        }

        "Force Close" {
            Write-Host "Closing conflicting applications: $appNames"

            foreach ($app in $RunningApps) {
                Stop-Process -Name $app.ProcessName -Force -ErrorAction SilentlyContinue
            }

            Start-Sleep -Seconds 3

            $stillRunning = Get-RunningConflictApps
            if ($stillRunning.Count -gt 0) {
                $stillRunningNames = ($stillRunning.AppName | Select-Object -Unique) -join ", "
                Stop-WithExitCode `
                    -Code 11 `
                    -Message "Failed to close: $stillRunningNames"
            }
        }

        "Reboot" {
            Write-Host "Installation of $PkgName requires a reboot because these apps are running: $appNames"
            Write-Host "Returning reboot exit code: $RebootExitCode"

            exit $RebootExitCode
        }

        default {
            Stop-WithExitCode `
                -Code 10 `
                -Message "Unknown ApplicationRestartBehavior value: $ApplicationRestartBehavior"
        }
    }
}

try {
    $runningApps = Get-RunningConflictApps

    if ($runningApps.Count -gt 0) {
        Handle-ConflictingApps -RunningApps $runningApps
    }

    Write-Host "No conflicting applications detected."
    Write-Host "All requirements are met."

    exit 0
}
catch {
    Stop-WithExitCode `
        -Code 1 `
        -Message "Unexpected error: $($_.Exception.Message)"
}

If you need the target endpoint to address some condition before running the main script (for example, make sure it was rebooted within the last 30 days), you can run a condition script:

• Action1 will run this script before the main script.
• If the condition script exits with a code other than 0 (this means that the condition was not met, and target endpoints are non-compliant), then Action1 will run the main script.
• The main script will bring the endpoint into compliance (for example, force a reboot if the number of days is more than 30).

To implement such a course of action, select Execute the script above only if the automation condition script returns a non-zero error code. Provide a condition script, specify its language, and exit codes.

NOTE: If there are multiple exit codes, enter them as a comma-separated list, without spaces. Do not use any other characters (such as semicolons).

• For details on the reboot behavior of Windows endpoints, refer to this section.
• For details on the reboot behavior of macOS endpoints, refer to this section.

This parameter instructs the offline or disconnected endpoints to retry the automation once they come online within the specified timeframe. The automation will be terminated if it exceeds this deadline.

Example configuration:

• Automation is scheduled to run at 2 am
• The deadline/maintenance window is set to 8 hours