Automated Actions - User Guide

Summary

This summary briefly explains how to set up the Automated Actions feature and create an automated action. It assumes that you have all the necessary permissions to configure automated actions, that there are Script Actions available in your organization that can be automated, and that you have not yet activated the 14-day free trial. All steps are performed from a ControlUp Console. More detailed information can be found in the rest of this guide.

Step 1Activate the Automated Actions feature:

  • In the Help menu, select About.
  • In the ControlUp Licensing window, select Start Free 14-day Trial of Automated Actions
    Additional information: Acquiring a License for the Automated Actions Feature

Step 2Begin creating an Incident Trigger for the automated action:

  • In the Trigger Settings window, select Add to create a new Incident Trigger.
  • Begin configuring the trigger’s settings. When you get to the trigger’s list of follow-up actions, select Add.
  • In the Follow-up Action screen, under Type, select Run an action.
    Additional information: Configuring an Automated Action

Step 3Set up the Automated Actions feature:

  • At the bottom of the Follow-up Action screen, select Run Automated Actions setup wizard, and follow the instructions. When you have finished running the wizard, you are returned to the Follow-up Action screen.
    Additional information: Setting Up the Automated Actions Feature

Step 4Complete the process of creating the Incident Trigger:

  • In the Follow-up Action screen, select the Script Name field, and then, from the list, select the Script Action you want to run whenever the trigger is activated.
  • Select OK and then select Finish.

Contents

Overview
Prerequisites
Acquiring a License for the Automated Actions Feature
Setting Up the Automated Actions Feature
Configuring an Automated Action
Advanced Features and Topics
Troubleshooting
Known Issues


Overview

Automated actions are Script Actions (SAs or SBAs) that are configured to run automatically as follow-up actions of Incident Triggers. This guide explains how the ControlUp Automated Actions feature works and can be used. The feature is available beginning with ControlUp version 7.4.

Examples of Use-Cases

Some examples of use-cases for the Automated Actions feature are:

Example of Incident Trigger

Example of Follow-up Action

A specified process consumes more than 90% of CPU for more than five minutes.

Run a script that kills the process.

The proportion of free space on the C: drive of a computer is lower than 5%.

Run a script that will find which files or directories are the largest, and log an event for further troubleshooting.

A service that must be running at all times stops running.

Run a script that restarts the service.

A machine is added to a host.

Run a script that adds the machine to ControlUp and installs a ControlUp Agent on it.

A browser points to the URL of a site that is on a list of blocked sites (e.g., a gambling site).

Run a script that kills the browser tab.

Security
Automation is by nature a sensitive process, inasmuch as mistakes made by users when they set it up can cause unexpected actions to be performed by the system, often without the users realizing these actions are taking place. Because of this, automation is limited in ControlUp, both by means of security policy and throttling.

Execution of Automated Actions
Automated actions are executed by the ControlUp Monitor. Therefore, at least one ControlUp Monitor must be running in your organization in order for the Automated Actions feature to be used.

Automated Actions Setup Wizard
An Automated Actions setup wizard is available to help you define which Script Actions can be used as automated actions and which users and groups have the permissions required to configure automated actions.

image003.png
A screen in the Automated Actions setup wizard


Prerequisites

In order to activate the Automated Actions feature, the organization must have:

  • At least one ControlUp Monitor running (see Execution of Automated Actions)
  • An Automated Actions license (see Acquiring a License for the Automated Actions Feature)

In order to work with the Automated Actions feature, users must have the following permissions:

  • Create Automated Actions
  • Configure Incident Triggers

Acquiring a License for the Automated Actions Feature

To purchase a license for the Automated Actions feature, please contact sales@controlup.com. If you want to test the feature before you purchase a license, you can activate the 14-day trial license.

Note:  The Automated Actions feature is disabled in free mode.

To activate the 14-day trial license:

  • In the Console, in the Help menu, select About. In the ControlUp Licensing window, select Start Free 14-day Trial of Automated Actions.
    image005.png
    ControlUp Licensing window

