Working with NetXMS

Practical how-to recipes for common NXSL scripting tasks in NetXMS. Each recipe states what it accomplishes, which script context it applies to, and provides a ready-to-use solution.

Find an Object by Name or ID

Goal: Locate a specific object in the NetXMS object tree by its name or numeric ID.
Context: Any script context (client scripts, EPP actions, scheduled tasks, etc.)

Use FindObject() with a name string or numeric ID. Always check for null — the object may not exist or the current user may lack access.

// Find by name
router = FindObject("Core-Router-01");
if (router != null)
{
    println("Found: " .. router.name);
    println("Type: " .. classof(router));
}

// Find by ID
node = FindObject(12345);

Iterate Over All Nodes

Goal: Process every node in the system (for reporting, auditing, or bulk operations).
Context: Client scripts, scheduled tasks. Avoid in transformation scripts due to performance cost (see Best Practices).

for (n : GetAllNodes())
{
    println(n.name .. " - " .. n.ipAddress);
}

Navigate Object Relationships

Goal: Traverse the parent-child hierarchy of the NetXMS object tree.
Context: Any script context where $node or $object is available.

// Get node's parents (containers, subnets, etc.)
for (parent : $node.parents)
{
    println("Parent: " .. parent.name .. " (type " .. parent.type .. ")");
}

// Get container's children
container = FindObject("Production Servers");
if (container != null)
{
    for (child : container.children)
    {
        println("Child: " .. child.name);
    }
}

List a Node’s Network Interfaces

Goal: Enumerate network interfaces on a node and check their operational state.
Context: Any script context where $node is available.

for (iface : $node.interfaces)
{
    println(iface.name .. " - " .. iface.macAddr);

    if (iface.operState == 1)  // Up
        println("  Status: UP");
}

// Get specific interface by index
iface = $node.getInterface(1);
if (iface != null)
    println("Interface 1: " .. iface.name);

Read DCI Values

Goal: Retrieve current or historical values from Data Collection Items.
Context: Any script context where $node or a target object is available. Common in EPP action scripts, condition scripts, and client scripts.

// Get current value by DCI ID
value = GetDCIValue($node, 123);
if (value != null)
    println("Current value: " .. value);

// Find DCI by description, then get value
dciId = FindDCIByDescription($node, "CPU Usage");
if (dciId > 0)
{
    value = GetDCIValue($node, dciId);
    println("CPU: " .. value .. "%");
}

Transform a Collected Value

Goal: Modify a DCI value before it is stored in the database.
Context: Transformation script — configured in DCI properties. The raw collected value is available as $1.

// Convert bytes to megabytes
return $1 / 1048576;

// Extract numeric value from string like "Temperature: 45C"
match = $1 ~= "(\d+)";
if (match)
    return match[1];
return DataCollection::ERROR;  // discard samples that do not match

To reject a collected value entirely, return DataCollection::ERROR, DataCollection::NO_SUCH_INSTANCE, or DataCollection::NOT_SUPPORTED from the transformation script — the sample is then discarded and not stored. There is no separate per-value filter script. Note that returning null does not discard the sample: the original (pre-transformation) value is stored instead.

Work with Table DCIs

Goal: Read and process multi-row, multi-column table DCI data.
Context: Any script context where the target object is available.

table = GetDCIValueByDescription($node, "Process List");
if (table != null)
{
    println("Columns: " .. table.columnCount);
    println("Rows: " .. table.rowCount);

    // Print first column name
    println("Column 0: " .. table.getColumnName(0));

    // Get cell value (row 0, column 0)
    println("Value: " .. table.get(0, 0));
}

Process Events in EPP Scripts

Goal: Access and use event data in Event Processing Policy scripts.
Context: EPP filter and EPP action scripts. The $event variable provides the current event.

println("Event: " .. $event.name);
println("Source: " .. $event.source.name);
println("Message: " .. $event.message);
println("Severity: " .. $event.severity);

// Access event parameters
println("Parameter 1: " .. $event.parameters[1]);

Add Custom Data to Events

Goal: Enrich an event with additional parameters for use in notifications and downstream processing.
Context: EPP filter scripts. The added parameter becomes available as %<name> in notification templates. Set the parameter in the rule’s filter script — a parameter added from an EPP action script of the same rule cannot be used in that rule’s notifications, because the notifications are prepared before the script action runs.

$event.setNamedParameter("location", $node.getCustomAttribute("location"));
// The parameter is now available as %<location> in notifications

Access Alarm Information

Goal: Read alarm properties and comments in scripts that process alarms.
Context: Hook::AlarmStateChange and scripts expanded via the %[script] macro (where $alarm is set when the event has an associated alarm). $alarm is not available in EPP action scripts.

println("Alarm: " .. $alarm.message);
println("State: " .. $alarm.state);
println("Acknowledged: " .. (($alarm.state == 1 || $alarm.state == 17) ? "yes" : "no"));

// Get alarm comments
for (comment : $alarm.getComments())
{
    println("Comment: " .. comment.text);
}

Check Node Capabilities

Goal: Determine what protocols and features a node supports before performing protocol-specific operations.
Context: Any script context where $node is available.

// Check if node supports SNMP
if ($node.capabilities & NodeCapability::SNMP)
    println("SNMP enabled");

// Check if node has NetXMS agent
if ($node.capabilities & NodeCapability::Agent)
    println("Agent installed");

See Node Capability constants for the full list of NodeCapability::* flags.

Read and Write Custom Attributes

Goal: Store and retrieve custom key-value data on objects for use across scripts and polling cycles.
Context: Any script context where the target object is available. Commonly used in Hook::ConfigurationPoll and EPP action scripts.

// Read custom attribute
location = $node.getCustomAttribute("location");
if (location != null)
    println("Location: " .. location);

// Set custom attribute
$node.setCustomAttribute("last_check", DateTime(time()).format("%Y-%m-%d %H:%M:%S"));

// List all custom attributes
attrs = $node.customAttributes;
for (key : attrs.keys)
{
    println(key .. " = " .. attrs[key]);
}

Perform SNMP Queries

Goal: Read SNMP data from a managed node.
Context: Any script context where $node is available and the node supports SNMP. Check with $node.capabilities & NodeCapability::SNMP first.

transport = $node.createSNMPTransport();
if (transport == null)
{
    trace(1, "Failed to create SNMP transport");
    return null;
}

// Get single value
sysDescr = transport.getValue("1.3.6.1.2.1.1.1.0");
println("System: " .. sysDescr);

// Walk a subtree
results = transport.walk("1.3.6.1.2.1.2.2.1.2");  // ifDescr
for (r : results)
{
    println(r.name .. " = " .. r.value);
}

Walk the Object Tree Recursively

Goal: Traverse the entire object hierarchy from a starting point, visiting all descendants.
Context: Client scripts or scheduled tasks (avoid in high-frequency contexts).

function walkTree(obj, level)
{
    for (i = 0; i < level; i++)
        print("  ");
    println(obj.name .. " [" .. classof(obj) .. "]");

    for (child : obj.children)
    {
        walkTree(child, level + 1);
    }
}

root = FindObject("Entire Network");
if (root != null)
    walkTree(root, 0);