Parameters, Validators, and Actions¶

This page explains how to configure the input parameters shown in the script launch dialog. It covers the available value sources for each parameter, display and visibility options, input validation via regular expressions, and combo box actions that dynamically control the dialog at runtime.

Parameters¶

Parameters define what the user sees and enters in the dialog before running a script. They are passed to the script in the order they are listed.

Declaring parameters¶

First, list all parameter identifiers for the script. The order here determines the order in the dialog and the order in which values are passed to the script.

oneclickext.scripts.<scriptitem>.params: p1 p2 p3

The identifiers (p1, p2, etc.) are arbitrary; they are only used internally to look up the other properties.

Each parameter needs at least a display name:

oneclickext.scripts.<scriptitem>.p1.name: IP Address

Value sources¶

A parameter's value can come from one of the following sources. Only one source should be set per parameter.

Static default value:

oneclickext.scripts.<scriptitem>.p1.value: SpecAdmin

Supports the %DATE% variable, which is replaced with the current date and time.

Spectrum attribute of the selected model:

oneclickext.scripts.<scriptitem>.p1.attr: 0x12d7f

The value is read from the specified attribute ID on the model selected in the console. If reading fails, the static .value is used as a fallback (unless .emptyvalueonerror is set).

Note

devattr (reading from the device of the selected model) is not supported for multi-device scripts.

Spectrum attribute of the device linked to the selected model:

oneclickext.scripts.<scriptitem>.p1.devattr: 0x12d7f

Reads the attribute from the device reached via the model's Significant_Model_ID (attribute 0x12a56). Only for single-device scripts.

System parameter:

oneclickext.scripts.<scriptitem>.p1.sysparam: osuser

Available values:

Value	Description
`osuser`	OS user name of the session
`specuser`	Spectrum user name
`starttime`	Formatted start time (format set by `oneclickext.scripts.starttime`)
`hostname`	Hostname of the client machine
`scriptip`	IP address of the current device (multi-device scripts only)
`scriptdns`	DNS name of the current device (multi-device scripts only)
`devlist`	Full device list file (multi-device scripts only)
`param1`, `param2`, …	Command-line parameters (standalone mode only)

URL parameter (for web-invoked scripts):

oneclickext.scripts.<scriptitem>.p1.urlparam: myParam

The value is taken from the URL query string: &myParam=<value>.

Combo box (dropdown):

oneclickext.scripts.<scriptitem>.p1.combo: Option A|Option B|Option C

Pipe-separated list of choices. See Combo boxes and actions below.

Display options¶

# Hide the parameter row entirely (value is still passed to the script)
oneclickext.scripts.<scriptitem>.p1.hidden: false

# Show asterisks instead of the actual value (for passwords). Not applicable to combo boxes.
oneclickext.scripts.<scriptitem>.p1.visible: true

# Make the field read-only. Not applicable to combo boxes.
oneclickext.scripts.<scriptitem>.p1.editable: true

# Show empty value when an attribute read fails, instead of an error string
oneclickext.scripts.<scriptitem>.p1.emptyvalueonerror: false

# Tooltip text shown on hover
oneclickext.scripts.<scriptitem>.p1.tooltip: Enter the management IP address

Input field width¶

# Width in pixels of all input fields in this script's dialog (default: 180)
oneclickext.scripts.<scriptitem>.width: 230

Validators¶

A validator checks user input against a regular expression before the script is allowed to run. If the input does not match, an error message is shown.

Validators are defined globally and then referenced per parameter:

# Define the validator
oneclickext.scripts.validator.<name>.regexp:  <regular expression>
oneclickext.scripts.validator.<name>.message: <error message shown to user>

# Reference from a parameter
oneclickext.scripts.<scriptitem>.p1.validator: <name>

Example¶

oneclickext.scripts.validator.valid_ip.regexp:  (25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])
oneclickext.scripts.validator.valid_ip.message: Please enter a valid IP address.

oneclickext.scripts.validator.non_empty.regexp:  .*\S+.*
oneclickext.scripts.validator.non_empty.message: This field must not be empty.

