Running playbooks

Select the File operations playbook to remotely:

• Download a file to a device from a server, or one of the following file hosting services:
  • Box
  • Dropbox
  • Google Drive
  • OneDrive
• Delete a file from a specified location on a device.

Your playbook can include up to 20 file actions. The actions are run in the order you specify in the playbook.

Requirements

• If the device's drive is encrypted by BitLocker Drive Encryption, enter the device's BitLocker recovery key in the playbook configuration. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.
• If you are adding a file:
  • And the file is stored on a file-sharing service, only direct download links are supported in the Host file URL field.
    About direct download links

    A direct download link is a URL that links directly to the file, allowing it to be downloaded immediately. In contrast, a shared link usually links to an intermediate webpage containing a link to initiate the download.

    In most cases, a direct download link includes the file name and extension, while a shared link does not.

    To generate a direct download link instead of a shared link, refer to your file-sharing service documentation for the correct URL format or generation method.

  • The file must be stored in a location that is not password-protected.

    To ensure the file is secure, it's best practice to create an AWS pre-signed URL.

Select the Restore from image playbook to use an image A snaphot of a hard drive that includes the operating system, settings, and installed software required by your organization. It serves as a template to ensure consistent and efficient device provisioning. It is also known as a system image or a base image. to remotely reimage an existing device, or set up a new device.

Requirements

• If the device's drive is encrypted by BitLocker Drive Encryption, enter the device's BitLocker recovery key in the playbook configuration. If you don't enter it, the playbook will fail to run.

  If the device is encrypted by another encryption product, the playbook will fail to run.

• The image has been created and stored in an accessible location. Password-protected locations are supported.

  If the location is not password protected, it's best practice to create an AWS pre-signed URL.

• If the image is stored on a file-sharing service, only direct download links are supported in the Manifest file URL field.
• The file format of the image is one of the following:
  Windows ISO file

  Ensure that the following files are uploaded to the storage location:

  • Windows installation ISO file (.iso)

  • Answer file (unattend.xml)

    For more information about creating an answer file, see Microsoft documentation.

  • Manifest file in JSON (.json) file format

    This file contains the URL to each of the above files.

    To create a manifest file:

    1. Open a new file in a text editor, such as Notepad ++.
    2. Copy the following code and paste it in the file.
       Copy

       {
           "answer_file": "https://abc.server.com/unattend_win11.xml",
           "image_file": "https://abc.server.com/win11_business_24h2.iso"
       }

    3. Edit the code as required.
    4. Save as a JSON (.json) file.
  Captured Windows image

  Ensure that the following files are uploaded to the storage location:

  • Windows image (.wim)

    To capture an image, ensure that you follow the instructions provided in Microsoft documentation.

  • Manifest file in JSON (.json) file format

    This file contains a parameter that resets (removes and recreates) a device's partitions, and contains the URL to the Windows image file.

    To create a manifest file:

    1. Open a new file in a text editor, such as Notepad ++.
    2. Copy the following code and paste it in the file.
       Copy

       {
         "reset_par":true,
         "image_file": "https://abc.server.com/image_win11.wim"
         }

    3. Edit the code as required.
    4. Save as a JSON (.json) file.

Select the Run script playbook to remotely run a script on a Windows device.

Note that the script content is pasted into a text field in the Run playbook dialog. You can't upload a file.

Requirements

• The following script types are supported:

  • Batch (.bat) script

  • PowerShell (.ps1) script

    For PowerShell scripts, ensure that "#PS" is added at the beginning of the script.

• The script cannot exceed 3 KB in size.

• If the device's drive is encrypted by BitLocker Drive Encryption, you can enter the device's BitLocker recovery key in the playbook configuration. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.

Select the Set/remove registry keys playbook to remotely:

• Add a registry key
• Update a key value
• Remove a key value

Your playbook can include up to 20 registry key actions. The actions are run in the order you specify in the playbook.

When editing the Windows registry, always proceed with caution. A misconfiguration can lead to significant issues, such as system instability, application errors, or an inability to restart Windows. Ensure that you understand the full impact of your registry edits before running this playbook. For more information about the Windows registry, see Windows documentation.

