Script Output and Exit Status: Best Practices for Remote Execution

In an enterprise environment managing a large fleet of Windows endpoints, a PowerShell script that simply “runs” is not enough. To maintain a secure and observable fleet, your scripts must effectively communicate their success or failure back to the Hexnode UEM console.

This document defines the standard for handling PowerShell Output Streams, Return Codes, and common execution pitfalls. This ensures that a “Success” status in the Hexnode console actually translates to a successfully completed task on the device.

1. The Strategic Logic: “Observability at Scale”

When executing a custom script to Windows devices via Hexnode (Manage > Devices > Actions > Execute Custom Script), the platform relies on two main data channels to report back to the administrator:

• Return Codes (Exit Codes): A numerical integer that tells the Hexnode Agent if the script completed successfully or failed.
• Output Streams: The actual text (logs, errors, or success messages) returned by the script. This output is captured and displayed directly in the Action History page of the device in the Hexnode portal.

Why this matters?

• Reliability: Prevents “False Positives.” Without proper exit codes, Hexnode might mark a task as “Success” simply because the .ps1 file executed, even if the internal commands failed.
• Forensics: Sending clear text to the Output Stream provides immediate error logs right in the UEM portal, eliminating the need to manually extract local event logs from the endpoint or disrupt the end-user.

2. Implementation Workflow: The Standard Pattern

To ensure your scripts are “UEM-Aware,” you must explicitly manage how data is returned to Hexnode.

Step A: Managing the Return Code

By default, PowerShell returns an exit code of 0 if it reaches the end of the script without crashing. However, if a specific critical command fails inside your script, you must manually catch the error and force a non-zero exit code, so Hexnode records it as a failure.

Use the try…catch block to handle errors and pass the correct exit code:

Step B: Capturing the Output Streams for Action History

Hexnode captures the Standard Output to display in the Action History.

• Write-Host: Avoid using this for critical data you want logged. Write-Host writes directly to the local console display, which the UEM agent may not reliably capture.
• Write-Output: Use this. Data sent via Write-Output is sent down the pipeline and reliably captured by the Hexnode Agent to display in the Action History tab.

Step C: Managing Execution Context

By default, scripts deployed via Hexnode run with System-level permissions, applying changes across the entire device. If you are modifying user-specific settings (like HKCU registry keys or the user’s desktop), you will need to customize the script itself. You can tailor your script to target a specific user, or dynamically capture the currently logged-in user (for example, by utilizing $currentUser).

3. Handling Common Hexnode Scripting Pitfalls

Based on Hexnode’s Windows scripting documentation, here are the most common issues you must account for when building enterprise scripts:

A. 32-bit vs 64-bit Architecture Mismatches

If a command works perfectly on your local machine but returns an error like “The term ‘xxx’ is not recognized as the name of a cmdlet” in Hexnode, it is likely an architecture issue. Some commands only run on 64-bit PowerShell, but 32-bit PowerShell might be invoked.

The Fix: Force the script to relaunch as x64 by adding this snippet to the top of your script:

B. Scripts Remaining in an “In Progress” or “Unknown” State

• In Progress: This usually means your script is stuck waiting for user interaction (e.g., a prompt to confirm a deletion). Because the UEM agent runs silently in the background, the user cannot see the prompt, and the script hangs infinitely. Always use -Silent, -Quiet, -Confirm:$false, or -Force parameters in your cmdlets.
• Unknown: If the Action History shows “Unknown,” it means the Hexnode Agent was interrupted during execution. This usually happens if the device is manually restarted by the user or if your script contains a command that forces an immediate reboot before the script can report its exit code back to Hexnode.

C. TLS 1.2 Internet Access Failures

If your script involves downloading an external file (e.g., Invoke-WebRequest), it may fail with an “Unable to download from URI” error. This occurs because older versions of PowerShell default to deprecated TLS protocols.

The Fix: Force PowerShell to use TLS 1.2 at the beginning of your script:

4. Security & Compliance Guardrails

• Execution Policies: Ensure your Windows endpoints are configured to allow script execution. You can deploy a configuration profile via Hexnode to set the PowerShell Execution Policy to RemoteSigned or Bypass so your deployed .ps1 files are not blocked by the OS.
• Credential Handling: Never hard-code passwords or API keys in plain text. If you need to authenticate, utilize secure credential objects or deploy necessary certificates to the devices beforehand via Hexnode policies.
• Transcript Logging (Optional): If your compliance team requires full forensic backups of everything a script does locally on the machine, include the Start-Transcript -Path “C:\Logs\HexnodeScript.txt” command at the top of your file to log the entire session to a secure local directory.