Note:  If your version of ControlUp was recently upgraded from an older version to version 7.4, and you are a privileged user (the configuration owner or a user who has the Change Permissions permission), an invitation to set up the Automated Actions feature will pop up automatically when you log into ControlUp from any Console. (Unless you select Don’t show me this message again, this invitation will continue to appear every time you log in until you have configured the Automated Actions settings.)
image007.png
Invitation to set up Automated Actions

Select Next to begin setting up the feature.
If you have not yet acquired a license, you can activate a trial license in the next screen.
image009.png
Next screen if you do not have a license

If you already have a license, selecting Next will open the Automated Actions setup wizard (see Setting Up the Automated Actions Feature, below).


Setting Up the Automated Actions Feature

The Automated Actions setup wizard streamlines the process of setting up the feature. Its main purpose is to configure the security settings that control which Script Actions can be automated and which users can create automated actions. This wizard can be opened from the Trigger Settings when you create a new trigger or edit an existing one. Only a privileged user (the configuration owner or a user who has the Change Permissions permission) can open this wizard.

In addition to running the wizard before you begin configuring automated actions, you can run it any time you want to modify the Automated Actions settings by enabling or disabling Script Actions for use as automated actions, and by modifying the list of users who can create automated actions.

Note: In order to create automated actions, a user must have both the Create Automated Actions permission and the Configure Incident Triggers permission. The Create Automated Actions permission can be granted to a user through the Automated Actions setup wizard (by adding them to the Automation Admins security role). For additional information, see Assigning Automated-Actions Permissions to User Roles, below.

To configure the Automatic Actions feature using the setup wizard:

  1. In the configuration of an Incident Trigger, in the Follow-up Action screen, under Type, select Run an action.
    image011.png
    Selecting Run an action in the Follow-up Action screen
  2. At the bottom of the screen, select Run automated actions setup wizard. The wizard opens.
    image013.png
    Link to the Automated Actions setup wizard at the bottom of the screen

    image015.png
    Automated Actions setup wizard
  1. Read the first page of the setup wizard (see screenshot above), and then select Next. A list of the scripts currently defined in your organization is shown.
    image003.png
    List of available scripts in the Automated Actions setup wizard
  1. Select the scripts that should be available for automation in your organization.
  2. If you want all scripts that are uploaded to ControlUp from now on to be available for automation by default, select Allow new Script Actions to be automated by default.
  3. Click Next. A list of users and groups that have the Automated Actions permission is shown.
    image018.png
    List of users who belong to the Automation Admins security role
  1. To add users or groups of users to the list, select Add Users/Groups. The Account Browser window opens.
    image020.png
    Account Browser window
  1. Select the domain and root in which the users’ accounts are defined, and use the Search Filter and Search Options to filter the list.
  2. Select the users and/or groups you want to add to the list of users who have the Create Automated Actions permission. Hold down Ctrl or Shift to select multiple items.
  3. Select OK. The selected users and groups are assigned the Create Automated Actions permission, and appear in the list in the setup wizard.
    image022.png
    User added to the list
  1. Select Finish. The settings you selected are applied. The wizard closes, and the Follow-up Action screen of the trigger settings becomes available again.

Configuring an Automated Action

An automated action is created by selecting a Script Action as a follow-up action for a trigger. As such, it is configured in the Trigger Settings.

When an automated action is triggered, ControlUp records information about the script execution in the Monitor’s Windows Event Log and in the ControlUp Audit Log. You can also configure ControlUp to send certain users an e-mail with the script-execution output whenever a script runs as a follow-up action. Not only is this likely to be a more convenient way of learning what scripts have been executed and whether they were successful, it also gives you more information, as it gives you all of the output (in an attached text file).