Requirements

• If the device's drive is encrypted by BitLocker Drive Encryption, you can enter the device's BitLocker recovery key in the playbook configuration. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.
• The HKEY_LOCAL_MACHINE registry hive is supported.

  Other registry hives, such as HKEY_CURRENT_USER, are not supported.

• Removal of a registry key is not supported. You can only remove registry key values.

Format guidelines

When entering registry paths, ensure that you use:

• HKEY_LOCAL_MACHINE for the registry hive. HKLM is not supported.

• Backslashes (\)

For example, HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

When you submit a Run playbook request, you need to configure the User initiated playbook option, which controls how the playbook will be launched. There are two options:

If a Run playbook request is already in progress on a device, you can submit a user-initiated playbook, but not a system-initiated playbook.

To run a playbook, your user role needs to be granted the Perform permission for Run playbook.

To view the following interface items on a device's Device Details page, your user role needs to be granted the View or Perform permission for Run playbook:

• Playbook requested banner
• Playbooks field

All default Administrator roles are granted these permissions.

To run a playbook, the following prerequisites must be met:

• The device meets the system requirements for this action.
• The device has not been reported stolen.
• The Playbooks policy is activated in the device's policy group.
• The device's Playbooks field shows a value of Enabled, meaning it is provisioned. Learn more
• At least 24 hours have elapsed since the policy was activated.

Before submitting a Run playbook request, you may want to verify that each device is provisioned to run playbooks. If a device is not provisioned, its action will immediately show an Action status of Failed in Action History.

To view provisioning status:

1. Log in to the Secure Endpoint Console as a user with the View or Perform permission for Run playbook.
2. On the navigation bar, click to open the Devices page.
3. [Optional] Filter the page to show only the devices for which you want to submit a Run playbook request.
4. Add the following report columns to the page:

   • Playbook > Status

     Possible values

     • Enabled: the Playbooks policy is activated on the device, and the device is provisioned to run playbooks.

       An obscured passcode () is also displayed. Learn more

       After the status is set to Enabled, it may take up to 24 hours for the device to be fully provisioned. Attempts to run a user-initiated playbook during this time may fail.

     • Not enabled: one of the following applies:

       • The Playbooks policy is activated in the device's policy group, but the device is not yet provisioned to run playbooks. A restart may be required.

       • The Playbooks policy is not activated in the device's policy group.

       The device is not provisioned to run playbooks.

     • Not supported: the device does not meet the system requirements for the Playbooks feature

     For more information about the specific requirements that were not met, review the information in the Playbooks > Status details report column.

   • Playbook > Status details

     Shows details about a Not supported or Not enabled status

     Possible values

     • Not provisioned
       • The Playbooks policy is not activated, or
       • The policy is activated in the console, but the device is offline, or
       • The policy is activated, but the device is not yet provisioned to run playbooks. A restart may be required.
     • Persistence 2.0 version not met
     • Agent version update required
     • TPM 2.0 not enabled
     • 3rd-party CA must be active when Secure Boot is enabled
     • Windows 10 and above not met
     • x86_64 CPU architecture not met

   Playbook status and status details are also available in the Playbooks field on each Windows device's Details page.

Troubleshooting unsupported (ineligible) devices

While configuring playbooks, you may need to enter device specific information, such as a file path on a device, or a device's BitLocker recovery key. You can use variables to specify this type of information. When the playbook runs on a device, the variable is replaced by the specific value for that device.

If you are submitting a request for multiple devices, and the playbook configurations require device specific information, you will most likely need to use a variable.

Playbooks support three types of variables:

• Hardware (select fields only)

• Custom Fields

• Custom Data Points

  Data points are assigned to devices at the policy group level. If you use a data point that is not assigned to a device's policy group, the playbook will fail to be processed and a Playbook failed event for the device will be logged to Event History.

You can view the complete list of supported variables by clicking View list of variables on the Run playbook dialog. To add a variable to a field, click its Insert variable field and then search for and select a variable from the list.

To run a playbook:

