Skip to content

Configurable values on scripts

In short: a script states which values it accepts from the outside. Those values then show up as fields on the check — thresholds, exclusion lists, switches. Adjusting a check no longer means touching the code.

Why this exists

Without configurable values the setting lives in the script:

$processName = "sqlservr"     # ← whoever needs a second process COPIES the script
$maxAgeHours = 26

The moment somebody copies, the copies drift: an improvement to the original never reaches them again. With configurable values one script feeds any number of checks, and every check has its own numbers.

Declaring a value

The declaration is a comment line inside the script:

# @vesana-param MAX_AGE_HOURS number "Maximum age" unit="hours" default=24 required
Part Meaning
MAX_AGE_HOURS Name. Uppercase letters, digits, underscore. Inside the script the variable is VESANA_MAX_AGE_HOURS.
number The kind of field (see below). Omit ⇒ text.
"Maximum age" The caption above the field on the check. In quotes.
default=24 Applies when the field is left empty.
unit="hours" Unit after the caption — display only.
required Mandatory. Without a value the check reports UNKNOWN instead of guessing.
help="…" Explanation below the field.
show_if=METRIC:a\|b The field only appears while the value METRIC is a or b (see below).

# is a comment in Bash, PowerShell and Python — the same line works in all three.

Why inside the script, not next to it

Because the script is what you hand to an AI (“add a value for X”). When it comes back with a new variable, the field is there immediately — nothing to add by hand. There is exactly one source of truth.

The field kinds — and how the script reads them

Every value arrives as an environment variable VESANA_<NAME>. Never as text substitution in the code: that way the value never becomes code, and the delivered body stays identical to the original.

Text

# @vesana-param DB_NAME text "Database" default=master

DB="${VESANA_DB_NAME:-master}"

$db = if ($env:VESANA_DB_NAME) { $env:VESANA_DB_NAME } else { "master" }

db = os.environ.get("VESANA_DB_NAME", "master")

Number

# @vesana-param WARN_PCT number "Warn above" unit="%" default=80

WARN="${VESANA_WARN_PCT:-80}"
[ "$value" -gt "$WARN" ] && exit 1

$warn = 80
if ($env:VESANA_WARN_PCT) { $warn = [double]$env:VESANA_WARN_PCT }

warn = float(os.environ.get("VESANA_WARN_PCT") or 80)

Prefer the threshold fields for limits

If your script prints a plain number, WARNING/CRITICAL belong in the check's threshold fields — they take effect immediately and can be overridden per device. A number value is meant for everything else: time windows, minimum counts, ports.

Yes / No

# @vesana-param INCLUDE_DISABLED boolean "Also check disabled jobs" default=no

Always arrives as 1 or 0 — never as true/yes. That makes the test identical in every language:

if [ "$VESANA_INCLUDE_DISABLED" = "1" ]; then …; fi

$withDisabled = $env:VESANA_INCLUDE_DISABLED -eq "1"

with_disabled = os.environ.get("VESANA_INCLUDE_DISABLED") == "1"

On the check the field has three states: Yes, No and not set — the last one falls back to the default from the declaration.

List

# @vesana-param EXCLUDE_JOBS list "Excluded jobs" help="Case-insensitive"

On the check you enter items one by one (press Enter after each) — spaces are fine, “Daily Backup” is one item. The script receives a comma-separated list: Daily Backup,Weekly.

# walk the comma list (POSIX, no arrays):
old=$IFS; IFS=','
for job in $VESANA_EXCLUDE_JOBS; do
  [ "$name" = "$job" ] && continue 2
done
IFS=$old

$exclude = @()
if ($env:VESANA_EXCLUDE_JOBS) {
    $exclude = $env:VESANA_EXCLUDE_JOBS -split ',' | ForEach-Object { $_.Trim() }
}
if ($exclude -contains $name) { continue }

exclude = [t.strip() for t in os.environ.get("VESANA_EXCLUDE_JOBS", "").split(",") if t.strip()]

An empty field leaves the variable unset — so [ -z "$VESANA_EXCLUDE_JOBS" ] cleanly means “no exclusions”.

Choice

# @vesana-param MODE choice "Report mode" options=summary|detailed default=summary

Separate the options with |. On the check this becomes a dropdown, so typos are impossible. Read it like a text value.

Password / token

# @vesana-param API_TOKEN password "API token" required

Technically exactly like text. The difference is how the interface treats it: the field is masked, and the “What the script receives” preview shows •••••• instead of the value. Use this kind for anything somebody could read over your shoulder — tokens, passwords, keys.

Showing fields only for the matching metric

One script often feeds many checks: the same ESXi script delivers CPU, datastores, VMs and uptime, depending on the metric selected on the check. Without further information, every one of those checks would show all fields — including those that contribute nothing to its metric.

show_if ties a field to the value of another one:

# @vesana-param METRIC choice "Metric" options=cpu|datastores|vms default=cpu
# @vesana-param DATASTORE_MIN_GB number "Skip datastores smaller than (GB)" show_if=METRIC:datastores
# @vesana-param VM_EXCLUDE list "Exclude VMs" show_if=METRIC:vms
  • The field appears as soon as the referenced value is one of the listed ones; separate several values with |.
  • What counts is the effective value: if nothing is set on the check, the referenced field's default applies.
  • A hidden field is not passed to the script — and a hidden mandatory field does not put the check on UNKNOWN. It is not part of this measurement.
  • In the script editor the condition can be set without editing the line by hand ("Only show when …").

Filling in values on the check

Open the check → Configuration. The fields appear below the selected script. Underneath, Vesana shows what the script will really receive on the next run:

What the script receives:
VESANA_MAX_AGE_HOURS=48
VESANA_EXCLUDE_JOBS=Daily Backup,Weekly
VESANA_INCLUDE_DISABLED=1
Takes effect on the next run of this check.

That is the honest answer to “does what I typed actually apply?”. There is deliberately no Run now button: only the Active Collector can run a check on demand, and most checks run through a collector or agent.

An empty field does not mean “empty value”, it means “the script's default”. An empty required field without a default lets the check report UNKNOWN honestly (Configurable values missing: …) instead of measuring against 0 and confidently reporting OK.

Values inherit as usual: what is set on the profile applies to all devices; what you change on the device applies there only.

Getting a value added

If the fields are not enough, the usual route is:

  1. Check → Configuration → Script → the pencil opens the content.
  2. Select the script, copy it, hand it to an AI: “Add a configurable value for the folder path to this script. Follow the # @vesana-param pattern already at the top.”
  3. Paste the result back into the window and save — the new field is there right away.

Because the declaration lives inside the script, the AI sees the pattern and does not have to guess.

One script feeds many checks

When saving, Vesana asks who the change applies to: all checks using this script (the normal case — only this way does an improvement reach everyone), as its own script (a visible copy in the library), or only this device. The last one no longer receives improvements made to the original.

Common pitfalls

Symptom Cause
Field does not appear The name must be uppercase and start with a letter. The editor shows messages about broken lines directly.
Value does not arrive The VESANA_ prefix is missing in the script.
Yes/No is not recognised Compare against "1", not "true" or "yes".
List is read as one item Split on the comma — the value arrives as a single string.
Check reports UNKNOWN “Configurable values missing” A required field is empty and has no default.
I'm looking for the limit at which the check turns yellow/red That is not an adjustable value. It lives on the check in the "Threshold verdict" block (Configuration tab, right below the script) — overridable per device, effective immediately. The script only prints the measured value.
Warning "declared but never read in the body" The header line exists, but the script never uses VESANA_<NAME> — the field would have no effect. Either read it in the script or remove the line.

See also