Creating a remote action

Contents

Creating a remote action

Overview

Remote actions let you execute PowerShell scripts in the devices of the end-users.

Applies to platforms: PlatformWindows.png

Procedure

To create a new remote action:

  1. Log in to the Finder as a user with the right to edit remote actions.
  2. Select the Remote actions section on the left-hand side panel of the main window.
  3. Right-click the header of the section or the empty area below it.
  4. Select Create new remote action from the menu. The form to define the new remote action shows up in a new tab.
  5. Type in an appropriate name for the action by replacing the temporary name Untitled remote action n .
  6. Optional: Briefly describe the purpose of the remote action in the field labeled Enter description here....
  7. In the SCHEDULE section, choose how to trigger the execution of the remote action:
  8. 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:
    1. 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.
    2. 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 evalutated investigations (frequency of 1 minute), the investigation must not compute aggregates and its time frame must be shorter than or equal to 1 hour.
    3. 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.
    4. 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.
  9. 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.
  10. In the SCRIPT section, click Import... to open the script that the remote action will execute.
    1. 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.
        1. Optional: Click the button Show certificate to open a stadard dialog that shows the cer.
  11. Optional: Click Export... to export the displayed script to an external file. This is useful if you want to modify a script that was provided as part of a content pack.
  12. If the script includes any formal parameters, these are listed under the Parameters subsection.
    1. 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.
  13. 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:
    1. Type in a Label for the output. Use this label to refer to the output when defining investigations or metrics that relate to the remote action.
    2. 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.
  14. In the Advanced configuration subsection, give additional details about the execution of the script:
    1. 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.
    2. 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.

Maximum number of remote actions

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 4 default fields per action) does not exceed 300 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.

Maximum number of enabled remote actions with automatic triggering

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).