1. Log in to the Secure Endpoint Console as a user with the Perform permission for Run playbook.

2. Do one of the following:

   To run a playbook on a single device

   On the Windows device's Device Details page, click > Run playbook.

   If a icon shows when you hover over Run playbook, the device is not eligible for the action.

   To run a playbook on multiple devices

   1. From the navigation bar, open a page that supports the Run playbook action. For example, open the All Devices page in the Devices area or open the Makes and Models report.
   2. In the work area, use the search field or filters to find the applicable Windows devices.

   3. In the results grid, select each device you want to include in the request. To select all devices, select the Select All checkbox in the result grid header. To select consecutive devices, select the first device and then hold down the Shift key and select the last device. To remove all selections, click Clear all.

      By default, this action type is limited to 500 total actions per day per account, but your Administrator can change this amount, or disable the setting. Learn more
      

      If the setting is disabled, the limit per request is 1000 devices.

   4. Click > Run playbook.
3. Under Playbook, click the Select playbook field and select one of the following playbooks:
   • All playbook parameter fields include an Insert variable field, which is optional. Learn more about using variables
   • The system does not validate the values that you enter in each playbook's parameter fields. To help ensure that a playbook runs successfully, verify the parameters before adding them, and then enter them carefully. If a playbook fails to run successfully, a Playbook failed event is logged to Event History.
   File operations (add or delete)

   1. Review the playbook's requirements.

   2. [Optional] Under Parameters, enter the device's BitLocker recovery key. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.

      If the device is not encrypted by BitLocker Drive Encryption, skip this step.

      If the device is encrypted by another encryption product, the playbook will fail to run.

   1. Click Add action and do one of the following:
      Add a file

      1. Click Add file.
      2. In the Host file URL field, enter the URL(HTTP or HTTPS protocol only) for the location where the file is stored. Learn more

      3. In the File path field, enter the full path and file name of the location on the device to save the file. You can use the original file name, or a file name of your choosing, but do not change the file extension.

         For example, enter C:\Documents\Temp\Filename.txt

         Note the following:

         • Environment variables are not supported.
         • If a file with the same file name already exists in the location, the file is replaced by the downloaded file.
         • If a folder in the specified path doesn't exist, the folder is created.
         • The added file's Date modified timestamp is based on the device's real time clock (RTC). If the device's display time has been adjusted in Windows date & time settings, the timestamp may not be in sync with the display time.
      Delete a file

      1. Click Delete file.

      2. In the Path and file name to delete field, enter the full path to the file that you want to delete, including the file name. For example, enter C:\Documents\Textfile.txt. Environment variables are not supported.

   2. To add another action, repeat step c. The playbook can include up to 20 actions. To remove an action, click its icon.
   3. Actions are performed in the order they are listed in the playbook configuration. To change the order of the actions, click an action's icon and drag the action to its new location.

   If one action in the playbook fails, a Playbook failed event is logged to Event History, even if all other actions in the playbook are completed.

   Set/remove registry keys

   1. Review the playbook's requirements.
   2. [Optional] Open the Registry Editor on your local machine and find the key that you want to update or remove. For example:
      1. In the Windows Search field, type regedit.
      2. Click Registry Editor and click Yes in the User Account Control dialog.

      3. Navigate to the registry key and make note of the Name, Type, and Data of the registry key value. Also note the registry key path.

         

      4. Return to the Secure Endpoint Console.

   3. [Optional] Under Parameters, enter the device's BitLocker recovery key. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.

      If the device is not encrypted by BitLocker Drive Encryption, skip this step.

      If the device is encrypted by another encryption product, the playbook will fail to run.

   4. Review the playbook's format guidelines.
   5. Click Add action and do one of the following:
      Add a registry key

      1. Click Set registry key.
      2. In the Registry path field, enter the path to the location where you want to add the new registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

      3. In the Registry name field, enter the name of the registry key value you want to add. In Registry Editor, this will show under Name.
      4. Under Registry type field, select the registry key's type. In Registry Editor, this will show under Type.
      5. In the Registry value field, enter the data associated with the value. In Registry Editor, this will show under Data.
      Update a registry key value

      1. Click Set registry key.
      2. In the Registry path field, enter the path to the registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

      3. In the Registry name field, enter the name of the registry key value. In Registry Editor, this shows under Name.
      4. Under Registry type field, select the registry key's assigned type. In Registry Editor, this shows under Type.
      5. In the Registry value field, enter the new data string. In Registry Editor, this value will replace the value under Data.
      Remove a registry key value

      1. Click Remove registry key.

      2. In the Registry name field, enter the name of the registry key value that you want to remove. In Registry Editor, this is the value under Name.

         You can't remove the (Default) value.

      3. In the Registry path field, enter the path to the registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

   6. To add another action, repeat step d. The playbook can include up to 20 actions. To remove an action, click its (Remove) icon.
   7. Actions are performed in the order they are listed in the playbook configuration. To change the order of the actions, click an action's icon and drag the action to its new location.

   If one action in the playbook fails, a Playbook failed event is logged to Event History, even if all other actions in the playbook are successful.

   Restore from image

   1. Review the playbook's requirements.

   2. Under Parameters, enter the device's BitLocker recovery key. Note that if you don't enter it, the device user will not be prompted to enter the key and the playbook will fail to run.

      If the device is not encrypted by BitLocker Drive Encryption, skip this step.

   3. In the Manifest file URL field, enter the URL (HTTP or HTTPS protocol only) for the location where the manifest file is stored.
   4. [Optional] If credentials are required to access the server, enter the applicable Username and Credentials (password, key, etc).
   Run script

   1. Review the playbook's requirements.
   2. Under Parameters:

      1. [Optional] Enter the device's BitLocker recovery key. Note that if you don't enter it, the device user will need to enter the key when the playbook runs on the device.

         If the device is not encrypted by BitLocker Drive Encryption, skip this step.

         If the device is encrypted by another encryption product, the playbook will fail to run.

      2. Open the script on your local machine and copy its contents.

      3. Click the Batch script text field and paste the script content.

         If the script content exceeds 3 KB in size, an error message shows.

