Augmented Help Reference
  • 04 Sep 2023
  • 4 Minutes to read
  • Dark
  • PDF

Augmented Help Reference

  • Dark
  • PDF

Article summary

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.

optionalindicates that the parameter is not required
values=...a list of acceptable or suggested values for the parameter as a comma-separated list
default=...specified the default value of the parameter
category=...displays the parameter in its own tab
inputparameter value will be "injected" as a variable into the script, prior to being run
outputparameter value will be captured at the end of the script, and set in OtterScript
environmentparameter name/value should be set as an environment variable before running the script
argsparameter value will only be used to format the argument string
sensitivedisplay the input as a password box and avoid logging the value when possible
textthe parameter value should be text
boolthe parameter value should be restricted to "true" or "false"
switchsame as bool, except when used in an argument string, the parameter value will be --param_name
listthe parameter value should be an OtterScript list
mapthe parameter value should be an OtterScript map

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.

AHExecModeThe name of a variable that Otter will set to either Collect or Configure to help determine which execution mode to use; this is always Collect in verify operations (e.g. PSVerify)

Required when Remediating Drift with PowerShell & PSEnsure
AHConfigTypeThis is the "configuration type" used by the script, which is a string that identifies the type of configuration collected, such as a file or an IIS Application pool.

Optional: when not specified, the operation name is used (e.g. PSVerify, PyVerify, etc.) is used.
AHConfigKeyThis is the "configuration key" used by the script, which is a string that uniquely identifies a specific type of configuration collected. It's like a file name (a file is uniquely identified by its name), or an IIS Application name pool (an application pool is unqiuely identified by its name).

Optional: When not specified, the name of the script is used.
AHDesiredValueThis is what you wish the configuration value to be.

Optional: When not specified, the true value (e.g. $true in PowerShell) is used
AHCurrentValueThis is the actual value of the configuration.

Optional: When not specified, the script's return (output) is used.
AHValueDriftedThis is an indicator as to whether the value is considered drifted.

Optional: When not specified, it's a basic comparison of the desired and current values.

Was this article helpful?