You can customize an action's message and certain configuration content using percent variables.

Note: For a table of WhatsUp Gold Alert Center specific variables, see the topic titled Alert Center Percent Variables.

Important guidelines when using percent variables

  • All percent variables in WhatsUp Gold are case sensitive.
  • The use of spaces in percent variables is not supported and not recommended.
  • Use of percent variables in script text (for example, Active Script Action) can expand to text containing special characters. For example ', ", %, [new line]. When unescaped, these literals can cause unexpected syntax or parsing errors, which break your script.
  • Active monitor variables are only used when an action is associated directly with an active monitor, and not the device as a whole.
  • When using percent variables as part of string literals in your PowerShell scripts, please use double quotation marks (" ") instead of single quotation marks (' ') to enclose the string literal. Example: $Message = "%Device.DisplayName changed state"

Several actions have individual data entry fields within their configuration dialogs that not only support, but also provide a list of percent variable for use.

Active Monitor Variables

Description

%ActiveMonitor.Argument

SNMP instance number. This is only used when an action is associated directly with an active monitor, and not the device as a whole.

%ActiveMonitor.Comment

String value that coincides with the comment(s) associated with the monitor. This is only used when an action is associated directly with an active monitor and not the device as a whole. Please note, in the case of interface active monitors, discovery uses this percent variable to automatically populate with the interface description.

%ActiveMonitor.Name

The name of the active monitor that fired an action. This is only used when an action is associated directly with an active monitor, and not the device as a whole.

%ActiveMonitor.NetworkInterfaceAddress

IP address for the network interface. This is only used when an action is associated directly with an active monitor, and not the device as a whole.

%ActiveMonitor.Payload

The payload returned by a WMI, Exchange, SQL, SNMP or Active Script active monitor. This is only used when an action is associated directly with an active monitor and not the devices as a whole.

For Active Script Active Monitors, the payload is the text that is passed to the SetResult() method in the script.

%ActiveMonitor.State

Current status of the monitor, such as "Down at least 5 min." This is only used when an action is associated directly with an active monitor and not the device as a whole.

Device Variables

Description

%Device.ActiveMonitorDownNames

List of down services using the abbreviated name if available.

%Device.ActiveMonitorDownNamesCSV

List of down active monitor names separated by a comma.

%Device.ActiveMonitorUpNames

Full service names of all UP monitored services on a device.

%Device.Address

IP address (from device properties).

%Device.Attribute.[Attribute Name]

Returns an attribute from the SNMP information available for the device, such as the Contact name. To specify the attribute, append the category name (listed below) to the end of the variable. For example: %Device.Attribute.Contact, returns the contact name.

Default categories:

  • *. Returns all attributes
  • Info1. Upgrade path from v8
  • Info2. Upgrade path from v8
  • Contact. Contact information from SNMP
  • Location. Location information from SNMP
  • Description. Description information from SNMP
  • Custom. If you have created a custom attribute, you can use the name of that custom attribute in the percent variable.

Example:

%Device.Attribute.Phone %Device.Attribute.RackPosition

Tip: To avoid an parsing error, ensure you include a space or line break at the end of the entire embedded percent variable (in other words, after the attribute name).

%Device.DatabaseID

Returns the database ID of a device.

%Device.DisplayName

Display Name (from General of device properties)

%Device.HostName

Host Name (from General of device properties)

%Device.Notes

Notes. (Notes are from the device properties Notes)

%Device.Role

Primary device role as displayed in the device properties interface.

%Device.RoleGUID

Global unique identifier for the primary role assigned to the device.

%Device.SNMPOid

SNMP Object identifier.

%Device.State

Device status description (for example, "Down at least 2 min" or "Up at least 5 min")

%Device.BestState

Device status description containing the "best" state of the device. For example, if a device has never been in the Up state because of failed monitors, the best state could be Down.

%Device.WorstState

Device status description containing the "worst" state of the device. For example, if a device has never been in the Down state because of failed monitors, the worst state could be Up.

%Device.Status

This shows the name of the active monitor, preceded by the device state id.

Example:

10 | DNS.

Device State ID values:

0 = Not Started, 1 = Paused, 2 = Canceled, 3 = Running, 4 = Complete, 5 = Resolving Hostname, 6 = Looking for Type, 7 = Scanning for SNMP Credentials, 8 = Scanning for Windows Credentials, 9 = Device Detail Scan, 10 = Scanning Custom Monitors, 12 = Scanning Custom Monitors, 13 = Device VMWare Host Scan, 14 = Scanning SSH Credentials, 15 = Layer 2 Scan, 16 = Computing Layer 2 Topology, 17 = Wireless Scan, 18 = Scanning Network Interfaces, 19 = Checking for Duplicate Devices, 21 = Scanning for Known Addresses

%Device.ManualMaintenanceReason

Custom string you populate with a reason for dropping a device into Maintenance Status.

%Device.Type

Device Type (from General of device properties)

Passive Monitor Variables

Description

%PassiveMonitor.DisplayName

The name of the monitor as it appears in the Passive Monitor Library.

%PassiveMonitor.LoggedText

Detailed Event description. (SNMP traps - Returns the full SNMP trap text.) (Windows Log Entries - Returns information contained in the Windows Event Log entries.) (Syslog Entries - Returns the text contained in the Syslog message.)

%PassiveMonitor.Payload.*

Payload generated by a passive monitor.

%PassiveMonitor.Payload.EventType

The type of passive monitor (Syslog, Windows Event, or SNMP Trap)

%PassiveMonitor.Payload.LogicalSource

Shows the device's logical IP address.

%PassiveMonitor.Payload.PhysicalSource

Shows the device's physical IP address.

System Variables

Description

%System.Date

Display system date (Uses the same format as the operating system on which the WhatsUp Gold server is running).

%System.DisplayNamesDownDevices

Display names of devices with down monitors

%System.DisplayNamesDownMonitors

Shows the name of a device and each monitor that is down on that device. The format of the response is 'device name':'monitor 1','monitor 2','...'

Example: ARNOR: FTP, HTTPS, Ping

%System.DisplayNamesUpDevices

Display names of up devices

%System.DisplayNamesUpMonitors

Shows the name of a device and each monitor that is up on that device. The format of the response is 'device name':'monitor 1','monitor 2','...'

Example: ARNOR: FTP, HTTPS, Ping

%System.InstallDir

Displays the directory on which WhatsUp Gold is installed

%System.NumberofDownDevices

Number of down devices on your network

%System.NumberOfDownMonitors

Shows the number of down monitors on your network

%System.NumberofUpDevices

Number of up devices on your network

%System.NumberOfUpMonitors

Shows the number of up monitors on your network

%System.Time

The current system time. The format is hh:mm:ss