To configure an automated action:

  1. In a ControlUp Console, in the Home ribbon bar, select Triggers. The Settings window opens with the trigger settings displayed.
    image024.png
    Trigger Settings
  1. If the trigger you want to use already exists, select it in the list, and then select Edit to open its settings. If it does not yet exist, select Add Trigger to create it and configure its settings.
  2. In the trigger’s settings, in the list of follow-up actions, select Add. The Follow-up Action screen opens.
    image026.png
    List of follow-up actions for a trigger (none added yet)
    image028.png
    Follow-up Action screen
  1. Under Type, select Run an action. The settings for the automated action open.
    image030.png
    Settings for the automated action
  1. Under Action Type, select Script Action.
  2. Select the Script Name field. A list of all of the Script Actions defined in the trigger’s scope opens. Those that can be used as automated actions appear in black; those that cannot are grayed out.
    Note: In many cases, grayed-out scripts can be modified slightly and then used as automated actions. For example, if they are interactive scripts, you may be able to use them if you set a default value for each of the arguments that would otherwise be supplied interactively. To find out what you have to do to enable a grayed-out script to be used as an automated action, select the script in the list. A message explaining the problem and what you should do to solve it is displayed. For additional information, see Specifying Default Credentials for an Interactive Script, Specifying Default (Current User) Credentials for Running a Script, and Specifying the Computer on which to Run a Script.

  3. Select the Script Action you want to use as a follow-up action for the trigger.
  4. If you want information about the script’s execution to be sent to users, select Send script execution output to e-mail recipients.
    Note: Even if this option is selected, the execution output is only sent if the Send an e-mail alert and/or the Send an e-mail alert using a local SMTP server follow-up actions are also configured for the trigger. If they are, the recipients specified for these follow-up actions receive an e-mail notification when the trigger is activated (because of the Send an e-mail follow-up actions) and a second e-mail containing the execution output of the Script Action when the Script Action is completed (because Send script execution output to e-mail recipients is selected here).

  5. If you selected Send script execution output to e-mail recipients, under Template, select the template to use for the e-mail.

  6. Select OK. The Follow-up Action screen closes, and the automated action is assigned to the trigger.
    image032.png
    Automated actions assigned to a trigger


Advanced Features and Topics

This section gives additional information about the Automated Actions feature and how it can be fine-tuned.

 Assigning Automated-Actions Permissions to User Roles

A user cannot set up an automated action unless they have two permissions – Create Automated Actions and Configure Incident Triggers.

NoteA user who has the Create Automated Actions and the Configure Incident Triggers permissions can even set up an automated action that uses a Script Action for which they do not have the permission to run manually.

The Create Automated Actions permission can be assigned to any roles that are locally created within the organization. Initially, it is assigned to two roles:

  • Configuration owner
  • Automation Admins: This role is built-in, and has the Create Automated Actions permission by default. No users are assigned to it initially.

The Create Automated Actions permission can be assigned to users or roles by the Automated Actions setup wizard (see Automated Actions Setup Wizard, above), but it can also be managed manually in the organization’s Security Policy. The Configure Incident Triggers permission can only be managed manually in the Security Policy.

To assign the Create Automated Actions and Configure Incident Triggers permissions to a role in the organization:

  • In the Security Policy screen, at the organization level, under Perform organization-wide actions, locate the Create Automated Actions and Configure Incident Triggers rows, and select Allow for those roles.
    image025.png
    Configure Incident Triggers and Create Automated Actions permissions allowed for the Automation Admins role

Manually Configuring the Automation Settings of a Script Action

The easiest way to make a script available for automation is by using the Automated Actions setup wizard (see Setting Up the Automated Actions Feature, above), but the manual method described below also works, and it enables a more granular configuration. This technique, which modifies the settings directly in the Security Policy, is useful if you want to make a script available to some folders and not to others.

Note: The setup wizard only enables or disables automation for scripts at the root level of the organization. By default, these settings are inherited by all of the scripts in the organization. If you manually disable the inheritance and change the settings of a script in folders below the root, these settings are not affected if the wizard is used later on to enable or disable automation for that script.

To manually configure the automation settings of a Script Action:

  • In the Security Policy screen, change the ControlUp Monitors permission of the Script Action as required (Allow or Deny).
    Screenshot_3.png
    Security Policy screen with the ControlUp Monitors role granted permissions to run some scripts

Throttling

