Augmented Help Reference

Modified on July 26, 2024

Script authors will often use "comment headers" to describe what a script does and how to use the script (i.e. the script's arguments). Many scripting languages have a convention for formatting these headers so that they can be read and used by various help tools.

For example, PowerShell has Comment-Based Help and provides information about parameters using this format:

.PARAMETER drive_letter
Drive letter to perform the operation on, such as "A:", 
"D:", etc.; this is optional, and "C:" will be used if none 
is specified

If your PowerShell script uses these conventions, Otter can automatically Create a GUI for Scripts with Input Forms for your script and display information and help text for users who need to execute it.

Otter also can read Python Script Docstring, and display a GUI using the provided parameter information.

What is Augmented Help?

While conventions like PowerShell's Comment-based Help and Python's Docstrings are a great start, they rely on a free-text description to provide instructions to the user on how to use the script. This can often lead to confusion or errors when the script is run - especially if the description isn't perfectly clear, or if the person running the script made a mistake.

Augmented Help is an Inedo-specific commenting format that you can use in your script's comment headers. It's similar to existing commenting conventions and, when used, Otter can generate a better user interface with input validation on the script.

Following the drive_letter example from earlier, the Augmented Help-version of the PowerShell .PARAMETER block would look like this:

.AHPARAMETER drive_letter(default="C:",format="[A-Z]:")
Drive letter to perform the operation on

It is nearly the same as the PowerShell .PARAMETER block, but instead of relying on the user to read the description, Otter will generate a textbox with

• default value of C:
• restricted values of [A-Z]:, which is a regex that allows values like A:, B:, or Z:

AHParameter: Augmented Help Parameters

An AHParameter (i.e., Augmented Help Parameter) describes a parameter to the script that will be used as an input variable, an output variable, an environment variable, or as part of the commandline arguments.

Using AHParameter is optional, and when a script's comment header defines one or more AHParameter items, Otter will use those instead of the convention-based parameters.

AHParameter Formatting

An AHParameter is formatted the same way across scripting languages:

param_name(category=..., default=..., optional, args/input/output/environment, sensitive, values="a,b,c,...", text/bool/switch/list/map): description

There's a lot of options, and only param_name is required.

Usage notes:

• If you don't specify parameter usage (input, output, environment, args), then input will be assumed.
• You can't specify an unsupported parameter usage (e.g. args for PowerShell).
• You can only specify one type restriction (bool, switch, list, map)
• You can't specify an unsupported type (e.g. switch for OtterScript)

Drift Detection & Remediation

If you want to use your scripts for drift detection and/or remediation, you can specify additional help items that will instruct Otter on how to use your script and record the results.