4. Under User initiated playbook, do one of the following:
   • If the device's operating system is fully operational, leave the toggle set to Off (gray).

     When the option is disabled (Off), the Run playbook request is deployed to the device on its next connection to the Absolute Monitoring Center, and the playbook runs automatically.

     To complete the Run playbook request, the Secure Endpoint Agent forces the device to restart. If a device user is logged in at this time, they are automatically logged out and data may be lost. Therefore, before submitting a Run playbook request, contact the device user and instruct them to save their work.

     Alternatively, if you want to run a script on a device, consider running a Reach script instead of the Run script playbook. The Reach script may not require a restart.

   • If the device's operating system won't boot up, click the toggle to set it to On (green). Note that if a playbook is already in progress on the device, the toggle defaults to On and it can't be changed.

     Learn more about user-initiated playbooks
     

5. Click Run on x devices.

   If the Daily action threshold reached dialog shows, the number of devices included in the request exceeds the daily threshold configured and enabled for this action. Learn more

   The request is created. A Playbook requested banner is added to each device's Device Details page, and a Playbook requested event is logged to Event History. If a device is ineligible for the Run playbook action, the Playbook requested event is immediately followed by a Playbook failed event.

   If you submitted a system-initiated playbook:

   • The request is deployed to each device on its next successful connection to the Absolute Monitoring Center, which is typically within a few minutes for Absolute Resilience accounts, or within 15 minutes for Absolute Control accounts, assuming the devices are online.

   • If the request requires dual approval, the request remains in the Pending Approval section in Action Requests. The action isn't sent to the device until the request is approved.

6. If you submitted a user-initiated playbook, go to the next section.

You can track the progress of a Run playbook request on the device's Actions page, or in Action History. If a playbook fails, add the Action > Status details column to the Actions page to see the reason for the failure. Also see the article, Manual Enable ABT in Boot Sequence in the Knowledge Base.

After the request is processed, one of the following events is logged to Event History:

• Playbook completed
• Playbook failed

