- Print
- DarkLight
- PDF
Script-Based Actions (SBA)
- Print
- DarkLight
- PDF
Introducing Script-based Actions
Do you want to use the Real-Time Console or ControlUp Monitor to run scripts on your remote machines? No problem! You can do so by using Script-based Actions (SBAs). You can run your own scripts or you can download them directly in the console. From version 9.0.5, you can configure actions with PowerShell cmdlets.
Benefits of Using SBAs
SBAs offer the following advantages over traditional system scripts:
- You can execute scripts 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 can 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.
- Once you configured input arguments in the script editor, ControlUp automatically passes the relevant arguments to the script without user interaction.
- With security context, you can define which user or user group can execute an 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.
- 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.
- You can run SBAs follow-up actions for triggers. From version 9.0.5, you can configure triggers with PowerShell cmdlets.
How to Find SBAs
You can find the main Scripts Management window on the Home ribbon of the ControlUp Console, and it is divided into three sections: My Draft Scripts, Organizational Scripts, and Community Scripts.
My Draft Scripts
When you first create an SBA (see Creating a Script-based Action), it is stored in the My Draft Scripts 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 can not be used against more than one target at a time, and they can not be shared with other ControlUp admins. When an SBA is finalized, it can also be shared with the user community at the same time (see Sharing SBAs with the Organization and the ControlUp Community below for more details).
Organizational Scripts
All finalized SBAs created by ControlUp users in the organization are listed in the Organizational Scripts section. If an SBA appearing in the Organizational Scripts section is selected to be modified, a copy of the script appears in the My Draft Scripts section until it is finalized (see Modifying an existing SBA below for more details). An SBA appearing in the Organizational Scripts section can also be selected to be shared with the user community (see Sharing SBAs with the Organization and the ControlUp community below for more details).
Community Scripts
SBAs shared by ControlUp users around the world are listed in the Community Scripts section. Everyone can download and use them.
Creating a Script-based Action
To create a new SBA, perform the following steps:
Click Script Actions in the Home ribbon of the Real-Time Console.
In the Organizational Scripts or My Draft Scripts of the Scripts Management window, click New. The New Script Action window opens.
Provide details for the new SBA according to the table below:
Field Information Name Required: A name for the new Script-based Action Description Optional: A description for the new Script-based Action – optional, but very helpful, especially when it is shared with the community Icon Optional: Any jpeg or png file, 5 KB or less in size (recommended: 32×32 pixels) Click Next and the New Script Action window opens.
Configure the SBA by selecting three available options.
a. Assigned to. Select the entity for which you want to run the SBA.
b. Execution Context. Select the computer the script will run on from the menu shown below. The only requirement from ControlUp is that the ControlUp Agent is installed on it. The script itself may have other requirements, such as certain PowerShell modules or snap-ins.
As a result, you can access the SBA only by right-clicking the user session under the Sessions tab.
If the action is also relevant to the Machines view, select Advanced in the Assigned to field. An list of views opens in which you can select the other views from which the SBA should be availabe. As we want to the SBA in the Sessions and Machines view, we need to select both of them.
c. Security Context. Define the user which runs the SBA. You can select three different users:
- Default user. Depending on the Execution Context, this can be a default user, currently logged-in user or the Local System account. The location where the script resides is
- Prompt upon execution. Before you can execute the script, you need to select a user from a drop-down.
- Shared credentials. You can select a user that is stored in the Shared Credentials store.
The Security Context defines where the PowerShell script resides. Find more information here.
- Click Next to get into the code editor view. This window provides the following options.
- Script window. Copy and paste your script into the script text box. Altneratively, you can import the script by selecting a file after clicking Import Script.... After clicking the file, the script content is automatically copied into the Script box.
- Script Type. The scripting language.
- Execution Timeout (seconds). Defines a timeout in seconds. If the script is not executed within the configured value, a timeout will be thrown.
- When timeout is reached. Define the action when timeout is reached. You can either kill the process or return and leave the process running.
- Do not run if previous instance is running. Mark the checkbox if you want to prevent the script from running in more than one instance.
- Execute script with .NET engine (Preview). Select this option, if you want the script to run in-memory instead of being executed as a file. You can learn more about this option in the .NET Engine Execution article.
- Once the script is set up, click Next to configure input arguments for your script.
This window provides the following options:
- Add Argument. To open the argument window which allows you to configure arguments for your script.
- Edit. If you have arguments configured, you can edit those.
- Remove. Removes a selected argument.
- Preview. This shows you a preview of the argument.
Learn more about using arguments in the Adding arguments to your script section.
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 are mapped according to the script type and are referenced appropriately:
Script Language | Arguments |
---|---|
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. |
Once the SBA is created, it appears under My Draft Scripts until finalized. This allows you to test the script at one target at a time.
Adding arguments to your script
Adding parameters to your scripts is a common practice to make scripts more flexible. If you add parameters to your PowerShell scripts by using Param()
attribute, you force the input of parameters.
When you add a parameter to the script, the value for this parameter can either be a value that is known in ControlUp or a user-defined value. We explain the difference by using the following example:
[CmdletBinding()]
Param
(
[Parameter(Mandatory=$true,HelpMessage='Session id of session to message')]
[int]$sessionId,
[Parameter(Mandatory=$true,HelpMessage='Message text to send to session')]
[string]$message = "Your WiFi signal is weak. We suggest you move closer to the WiFi access point or use a different WiFi network."
)
Using record types as script parameters
The first parameter in our example is $sessionID which stores the value of the user session ID. This ID is already known to ControlUp, so we need to select the Use this record property checkbox and provide the following values:
Field | Value |
---|---|
Record type | Session |
Record property | ID |
When executing the script, the ID of the selected user session (in our case 1) is taken as the parameter value.
In the same window, you can define your own parameter name and add an input validation to your record property.
Using user-defined parameters
The second parameter we define is $message. This is the message we want to send to our user. If you define your own parameter, follow best practice and add parameter captions, a default value and some validation.
Field | Value |
---|---|
Parameter Caption | Message text to send to user |
Default | Your message |
Input Validation string (Regex) | \S+ |
Validation message | Please enter the message to be send to the user with this script |
When executing the SBA on a user session, the user that runs the SBA is prompted to provide a value for the message.
Once you click OK, the SBA is executed and the popup with the provided message is shown in the user session.
Input validation of a record property
When you select a record type, you can define how the value is validated.
- Pass empty parameter. This is the default behaviour. This passes "" as the a value.
- Do not pass parameter. (new in 8.6.5). No value is passed even when the parameter is empty.
- Abort script and log (new in 8.6.5). Does not run the script and logs the value(s) which were missing in the script in the Central Auditing log.
You can find more information on each option in the Options to ignroe empty metric data section.
Input validation with regular expressions
To validate or prevent wrong user input, you can use regular expressions. For example, if you want only digits to be allowed as the value, type \d
If the user uses any string message, the script is not executed and the following error is thrown:
Version numbers
Versioning your scripts is important to version control. The structure for version numbers is
{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 organization 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.
Modifying an existing SBA
You can modify an SBA either from the Organizational Scripts or My Draft Scripts section. There are three ways to do it:
- Select the SBA and click Modify.
- Double-click the SBA.
- Click the pencil icon right next to the SBA.
When you modify an organizational script, a copy of the script appears in My Draft Scripts with its draft version number incremented by 1. For example, we have script in the Organizational Scripts tab that has version 0.1.47.
After modifying the script, a copy of the script is created under My Draft Scripts with version 0.1.48.
You will then see two scripts with the same name in the context menu, one from the Organizational Actions and the other from the My Drafts Action, with the SBA name appended with the label (Draft).
If you edit the same organizational SBA while there is already a version in My Draft Scripts, 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.1.49)
Export an SBA
Click a script action or shift click to select multiple script actions. Once selected, click Export to create an XML file that contains the script definition and content. If
Import an SBA
By clicking Import, you can import an XML file that was exported from the same or another system.
Run Script-based Actions
You can execute scripts by right-clicking ControlUp objects, such as a virtual machine, a user session, or a process.
Hover over Script Actions and select the script from the context menu. Alternatively, you can use the Actions button in the Home ribbon. Draft and finalized scripts are visible in the context menu.
The listed SBAs will be appropriate to the current view. Click on the script you want to run while the targets on which you want it to run are selected in the grid.
If the SBA is configured to prompt for parameter input from the admin (for example, execution context of Other Machine, or security context for 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 without requesting input from the admin.
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.
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.
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/PowerShell 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
To remove an SBA from the Organizational Scripts or My Draft Scripts section, perform the following steps:
- Select the SBA you want to remove by clicking on it.
- Click Remove. The Delete Script Action dialog box opens.
- Click Yes to confirm deletion of the SBA.
When you delete your finalized (organizational) SBA, the community version will not be deleted. If you want a public script to be removed from the community SBA collection, contact our support team
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 ControlUp users around the world. At the same time, you can also benefit from the SBAs created and shared by other ControlUp users around the world. Once your script is ready, you can share it from either the My Draft Scripts or the Organizational Scripts section of the Main Scripts Management dialog box, as explained further below.
Sharing SBAs from My Draft Scripts
All SBAs appearing in the My Draft Scripts section are stored in your private configuration. When you share an SBA in the My Draft Scripts section by clicking Finalize as described in the procedure below, the following things occur:
- The SBA is transferred to your organization’s configuration.
- The version number is incremented.
- The single target restriction is lifted.
- All organization members receive a notification in the console that the SBA is available for use, and they are immediately be able to use it.
To share an SBA from the My Draft Scripts section, perform the following steps:
- Select the SBA you want to share by clicking on it. In the example screenshot shown below, you can see that the selected SBA is named My First Script Action.
- Click Finalize and the Share script dialog opens.
- Provide sharing details for your SBA.
- Yes, I want to share my work with the community. Click this checkbox if you want to share your script with the ControlUp community. Before the script is published to our official script library. It will be reviewed by a specialist who will contact you via email.
Fill in the next fields only if you want to share your script:
- Credit to. This field is the place to give credit to other people if they made contributions to the script. You can mention the original author of the code, which web site it came from (if applicable), or anyone else you want to acknowledge.
- Tags. Add a comma-separated list of tags that can be used to search for this SBA.
- Publish anonymously. Click this checkbox if you do not want your identity to be revealed. The author and last editor of the SBA will be listed as anonymous.
If you check the Publish anonymously box, the Allow community members to contact me by e-mail box is deactivated, and can not be checked.
Allow community members to contact me by e-mail. Allow community members to contact you by email. This checkbox is not available when the Publish anonymously checkbox is checked.
Notes. Add a note to ControlUp related to the SBA approval (this field is only visible to ControlUp).
- I accept the terms of the license agreement. You must agree to the terms of the license agreement.
Click Next to configure the permissions for the script. Define the user group that is allowed to run the script.
You can change the permissions in the Security Policy pane after you finalized the script.
Click OK to finalize your script. This removes the DRAFT tag from the script and moves the script to the Organizational Scripts section.
Downloading Community SBAs
You can find SBAs shared by ControlUp or the ControlUp community under the Community Scripts section of the Scripts Management window.
To import the community SBA for use in your organization, perform the following steps:
- Under the Organizational Scripts tab, search the SBA you want to download and click Add Script.
- In the details window of the script, accept the terms of the license agreement and click Next.
- Grant permissions to the user groups that should be allowed to run the script and click Add Action.
- Within a few seconds, the text on the button changes to Installed, and you can run the script within ControlUp.
SBAs and Security Policies
ControlUp offers great granularity to manage SBA permissions for user groups. In the Security Policy pane, you can grant permissions to four different actions:
- Run shared Script Actions. Permission to run SBAs in the organization
- Run draft Script Actions. Permission to run SBAs in the drafts folder
- Download and share Script Actions. Permission to download SBAs from the community and share them with the community.
- Manage Script Actions. Permission 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.
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.
Options to Ignore Empty Metric Data
With ControlUp version 8.6.5, we added two new options to validate input for empty record properties. Let's say you write a script and some of your arguments use empty record properties, then you don't want your script to run into an error. The screenshot below shows a Company value for the cuAgent.exe, but an empty value for the cuAgentHelper.exe process.
The two new options that we added to the Input Validation are
- Do not pass parameter. The script is being executed without the parameter.
- Abort script and log. The script is not being executed and the empty parameter value is logged in the Centralized Auditing Log.
Script Locations and How To Change Them
The folder in which PowerShell scripts reside is determined by the Security Context settings.
If you use “Default (Local System)” the location is: the System account AppData folder (e.g., C:\Windows\System32\config\systemprofile\AppData\Roaming\ControlUp\Scripts
)
If you use “Prompt upon execution” or “Shared Credentials” it will use %ProgramData%\Smart-X\ControlUp\Scripts
. For this option there is a way to override the location through the registry by adding a String value under HKEY_LOCAL_MACHINE\Software\Smart-X\ControlUp\
with the name SBATempFolder and the value being the location