Writing scripts for remote actions on Windows
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:
Creating the script
Generic scripts and input variables
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.
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.dl
l) 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:
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:
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:
The methods of Nxt.CampaignAction to control campaigns are the following:
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
.
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.
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.