Throttling places limitations on the quantity of automated actions that can take place at one time, in the entire system and on one target, for a single Incident Trigger. The following throttling rules are in effect for the Automated Actions feature:

  • The Monitor cannot run more than 50 automatically executed Script Actions simultaneously. If additional jobs are generated, they are queued, and will run when jobs that are already in progress are completed. The queue itself can contain a maximum of 10,000 jobs.

  • The Monitor cannot run more than one automatically executed Script Action at a time on a single target. If additional jobs are generated, they are queued, and will run one after the other. The queue itself can contain a maximum of 1,000 jobs.

  • If a single Incident Trigger generates more than 50 automatically executed Script Actions, none of the Script Actions are executed, and an exception is logged in the Monitor’s Windows Event Log and in the ControlUp Audit Log.

The values given above are the default values. They can be modified in the Windows Registry of the Monitor’s computer at HKEY_USERS\S-1-5-20\SOFTWARE\Smart-X\ControlUp\MonitorSvc using the keys listed below. By default, these keys do not exist; when one of these keys does not exist, its default value is used. When the key exists but its value is “0,” no limit is in place for that value. Otherwise, the value assigned to the key is used.

Throttling Limitation

Default Value

Registry Key

Maximum number of simultaneous automatically executed Script Actions

50

MaxAutoExecJobsTotal

Maximum number of automatically executed Script Actions in the queue

10,000

MaxAutoExecQueueSizeTotal

Maximum number of simultaneous automatically executed Script Actions on a single target

1

MaxAutoExecJobsTarget

Maximum number of automatically executed Script Actions in the queue for a single target

1,000

MaxAutoExecQueueSizeTarget

Maximum number of automatically executed Script Actions generated by a single Incident Trigger

50

MaxAutoExecJobsTrigger

 

Compatibility between the Scopes of Script Actions and Incident Triggers

A Script Action cannot be used as an automated action unless it is available for automation in the entire scope of the Incident Trigger.
If you use the Automated Actions setup wizard to configure which Script Actions are available for automation, they are always configured to be available in the entire organization. In this case, a situation in which a Script Action is not available for automation in the scope of an Incident Trigger should not arise.
As explained above, it is possible to configure the security settings of a Script Action manually in the Security Policy, making it available for automation in some folders or subfolders and not in others. If this has been done, it is possible for a Script Action to be unavailable for automation in part or all of the scope of an Incident Trigger.
Two measures have been implemented in order to prevent a Script Action from running as an automated action when it is not available for automation in the scope of the Incident Trigger:

  • Script Actions that are not fully available in the entire scope of an Incident Trigger appear grayed-out in the list of available Script Actions for that trigger.
    image038.png
    List of available Script Actions for an Incident Trigger

  • At runtime, the system checks whether the Script Action is currently configured to be available for automation in the entire scope of the Incident Trigger. This prevents security violations when changes to the Security Policy that take place after the automated action was configured. If the Script Action is not available for automation at runtime, it is not run.

Compatibility of Mappings between Script Actions and Incident Triggers

In principle, in order for a Script Action to be mapped to an Incident Trigger, the assigned type of the Script Action must match the record type of the trigger. For example, if the Script Action is assigned to computers, the record type of the trigger must be computer. However, the system is somewhat flexible in this regard, usually enabling mappings between Script Actions and Incident Triggers when the Script Action’s assigned type is the parent of the trigger’s record type.
The following table shows which mappings between assigned types of Script Actions and record types of Incident Triggers are supported:
image040.png
Compatibility between assigned types of Script Actions and record types of Incident Triggers

In general, you do not need to know the rules that define which Script Actions can be mapped to which Incident Triggers, because only those scripts that meet the requirements are included in the list of scripts in the Follow-up Action settings.
image038.png
Only applicable scripts appear in the list of options

Bear in mind when you select a script for automation that the arguments that will be passed to the script during its execution are those of the script’s assigned type. For example, if a script is assigned to computers, and mapped to a session, the arguments it will receive are the properties of the computer on which the session is running, and not the session.

