Documentation forServer & Application Monitor

Use macros and custom properties to populate API requests in SAM

The API Poller feature supports the use of macros (also called variables) to populate API request URLs and headers with node-specific data, so you can reuse the same request URL for multiple nodes. When you send the request, the Orion Platform automatically injects node-specific parameters into the URL.

Supported macros are based on the Node entity in the SolarWinds Information Service (SWIS), a data access layer in the Orion Platform. You can also use node-based custom properties, such as DeviceOwner or AssetTag, in API request macros.

Click here to learn more about custom properties in the Orion Platform Administrator Guide. See also Creative ways to use custom properties and Custom properties and how to use them. You can also watch this THWACKcamp (23:03).

Here is an example of a URL that uses a custom property to retrieve data about Nutanix clusters hosted on a node:
https://${cluster_host}:9440/api/nutanix/v2.0/clusters

This example includes the following elements:

  • The https protocol encrypts data sent back and forth.
  • cluster_host is a node-based custom property created for controller VMs.
  • 9440 is the default Nutanix Prism communication port.
  • /api/nutanix/v2.0/clusters is the endpoint for the request in the Nutanix REST API.

Use the standard, Latin1 character set in custom properties. Do not use angle brackets (<, >) as values.

Note the following details about using macros in the URLs of API requests:

  • The value of a node macro is unique for each node.
  • Wrap each macro in these characters: ${ }. For example, the macro for system name is ${SysName}.
  • Macros are not case-sensitive.
  • Currently, macros are not encrypted.
  • If SWIS doesn't recognize a macro, messages appear in polling logs and status is set to Unknown.

The API Poller feature supports the following Orion Platform macros in request URLs:

Macro

Description

${AgentPort}

Node SNMP port number.

${Allow64BitCounters}

Node allows 64-bit counters (1), or not (0).

${AvgResponseTime}

Average node response time , in msec, to ICMP requests.

${BlockUntil}

Day, date, and time until which node polling is blocked.

${BufferBgMissThisHour} Device‑dependent count of big buffer misses on node in current hour, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferBgMissToday} Device‑dependent count of big buffer misses on node in current day, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferHgMissThisHour} Device‑dependent count of huge buffer misses on node in current hour, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferHgMissToday} Device‑dependent count of huge buffer misses on node in current day, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferLgMissThisHour} Device‑dependent count of large buffer misses on node in current hour, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferLgMissToday} Device‑dependent count of large buffer misses on node in current day, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferMdMissThisHour} Device‑dependent count of medium buffer misses on node in current hour, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferMdMissToday} Device‑dependent count of medium buffer misses on node in current day, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferNoMemThisHour}

Count of buffer errors due to low memory on node in current hour.

${BufferNoMemToday}

Count of buffer errors due to low memory on node in current day.

${BufferSmMissThisHour} Device‑dependent count of small buffer misses on node in current hour, queried with MIB 1.3.6.1.4.9.2.1.30.
${BufferSmMissToday} Device‑dependent count of small buffer misses on node in current day, queried with MIB 1.3.6.1.4.9.2.1.30.

${Caption}

User-friendly node name.

${Category} Category of the node (for example, Other, Network, Server, or Auto-detected).
${ChildStatus}

Status of child objects (for example, interfaces or applications) monitored on a node.

For details, see Node status contributors.

${CMTS} The Cable Modem Termination System (CMTS) connected to a node.

${Community}

Node community string.

${Contact} Contact information for person or group responsible for node.
${CPUCount} Node CPU count at last poll.

${CPULoad}

Node CPU utilization rate at last poll.

${CustomPollerLastStatisticsPoll}

Day, date, and time of last poll attempt on node.

${CustomPollerLastStatisticsPollSuccess}

Day, date, and time that node was last successfully polled.

${CustomStatus} Status of node does not affect actual, polled values and alerts do not trigger.

${Description}

Node hardware and software.

${DetailsUrl} The URL of the Details page for the node.
${DisplayName} Name that appears for the node in the Orion Web Console.

${DNS}

Fully qualified node name.

