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, enabling you to reuse the same request URL for multiple nodes. You can also use node-based custom properties, such as DeviceOwner or AssetTag, in URLs. When you send a request that includes a macro or custom property, node-specific parameters are automatically injected into the URL.

Here is an example of a URL that uses a custom property, cluster_host, 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.
  • cluster_host is a node-based custom property created for 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.

Note the following details about using macros and custom properties in API request URLs:

  • The value of a node macro is unique for each node.
  • Supported macros are based on the Node entity in the SolarWinds Information Service (SWIS), a data access layer in the Orion Platform.
  • Wrap each value in the following characters: ${ }. For example, to use the macro that represents the total amount of memory for a node, include ${TotalMemory} in the request URL.

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

  • Macros are not case-sensitive.
  • Currently, macros are not encrypted.
  • If SWIS doesn't recognize a macro, messages appear in polling logs and the API poller status changes to Unknown.

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

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).

${AncestorDetailsUrls}

URLs of node ancestors.

What are descendants and ancestors? Those terms represent relationships between nodes. For example, if a server hosts a VM, the VM is a descendant of the server. Ancestors for the server may be a cluster, data center, or vCenter server.

${AncestorDisplayNames} Names of node ancestors, as displayed in the Orion Web Console, reports, alerts, and so on.

${AvgResponseTime}

Average node response time , in milliseconds (ms), for 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.
${Image}

An image associated with a node. For example, an image may show a node's physical location, such as a network rack.

See this THWACK post for ideas about using images with nodes.

${InstanceSiteId} The site where data originated.
${InstanceType} Description of instance on node.

${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}

Node hardware and software.

${NodeID}

Unique ID assigned to the node.

The NodeID in the dbo.NodesData SQL database table is a unique key for monitored nodes. Assigned NodeIDs do not change; they are created by a counter that increments values by one automatically. For example, if NodeIDs 1, 2, and 3 exist, deleting NodeID 3 causes a gap in numbering when the next NodeID is added (1,2,4, 5, and so on).

${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} Indicates the operational status of the node (for example, UP).

${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 identifier that denotes node status. For details, see Status Icons and Identifiers.

${StatusDescription}

User-friendly text that represents node status.

${StatusIcon} File name of icon that represents node status.
${StatusIconHint} File name of icon that represents general status (for example, a green check mark indicating acceptable status).

${StatusLED}

File name of LED control associated with a node.

${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}

Returned result from a call to the Nutanix REST API.

${UnManaged} Indicates if a node is unmanaged.
${UnManagedFrom} The date when a node was unmanaged.
${UnManagedUntil} The date when a node was switched back to be a managed node.
${Uri} The Uniform Resource Identifier (URI) assigned to the node.

${Vendor}

Node manufacturer or distributor.

${VendorIcon}

File name of node vendor logo icon.