Script Execution Contexts

NXSL scripts run in different contexts within the NetXMS server. Each context provides specific predefined variables and expects particular return value semantics. This page documents all available script execution contexts.

Common Variables

Most server-side script contexts automatically receive these variables through the SetupServerScriptVM() infrastructure:

Variable Type Description

$object

NetObj

Current object context (node, container, etc.)

$node

Node

Current node (set only when $object is a Node)

$map

NetworkMap

Current network map (set only when $object is a network map)

$isCluster

Boolean

true if $object is a Cluster

Additional variables are set depending on the specific context, as documented below.

Transformation Script

Modifies a collected DCI value before it is stored in the database. Configured in DCI properties under Transformation.

Item Details

Predefined variables

$object, $node, $dci (DCI)

Script arguments

$1 — raw collected value

Return value

Transformed value to store. Returning null does not discard the sample — the original (pre-transformation) value is stored instead. To discard the sample, return DataCollection::ERROR, DataCollection::NO_SUCH_INSTANCE, or DataCollection::NOT_SUPPORTED

 
// Convert bytes to megabytes
if ($1 == null)
    return DataCollection::ERROR;  // discard this sample
return $1 / 1048576;

Threshold Script

Custom threshold condition on a DCI. Evaluated each time a new value is collected. Configured in DCI threshold properties.

Item Details

Predefined variables

$object, $node, $dci

Script arguments

$1 — current DCI value, $2 — configured threshold value

Return value

true to activate the threshold, false to deactivate. Alternatively, a hash map with keys match (boolean match result) and optional currentValue and thresholdValue overriding the values used in generated events

 
// Activate if value exceeds 90 and node is not in maintenance
$1 > 90 and not $node.isInMaintenanceMode

Script DCI

Computes a DCI value using an NXSL script instead of collecting from an external source. Configured by setting the DCI origin to Script and specifying the script name in DCI properties.

Item Details

Predefined variables

$object, $node, $dci (DCI), $targetObject (the object that owns the DCI; differs from $object when the DCI has a source node, in which case $object is the source node)

Script arguments

Arguments configured in DCI properties as positional arguments

Return value

The computed DCI value to store. Returning one of the DataCollection:: constants reports the corresponding collection error

 
// Count the number of child nodes with agent
count = 0;
for (child : $node.children)
{
    if (classof(child) == "Node" && child.isAgent)
        count++;
}
return count;

Instance Discovery Filter

Filters instances found during instance discovery polling. Runs once per discovered instance. Configured in DCI instance discovery properties.

Item Details

Predefined variables

$object, $node, $targetObject (object where DCIs will be created, may differ from source), $sourceNode (set when an instance discovery source node is configured), $dci

Script arguments

$1 — instance key, $2 — instance display name

Return value

true to create a DCI for this instance, false to skip, or an array [instance, instance-name, related-object] to accept with custom instance name and related object (see Instance function for array format details)

 
// Only monitor physical network interfaces (exclude loopback and virtual)
not ($1 ~= "^(lo|veth|docker|br-)") and not ($2 ~= "Loopback")

EPP Filter Script

Determines whether an Event Processing Policy rule matches the current event. Configured in EPP rule properties under Filter.

Item Details

Predefined variables

$object, $node, $event (Event), $dci (DCI, set when the event is associated with a DCI), CUSTOM_MESSAGE, EVENT_CODE, SEVERITY, SEVERITY_TEXT, OBJECT_ID, EVENT_TEXT

Script arguments

Event parameters as positional arguments ($1, $2, …​)

Return value

true if the rule matches, false to skip this rule. If the rule matches and the script assigned a string to CUSTOM_MESSAGE, that string becomes the event’s custom message

 
// Match only events from nodes with NetXMS agent
$node.isAgent

EPP Action Script

Executes custom logic when an EPP rule matches. Configured as a Script action in EPP rule actions.

Item Details

Predefined variables

$object, $node, $event (Event), $dci (DCI, set when the event is associated with a DCI)

Script arguments

Event parameters as positional arguments ($1, $2, …​)

Return value

Not used (script runs for side effects)

 
// Set custom attribute on node when specific event occurs
$node.setCustomAttribute("lastIncident", $event.message);

Action Script