Setting Argument Values for Interactive Scripts

Because automated actions run independently, interactive scripts cannot be used. However, if you have an interactive script that you want to use as an automated action, you can use it if you set a default value for each of the arguments that would otherwise be supplied interactively.

To set a default value for an argument:

  1. In a ControlUp Console, in the My Organization screen, in the Home ribbon bar, select Script Actions. The Scripts Management window opens.

  2. Double-click the script. The Modify Script Action window opens.

  3. In the Arguments tab, double-click an argument whose default value you want to set. The Script Argument dialog box opens.

  4. Under Default, enter the default value for the argument, and then select OK. The value appears in the list of arguments, under Default.
    image043.png
    Script Argument dialog box with default value entered

  1. Repeat the last two steps for every other argument whose default value you want to set.

  2. Select OK, and then, in the Scripts Management window, select Close.

Specifying Default Credentials for an Interactive Script

Script Actions whose security context is Prompt upon execution, which receive their credentials interactively, cannot be used as automated actions unless default shared credentials are specified in the script settings.

When no default shared credentials are specified for these types of Script Actions, they appear in gray in the list of available scripts for a trigger. If you select one, a notification like the one in the illustration below is added to the Follow-up Action screen. If you have the Manage Script Actions permission, you can specify the credentials to use in the script’s settings. In this case, a Click here to edit the Script Action link also appears.
image045.png
Notification indicating that the selected script prompts for credentials

Note: If you set up default credentials for a script to use when it runs automatically, as explained here, and the script is later run manually, the user is still prompted to enter the credentials to use. The credentials specified in the script’s settings appear as the default credentials, but they can be modified.

To specify the credentials a Script Action should use:

  1. In the Follow-up Action screen, select Click here to edit the Script Action. The script’s Properties window opens.

  2. In the Settings tab, under Security Context, in the Default shared credentials for automation field, select the credentials to use when the script is run automatically.
    image047.png
    Default shared credentials field with credentials selected

  1. Select OK.

Specifying Default (Current User) Credentials for Running a Script

Script Actions whose security context is Default (Current User) cannot be used as automated actions because no Current User is defined for them. In order to enable such scripts to be used as automated actions, default shared credentials must be specified in the script settings.

When no default shared credentials are specified for these types of Script Actions, they appear in gray in the list of available scripts for a trigger. If you select one, a notification like the one in the illustration below is added to the Follow-up Action screen. If you have the Manage Script Actions permission, you can specify the credentials to use in the script’s settings. In this case, a Click here to edit the Script Action link also appears.
image045.png
Notification indicating that the selected script prompts for credentials

Note: If you set up default credentials for a script to use when it runs automatically, as explained here, and the script is later run manually, the credentials of the current user are used.

To specify the credentials an automated-action script should use instead of Default (Current User):

  1. In the Follow-up Action screen, select Click here to edit the Script Action. The script’s Properties window opens.

  2. In the Settings tab, under Security Context, in the Default shared credentials for automation field, select the credentials to use when the script is run automatically.
    image049.png
    Default shared credentials for automation field with credentials selected

  1. Select OK.

Specifying the Computer on which to Run a Script

Script Actions whose execution context is Other computer prompt the user to select the computer on which they will run, and therefore cannot be used as automated actions. In order to enable them to be used as automated actions, the computer on which to run them can be specified in the Script Action’s settings.

When no default computer is specified for these types of Script Actions, they appear in gray in the list of available scripts for a trigger. If you select one, a notification like the one in the illustration below is added to the Follow-up Action screen. If you have the Manage Script Actions, you can specify the computer to use in the script’s settings. In this case, a Click here to edit the Script Action link also appears.
image051.png
Notification indicating that the selected script prompts for the target computer

Note: If you specify a default target computer for a script to use when it runs automatically, as explained here, and the script is later run manually, the user is still prompted to select the computer to use. The computer in the script’s settings appears as the default, but it can be modified.

