Set Up and Run Remediation to Resolve Device Issues

In order to reduce the number of IT tickets and improve user experience, Aternity developed the Remediation feature. Remediation allows IT help desk personnel to identify issues that can cause problems and remotely fix them before they are escalated. Running remediation actions remotely resolves performance issues on end user Windows devices by one-click reducing the problem-solving time and the risk of human errors. Remediation actions can be triggered automatically based on Service Desk Alerts, manually by IT help desk personnel or from external systems using REST API. For example, identify that a user has low disk space and trigger the Empty Recycle Bin action before end user is out of disk space, or stop Windows service that should not run on the device.

This functionality applies only to end-user devices with Agent 12 or later and only for customers who participate in the Beta program. Contact Aternity Beta Team.

The workflow involves writing scripts, adding them to Aternity and then executing remediation actions manually (from the Troubleshoot Device Events dashboard or from the Remediation screen) or automatically (triggered by service desk alerts).

Initiate Remediation on End User Devices

Create as many various remediation actions as you need by adding scripts to Aternity. For example, automatically clean disk to free some space or stop Agent before system update, clear cache or disable a problematic add-on to improve the web pages load time.

Use Remediation screen to view, configure, and add remediation actions to Aternity to provide early and easy one-click fixes for performance issues, improve user experience and decrease the volume of IT support cases.

Before you begin

  • Create script(s) and upload them to Aternity in order to run remediation actions on end user devices. Here are several tips about how to create scripts.

    When creating a script, you must include the ActionExtensionsMethods.dll file. To do this, use the command:
    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
    Now you have two functions you can use:
    • SetScriptOutput - This function returns an output message with some additional information that you can later use to examine action results. For example, if your script cleared space, then it can return information about how much space was cleared. For example:
      #[ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput("<write here your message>")
    • SetFailed - This function identifies the action as failed. You should identify as a failure any case in which the action most likely failed to remedy the original issue. For example, if there was no space to clear, then the script should identify this action as a failure. As a parameter, send the type of the failure. For example:
      #[ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed("<write your error here>")
    Try a sample action script that performs a remediation successfully:
    {
                    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
                    # This script is a sample script that does nothing but it will finish successfully. 
     # Add your remedy logic here…
                    
                    # If you want this script to set an Output Message to be included in dashboards, then comment-out the next line and set the string parameter
                    #[ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput("<write here your message>")
    }
    catch
    {
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
    }
    
    
    Try a sample action script that fails to perform remediation:
    {
                    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
                    # This script is a sample script that does nothing but ends with a failure
    # Add your remedy logic here…
                    
                    # In order to notify Aternity about the failure, comment-out the next line and set the string parameter with the error message to be included in dashboards
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed("<write your error here>")
    }
    catch
    {
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
    }
    
  • For security reasons, by default, the Agent runs only scripts that are signed either by Aternity or by certificates listed in the Trusted Publishers store of the device on which you run the script. To open the Certificates dialog-box and to see the certificates included in the Trusted Publishers store of the device, open a Command Prompt window and run the certlm command.
    Launch Local Computer Certificates
    Tip

    Find the shared samples of the scripts in the Riverbed Community repository. Use the readme file to better understand how to use the repository, how to contribute and more.

    Tip

    If using the default execution policy during Agents mass deployment, which is ACTION_EXECUTION_POLICY=Trusted, make sure to place your certificates in the folder shown in the above figure.

    It is possible to change the default parameter of the ACTION_EXECUTION_POLICY in the Agent's batch file only during its installation. There are three possible options to alter:
    • Trusted - The default policy that automatically applies during Aternity Agent mass deployment.

    • Unrestricted - Aternity Agent runs any script, both signed and not signed.

    • Blocked - Aternity Agent blocks any script, either signed or not.

    Currently, changing these options is supported only for the mass installation batch file by entering the following parameter: ACTION_EXECUTION_POLICY=Unrestricted or ACTION_EXECUTION_POLICY=Blocked

  • If the certificate you use for signing is not listed in the Trusted Publishers store, specify in the Agent's batch file with what certificate to sign scripts. You can define up to two certificates during Agent's mass deployment: TRUSTED_CERTIFICATE_SUBJECT1= and TRUSTED_CERTIFICATE_SUBJECT2=. Enter the value to specify the subject of the certificate.

  • To set up remediation actions, you need administrator privileges.

  • To run remediation actions without being an administrator, you need Execute Remediation Actions privilege.