Named server action of type NXSL Script. Executed from EPP rule actions (including their delayed or scheduled re-execution). Configured in Configuration → Actions.

Item Details

Predefined variables

$object, $node, $event (always set)

Script arguments

Action parameters as positional arguments, followed by the event parameters

Return value

Not used

Auto-Bind / Auto-Apply Script

Determines whether an object should be automatically bound to a container or have a template applied. Configured on containers (auto-bind) and templates (auto-apply).

A single filter script is evaluated per candidate object; whether matching objects are bound and non-matching objects are unbound is controlled by the apply/bind automatically and remove/unbind automatically flags in the owning object’s properties, not by a second script. Business services additionally have a separate DCI auto-bind filter that is evaluated per DCI (with $dci set).

Item Details

Predefined variables

$object (the candidate object being evaluated), $node (set when the candidate is a node), $isCluster, $container (the object owning the auto-bind script), plus an owner-specific alias for the owning object: $dashboard, $map, $service, or $template. For the DCI auto-bind filter of business services, $dci is also set

Return value

true to bind/apply, false to unbind/unapply (when automatic unbinding is enabled), null to leave the current binding unchanged

 
// Auto-apply template to all Linux nodes with agent
$node.platformName ~= "^linux" and $node.isAgent

Condition Script

Evaluated periodically for Condition objects. Determines whether the condition is active. Configured in Condition object properties.

Item Details

Predefined variables

$object (the Condition object; $node is never set), $values — array with values of the configured DCIs (1-based index)

Script arguments

Values of the configured DCIs as $1 …​ $N, in configuration order

Return value

true if condition is active, false if inactive

Generates activation event when transitioning from inactive to active, and deactivation event for the reverse.

Object Query Script

Used for ad-hoc or predefined object queries. Executed via the management console object query feature or via the API.

Item Details

Predefined variables

$object (each object in turn during filtering), $node, $isCluster, and $map (set per evaluated object, as in other contexts), $INPUT (hash map with values of query input fields), $context (caller-supplied context object)

Script arguments

None — input fields are passed in the $INPUT hash map, not as positional arguments

Return value

true to include the object in results, false to exclude

Object attributes can be referenced without qualification (e.g. type and state instead of $object.type and $object.state). Object class constants (NODE, CONTAINER, etc.) are available only in this context.

// Find all nodes with agent version older than 5.0
classof($object) == "Node" and $object.isAgent and $object.agentVersion < "5.0"

Scheduled Task Script

Runs at scheduled times. Created via Configuration → Scheduled Tasks. The script name and arguments are specified in the format scriptname(arg1, arg2, …​).

Item Details

Predefined variables

$object, $node (if task is associated with an object)

Script arguments

Arguments from the task definition as positional arguments

Return value

Not used

If the task is associated with an object, the task owner needs the Control access right on it, otherwise the script is not run.

The script runs under the security context of the task owner. Since 6.2.6

Discovery Filter Script

Determines whether a newly discovered node should be added to the system. This filter is implemented by the Hook::DiscoveryFilter hook script. See Hook::DiscoveryFilter for predefined variables, return value semantics, and examples.

DCI Summary Table Filter Script

Filters which nodes are included in a DCI summary table. Configured in summary table properties.

Item Details

Predefined variables

$object, $node (candidate node)

Return value

true to include the node, false to exclude

Network Map Link Styling Script

Customizes the appearance of links on network maps. Configured in network map link properties.

Item Details

Predefined variables

$object and $map (the map object), $link (NetworkMapLink)

Return value

Not used (script modifies $link properties directly)
The link color provider script additionally receives $endpoint1 and $endpoint2 (the objects on either end of the link). These variables are not available in the link styling script. 
// Color link red if either connected object has Major or Critical status
obj1 = $link.object1;
obj2 = $link.object2;
if ((obj1 != null && obj1.status >= 3) || (obj2 != null && obj2.status >= 3))
    $link.setColorConfig(MapLinkColorSource::CustomColor, "red");

Business Service Check Script

Evaluates the status of a business service check of type Script. Configured in business service check properties.

Item Details

Predefined variables

$service (the business service being checked), $object — the check’s related object, with $node set when it is a node (both unset when the check has no related object configured), $reason (assignable — set it to provide a failure reason)

Return value

