Executing custom scripts for Windows

The Execute Custom Script remote action allows IT administrators to automate routine system operations, software deployments, and configurations on Windows endpoints by pushing scripts that execute automatically without manual intervention.

What is Windows Scripting in Hexnode?

Scripting utilizes command-line sequences to perform complex tasks not natively supported by the UEM interface. By deploying scripts over-the-air, organizations can ensure consistent system states and high operational efficiency across their entire fleet.

• Automation: Executes time-consuming tasks like server setup or mass installations automatically.
• Scalability: Pushes configurations to multiple PCs and tablets simultaneously.
• Flexibility: Supports advanced logic, including loops and conditionals, for sophisticated management.

Supported Scripting Languages

Hexnode UEM supports the primary scripting environments used in Windows administration.

Prerequisites and Constraints

Before deploying scripts, verify the following environmental and safety requirements:

Device Requirements

• OS Support: Windows 10 (v1709+) and Windows 11 PCs/tablets.
• Enrollment: Devices must be enrolled via the Hexnode Installer app to ensure the latest Hexnode Agent app is present.

Functional Constraints

• No User Interaction: Scripts that require UI interactions (e.g., opening an app window, playing a video, or requiring user clicks) are not supported.
• Naming Conventions: Filenames must not contain: / : ? \ * | “ [ ] @ ! % ^ #.
• Safety: Always validate scripts on a single test device before bulk deployment to avoid business continuity disruptions.

Step-by-Step Guide: Creating and Uploading Scripts

1. Creating a Script File

The simplest method is using the Notepad editor on a Windows PC.

• For PowerShell (.ps1):
  Powershell Script

  New-Item -Path 'D:\temp\Hexnode Folder' -ItemType Directory

  1	New-Item -Path 'D:\temp\Hexnode Folder' -ItemType Directory

• For Batch (.bat / .cmd):
  Bash Script

  @echo off echo "Hello">C:\Hexnode.txt

  1 2	@echo off echo "Hello">C:\Hexnode.txt

2. Uploading to Hexnode Repository

1. Navigate to the Content tab in the Hexnode UEM portal.
2. Select My Files and click Add.
3. Enter a file name and upload your .ps1, .bat, or .cmd file.
4. Click Save.

Executing the Remote Script

Follow these steps to deploy the script from the Hexnode console:

1. Navigate to Manage > Devices.
2. Select the target Windows PCs or tablets.
3. Select Actions > Others > Execute Custom Script.
4. Choose Windows as the platform.
5. Select Script File Source:
   • Upload file: Select a file directly from your machine.
   • Hexnode repository: Pick a file previously added to the Content tab.
     
     Note:

     
     You can also use Hexnode Genie to generate scripts.
     

6. Arguments: Enter command-line variables separated by spaces. Pro Tip: Enclose wildcards in double quotes (e.g., “%name%”) if the values contain multiple words.
7. Timeout: Set the duration (Minimum 15 mins; 30 mins recommended). Scripts exceeding this limit will be terminated.
8. Click Execute.

Supported Wildcards for Arguments

%devicename%, %model%, %serialnumber%, %imei%, %osname%, %osversion%, %deviceid%, %phonenumber%, %name%, %email%, %username%, %domain%, %netbiosname%, %assettag%, %department%, %devicenotes%, %userprincipalname%, %alternateemail%.

Troubleshooting Guides

Resolving Windows script failures often requires adjusting execution parameters, bypassing UI interaction blocks, ensuring TLS compatibility, or allowlisting management agents within security software (EDR).

1. ‘Execute Custom Script’ remains in ‘In Progress’ state

• Description: Scripts remain “In progress” for an extended period in the Action History.
• Cause: The script likely requires user or UI interaction, which the system blocks in the background.
• Solution: Use silent or non-interactive parameters. Including keywords like -silent, -passive, -quiet, or -nointeractive can allow cmdlets to run without prompts.

2. PowerShell Internet Access Errors

• Description: Errors such as “Unable to download from URI…” when scripts try to fetch modules or files.
• Cause: PowerShell may not be using the TLS 1.2 protocol required by modern web endpoints.
• Solution: Force the use of TLS 1.2 by adding this command to the start of your script:
  Powershell Internet access error script

  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

  1	[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

3. Cmdlet/Function Not Recognized

• Description: Commands that work in the local Terminal fail when executed via script.
• Cause: Certain commands require PowerShell x64 and fail in 32-bit environments.
• Solution: Include this snippet at the beginning of your script to force a relaunch in x64:
  cmdlet not recognized error script

  if ($PSHOME -like "*syswow64*") { Write-Output 'Relaunching as x64' & (Join-Path ($PSHOME -replace 'syswow64', 'sysnative') powershell.exe) -File $Script:MyInvocation.MyCommand.Path @args Exit }

  1	if ($PSHOME -like "*syswow64*") { Write-Output 'Relaunching as x64' & (Join-Path ($PSHOME -replace 'syswow64', 'sysnative') powershell.exe) -File $Script:MyInvocation.MyCommand.Path @args Exit }

4. ‘Unknown’ Action Status

• Description: The Action History shows “Unknown” and cannot fetch output.
• Cause: The Hexnode Agent was restarted during execution (e.g., manual restart, third-party app trigger, or the script itself contained a restart command).
• Solution: Ensure the device is not restarted manually or by other apps until the script completes. If a restart is necessary, perform it as a separate action.

5. Abrupt Termination (“Device must be awake and idle”)

• Description: Execution fails with a termination error message.
• Cause: Issues include lack of internet, device inactivity, or blocking by EDR/Antivirus software.
• Solution:
  • Verify the device is active and connected to Wi-Fi.
  • Allowlist the Hexnode agent (HexnodeAgent) in your EDR/Antivirus portal.
  • Ensure the script has correct execution level parameters. Use $currentUser if the script must run only for the logged-in user.

Frequently Asked Questions (FAQs)

Can a script be executed that opens a browser for the user?

No. Hexnode does not support scripts that interact with the Device UI or require user interaction. All scripts must run in the background.

How can the output of a successful script be viewed?

Navigate to Manage > Devices > [Your Device] > Action History. Locate the script action and click Show Output. This displays the result returned by the script.

What version of PowerShell is supported?

Hexnode supports standard PowerShell scripts; however, success depends on the version available on the local OS. For newer modules, you may need to force TLS 1.2 as described in the troubleshooting section.

Is the 30-minute timeout mandatory?

The default is 30 minutes, but you can set a minimum of 15 minutes. If a script is complex (e.g., large software install), ensure the timeout is sufficient to prevent abrupt termination.