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 /noprofile’.

Note: Be aware that scripts are not run in a shell with elevated privileges.

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

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.

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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Powered by Zendesk