OK or FAIL (predefined constants). A string return value marks the check as failed, with the string used as the failure reason. Any other return value is evaluated for truth: truthy means the check passed, falsy means it failed. A script runtime error leaves the check in the passed state

Asset Attribute Autofill Script

Automatically populates asset attributes during configuration polls. Configured in asset attribute definitions.

Item Details

Predefined variables

$object (the linked object), $node (set only when the linked object is a node — assets can be linked to several object classes), $asset (the Asset object), $name (attribute name), $value (current attribute value), $enumValues (array of allowed values for enum attributes)

Return value

Value to set for the asset attribute, or null to leave unchanged

 
// Auto-fill OS name from node's platform
return $node?.platformName;

SNMP Trap Transformation Script

Provides script access to SNMP trap data during trap-to-event mapping. The script VM is used to expand %[script] macros in trap mapping parameters — the macro is replaced with the value returned by the referenced script. Configured in SNMP trap mapping configuration.

Item Details

Predefined variables

$object, $node, $trap (trap OID as string), $varbinds (array of SNMPVarBind objects)

Return value

Value returned by a script referenced in a %[script] macro replaces that macro

Agent Configuration Filter Script

Determines which agent configuration policy to apply when an agent requests its configuration. Used in agent configuration matching.

Item Details

Predefined variables

None

Script arguments

$1 — agent IP address, $2 — platform name, $3 — agent major version number, $4 — agent minor version number, $5 — agent release number

Return value

true if the configuration matches the requesting agent, false otherwise

Network Map Object Filter Script

Decides which objects are placed on an automatically populated network map. Configured in network map properties.

Item Details

Predefined variables

$object, $node (the candidate object), $map (the network map)

Return value

true to place the object on the map, false to exclude it

Root Cause Analysis Script

Finds the parent (root cause) alarm for an alarm created by an EPP rule. Configured in the alarm settings of the EPP rule.

Item Details

Predefined variables

$object, $node (event source), $event

Return value

Alarm object to become the parent of the new alarm, or anything else for no parent

Macro Script

Script library script referenced by the %[name] macro in event messages, alarm messages, and action texts. The returned value replaces the macro. See Action Macro Reference.

Item Details

Predefined variables

$object, $node, $dci (when the event refers to a DCI), $event; when an alarm is in context also $alarm, $alarmMessage, and $alarmKey

Script arguments

Arguments given in the macro as %[name(arg1, arg2)]

Return value

Text that replaces the macro

Notification Channel Script

Notification channels using the built-in NXSL driver run the script given as the channel configuration for every notification sent through the channel.

Item Details

Predefined variables

$RECIPIENT, $SUBJECT, $MESSAGE (strings); $object, $node and $event when the notification was sent for an event

Return value

null or true for success, false for failure, a positive integer to retry delivery after that many seconds; a runtime error also marks the notification as failed

Business Service Prototype Instance Filter

Filters instances found by instance discovery of a business service prototype. Configured in business service prototype properties.

Item Details

Predefined variables

$object, $node (the instance discovery source object), $prototype (the business service prototype), $1 — instance key, $2 — instance value

Return value

true to accept the instance, false to skip it, or an array [key] or [key, name] to accept it with a different key and name

Housekeeper Script

Files with the .nxsl extension in the housekeeper subdirectory of the server data directory. The server runs each of them at the end of every housekeeper cycle, after the built-in cleanup. The scripts run without a user security context, so they are not subject to access right checks. Only in this context the SQLQuery() function is available.

Item Details

Predefined variables

None

Script arguments

None

Return value

Not used. Compilation and runtime errors are written to the server log.

Client Script Execution

Scripts executed from the management console via right-click → Execute Script or from the Script Editor. Runs on the server with the selected object as context.

Item Details

Predefined variables

$object, $node (the selected object). Object tools of type Server Script also receive $INPUT — hash map with values of the tool’s input fields

Return value

Displayed to the user in the script output window

Hook Scripts

Hook scripts have names prefixed with Hook:: in the Script Library. They are called automatically at specific server events. Each hook receives context-specific predefined variables and some hooks use return values to accept or reject operations.

See Hook Scripts for complete documentation of all NetXMS hook scripts, including predefined variables, return value semantics, and examples.

See Also