Skip to content
English
  • There are no suggestions because the search field is empty.

Variables in Automations

Use Variables in Automations in your Kilter environment.

Purpose

This article describes the variables available when you build automations in Kilter, what each type is for, and how Kilter substitutes them while an automation runs. It includes example use cases.

Overview

An automation command can contain variables written as %%NAME%%. When the automation runs, Kilter replaces each variable with its current value before the command is sent. Kilter supports these types:

Type Set By Scope
Environment variables Kilter Available to every automation. Values come from the device, the session, and the server.
Global variables (Site-level and Device-level) User-defined in the Kilter webUI Shared across automations. Values are loaded for the device being run.
Dynamic variables (Dynamic Fields) The automation Created while the automation runs and available to later steps in the same run.

Environment variables are not currently listed in the Kilter webUI. They are described below.

Environment Variables

Device And Connection

Description Variable
Device name %%DEVICE_NAME%%
Device ID %%DEVICE_ID%%
Device external ID %%EXTERNAL_ID%%
Device hostname %%DEVICE_HOSTNAME%%
Device IP address %%HOST%%
Device connection port %%PORT%%
Device authentication username %%USER%%
Device authentication password %%PASSWORD%%
Extra password (usually enable) %%SU_PASSWORD%%
Second username (if required) %%COMMAND_USER%%
Second password (if required) %%COMMAND_PASSWORD%%
SNMP community string %%SNMP_COMMUNITY%%
SNMP version %%SNMP_VERSION%%
Vendor and product of the backup type %%VENDOR_NAME%%, %%PRODUCT_NAME%%
Device custom fields (n is the field number) %%CUSTOM_FIELDn%%, for example %%CUSTOM_FIELD1%%
Value from the "getprompt" command %%CURRENT_PROMPT%%

Server and File Locations

Description Variable
Kilter IP address for this session %%SERVER_IP%%
Kilter IP address from Settings → Administration %%DEFAULT_SERVER_IP%%
Working directory of the current run %%DEFAULT_BACKUP_LOCATION%% or %%DBL%%
Working directory of the previous run %%PREVIOUS_BACKUP_LOCATION%%
Location of the last successful backup %%LAST_SUCCESSFUL_BACKUP%%
Task variables %%TASK_VARIABLE1%%, %%TASK_VARIABLE2%%

Keystrokes and Special Characters

Description Variable
Enter (carriage return) %%ENTER%% or %%CR%%
New line %%NL%%
CTRL + C %%CTRL_C%%
Break %%CTRL_BREAK%%
CTRL + Y %%CTRL_Y%%
CTRL + Z %%CTRL_Z%%
Any ASCII character by decimal code %%char_N%%, for example %%char_27%% for Escape

Global Variables

Global variables are user-defined and shared across automations. They store named, reusable values that you reference in automation commands, so you change a value in one place. You configure them under Settings → Variables. There are two types: Site variables and Device variables.

When an automation runs against a device, Kilter loads that device's site and device variables into the run, using the variable name exactly as you defined it. Variables marked Encrypt are stored encrypted and masked in logs.

Why Use Site and Device Variables

Custom fields (%%CUSTOM_1%%, %%CUSTOM_2%%, %%CUSTOM_FIELDx%%) are a fixed, numbered set of slots defined per backup type. They have no descriptive name inside an automation, the number of slots is limited, and you must check the backup type configuration to know what each one holds.

System variables such as %%DEVICE_NAME%%, %%HOST%%, and %%SERVER_IP%% are predefined by Kilter and cannot be user-defined, so they cannot hold custom business data such as ticket IDs or owner contacts.

Site and Device variables avoid both limitations:

  • They have descriptive names, such as %%site.backupPath%% or %%device.snowCiSysId%%, so automations are easier to read.
  • They are user-defined, so you can add any data point without changing a backup type configuration.
  • They are scoped correctly. Site variables are shared across a site, and Device variables are unique to each device.
  • Device variables can be edited per device from the device grid, and sensitive values can be flagged for encryption.

Site Variables

Use a Site variable when the value is the same for every device at a site, or across all sites if it is scoped globally. Good candidates include a shared backup destination path, a shared SNMP community string, or any site-wide default.

Site variables are created in the webUI as %%site.<name>%%. They are intended to be administrator-managed inputs, and automations should not change them.

Example: A Site variable named %%site.backupPath%% is set to /data/backups/hq.

Command 1: scp %%DEVICE_NAME%%:%%site.backupPath%%/running-config.cfg /tmp/running-config.cfg Command 2: %%ENTER%%

Every device at the site resolves %%site.backupPath%% to the same value, so the same automation works across the whole site without per-device edits.

Device Variables

Use a Device variable when the value is unique to each device but the automation logic is the same. Good candidates include a CMDB or ticketing identifier, an owner or contact, or a per-device override such as a non-standard enable password.

Device variables are created in the webUI as %%device.<name>%%, with a value assigned to each device. Unlike Site variables, Device variables can be updated during automation execution.

Ways To Populate A Device Variable

  1. Manually: Type the value for each device from the variable's grid.
  2. Automatically: Capture it from a command inside an automation. On the command, enable the Save totoggle, set Output Type to Variable, and set Save Output to the variable's exact name, for example %%device.snowCiSysId%%. When the job finishes, the command's output is written to that device's stored value.