${DynamicIP}

If node supports dynamic IP address assignment via BOOTP or DHCP (1); static IP address return (0).

${EngineID}

Internal unique identifier of the polling engine to which node is assigned.

${EntityType}

Indicates if a node is a VM.

See Hardware field values in NPM Node Details.

${External}

States if node is currently designated as external.

${GroupStatus}

File name of status icon for node and its interfaces.

${Icon} File name of an icon.

${IOSImage}

Family name of Cisco IOS on node.

${IOSVersion}

Cisco Internetwork Operating System (IOS) version on node.

${IP} Node IP address.

${IP_Address}

Node IP address.

${IPAddress} Node IP address, as may be represented in legacy Orion Platform modules.
${IPAddressGUID} The IP address of the node converted into GUID format using IPv6.
${IPAddressType} The protocol used for the IP address, such as IPv4.
${IsOrionServer} Indicates if a node is the main Orion server.
${IsServer} Indicates if a node is a Windows server running applications.*

${LastBoot}

Day, date, and time of last node boot.

${LastSync}

Time and date of last node database and memory synchronization.

${LastSystemUpTimePollUtc}

Time and date, in UTC format, when node was last polled for sysUpTime.

See also NPM Polling values explained in the Success Center.

${LoadAverage1} Load average over the last 1 minute.
${LoadAverage15} Load average over the last 15 minutes.
${LoadAverage5} Load average over the last 5 minutes.
${Location} Location of the node.

${MachineType}

Node manufacturer or distributor and family or version information.

${MaxResponseTime}

Maximum node response time , in msec, to ICMP requests.

${MemoryAvailable} Total node memory available.

${MemoryUsed}

Total node memory used over polling interval.

${MinResponseTime}

Minimum node response time , in msec, to ICMP requests.

${MinutesSinceLastSync} Number of minutes since the node was synced.

${NextPoll}

Day, date and time of next scheduled node polling.

${NextRediscovery}

Time of next node rediscovery.

${NodeDescription}

Internal unique identifier of node.

${NodeName}

Node host name. Defaults to node IP address ${IP_Address} if host name does not resolve.

${NodeStatusRootCause}

Node status, as influenced by child nodes.

For details, see Node status contributors.

${NodeStatusRootCauseWithLinks} Node status, as influenced by child nodes, that includes hyperlinks in HTML format.

${ObjectSubType}

States if node supports SNMP or is ICMP-only.

${OrionIdColumn} Orion ID column string.
${OrionIdPrefix} Orion ID prefix.

${PercentLoss}

ICMP packet loss percentage when node last polled.

${PercentMemoryAvailable} Percentage of node memory available over polling interval.

${PercentMemoryUsed}

Percentage of total node memory used over polling interval.

${PolledStatus} Basic node status that is not influenced by child nodes.

For details, see Node status contributors.

${PollInterval}

Node polling interval, in seconds.

${RediscoveryInterval}

Node rediscovery interval, in minutes.

${ResponseTime}

Node response time, in milliseconds, to last ICMP request.

${RWCommunity}

Node read/write community string; acts as security code for read/write SNMP access.

${Severity}

A network health score providing 1 point for an interface in a warning state, 1000 points for a down interface, and 1 million points for a down node.

${SkippedPollingCycles} The date and time of the last skipped polling cycle.

${SNMPVersion}

States the version of SNMP used by the node

${StatCollection}

Statistics collection frequency, in minutes.

${Status}

Numerical node status.

For details, see Status Icons and Identifiers.

${StatusDescription}

User-friendly node status.

${StatusIcon} File name of node status icon.

${StatusLED}

File name of node status icon.

${SysName}

String reply to SNMP SYS_NAME OID request.

${SysObjectID}

Vendor ID of the network management subsystem in OID form. Clearly determines the type of node.

${SystemUpTime}

Time, in hundredths of a second, since monitoring started.

${TotalMemory}

Total node memory available.

${UiSeverity}

States if node is currently unmanaged.

${Vendor}

Node manufacturer or distributor.

${VendorIcon}

File name of node vendor logo icon.