Creating a remote action
Last updated
Last updated
Remote actions let you run executable scripts on the devices of the employees from another system either manually or automatically.
Applies to platforms | Windows | macOS |
To create a new remote action:
Log in to the Finder as a user with the right to edit remote actions.
Select the Remote actions section on the left-hand side panel of the main window.
Right-click the header of the section or the empty area below it.
Select Create new remote action from the menu. The form to define the new remote action shows up in a new tab.
Type in an appropriate name for the action by replacing the temporary name Untitled remote action n .
Optional: Briefly describe the purpose of the remote action in the field labeled Enter description here....
In the SCHEDULE section, choose how to trigger the execution of the remote action:
Optional: Tick Automatically run the remote action to let the system trigger the remote action on a selected group of devices. Once the box is ticked, the Finder displays completely the sentence as Automatically run the remote action on the following devices (evaluated every [period]) and opens up the controls to specify the devices on which to act:
Choose the evaluation period of the investigation that retrieves the devices on which to act. There are three possible choices (see the maximum number of remote actions that you can define):
1 hour (default): for normal evaluation frequency.
10 minutes: for medium evaluation frequency.
1 minute: for fast evaluation frequency.
Specify the target devices by dragging an investigation on devices and dropping it into the area labeled Drag & Drop device investigation here.
The time frame of the investigation must be the full available period or during the last n days, hours, or minutes.
For fast evaluated investigations (frequency of 1 minute), the investigation must not compute aggregates and its time frame must be shorter than or equal to 1 hour.
Optional: Right-click the dropped investigation and select Run... to see the devices that would be targeted. Keep in mind that the Finder displays the results of a single Engine only, so the actual number of target devices may be much bigger in a multi-Engine setup. Get more information at the moment of saving the remote action.
Define the triggering period of the remote action by selecting a value and a unit from the lists inside the sentence Trigger the remote action [value] [unit] on devices that are still returned by the investigation. A device that executes a remote action and responds to it will not execute the same remote action again until the triggering period has elapsed, and only if the device is still a target (part of the results of the investigation). The triggering period must be bigger than or equal to the evaluation period.
For remote actions whose investigations to select target devices are based on activities or events, ensure that every evaluation of a device as a target triggers the remote action once and only once by choosing a triggering period that matches the time frame of the investigation.
Optional: Tick Allow manual triggering of the script on these devices to let users with the right to edit remote actions or with the remote action included in their roles to manually trigger the execution of the remote action on particular devices. Once the box is ticked, the Finder displays a list for you to choose the devices on which the remote action may be manually triggered:
Choose any to let users manually trigger the remote action on any of all the available devices.
Choose with keyword to let users manually trigger the remote action on devices tagged with a particular keyword. If you choose this option, two additional lists show up to let you choose one category on devices and the exact keyword.
Optional: Tick The remote action can be triggered on multiple devices at once so that users can manually run the remote action on a selection of multiple devices. By default, to prevent misuse of remote actions, users can manually run a remote action on a single device only.
As a rule of thumb, do not allow for potentially dangerous remote actions to be triggered manually on multiple devices. For example, do not allow multiple manual triggering of remote actions that require rebooting a device or that are network intensive.
In the SCRIPT section, select either the Windows or the macOS tab, depending on the target platform of the remote action. Provide scripts for both platforms if the remote action targets both Windows and Mac devices.
Click Import... to open the script that the remote action will execute.
If in the Windows tab:
Select a PowerShell script from the dialog. The dedicated text area displays the script with syntax highlighting. Below the text area, the Finder shows a security message about the script signature:
The script is unsigned, for scripts that are not signed.
The script is signed by: [author], for scripts that include a digital signature.
Optional: Click the button Show certificate to open a standard dialog that shows the certificate.
If in the macOS tab:
Select a package (tar.gz) file, that encapsulates a Bash script and its signature from the dialog. The dedicated text area displays the script with syntax highlighting.
The signature for macOS scripts is mandatory, but not displayed in Finder, as stated in the message below the text area for the script.
Optional: Click Export... to export the displayed script to an external file. This is particularly useful if you want to modify a script that was provided as part of a content pack.
Select the Purpose of the remote action. Tick at least one of the following options:
Data collection, for remote actions whose main goal is to retrieve data on demand.
Remediation, for remote actions whose main goal is to fix an issue on the device.
Tick both options if the purpose of the remote action combines on-demand data retrieval and issue remediation.
If the script includes any formal parameters, these are listed under the Parameters subsection.
Type in the actual values to the right of each of the parameters listed. The actual values substitute the named parameters in the script during its execution.
Warning: Do not enclose the actual values for the parameters within any kind of quotation marks. Some scripts may require the use of two consecutive double-quotes to indicate an empty value for a parameter ("").
Each parameter indicates its platform scope, Windows or Mac, with an icon placed to the right of its value. If the remote action targets both platforms, a parameter with the same name in the two scripts displays both icons and gets the same value.
If the script provides any outputs, these are listed under the Outputs subsection. For each output, the Finder displays its name in the script and its data type. Add the following:
Type in a Label for the output. Use this label to refer to the output in the Finder, when defining investigations or metrics that relate to the remote action. In NXQL, use always the output name instead.
Optional: Type in a brief Description of the output. The description is displayed as a column tooltip when the output is added to the results of an investigation.
Each output indicates its platform scope, Windows or Mac, with an icon placed to the right of its value. If the remote action targets both platforms, an output with the same name and the same type in the two scripts displays both icons and is assigned the same label for later use.
In the Advanced configuration subsection, give additional details about the execution of the script:
Choose the user of the device that the remote action must impersonate to run the script. Under Run the script as, choose:
local system (default), to run the script as the system user.
current interactive user, to run the script in the context of the user who is logged in to the device at the point when the remote action is triggered.
Set the maximum duration of execution of the script within the sentence The script will time out after [n] seconds. If the script is not finished by the specified time, it is stopped with a failure status. The default time-out value is 120 seconds (2 minutes). Allowed values range from 10 to 604800 seconds.
Click Save to permanently store the remote action.
If you created an automatically triggered remote action, a dialog with the number of impacted devices across all Engines (calculated at the moment of saving the remote action) shows up:
Press Yes, target N devices to proceed.
To optimize your remote actions and reduce the number of them, you can use dynamic parameters. For existing remote actions, you can adapt the parameter used by making them dynamic When the remote action is triggered using the Finder, the user is asked to enter specific information that the system requires to execute the script.
The remote action author can either choose to create a predefined set of parameters to choose from or leave the field as free text.
Using the procedure described above, create as many remote actions as needed provided that the total number of generated custom fields (the sum of the outputs specified in each action plus 6 default fields per action) does not exceed 500 fields.
This is a hard limit that applies to both manually and automatically triggered remote actions. Additional limits apply to the maximum number of automatically triggered remote actions that you can enable simultaneously. See the details below.
Enable up to 60 automatically triggered remote actions in total.
Out of these 60 remote actions, up to 30 remote actions may have an evaluation period of less than 1 hour.
Out of these latter 30 remote actions, up to 10 remote actions may have an evaluation period of 1 minute.
For example, to fully utilize the maximum number of remote actions with the highest frequency possible, distribute the 60 available remote actions in the following way:
10 fast frequency remote actions (1 minute).
20 medium frequency remote actions (10 minutes).
30 normal frequency remote actions (1 hour).
In November 2020, Nexthink introduced a brand new user interface for campaigns. From the Finder, you can specify which design you want the Collector to use.
When you select the Use new Engage campaign design option, all the devices equipped with the Collector version 6.29.1.17 or higher use the new design and all the ones with a previous version, the classic design. Note that by ticking that box, the system is automatically instructing the Collector to skip the notification.
RELATED TASK
RELATED REFERENCE