Example: %%device.snowCiSysId%% holds ABCD-1001 on one device and ABCD-1002 on another.

Command 1: curl -X POST https://example.service-now.com/api/now/table/incident -d "cmdb_ci=%%device.snowCiSysId%%&device=%%DEVICE_NAME%%"

The same command runs against every device but resolves to a different CMDB record each time.

Combining Site And Device Variables

You can use both in one step. With %%site.region%% set to NA-East and %%device.ownerEmail%% assigned per device:

Command 1: curl -X POST https://alerts.example.com/notify -d "region=%%site.region%%&owner=%%device.ownerEmail%%&device=%%DEVICE_NAME%%"

The region is managed centrally at the site, while the owner travels with each device record.

Choosing The Right Option

If The Value... Use
Differs per device Device variable
Is the same across a site or all sites Site variable
Is a small, fixed value already tied to a backup type configuration Custom field (acceptable, though a Site or Device variable is preferable if you need a clear name or per-device scope)
Is built-in device or session context, such as %%HOST%%, %%USER%%, or %%DEVICE_NAME%% The existing system variable

Dynamic Variables

Dynamic variables (Dynamic Fields) exist only for the duration of one automation run. Use them to store command output, capture a runtime value, or hold a temporary value for conditional logic in later steps. You can name them freely. Start and end the name with %% so it matches the other variables, for example %%FW_VERSION%%.

Each dynamic field can have these options:

  • Mandatory: a value is required. You cannot save the Device Details tab without it.
  • Encrypt: the value is encrypted. This is the default for fields such as Password.
  • Hide Command: the value is hidden from the Backup log.
  • Free Text: sets the text displayed as the field name.
  • Default Value (optional): the value shown when the screen is selected.

How Kilter Substitutes Variables

  • Substitution happens each time a command is prepared, so a value set by an earlier step is available to every later step.
  • A variable whose value contains another variable is expanded, up to three levels deep.
  • Variables marked Encrypt or Hide Command are replaced with ***** in the logs. The real value is still sent to the device.
  • A variable that has no value is replaced with an empty string.

Example Use Cases

1. Copy A File From Kilter To A Device And Accept The Prompt

Use environment variables for the device and server, and %%ENTER%% for the confirmation:

Command 1: scp %%DEVICE_NAME%%:/tmp/file.example %%SERVER_IP%%:/data 

Command 2: %%ENTER%%

2. Log In With The Device's Own Credentials

Reference %%USER%% and %%PASSWORD%% instead of typing credentials into the automation. Each device uses its own stored values, and the password is masked in the log.

3. Save Output To A Per-Run Folder

Write results under %%DEFAULT_BACKUP_LOCATION%% so each run keeps its own files. Use %%PREVIOUS_BACKUP_LOCATION%% to compare against the last run.

4. One Task, Many Devices, Different Values

When you need to run the same commands on many devices and one detail differs per device (a port number, interface name, or slot ID), you do not need a separate automation per device or edits before each run.

Create a Device variable such as %%device.portNumber%% and assign each device its value. Reference it once in a single Task automation:

Command 1: configure terminal 

Command 2: interface %%device.portNumber%%

Command 3: shutdown

Command 4: no shutdown

Command 5: end

Assign the Task job to all devices at once. Kilter processes each device in the job and substitutes that device's own %%device.portNumber%% before the commands run.

To avoid typing port numbers by hand, run a discovery automation first. Add a command that queries the switch for the port a given host is connected to, enable Save to, set Output Type to Variable, and set Save Output to %%device.portNumber%%. Running it once across your switches fills in the variable for every device.

5. Passing Data Between Automations

A Device variable does not need a value when it is created. It can start empty, be filled by one automation, and be read by another on a later run.

Create %%device.lastInterfaceStatus%% and leave it unassigned. In Automation A, capture the output into it:

Command 1: show interface status %%device.portNumber%%

On this command, enable Save to, set Output Type to Variable, and set Save Output to %%device.lastInterfaceStatus%%. When the job finishes, the output is stored for that device. Automation B can then read it back later:

Command 1: echo Previous status was %%device.lastInterfaceStatus%%

The value is stored on the device record, not inside either automation, so it remains available to any automation that runs against that device later.

6. Capture A Value And Reuse It

Store the output of a command in a dynamic variable such as %%FW_VERSION%%, then use it in a later command or condition in the same automation.

7. Send A Key That Has No Name

Use %%char_27%% to send the Escape character, or %%CTRL_C%% to interrupt a running command.

Common Mistakes To Avoid

  • Storing a per-device value in a Site variable, which makes every device resolve to the same value.
  • Creating a separate Device variable per device for a site-wide default, which duplicates data that you must keep in sync by hand.
  • Using numbered custom fields for values that need a clear name or must scale beyond the fixed slots.
  • Leaving sensitive values, such as passwords or API tokens, unencrypted on a Site or Device variable. Flag them for encryption.

Tips

  • Use environment variables for values Kilter already knows, and global variables for values that vary by site or device.
  • Mark passwords and tokens Encrypt so they are masked in logs.
  • Variable names are case sensitive. Use the exact spelling shown in this article.

Related Articles

If you need additional information, contact support@backbox.com.