oneclickext.scripts.MyScript.p1.validator: valid_ip

Combo boxes and actions¶

A parameter can be displayed as a dropdown (combo box). When the user selects an entry, optional combo actions can automatically update other parameters or enable/disable the Run button.

Defining a combo box¶

# Pipe-separated list of options
oneclickext.scripts.<scriptitem>.p1.combo: Option A|Option B|Option C

# Return the index (1, 2, 3, ...) instead of the text value (default: false)
oneclickext.scripts.<scriptitem>.p1.comboidx: false

# Pre-select the nth entry (1-based; default: first entry)
oneclickext.scripts.<scriptitem>.p1.combosel: 1

Combo actions¶

Actions are triggered when a specific combo entry is selected. They are indexed by selection number (1 = first entry, 2 = second, etc.).

# List of action names to execute when entry n is selected
oneclickext.scripts.<scriptitem>.p1.comboaction.<n>.list: action1 action2

# Inline action definition (scoped to this parameter)
oneclickext.scripts.<scriptitem>.p1.comboaction.<actionname>.action: <action>
oneclickext.scripts.<scriptitem>.p1.comboaction.<actionname>.value:  <value>
oneclickext.scripts.<scriptitem>.p1.comboaction.<actionname>.param:  <Pn>

Actions can also be defined globally (shared across scripts) and referenced by name:

# Global action definition
oneclickext.scripts.comboaction.<name>.action: <action>
oneclickext.scripts.comboaction.<name>.value:  <value>
oneclickext.scripts.comboaction.<name>.param:  <Pn>

Available actions¶

Action	Value	Parameter	Description
`enable`	—	`Pn`	Enable the input field of parameter n
`disable`	—	`Pn`	Disable the input field of parameter n
`clear`	—	`Pn`	Clear the value of parameter n
`text`	text to insert	`Pn`	Set the value of parameter n to the given text
`date`	date specifier	`Pn`	Set parameter n to a computed date range value
`rbenable`	—	—	Enable the Run button
`rbdisable`	—	—	Disable the Run button

Date specifiers for the date action: lastDay.from, lastDay.to, lastWeek.from, lastWeek.to, lastMonth.from, lastMonth.to.

Disabling the Run button by default¶

To force a user to make a combo selection before the script can run, disable the Run button in the initial state and use rbenable to re-enable it:

oneclickext.scripts.<scriptitem>.runbutton.enabled: false

oneclickext.scripts.comboaction.en_rb.action: rbenable
oneclickext.scripts.comboaction.di_rb.action: rbdisable

Exit code formatting¶

After a script finishes, a completion dialog reports the exit code. The output window remains open so the user can review the full output:

Exit codes can be highlighted with HTML formatting in the output dialog. Define named format rules and list them in the order they should be applied:

oneclickext.scripts.exitcode.formats: ltZero zero gtZero

oneclickext.scripts.exitcode.format.zero.op:    eq
oneclickext.scripts.exitcode.format.zero.val:   0
oneclickext.scripts.exitcode.format.zero.start: <font size='5' color='green'>
oneclickext.scripts.exitcode.format.zero.end:   </font>

oneclickext.scripts.exitcode.format.gtZero.op:    gt
oneclickext.scripts.exitcode.format.gtZero.val:   0
oneclickext.scripts.exitcode.format.gtZero.start: <font size='5' color='red'>
oneclickext.scripts.exitcode.format.gtZero.end:   </font>

oneclickext.scripts.exitcode.format.ltZero.op:    lt
oneclickext.scripts.exitcode.format.ltZero.val:   0
oneclickext.scripts.exitcode.format.ltZero.start: <font size='5' color='blue'>
oneclickext.scripts.exitcode.format.ltZero.end:   </font>

Supported operators: eq (equal), gt (greater than), lt (less than).

The text block surrounding the output can also be formatted:

oneclickext.scripts.exitcode.format.text.start: <font size='5' face='verdana' color='black'>
oneclickext.scripts.exitcode.format.text.end:   </font>