If you need help performing the operations described in this article, please contact your Nexthink Certified Partner.
This article details the process of preparing Nexthink remote action scripts on Windows. The scripts are written in PowerShell, a Microsoft scripting language built on the Windows .NET Framework, and then signed with a certificate for security purposes. PowerShell scripts are suited for automating tasks and configuration management; They allow for remote actions to be run on employee devices.
The main use cases for remote actions are on-demand data collection from devices, self-healing tasks and modifying configuration settings.
The article assumes that the reader is familiar with PowerShell scripting.
For more information about writing scripts for remote actions on Community, refer to the following documentation:
Generic scripts are useful in situations where a signed script requires customization. Modifying a signed script breaks its signature, but a generic script can be customized through parameters, keeping the signature intact.
Declare formal parameters at the beginning of a PowerShell script to make it generic. When editing the relevant remote action, the parameter values can be modified in the Nexthink web interface.
For example, to make a script that reads from a generic registry key, declare a parameter in the script that contains the path to the key in the registry. Several remote actions may use the same script to read from different registry keys by supplying a different path to the parameter in the script.
param(
[string]$filePath,
[string]$regPath
)
When uploading the script during the remote action configuration, the system recognizes the parameters of any imported PowerShell script and lists them in the Parameters section. Provide actual values to the parameters in the text input boxes displayed to the right of each parameter name.
Actual values are always passed to the script as text: if the script declares parameters with a type other than string, ensure that you provide values that the script can convert to their expected type.
Creating output variables
Executing a script may generate output that you want to store as on-demand data. Nexthink provides a .NET assembly (nxtremoteactions.dll) that is installed on an employee device at the same time as the Collector. The assembly includes a class called Nxt that provides the methods to write results to the data layer.
To use the Nxt class, add the following line at the beginning of a PowerShell script for remote actions:
Use the Nxt class methods to write the desired outputs. All write methods accept two arguments: the name of the output and the value to write. For instance, to write the size of a file to the data layer:
[Nxt]::WriteOutputSize("FileSize", $fileSize)
When uploading the script during the remote action configurations, the system recognizes the calls to write outputs in the script and lists the output variables under the Outputs section below the script text. Set the output's label to indicate how to refer to it in investigations and metrics.
The ending of each written method indicates the type of output. Find the list of available methods and the corresponding PowerShell type of the value to be written in the table below:
Nxt write method
PowerShell type
Constraints
WriteOutputString
[string]
0 - 1024 characters (output truncated if bigger)
WriteOutputBool
[bool]
true / false
WriteOutputUInt32
[uint32]
Min: 0
Max: 4 294 967 295
WriteOutputFloat
[float]
Min: -3.4E+38
Max: 3.4E+38
WriteOutputSize
[float]
Min: 0
Max: 3.4E+38
WriteOutputRatio
[float]
WriteOutputBitRate
[float]
WriteOutputDateTime
[DateTime]
DD.MM.YYYY@HH:MM
WriteOutputDuration
[TimeSpan]
Min: 0 ms
Max: 49 days
Precision in milliseconds
WriteOutputStringList
[string[]]
Same as string
Implementing campaigns
Combine remote actions with campaigns to help employees solve issues independently. Campaigns let you inform employees about the detection of an issue and guide them through its resolution.
To display a campaign on the desktop of an employee who is interacting with a device:
The campaign must have a Remote action trigger and be published.
The script of the remote action can be executed either:
In the context of the employee, if the action does not need any special privileges.
In the context of the local system account, if the action needs administrative privileges.
Obtaining a campaign identifier
The methods to run a campaign from a remote action require a campaign identifier to be passed as an argument. You can use both the campaign NQL ID (recommended) and the campaign UID (classic option).
Support for the NQL ID as an identifier requires Collector version 23.5 or later.
To pass the campaign identifier to a remote action, declare a parameter in the script of the remote action for each required campaign. Use the NQL ID (or UID) as the actual value for the parameter when editing the remote action.
For more information on how to get the NQL ID or the UID of a campaign, refer to the Triggering a campaign documentation.
Running a campaign from the script of a remote action
To interact with campaigns, the remote action script must load a .NET assembly (nxtcampaignaction.dll) that is installed on an employee device along with Collector. The assembly includes the class Nxt.CampaignAction which provides the methods of controlling the execution of a campaign and getting the responses from an employee.
To load the assembly, add the following line at the beginning of the script:
Run the campaign identified by the campaignUid and wait until the employee finishes answering the campaign. The campaignUid argument can contain either the UID or the NQL ID (recommended). Return the response in an object of type NxTrayResp.
[nxt.campaignaction]::(string campaignUid, int timeout)
Run the campaign identified by the campaignUid and wait until the employee finishes answering the campaign or after the specified amount of time defined by timeout (in seconds) elapses. The campaignUid argument can contain either the UID or the NQL ID (recommended). Return the response in an object of type NxTrayResp.
Run the campaign identified by the campaignUid. The campaignUid argument can contain either the NQL ID (recommended) or the UID.
string GetResponseStatus(NxTrayResp response)
Given a response object of type NxTrayResp, the method returns a string that reflects the status of the campaign. Possible values for the status:
fully: the employee has fully answered the campaign questions.
declined: the employee has declined to participate in the campaign.
postponed: the employee has agreed to participate in the campaign.
timeout: the system timed out the campaign before the employee finished answering it.
connectionfailed: the script was unable to connect to the Collector component that controls campaign notifications due to a technical error in communication between Collector components.
notificationfailed: the script was unable to display the campaign successfully, due to one of the following:
The campaign definition could not be retrieved from the platform because of a non-existing campaign or non-published campaign.
Another campaign is already being displayed to employees.
A non-urgent campaign cannot be shown due to the focus protection or do-not-disturb rules of Collector. Refer to the Limiting the reception rate of campaigns documentation for more information.
Given a response object of type NxTrayResp and the label that identifies a question in the campaign, the method returns the response given by the employee.
In the case of a single-answer question, the returned string array only has one element.
In the case of a multiple-answer question, the returned string array has as many elements as answers selected by the employee. Optional free text is ignored.
If the employee has not fully answered the campaign, for example, status is not fully, the returned string array is empty. Optional free text is ignored.
For security reasons, remote actions for self-help scenarios ignore the optional free text answers of multiple answer or opinion scale questions. It serves no use to include optional free text answers in campaigns to be used exclusively in self-help scenarios.
Encoding the script
PowerShell script files must be encoded in UTF-8 with byte order mark (BOM). BOM is a Unicode character that must be present at the beginning of the file, whose representation in UTF-8 is the following sequence of three bytes, in hexadecimal: EF BB BF.
Each line of code must end with the following character sequence in Windows: CR+LF.
Ensure proper encoding to avoid errors or nonfunctioning scripts.
Code examples
Calling a campaign
In this example, the remote action executes a basic campaign call by its ID, outputting a status message if successful or an error message if unsuccessful.
In this example, the remote action calls for campaign answer data and outputs it as an array. Each answer is represented by its corresponding numbered option. Note that PowerShell uses 0 to n-1 indexing.
# Function to get campaign responsefunctionGet-CampaignResponse ([string]$CampaignId) {return [nxt.campaignaction]::RunCampaign($CampaignId, $CAMPAIGN_TIMEOUT)}# Function to get campaign statusfunctionGet-CampaignResponseStatus ($Response) {return [nxt.campaignaction]::GetResponseStatus($Response)}# Function to get response answersfunctionGet-CampaignResponseAnswer ($Response, [string]$QuestionName) {return [nxt.campaignaction]::GetResponseAnswer($Response, $QuestionName)[0]}#get campaign response$campaignResponse =$null$campaignResponse =Get-CampaignResponse-CampaignId $campaignId# Get campaign status$status =$null$status =Get-CampaignResponseStatus-Response $campaignResponseWrite-Host"The response status is $status"# Get response answers$answersArray =$null$answer =Get-CampaignResponseAnswer-Response $campaignResponse -QuestionName "Question1"Write-Host"The answer is $answer"
Running a campaign with a timeout
In this example, the remote action is set to run a campaign that times out and closes after a specified amount of time, using seconds as input.
# Run a campaign with timeout# timeout is in seconds (100s or 00:01:40)$campaignId ="#my_campaign_nql_id"$timeout =100functionGet-CampaignResponse ([string]$CampaignId) {return [nxt.campaignaction]::RunCampaign($CampaignId, $timeout)}functionGet-CampaignResponseStatus ($Response) {return [nxt.campaignaction]::GetResponseStatus($Response)}$result =Get-CampaignResponse-CampaignId $campaignId -timeout $timeout$status =Get-CampaignResponseStatus-Response $resultif ($status -eq"fully") {Write-Output"Campaign succeeded"} else {Write-Output"Status is $status"}
Running a non-blocking campaign
In this example, the remote action does not require user input and continues executing after triggering a campaign. The user can dismiss the campaign at any point. This is used mainly for providing users with information rather than obtaining data.
In this example, the remote action script loads the .dll file installed on a device alongside Collector, which acts as a bridge between Collector and any remote action executions. It issues commands from PowerShell scripts to Collector, allowing the use of specialized functions that begin with [Nxt.CampaignAction].
The remote action executes a campaign using the Nxt.CampaignAction]::RunCampaign function with the campaign ID and a timeout measured in seconds as input. Then, it collects the user's response or lack thereof and uses that data to determine a status. If the user responds yes, the remote action starts a process, in this case, Notepad.
Add-Type-Path "$env:NEXTHINK\RemoteActions\nxtcampaignaction.dll"$CampaignUid ="<NQL ID of a single-answer campaign>"$maxWaitTimeinSeconds =60$result = [Nxt.CampaignAction]::RunCampaign($CampaignUid, $maxWaitTimeinSeconds)$status = [Nxt.CampaignAction]::GetResponseStatus($result)if ($status -eq"fully") { $questionName ="question1" $choiceName =[Nxt.CampaignAction]::GetResponseAnswer($result, $questionName)if ($choiceName -eq"yes") {# user has confirmed - let's do some actions:Start-Processnotepad.exe }}
Checking if a specific application is present on the device
In this example, the remote action checks if the application name you provide as input is present on the device using Kanopy:
## Input parameters definition#param( [Parameter(Mandatory =$true)][string]$application_name)# End of parameters definition$env:Path ='C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\'## Constants definition#$ERROR_EXCEPTION_TYPE =@{Environment ='[Environment error]' Input ='[Input error]' Internal ='[Internal error]'}Set-Variable-Name 'ERROR_EXCEPTION_TYPE'-Option ReadOnly -Scope Script -Force$LOCAL_SYSTEM_IDENTITY ='S-1-5-18'Set-Variable-Name 'LOCAL_SYSTEM_IDENTITY'-Option ReadOnly -Scope Script -Force$REMOTE_ACTION_DLL_PATH ="$env:NEXTHINK\RemoteActions\nxtremoteactions.dll"Set-Variable-Name 'REMOTE_ACTION_DLL_PATH'-Option ReadOnly -Scope Script -Force$WINDOWS_VERSIONS =@{Windows7 ='6.1' Windows8 ='6.2' Windows81 ='6.3' Windows10 ='10.0' Windows11 ='10.0'}Set-Variable-Name 'WINDOWS_VERSIONS'-Option ReadOnly -Scope Script -Force## Invoke Main#functionInvoke-Main ([hashtable]$InputParameters) { $exitCode =0 $appPresent =$falsetry {Add-NexthinkRemoteActionDLLTest-RunningAsLocalSystemTest-MinimumSupportedOSVersion-WindowsVersion 'Windows8'Test-InputParameter-InputParameters $InputParameters $appPresent =Invoke-CheckApplcationExistance-appName $InputParameters.application_name } catch {Write-StatusMessage-Message $_ $exitCode =1 } finally {Update-EngineOutputVariables-applicationPresent $appPresent }return $exitCode}## Template functions#functionAdd-NexthinkRemoteActionDLL {if (-not (Test-Path-Path $REMOTE_ACTION_DLL_PATH)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) Nexthink Remote Action DLL not found. " }Add-Type-Path $REMOTE_ACTION_DLL_PATH}functionTest-RunningAsLocalSystem {if (-not (Confirm-CurrentUserIsLocalSystem)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script must be run as LocalSystem. " }}functionConfirm-CurrentUserIsLocalSystem { $currentIdentity =Get-CurrentIdentityreturn $currentIdentity -eq $LOCAL_SYSTEM_IDENTITY}functionGet-CurrentIdentity {return [security.principal.windowsidentity]::GetCurrent().User.ToString()}functionTest-MinimumSupportedOSVersion ([string]$WindowsVersion, [switch]$SupportedWindowsServer) { $currentOSInfo =Get-OSVersionType $OSVersion = $currentOSInfo.Version -as [version] $supportedWindows = $WINDOWS_VERSIONS.$WindowsVersion -as [version]if (-not ($currentOSInfo)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script could not return OS version. " }if ( $SupportedWindowsServer -eq$false-and $currentOSInfo.ProductType -ne1) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script is not compatible with Windows Servers. " }if ( $OSVersion -lt $supportedWindows) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script is compatible with $WindowsVersion and later only. " }}functionGet-OSVersionType {returnGet-WindowsManagementData-Class Win32_OperatingSystem |Select-Object-Property Version,ProductType}functionGet-WindowsManagementData ([string]$Class, [string]$Namespace ='root/cimv2') {try { $query = [wmisearcher] "Select * from $Class" $query.Scope.Path ="$Namespace" $query.Get() } catch { throw "$($ERROR_EXCEPTION_TYPE.Environment) Error getting CIM/WMI information. Verify WinMgmt service status and WMI repository consistency. "
}}functionWrite-StatusMessage ([psobject]$Message) { $exceptionMessage = $Message.ToString()if ($Message.InvocationInfo.ScriptLineNumber) { $version =Get-ScriptVersionif (-not [string]::IsNullOrEmpty($version)) { $scriptVersion ="Version: $version. " } $errorMessageLine = $scriptVersion +"Line '$($Message.InvocationInfo.ScriptLineNumber)': " }$host.ui.WriteErrorLine($errorMessageLine + $exceptionMessage)}functionGet-ScriptVersion { $scriptContent =Get-Content$MyInvocation.ScriptName|Out-Stringif ($scriptContent -notmatch'<#[\r\n]{2}.SYNOPSIS[^\#\>]*(.NOTES[^\#\>]*)\#>') { return } $helpBlock =$Matches[1].Split([environment]::NewLine)foreach ($line in $helpBlock) {if ($line -match'Version:') {return $line.Split(':')[1].Split('-')[0].Trim() } }}functionTest-StringNullOrEmpty ([string]$ParamName, [string]$ParamValue) {if ([string]::IsNullOrEmpty((Format-StringValue-Value $ParamValue))) {throw"$($ERROR_EXCEPTION_TYPE.Input) '$ParamName' cannot be empty nor null. " }}functionFormat-StringValue ([string]$Value) {return $Value.Replace('"','').Replace("'",'').Trim()}## Input parameter validation#functionTest-InputParameter ([hashtable]$InputParameters) {Test-StringNullOrEmpty`-ParamName 'application_name'`-ParamValue $InputParameters.application_name}## application management#functionInvoke-CheckApplcationExistance ([string]$appName) { $installedApps =Get-CimInstance-Query "SELECT * FROM Win32_Product WHERE Name LIKE '%$appName%'"if ($installedApps) {return$true } else {return$false }}## Nexthink Output management#functionUpdate-EngineOutputVariables ([bool]$applicationPresent) { [nxt]::WriteOutputBool('application_present', $applicationPresent)}## Main script flow#[environment]::Exit((Invoke-Main-InputParameters $MyInvocation.BoundParameters))
Checking if a specific application is present on the device: error handling
In this example, the remote action uses the application log path and error code as input and then parses the logs for the specified error code. If this code is present, it outputs an error message:
## Input parameters definition#param( [Parameter(Mandatory =$true)][string]$application_log_path, [Parameter(Mandatory =$true)][string]$error_code)# End of parameters definition$env:Path ='C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\'## Constants definition#$ERROR_EXCEPTION_TYPE =@{Environment ='[Environment error]' Input ='[Input error]' Internal ='[Internal error]'}Set-Variable-Name 'ERROR_EXCEPTION_TYPE'-Option ReadOnly -Scope Script -Force$LOCAL_SYSTEM_IDENTITY ='S-1-5-18'Set-Variable-Name 'LOCAL_SYSTEM_IDENTITY'-Option ReadOnly -Scope Script -Force$REMOTE_ACTION_DLL_PATH ="$env:NEXTHINK\RemoteActions\nxtremoteactions.dll"Set-Variable-Name 'REMOTE_ACTION_DLL_PATH'-Option ReadOnly -Scope Script -Force$WINDOWS_VERSIONS =@{Windows7 ='6.1' Windows8 ='6.2' Windows81 ='6.3' Windows10 ='10.0' Windows11 ='10.0'}Set-Variable-Name 'WINDOWS_VERSIONS'-Option ReadOnly -Scope Script -Force## Invoke Main#functionInvoke-Main ([hashtable]$InputParameters) { $exitCode =0 $outputs =@{'error_message'="-"'error_found'=$false }try {Add-NexthinkRemoteActionDLLTest-RunningAsLocalSystemTest-MinimumSupportedOSVersion-WindowsVersion 'Windows8'Test-InputParameter-InputParameters $InputParameters $outputs = Invoke-CheckApplicationLogError -applicationLogPath $InputParameters.application_log_path -errorCode $InputParameters.error_code
} catch {Write-StatusMessage-Message $_ $exitCode =1 } finally {Update-EngineOutputVariables-OutputData $outputs }return $exitCode}## Template functions#functionAdd-NexthinkRemoteActionDLL {if (-not (Test-Path-Path $REMOTE_ACTION_DLL_PATH)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) Nexthink Remote Action DLL not found. " }Add-Type-Path $REMOTE_ACTION_DLL_PATH}functionTest-RunningAsLocalSystem {if (-not (Confirm-CurrentUserIsLocalSystem)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script must be run as LocalSystem. " }}functionConfirm-CurrentUserIsLocalSystem { $currentIdentity =Get-CurrentIdentityreturn $currentIdentity -eq $LOCAL_SYSTEM_IDENTITY}functionGet-CurrentIdentity {return [security.principal.windowsidentity]::GetCurrent().User.ToString()}functionTest-MinimumSupportedOSVersion ([string]$WindowsVersion, [switch]$SupportedWindowsServer) { $currentOSInfo =Get-OSVersionType $OSVersion = $currentOSInfo.Version -as [version] $supportedWindows = $WINDOWS_VERSIONS.$WindowsVersion -as [version]if (-not ($currentOSInfo)) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script could not return OS version. " }if ( $SupportedWindowsServer -eq$false-and $currentOSInfo.ProductType -ne1) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script is not compatible with Windows Servers. " }if ( $OSVersion -lt $supportedWindows) {throw"$($ERROR_EXCEPTION_TYPE.Environment) This script is compatible with $WindowsVersion and later only. " }}functionGet-OSVersionType {returnGet-WindowsManagementData-Class Win32_OperatingSystem |Select-Object-Property Version,ProductType}