PowerShell guidelines
The Absolute Reach® feature allows you to run PowerShell scripts on your Windows devices. Windows PowerShell is a command-line shell and scripting language. System Administrators use PowerShell to automate the administration of their devices' operating systems and the application processes that run on them.
Before you use Absolute Reach to deploy PowerShell scripts to Windows devices in your Absolute account, it's best practice to familiarize yourself with the schema supported by Absolute Reach.
NOTE Due to restrictions imposed by Microsoft, PowerShell is not supported on Windows 11 SE. The Reach® feature uses PowerShell and is not supported on devices running Windows 11 SE.
The Absolute schema supports the parsing of script parameters, meaning you can show parameters as labeled user-input fields in the Run Script wizard. When users use the wizard to create Run Script requests, they can enter a value for a script parameter directly in a labeled field.
To enable script parameters to be parsed, you need to adhere to the following guidelines:
- PowerShell scripts must be in UTF-8 format.
-
Include the following flag in the script header:
Copy.ABSOLUTEPARSE True
-
Ensure that all parameters that you want parsed are in the first parameter (Param) block. The block can be at the script level or the function level.
If there are multiple Param blocks in your script, the first block is parsed and all subsequent blocks are ignored.
- The parsed Param block can contain any number of parameters, except zero (0).
- Parameter names can't contain spaces, but all Unicode characters and camel case (for example DeviceName) are supported.
-
The following parameter attributes are supported:
-
Mandatory: to make a parameter show in the Run Script wizard as a required field, include the following in the parameter description:
CopyMandatory=$True
-
HelpMessage: to provide a description of the parameter or a list of possible values, include this attribute. HelpMessage text shows under the field on the Run Script wizard.
CopyHelpMessage="Your help message here"
NOTE Other parameter attributes are not supported at this time.
-
-
To ensure that users enter the correct type of data in each variable field, specify a type constraint for each parameter. The following type constraints can be parsed:
- [int]: 32-bit signed integer
- [long]: 64-bit signed integer
- [string]: Fixed length string of Unicode characters
- [char]: Unicode 16-bit character
- [decimal]: 128-bit decimal value
-
To show instructions or notes at the top of the script to a user using View Script in the Run Script wizard, enter comments in the following format at the beginning of the script:
Copy<#
<Your instructions or notes …>
#>
Script sample
<#
Enter the SSID and security key for the wireless network you want devices to connect to.
.SYNOPSIS Configure a wireless network profile for a device
.DESCRIPTION Add a profile by passing the wireless network's SSID and key to a device
.NOTES Sample script only. Do not deploy.
.RELEASED 03-Feb-2018
.AUTHOR XYZ Corporation
.ABSOLUTEPARSE True
--------------------------------------------------------------------------------------------------------------------
#>
param(
[parameter(Mandatory=$True, HelpMessage="Wireless network SSID name")] [string] $SSID,
[parameter(Mandatory=$True, HelpMessage="Wi-Fi security key")] [string] $Key
)
$xmlpath = 'C:\ProgramData\Test\wireless.xml'
$ans = ''
[System.Text.Encoding]::ASCII.GetBytes($ssid) | % { $ans += "{0:X2}" -f $_ }
New-Item $xmlpath -type file -force
… <end of example>
Parsed script sample in Run Script wizard
If your script generates output, you can add code to your script to enable that output to be available in custom device fields in the Secure Endpoint Console.
NOTE If you want to collect user input that you can review in the Secure Endpoint Console, we recommend that you use a Send Message request instead of a script. If you use a script, the custom device fields may fail to be populated with the users' responses.
To show script output in custom device fields:
- Log in to the Secure Endpoint Console as a user with Manage permissions for Reach Script.
- On the navigation bar, click > Custom fields > Manage device fields.
- Create one or more new custom device fields for the script output. The schema supports custom device fields in both text and date formats.
-
In your PowerShell script, enter the code for the custom device fields in a try catch block:
Copytry {
} catch [Exception] {
Write-Host $_.Exception.Message
Write-Host $_.InvocationInfo.PositionMessage
} -
To import the Absolute Reach helper library, add the following line of code to the try catch block:
Copy$libraryPath = $Env:ProgramData + "\CTES\Components\ANS\CDFClientLibrary.dll"
[Reflection.Assembly]::LoadFile($libraryPath) -
For each custom device field that you want to update, add the following line of code after the lines added in the previous step:
Copy[CDFClientLibrary.CDFParser]::AddCDF("<CDFName>", <CDF Value>, "<CDF Type>")
Where the variables are defined as:
- <CDF Name>: the exact name of the custom device field in the Secure Endpoint Console
-
<CDF Value>: the PowerShell script variable (for example, $OSWindowsVersion) that you want to show in the custom device field
NOTE To pass a null value, use [NullString]::Value.
-
<CDF Type>: the type of data supported by the custom device field. The following types are supported:
- text: string of Unicode characters
- date: date format must be mm/dd/yyyy
-
To parse the CDF collection and generate the output file that will be uploaded to the Absolute server, add the following line of code after the lines of code entered in the previous step:
Copy[CDFClientLibrary.CDFParser]::CompleteCDFProcessing()
Script sample
Copy#
# Get the version of windows operating system
#
function GetOSWindowsVersion {
return [string] (Get-CimInstance Win32_OperatingSystem).version
}
#
# Get the date that the script was run
#
function GetCurrentDate {
# the current date is the date that the script was run
$date = Get-Date
return [string] $date.month + "/" + $date.day + "/" + [string]$date.year
}
$OSWindowsVersion = GetOSWindowsVersion
$CurrentDate = GetCurrentDate
Write-Host $OSWindowsVersion
Write-Host $CurrentDate
# Sample code to add cdf information
# Code should be in a try catch block
try {
# Import Client CDF Library
$libraryPath = $Env:ProgramData + "\CTES\Components\ANS\CDFClientLibrary.dll"
[Reflection.Assembly]::LoadFile($libraryPath)
# Add multiple CDFs to cdf collection
[CDFClientLibrary.CDFParser]::addCDF("OSWindowsVersion", $OSWindowsVersion, "text")
[CDFClientLibrary.CDFParser]::addCDF("OSWindowsCheckDate", $CurrentDate, "date")
# When script is finished adding CDFs, parse collection and output JSON with cdf.out name
[CDFClientLibrary.CDFParser]::completeCDFProcessing()
} catch [Exception] {
Write-Host $_.Exception.Message
Write-Host $_.InvocationInfo.PositionMessage
} - In the Secure Endpoint Console, create a Run Script request to upload the script and deploy it to your devices.
After the script runs on a device, the script output file is uploaded to the Absolute database and the devices' custom device fields are updated.
To view the updated fields, complete the following steps:
- On the navigation bar, click Devices.
- Click > Edit columns. The Show/Hide Columns dialog opens.
- Search for "Custom Field" and add the applicable fields.
- Optionally, save the report as a new report.