To specify the computer on which the Script Action should run:

  1. In the Follow-up Action screen, select Click here to edit the Script Action. The script’s Properties window opens.

  2. In the Settings tab, under Execution Context, select theimage053.gif button. A Choose Computer dialog box opens.
    image054.png
    Settings tab
    image056.png
    Choose Computer dialog box

  1. In the grid, select the computer to run the script on when it is run automatically, and then select OK. The dialog box closes and the selected computer appears in the script’s Execution Context settings.
    image058.png
    Default computer selected

  1. Select OK.

Setting Up Pass-Through Authentication

If you do not want to include a plaintext password in a PowerShell Script Action, you can use pass-through authentication instead. To do this, you must configure the script to run on the Console with the Default (Current User) security context and specify appropriate default shared credentials. Then, do not specify any credentials for the script to use when it connects to VIServer. The lack of credentials there invokes pass-through authentication, and the default credentials you specified will be used to connect to VIServer and run the script.

To set up pass-through authentication for a PowerShell script:

  • In the script’s settings, configure the following settings:

Setting

Configuration

Execution Context

Select ControlUp Console.

Security Context

1.  Select Default (Current User).

2.  Under Default shared credentials for automation, select the credentials to use.

image060.png
Execution Context and Security Context settings configured for pass-through authentication


Troubleshooting

ControlUp provides two PowerShell cmdlets for management of the Automated Actions job queues. In addition, to get more information about the Script Actions that have run automatically, you can check the Windows Event Logs on the Monitor’s machine and on the target machines.

Powershell Commands

If Automated Actions jobs are not running when you expect them to, there may be a backlog in your system. This can occur, for example, if the throttling limitations are exceeded (see Throttling, above).

You can use the following PowerShell cmdlets to see what jobs are in the job queue and to clear the queue if necessary:

  • Get-CUAAQueue: Shows the Automated Actions job queue, per target computer, and the total number of jobs in the queue

  • Clear-CUAAQueue: Clears the queue of all pending Automated Actions jobs

To use the PowerShell scripts:

  1. On the Monitor’s computer, open Windows PowerShell as an administrator.

  2. Enter the following two commands once at the beginning of each session:

Import-Module -Name .\ControlUp.PowerShell.Monitor.dll
Open-ControlUpMonitor
  1. Enter the name of the cmdlet you want to run (Get-CUAAQueue or Clear-CUAAQueue). The cmdlet runs, and the output is displayed.
    image062.png
    Running the Get-CUAAQueue cmdlet to see the queue, and the Clear-CUAAQueue cmdlet to cancel all pending jobs

Windows Event Log

You can see information about every automated action performed by ControlUp in the Windows Event Logs of the Monitor’s machine and of the target machines on which the scripts ran. Automated actions appear in the Windows Event Viewer under Windows Logs > Applications.
image064.png
Windows Event Viewer showing a list of ControlUp Events
image066.png
Log of an Automated Actions event on the Monitor’s machine
image068.png
Log of an Automated Actions event on a target machine


Known Issues

The following issue has been identified and, at the time of this writing, has not yet been corrected:

  • Event logging of automated actions is not performed in some configurations. Normally, the Master CU Monitor fires all triggers and executes all Automated Actions. Each attempt it makes to run an automated action, whether it succeeds or fails, is documented in the Windows Application Log of the CU Monitor machine as Event ID 5005.

    In some configurations, Event ID 5005 is not added to the Windows Application Log of the CU Monitor computer as expected. To solve this problem, run CU Console once on the computer on which the Master CU Monitor is running. (After this has been done once, the Console does not have to be open or even installed on the machine any more in order for the event-logging to be performed properly.)

  • Under the following circumstances, an automated action will fail to run, with the error Exception: Failed to get environment block:

    The Execution Context of a Script Action that is used as an automated action is User Session, and the Security Context of that Script Action is the same user account under which the User Session is running.
    User account of session and of script are identical

    To avoid this problem, do not use the Default (Session’s User) option to run an automated action whose Execution Context is User Session.

Note: It is not recommended to use the credentials of an actual user to run Script Actions. Instead, you can create a dedicated user account to run Script Actions.

Powered by Zendesk