Automated Actions - User Guide

The following is a user guide that explains how to set up the Automated Actions feature and create an automated action.

Prerequisites

Make sure you meet the following requirements before using Automated Actions.

1. You have all the necessary permissions to configure automated actions.
2. There are Script-based Actions (SBAs) available in your organization that can be automated.
3. A valid commercial license.

Using Automated Actions in trial mode

If you use the trial version, make sure the 21-days trial has not expired yet. If the trial expired, you will not be able to use Automated Actions.

Process Summary

All steps are performed from the Real-Time Console.

1. Verify that your license includes Automated Actions:
   a. In the Real-Time Console, click the Help tab in the Home ribbon and click About.
   b. Click Licensing to open the License window and check the value in the Automated Actions row.

2. Create an Incident Trigger for the automated action:
   a. In the Trigger Settings window, select Add to create a new Incident Trigger.
   b. Begin configuring the trigger settings. When you get to the trigger list of follow-up actions, select Add.
   c. In the Follow-up Action screen, under Type, select Run an action.

For more details about this step, see Configuring an Automated Action.

3. Set up the Automated Actions feature:
   a. 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.

For more details about this step, see Setting Up the Automated Actions Feature.

4. Complete the process of creating the Incident Trigger:
   a. In the Follow-up Action screen, select the Script Name field.
   b. From the list, select the Script Action you want to run whenever the trigger is activated.
   c. Select OK.
   d. Select Finish.

---

Overview

Automated Actions are Script-based Actions (SAs or SBAs) that are configured to run automatically as follow-up actions of Incident Triggers. This guide explains how the Automated Actions feature works and can be used.

Use Cases

Some use cases for Automated Actions are:

Example of an Incident Trigger	Example of a Follow-up Action
A specified process consumes more than 90% of CPU for more than 5 minutes.	Run a script that kills the process.
The free disk space on the C:\ drive of a machine is lower than 5%.	Run a script that finds large files or directories, and log an Windows Event for further troubleshooting.
A service that is supposed to run all the time 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 the ControlUp Agent on it.
A browser points to a URL that is on a list of blocked sites (e.g., a gambling site).	Run a script that kills the browser tab.

Security

The process of automation is by nature sensitive, since mistakes made by users in setting it up can result in unexpected actions being taken by the system, sometimes without the users even being aware that this is happening. As a result, ControlUp limits automation via security policies and throttling.

Execution of Automated Actions

Automated Actions are executed by the ControlUp Monitor. The Automated Actions feature can only be used when you have at least one ControlUp Monitor running in your organization.

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.

---

Prerequisites

To use the Automated Actions feature, the organization must have
least one ControlUp Monitor running (see Execution of Automated Actions)

To work with the Automated Actions feature, users must have the following permissions:

• Create Automated Actions
• Configure Incident Triggers

---

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 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:

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 Acquiring a License for the Automated Actions Feature 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.
   

2. At the bottom of the screen, click Run automated actions setup wizard. The Automated Actions Setup wizard opens.
   
   

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

4. Select the scripts that should be available for automation in your organization.

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

6. Click Next. A list of users and groups that have the Automated Actions permission is shown.
   

7. To add users or groups of users to the list, select Add Users/Groups. The Account Browser window opens.
   

8. Select the domain and root in which the users’ accounts are defined, and use the Search Filter and Search Options to filter the list.

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

10. Select OK. The selected users and groups are assigned the Create Automated Actions permission, and appear in the list in the setup wizard.
    

11. 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-based 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 Windows Event Log of the monitor machine and in the ControlUp Audit Log. You can also configure ControlUp to send an e-mail send certain users 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 the ControlUp Real-Time Console, in the Home ribbon, select Triggers. The Settings window opens with the trigger settings displayed.
   

2. If the trigger you want to use already exists, select it from the list, and then click Edit to open its settings. If it does not yet exist, select Add Trigger to create it and configure its settings.

3. In the trigger’s settings, in the list of follow-up actions, select Add. The Follow-up Action dialog box opens.
   {height="" width=""}
   

4. Under Type, select Run an action. The settings for the automated action open.
   

5. Under Action Type, select Script Action.

6. 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
• Specifying the Computer on which to Run a Script

7. Select the Script Action you want to use as a follow-up action for the trigger.
8. 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).

9. If you selected Send script execution output to e-mail recipients, under Template, select the template to use for the e-mail.
10. Select OK. The Follow-up Action screen closes, and the automated action is assigned to the 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
• Manually Configuring the Automation Settings of a Script Action
• Throttling
• Compatibility between the Scopes of Script Actions and Incident Triggers
• Compatibility of Mappings between Script Actions and Incident Triggers
• Setting Argument Values for Interactive Scripts
• Specifying Default Credentials for an Interactive Script
• Specifying Credentials for Running a Script
• Specifying the Computer on which to Run a Script
• Setting Up Pass-Through Authentication

Assigning Automated-Actions Permissions to User Roles

A user cannot set up an automated action unless the user group in which the user exists has two permissions – Create Automated Actions and Configure Incident Triggers .

Note

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

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

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.
  

• 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:

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.

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.
   

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

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

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.
   

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

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.
   

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

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 Actionscreen, select Click here to edit the Script Action. The script’s Properties window opens.

2. In the Settings tab, under Execution Context, select thebutton. A Choose Computer dialog box opens.
   
   

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

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

---

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

You can use the following PowerShell cmdlets to see what jobs are in the job queue and to clear the queue if necessary. Make sure you run both commands as an administrator.

• 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

3. Enter the name of the cmdlet you want to run (Get-CUAAQueue or Clear-CUAAQueue). The cmdlet runs, and the output is displayed.

The screenshot below shows 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.

Windows Event Viewer showing a list of ControlUp Events:

Log of an Automated Actions event on the Monitor’s machine:

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.