Running scripts on devices

You can upload a Custom script if it meets the following requirements:

• The script is in one of the following formats:
  • PowerShell script (.ps1): for Windows devices
  • Bash shell script (.sh): for Mac devices

• The script doesn't exceed 1468 KB in size

Absolute Reach is supported on Windows and Mac devices with an active Absolute agent that is regularly connecting to the Absolute Monitoring Center.

It is not supported on the following devices:

• Chromebook and Android devices
• devices that are not running a supported version of the Windows or macOS operating system
• devices with an Agent Status The operating condition of an Absolute agent. Possible values are Active (indicates that the agent has connected to the Monitoring Center), Inactive (indicates that the agent has started its first connection to the Absolute Monitoring Center and agent activation is in progress and when activation is completed, the status is updated to Active), and Disabled (indicates that the agent is either flagged for removal or removed from the device). set to Inactive or Disabled
• devices with an open theft report

The following practices ensure that the script produces the desired results before you use Absolute Reach to deploy a script across your fleet of devices:

• Add error handling to your script to help troubleshoot any issues that may arise. Script return codes show in Action History and Event History.
• Before you upload a PowerShell script, review the PowerShell guidelines pertaining to the Absolute schema.
• In the Absolute console, use the Run Script option to deploy the script on a small subset of test devices and observe the results.

To submit a Script request:

1. Log in to the Absolute console as a user with Run permissions for Reach Script.
2. Do one of the following:
   Run a script on a single device

   On its Device Details page click > Run Script.

   Run a script on multiple devices

   1. From the navigation bar, open a page that supports the Run Script action. For example, click to open the Devices page.
   2. In the work area, use the search field or filters to find the applicable devices.

   3. In the results grid, select the check box next to each device. To select all devices, select the Select All check box in the result grid's header. You can select up to 9,999 devices. To remove all selections, clear the Select All check box or click Clear all.

   4. Depending on the page you're on, click either Run Script or Device Actions > Run Script.

   Alternatively, you can upload a file of device identifiers and submit a request.

   If there are no Windows or Mac devices selected, a message shows. Click to close the dialog.

3. Add a script to your request by doing one of the following:

   Select a script from the Script Library

   1. The list of scripts is pre-filtered based on whether Windows or Mac devices are selected. Enter part of the name or description of the script that you want to run in Search Scripts. Click Absolute or Custom to limit the search results. Search results update dynamically as you type.

      NOTE  If the eligibility check takes more than 10 seconds, the scripts aren't filtered by device type.

   2. Click the script that you want to run.
   3. [Optional] Edit the script description.
   Upload a new script

   1. Click Create Script.

      NOTE  The Create Script option is available only if you are logged in as a user with Manage permissions for Reach Script.

   2. Enter a unique name for the script.

      If you don't update the name of the script, the script is called Custom Script - <Date>.

   3. [Optional] In Add description, enter a description for the script.

   4. If you do not want to be able to use the script for a future request, clear Save to Custom library.

      NOTE  If Save to Custom library is selected, any PowerShell Parameters, Bash Parameters, and Advanced Configuration Options you set in the following steps are saved with the script in the Script Library. If you upload both a PowerShell and a Bash script, they are saved together.

   5. Do one or both of the following:
      • To upload a script for Windows devices, click Upload PowerShell Script, navigate to and select the PowerShell script you want to upload and click Open. Ensure that the file is a valid PowerShell script with a .ps1 file extension and the file name doesn't contain any spaces. Upload PowerShell Script is available only if you selected Windows devices.
      • To upload a script for Mac devices, click Upload Bash Script, navigate to and select the Bash script you want to upload and click Open. Ensure that the file is a valid Bash script with a .sh file extension and the file name doesn't contain any spaces. Upload Bash Script is available only if you selected Mac devices.
4. Depending on the type of script selected or uploaded, do one or both of the following:
   PowerShell script

   1. In the Windows Devices section, click View Script to see a preview of the script.

      NOTE   You can't edit the text in the preview box. If you need to edit a custom script, open the script file on your computer and edit it. You can replace the original uploaded script with the edited script by clicking the Upload PowerShell Script button and selecting the edited script file.

   2. If the Script Variables section shows, enter a value in any field marked required. For all other fields, enter a value, if applicable.

   3. If you want to specify one or more parameters for your script, enter them in the PowerShell Parameters field.

      NOTE  The PowerShell Parameters field is not validated for correct syntax. Ensure that you enter the parameters correctly.

   4. Set the Advanced Configuration Options for the script:

      Configuration	Options
      Rights	Select one of the following options: Run with system account rights: run the script using the rights associated with the local system account Ensure that you select this option if the PowerShell script references Absolute .dll files, as non-system accounts do not have access to these files. Run with logged in user rights: run the script using the rights of the logged in user Ensure that you select this option if the PowerShell script requires access to the device user's data or input from the device user (such as acknowledgment of a license agreement).
      Display Mode	Select one of the following options (if available): Hidden: run the script in the background so it is not visible to the user Maximized: show the Windows PowerShell dialog on the device Minimized: minimize the Windows PowerShell dialog to the Windows taskbar
      Run Condition	Select one of the following options: No user is signed in: run the script only when no user is logged in User is or isn't signed in: run the script regardless of whether a user is logged in User is signed in: run the script only when a user is logged in
      Maximum Run Time	Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported. To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
      Run 32-bit version	If you want to use the 32-bit version of PowerShell (x86) to run the script on 64-bit Windows devices, select the check box. If you leave the check box cleared, the 64-bit version of PowerShell is used to run the script on these devices.

   Bash script

   1. In the Mac Devices section, click View Script to see a preview of the script.

      NOTE   You can't edit the text in the preview box. If you need to edit a custom script, open the script file on your computer and edit it. You can replace the original uploaded script with the edited script by clicking the Upload Bash Script button and selecting the edited script file.

   2. If you want to specify one or more parameters for your script, enter them in the Bash Parameters field.

      NOTE  The Bash Parameters field is not validated for correct syntax. Ensure that you enter the parameters correctly.

   3. Set the Advanced Configuration Options for the script:

      Configuration	Options
      Rights	Select one of the following options: Run with system account rights: run the script using the rights associated with the local system account Run with logged in user rights: run the script using the rights of the logged in user
      Display Mode	This field is unavailable for Bash Scripts
      Run Condition	This field is unavailable for Bash Scripts
      Maximum Run Time	Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported. To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.

5. Click Run Script.

The request is submitted and a Script requested event is logged to Event History. You can track the progress of the Run Script request in Action History.

When the script is deployed to the device on the next successful agent connection, it is placed in the device's job queue. In Action History, the device's Action status is set to Processing. If the request requires dual approval, the request remains in the Pending Approval section in Actions History. The action isn't sent to the device until the request is approved. After the script runs on the device, the Action status is set to Succeeded. If the script fails to complete for any reason, such as ineligibility or exceeding the Maximum Run Time, the Action status is set to Failed and the reason is displayed in Failure reason.

If you need to cancel a Run Script request after you created it, you can attempt to cancel the request on devices if the request is still pending.

• To cancel all pending Run Script requests for a single device, go to the device's Device Details page. Learn more
• To cancel a single pending request for one or more devices, go to Action History. Learn more