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

    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)

    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.

  • Script-based Actions

    Introducing Script-Based Actions

    Script-based Actions (SBA) allow the admin to extend the functionality of ControlUp to include anything that can be written in a CMD batch file, VBScript, or PowerShell script. Scripts can be run on the target computers, the ControlUp console, or any other computer in the ControlUp environment. They can also be run in different security contexts, if needed. Any admin can create an SBA and share it not only with the rest of their organization, but also share it with the ControlUp community. Users are automatically notified when there are additions and updates to either community or organizational SBAs.

    ControlUp SBAs offer the following advantages over traditional system scripts:

    1. Each time you run an SBA, you can choose any number of remote computers / user sessions / processes to act upon. ControlUp will handle the concurrent task execution, while passing all the relevant arguments to the scripts, depending on the objects you select.
    2. The user credentials used to execute the script can be configured every time you run the SBA. In addition, you can run SBAs on computers that belong to untrusted Active Directory domains and forests, as long as you have added them to ControlUp with valid credentials.
    3. Script output is automatically collected and compared, so you can quickly determine the outcome of the SBA execution on multiple targets, which can be a laborious task with scripts.
    4. Scripts can be executed either on your console machine, on any of your managed computers, or on a third computer of your choice. This feature allows for a great deal of flexibility – for example you may configure an SBA that uses a command-line tool that only exists on a specific server in your environment, select multiple computers and run the SBA on that dedicated server against all of the selected computers.

    The main SBA management window can be found on the Home Ribbon of My Organization pane and is divided into three sections: My Draft Actions, Organizational Actions, and Community Actions.

    My Draft Actions

    When you first create an SBA (see below for the procedure), it is stored in the My Draft Actions section in your private configuration where it can be tested and debugged until it is ready to be shared with others. The only restrictions on draft SBAs are that they cannot be used against more than one target at a time, and they cannot be shared with other ControlUp admins. When an SBA is finalized, it can also be shared with the user community at the same time.

    Organizational Actions

    In this section are all of the finalized SBAs created by all of the ControlUp users in the organization. If an SBA is modified here, it automatically goes back to the Drafts section until it is finalized again. From here, the SBAs can also be shared with the user community.

    Community Actions

    In this section are SBAs that have been shared by other ControlUp users throughout the world. They are all freely availble for use by all.

    Creating a Script-based Action

    To create a new SBA, click the ‘New’ button on either the Organizational Actions or My Draft Actions. Either way, the newly created SBA will be saved in the My Draft section.

    Name A name for your script-based action – required.
    Description Optional, but very helpful, especially when it is shared with the community.
    Icon Any JPEG or .png file that is 5KB or less in size. (This is usually 32×32 pixels.)
    Assigned to Which record type that the script will act upon as well as the basis for creating and evaluating script arguments (see below). The assignment also defines which view the script can be invoked from. If multiple views are desired, then the assignment ‘Advanced’ is chosen and multiple views can be defined.

    Note: that an action can only be assigned to one record type, even if it can be invoked from multiple views.

    For example: An SBA assigned to Computer is only viewable/runnable from the Computer view. If the action is also relevant to the Folders view, then the original assignment is ‘Advanced’ and within the Advanced Assignment box that appears, assign the action to ‘Computer’ and then choose to invoke it from both the Computer and Folders views. This could be useful if you want to use the folder as a method of choosing a group of computers to act upon.
    Execution Context This indicates which computer the script will run on. The only requirement from ControlUp is that the agent is installed on it. The script itself may have other requirements, such as certain PowerShell modules or snap-ins.
    Security Context Which user account will be used to run the script. The ‘Network Only Credentials’ checkbox is similar to ‘runas /netonly’ command-line option.

    Script tab

    The script text is what would be run if it were executed directly at the configured execution context. Parameters can be passed to the script according to the script type (see next section on arguments).

    Arguments tab

    Any property of a ControlUp record can be used as an argument to the script. The list of properties depends on the type of record that the script is assigned to (e.g., Computer, Session, Process).

    Example: A script is assigned to ‘Computer’. If arguments are assigned, ‘Name’ and ‘IP Addresses’ are possible properties that can be used. If the script were assigned to ‘Session’, those properties are not there but instead ‘Logon Time’ and ‘User’ are in the list, because those are relevant to the record type.

    It is also possible to prompt for parameter input at runtime. Manually entered parameters can be validated with a regex expression, if desired.

    Note: if you want to ensure that the field is not left blank, a simple “.+” (no quotes) can be used in the input validation box.

    The arguments will be mapped according to the script type and are referenced appropriately:

    BAT/CMD %1, %2, %3, etc.
    VBScript wscript.arguments(0), wscript.arguments(1), wscript.arguments(2), etc.
    PowerShell $args[0], $args[1], $args[2], etc.

    The Preview button allows you to preview exactly how the arguments will be passed to the script. If an argument comes from a record property, you are prompted to choose a record to use for the preview. If an argument is from user input, then you are given the opportunity to type in the input you are looking for and validate it with the regex expression that was supplied. This way you can easily test the field and the validation.

    Once the SBA is created, it is placed in the My Draft Actions tab until finalized. This allows you the opportunity to test the SBA privately (and on only one target at a time).

    Version numbers

    Version numbers are organized according to the following system:
    <community>.<organization>.<draft>

    Examples:
    • A script with a version of 0.3.3 means that it was edited 3 times in the draft folder, and also 3 versions of it at the organizational level. It has never been published to the community. (every time it was edited, it was finalized).
    • A script with a version of 0.1.3 means that it was edited 3 times in the drafts folder, and then finalized once to the organization. It has never been published to the community.
    • A script with a version of 3.8.22 means that it has been edited 22 times in the drafts folder, finalized to the organization 8 times, and also published/shared to the community 3 times.

    Editing an existing SBA

    Editing an SBA, whether from Organization or from My Draft, is done the same way. Highlight the SBA, click the ‘Modify’ button (or double-click the item or click on the pencil at the right side of the row), and then you will have a window with all three tabs/sections of the SBA available for editing.

    If an organizational script is edited, it creates a new draft script, incrementing the draft version number (e.g., an organizational script at version 0.1.2 after editing will also be in the drafts folder at version 0.1.3.). You will then see two scripts in the context menu, one from the Organizational Actions and the other from the My Drafts Action, labeled ‘(Draft)’.

    2018-10-29_1546.png

    If you edit the same organizational SBA while there is a version already in the drafts folder, ControlUp will warn you that the existing draft version will be overwritten by the new edits if you continue.

    When the new draft SBA is finalized, it will replace the previous organizational script (if it exists) and increment the organizational version number (in our example above, the script becomes version 0.2.3)

    Using an SBA and understanding the output

    SBAs can be invoked for ControlUp records from the Actions ribbon bar (Home -> Actions), the Actions side panel, or the context menu for the appropriate record. All SBAs from Organizational Actions and My Draft Actions will be in the list.

    2018-10-29_1547.png

    The listed SBAs will be appropriate to the current view. Click on the desired script while the desired targets are chosen from the grid.

    If the SBA is configured to prompt for parameter input from the admin (for example, execution context of ‘other computer’, or security context ‘prompt upon execution’), those values will be requested when the script is run. If the script uses record properties as arguments, the console automatically retrieves those properties at this time without requesting input from the admin.

    The results screen is below. There are a number of sections of the results screen of interest.

    In the top half of the window, the ‘Output’ section displays normal output (StdOut) and the ‘Error’ section displays StdErr. The bottom section gives various details about the script execution on each target attempted. Some of the fields, like ‘Status’ and ‘Exit Code’ can depend on how the script is written. In the top half of the window, ‘Output’ and ‘Error’ refer to command line output and errors.

    Example:

    Here we see a VBScript that failed to run because the target computer (Execution Context) is not a part of a domain that has a trust relationship with the domain that the running user (Security Context) belongs to. There is a command-line error shown, but since the script never ran, nothing was in StdErr.

    Consider this XenDesktop PowerShell script snippet:

    If ($TargetMachine -ne $null) {
            $TargetMachine | Set-BrokerPrivateDesktop -InMaintenanceMode $false
            Write-Host "$machineName is no longer in Maintenance Mode"
        } else {
            Write-Host "Could not find desktop $machineName"
            Exit 1
        }

     

    Without the ‘Exit 1’ command to explicitly send the exit code, the script status would show ‘Exit Successfully’, even though there was a failed condition. This is due to how PowerShell evaluates error conditions and return codes. Since we want regular messages to StdOut, the Write-Host is used to write to the ‘Output’ window. Write-Error would put the message into StdErr (‘Error’ – see below).

    Getting the script to report on the result screen as desired may take some extra scripting. For example, continuing to use the PowerShell snippet above, $TargetMachine could have a value, but the Set-BrokerPrivateDesktop cmdlet could still fail for some reason. The cmdlet in this case may require a Try/Catch construct to get the desired behavior from the results window.

    Batch commands and VBScript will behave similarly. If you do not see the results in the windows that you expect, try other similar batch/VBS/PoSh commands and review how the language processes output and return codes.

    The result groups are simply a way of grouping records with identical outputs to help simplify reading and interpreting results. Any error messages must also be identical for the targets to be in the same result group.

    Lastly, the Stop/Rerun buttons at the top give the admin a way to force an SBA to quit before it is finished, or immediately re-run the action on the desired targets with the same parameters without having to go through the setup steps again. This could be useful if, for example, there was an error condition that prevented a script from completing successfully. Upon seeing the script error, the admin makes the necessary fix and can now re-run the script just on the failed computer/account with a single click.

    Removing SBAs

    Removing SBAs in My Draft Actions or Organizational Actions is as simple as highlighting the SBA(s) that you want deleted and click ‘Remove’. You will be prompted to confirm your choice before deletion.

    Important Tip: Changes (add/edit/delete) made in the Scripts Management window are not committed to disk until ‘Apply’ or ‘OK’ is clicked in the main Scripts Management window. If a script was changed or deleted by mistake, cancelling out of the main Scripts window will throw away those changes, even if ‘OK’ or ‘Finish’ was clicked in the specific SBA window itself.

    Sharing SBAs with the Organization and the ControlUp community

    One of the powerful features of ControlUp is the ability to share your SBAs with other admins in your organization as well as with all ControlUp users. Conversely, you can also benefit from the SBAs of other ControlUp users all over the world. Once your script is ready, you can share it from either the My Draft Actions folder, or the Organizational Actions folder.

    All SBAs in the My Drafts Actions list are in your private configuration. For an SBA that is in the My Drafts Actions folder, there is a ‘Finalize’ button. This will transfer your SBA to your organization’s configuration, increment the version number, and remove the single target restriction. All organization members will receive a notification in the console and immediately be able to use it. At the same time, you can upload it to the ControlUp servers to be made available to all ControlUp users worldwide. The community scripts are approved by Smart-X before they are released. Although Smart-X will review all scripts before releasing them, safety and best practice dictate that you are responsible to review for yourself any script you download before you run it so that you are fully aware of what actions it will take.

    To finalize a draft SBA, simply highlight it in the ‘My Draft Actions’ tab and click the ‘Finalize’ button on the screen. The options here are:

    Yes, I want to share my work with the community In addition to moving it to the online organizational configuration, you may also share it with the community at the same time by leaving this box checked. If you do so, then the following fields are available.
    Credit to: This text box is to allow you to give credit to other people if they made contributions to the script, mention the original author of the code, which web site it came from (if applicable) or anyone else you want to acknowledge (Thanks, Mom!). For example, you may find something at the Scripting Guy website that you use to create an SBA. This would be the place to mention that and the URL where others can go to see the source for themselves.

    Tags

    If desired, enter a comma-separated list of tags that can be used to search for this SBA.

    Publish anonymously If you do not wish to be known, checking here will make the Author/Last Editor fields be filled by the word “Anonymous”.
    Allow community members to contact me by e-mail If you publish anonymously, this is automatically unchecked and greyed out. Otherwise, you have the option to allow others to contact you or not.
    Notes Enter a note to Smart-X relevant to the SBA approval (this field is only seen by Smart-X).
    “I accept the terms of the license agreement” You mus

    If you have finalized an SBA without sharing it, you can share it later from the Organizational Actions tab using the ‘Share’ button. This contains the same information and choices as the Finalize window in the ‘My Drafts Action’ section.

    Once an SBA is shared, it is reviewed and approved by ControlUp and then released to the community.

    If you remove a finalized (organizational) SBA that you have already shared with the community, the community version will not be deleted. If you need a public script removed from the community SBA collection, please contact ControlUp Support.

    Downloading community SBAs

    The ‘Community Actions’ tab contains all of the scripts contributed by ControlUp users everywhere. There are also a few scripts from ControlUp to demonstrate different SBA functions and some things that can be accomplished with SBAs, although they are not meant to be comprehensive examples.

    In order to import the community SBA for use in your organization, click the green ‘Add’ button. You will get a window with the full description, credits given, and a check box to accept the terms of the License Agreement. Click ‘Add Action’ and the script will be downloaded to your organizational configuration. In a few moments the button will turn to grey, show “Installed”, and you will see the script on the ‘Organizational Actions’ tab, at which point you will have full use of the script. You may also modify it and re-publish your version of the script (giving credit to the original author, of course). If the author chose to allow others to contact them by email, then the ‘Contact Author’ button will be active. When the user clicks that button, ControlUp will shell execute the ‘Mailto:’ command with the author’s email address.

    If you already have a community SBA and it is updated, the button for that SBA changes to ‘Update’ so that you know that a new version has been published. The first time that the Scripts Management window is opened after the updated SBA is published, there will also be a “New” graphic on the SBA. When the Scripts Management window is closed, the “New” graphic goes away, but the button will still be ‘Update’, so that you can update your organization’s copy of the SBA when you are ready.

    Additionally, all of your downloaded community scripts can be updated from the Organization Actions tab, either by clicking on each individual update icon on the right, or using the ‘Update All’ button that will appear on the top of the table. The ‘Update All’ button does not appear if there are no scripts to update.

    For your convenience, there is a search box on the right side of the Community Actions tab which searches by any text in the window – name, author, description, tags, etc.

    SBA and Security Policies

    Security Policies can be configured for SBAs.

    There are four management actions at the organizational level regarding SBAs:

    – Run shared SBAs: ability to run SBAs in the organization

    Run draft SBAs: ability to run SBAs in the drafts folder

    Download and share SBAs: ability to download SBAs from the community and share them with the community.

    Manage SBAs: ability to open the SBA window to manage SBAs. This does not prevent a ControlUp user from running SBAs they have been given permission to run. It just prevents opening the SBA management window.

    Once an SBA is finalized from a draft or imported from the community, it will be entered into the Security Policy template in the appropriate assignment and permissions can be assigned to SBAs individually if desired. Permissions granted or denied at the individual script level override anything granted at the organization level.

    SBAs assigned to Computer, Session, or Process records are part of the normal folder hierarchy of Security Policies. However, SBAs assigned to Folder, Account, or Executable records are not associated with the folder hierarchy and the security settings assigned to them will be in effect for the entire organization.

    Please refer to the documentation page for Security Policies for more details on how to assign permissions to Security Policy items.