If you enabled the User initiated playbook option in a Run playbook request, the following tasks need to be completed to initiate the playbook:

1. Get the device's Playbooks passcode
2. Initiate the playbook locally on the device

The first task is performed in the Secure Endpoint Console by an Administrator, while the second task is performed locally on the device by the device user. Note that it is best practice to maintain phone contact with the device user to guide them through the steps in the second task.

If the request requires dual approval, you can't complete these steps until the request is approved.

Prerequisite

You submitted a Run playbook request with the User initiated playbook option set to On. Learn more

Getting the device's passcode

To allow the user-initiated playbook to run, the device user needs to enter the device's Playbooks passcode during the boot process.

To get the device's passcode:

1. Log in to the Secure Endpoint Console as a user with the View or Perform permission for Run playbook.
2. Navigate to the device's Device Details page.
3. Click the Details tab.
4. On the Summary page, scroll to the bottom of the first table of information and view the Playbooks field.
5. Next to Enabled, click to view the passcode.
6. Leave the page open and go to the next section.

Initiating the playbook

The device user must perform the steps in this task. If they are unable to receive written instructions (due to the fatal system error), contact them by phone or text message.

To run a user-initiated playbook:

1. Provide the Playbooks passcode from step 5 to the user. Optionally ask them to record it somewhere temporarily.
2. Instruct the user to:
   1. Restart the device.
   2. When the manufacturer logo appears, press F6 (or Fn+F6, as applicable) repeatedly until an Absolute branded window opens.

   3. In the passcode field, enter the passcode from step 1 and then press Enter to initiate the playbook.

      The passcode window is only available for 2 minutes. If the user fails to enter a valid passcode before the window closes, instruct them to press F6 (or Fn+F6, as applicable) again. Note that after three failed passcode attempts, the device automatically boots into Windows.

      A Command Prompt window opens.

   4. An internet connection is required to run the playbook. If the following message shows in the window, the device is not currently connected.

      Network Connection Options:
      [C] Connect via WiFi networks
      [R] Reset and retry Ethernet connection
      [H] Connect to a hidden Wireless network
      [X] Exit (bypass network check)
      
      Enter your selection[C or R or H or X]:

      Do one of the following:

      • If the device is using a physical ethernet cable to connect to a network, the connection failed. Reset the connection by disconnecting the ethernet cable from the device and reconnecting it.

        When the Network Connection Options message shows, enter R to try again.

        Enter your selection[C or R or H or X]: R

      • If the device is not using an ethernet connection, you need to select an available Wi-Fi network and enter credentials.

        1. When the Network Connection Options message shows, enter C:

           Enter your selection[C or R or H or X]: C

           To connect to a hidden Wi-Fi network, enter H instead of C.

        2. A list of available Wi-Fi networks shows.

           Enter the numeric code for the network you want to use. For example:

           Enter your selection in number: 2

           If you are connecting to a hidden Wi-Fi network, you will need to manually enter the SSID name of the network.

           For information about supported Wi-Fi authentication methods, see System requirements.

        3. Enter the password for the Wi-Fi network. For example:

           Enter password for SSID 'MyNetwork': ******************

           Note that it will take approximately 30 seconds to authenticate the connection.

   5. Wait while the playbook runs. Note that the device will automatically restart to complete the recovery operation. If the Restore from image playbook was requested, the device will restart multiple times. Do not perform a manual restart while the playbook is running. If the operating system loads after a restart, the playbook ran successfully.

      You can track the progress of the request on the device's Actions page, or in Action History.

      After the request is processed on the device, one of the following events is logged to Event History:

      • Playbook completed
      • Playbook failed

If you are logged in as a user with the Perform permission for Run playbook, you can update an existing user-initiated Run playbook request by submitting a new request to replace the existing one.

You can't replace an existing system-initiated playbook.

As long as the existing request has an action status of Pending in Action History, you can submit a new user-initiated playbook to replace it. The action status of the existing request is updated to Failed and the new request is set to Pending.

The following events are logged in this scenario:

• Playbook requested (references the new request)

• Playbook replaced (references the existing request that was replaced)