Procedure

  1. Step 1 Open a browser and sign in to Aternity.
  2. Step 2 Hover over the panel, click the gear icon , and select Remediation.
    Open the Remediation screen to add new remedial actions to Aternity
    Field Description
    Action Name

    Displays the name of the remediation action that you entered while adding new actions.

    Description

    Displays the description of the remediation action that you entered while adding new actions.

    Requires Confirmation

    Displays Yes or No depending on whether you enabled or disabled sending a request for end user confirmation (before executing remediation).

    Attached To Displays the name of SDA alert in case the remediation action attached to an SDA and will be automatically executed upon this SDA alert.
    Last Modified Displays date and time when the action was last edited.
  3. Step 3 To add a new action to Aternity, do the following:
    1. a Select Add Action.
    2. b In the Step 1 screen, fill in all necessary fields.
      Field Description
      Enable Action

      Toggle to enable or disable the action.

      Display Name

      Enter the name for the action.

      Description

      Clearly describe to end users what this action will do to their device.

      Action Expiration

      The time period (in hours) after which the action cannot be carried out any more.

      Action Script

      Select Upload to add a script to Aternity. This script will run an action that should remedy the end user device upon an SDA alert or manually by an IT person.

      Script privileges

      Defines whether to run the script with the current user (the default option) or with system account.

      Fill in the fields
    3. c Select Upload and then choose the script file to add to Aternity.
    4. d Click Next.
    5. e In the Step 2 screen, toggle to enable or disable adding an input parameter to the script.
      An optional usage of input parameter enhances remediation action capabilities. It raises the number of possible remediation actions while minimizing the amount of required scripts. You can use a variable as your input parameter to perform a single action in multiple cases. For example, you can now create a script for restarting services and define that the name of the service is your input parameter (variable). So that you can modify the name of the service every time you want to restart some service. Another example, if you have a remediation action that uninstalls malicious apps, you might have the name of an application as a variable.
      Define the parameter and use one script for multiple actions
    6. f Fill in all necessary fields.
      Field Description
      Parameter Name

      Enter the name for this parameter. For example, directory or service name, depending on your action.

      Mandatory

      Once you define this parameter as mandatory, the current action cannot be automatically triggered by Service Desk Alerts.

      Description

      Enter the parameter description. For example, the directory from which to clear files.

      Sample

      Enter the parameter. For example, d://.

    7. g Click Next.
    8. h In the Step 3 screen, toggle to enable or disable sending a request message for end user confirmation.
    9. i (Only if you enable sending the request for end user confirmation) In the Step 3 screen, fill in all necessary fields.
      Field Description
      Message From

      Enter the company name who sends this message. Usually, the IT service provider sends this kind of messages to request from users to run a remedial action on their devices.

      End user confirmation message

      Toggle to enable or disable sending a request message for end user confirmation.

      Enable it in case you want end user to confirm the action. Disable it in case you want to silently initiate a remediation action on end user devices.

      When disabled, all other fields become grayed out.

      Header

      Enter the title of the message. For example: Your device is running out of disk space.

      Question

      Enter the question itself. For example, Do you want to empty a recycle bin to clean some space?

      Accept Button Decide and enter what will be written on the acceptance button. For example, OK or Yes.
      Decline Button Decide and enter what will be written on the declination button. For example, No or Cancel.
      Preview

      It is possible to view how the message will be seen by end users before sending it out.

      Fill in all necessary fields
    10. j (Optional) After filling all necessary fields, click Preview.

    Make sure the message is clear to end users and prompts to confirm the action execution.

    Preview the message before sending it out
    1. a Click Save.
      You can select Cancel to cancel the procedure of adding a new script to the system or Back to go back to the first step and to change the text in the fields.
  4. Step 4 To edit the existing action, like changing the action name or updating its script, select the row's context menu on the right > Edit. (Learn how to connect actions to an SDA for an automatic execution upon alert.)
    Edit the script details

    You can change the name of the button as well as any other text by selecting Edit and typing new texts in the fields.

    1. a In the Step 1 screen, fill in all necessary fields.
      Field Description
      Enable Action

      Toggle to enable or disable the action.

      Display Name

      Enter the name for the action.

      Description

      Clearly describe to end users what this action will do to their device.

      Action Expiration

      The time period after which the action cannot be carried out any more.

      Action Script

      Select Upload to add a script to the system. This script will run an action that should remedy the end user device upon an SDA alert or manually by an IT person.

      Script privileges

      Defines whether to run the script with the current user (the default option) or with system account.

    2. b Click Next.
    3. c In the Step 2 screen, fill in all necessary fields.
      Field Description
      Parameter Name

      Enter the name for this parameter. For example, directory or service name, depending on your action.

      Mandatory

      Once you define this parameter as mandatory, the current action cannot be automatically triggered by Service Desk Alerts.

      Description

      Enter the parameter description. For example, the directory from which to clear files.

      Sample

      Enter the parameter. For example, d://.

    4. d Click Next.
    5. e In the Step 3 screen, fill in all necessary fields.
      Field Description
      Message From

      Enter the company name who sends this message. Usually, the IT service provider sends this kind of messages to request from users to run a remedial action on their devices.

      Header

      Enter the title of the message.

      Question

      Enter the question itself. For example, Your device is running out of disk space. Do you want to empty a recycle bin to clean some space?

      Accept Button Decide and enter what will be written on the acceptance button. For example, OK or Yes.
      Decline Button Decide and enter what will be written on the declination button. For example, No or Decline.
      Preview

      It is possible to view how the message will be seen by end users before sending it out.

    6. f Click Save.
  5. Step 5 To connect Service Desk Alert to a remediation action in order to automatically execute a remediation action upon the Service Desk Alert, go to the Service Desk Alerts configuration screen (learn more).
  6. Step 6 Select the device on which you need to run remediation. To run the action, select the row's context menu on the right > Run.

    Only devices with Agent for End User Devices 12 or later support this functionality and are available for selection.

  7. Step 7 (Optional) Add your company logo to the message you send to end users.

    This setting applies to all remediation scripts, so you do this only once and not per each script.

    1. a Go to the the Gear Icon > and select Remediation.
    2. b Click Settings and go to the Branding tab.
    3. c Enable the functionality by toggling ON. By default, it is disabled.
    4. d Upload an image that meets the requirements.
      Upload the PNG file of the appropriate size
    5. e Select Preview to see the output.
      View the output before sending messages to end users
    6. f Save and exit.

    To view the status of currently running actions, go to the Device Events dashboard (learn more).

    To view and analyze all remediation actions, go to the Remediation Actions (Beta) dashboard (learn more).

    To customize the dashboard, go to the Remediation Actions (Advanced, Beta) dashboard (learn more).

    Only users with administrative privileges can perform the procedure described in this article. Users with the Execute Remediation Actions privilege can run actions using the Troubleshoot Device Events dashboard (learn more).