- 04 Sep 2023
- 4 Minutes to read
Augmented Help Reference
- Updated on 04 Sep 2023
- 4 Minutes to read
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.
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
- restricted values of
[A-Z]:, which is a regex that allows values like
AHParameter: Augmented Help Parameters
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.
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 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.
|indicates that the parameter is not required|
|a list of acceptable or suggested values for the parameter as a comma-separated list|
|specified the default value of the parameter|
|displays the parameter in its own tab|
|parameter value will be "injected" as a variable into the script, prior to being run|
|parameter value will be captured at the end of the script, and set in OtterScript|
|parameter name/value should be set as an environment variable before running the script|
|parameter value will only be used to format the argument string|
|display the input as a password box and avoid logging the value when possible|
|the parameter value should be text|
|the parameter value should be restricted to "true" or "false"|
|same as |
|the parameter value should be an OtterScript list|
|the parameter value should be an OtterScript map|
- 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.
- You can only specify one type restriction (bool, switch, list, map)
- You can't specify an unsupported type (e.g.
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.
|AHExecMode||The name of a variable that Otter will set to either |
Required when Remediating Drift with PowerShell & PSEnsure
|AHConfigType||This 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.
|AHConfigKey||This 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.
|AHDesiredValue||This is what you wish the configuration value to be. |
Optional: When not specified, the true value (e.g.
|AHCurrentValue||This is the actual value of the configuration. |
Optional: When not specified, the script's return (output) is used.
|AHValueDrifted||This 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.