Scripting Overview

NetXMS includes a built-in scripting language called NXSL (NetXMS Scripting Language). NXSL provides server-side automation for data processing, event handling, and object manipulation without external tools or dependencies.

For the complete NXSL language reference (syntax, data types, operators, built-in functions, and class reference), see NXSL Reference.

For Python-based automation via NXShell, see NXShell.

Where Scripting Is Used

NXSL scripts are used throughout NetXMS for automation and customization:

Context Purpose Details

Data Collection

Computed metrics, data transformation

Data Collection Concepts

Thresholds

Custom threshold conditions using script logic

Thresholds

Event Processing

Script-based event filters in EPP rules

Event Processing Policy

Actions

Execute NXSL scripts in response to events

Actions

Server Hooks

Automatic processing during configuration polls, node creation, and other server events

Server Hooks

Scheduled Tasks

Run scripts on a schedule for periodic automation

Scheduling

Auto-Apply / Auto-Bind

Template and container membership rules based on object properties

Auto-Apply Rules

Object Queries

Filter and find objects using script expressions

Object Model

Dashboard Elements

Dynamic labels, colors, and data in dashboards

Dashboards

Script Library

The script library is a centralized repository of named NXSL scripts stored in the NetXMS database. Scripts in the library can be referenced by name from any context that supports NXSL, avoiding code duplication and simplifying maintenance.

Managing the Script Library

Access the script library through the management client:

  1. Navigate to Configuration > Script Library

  2. The library displays all scripts with their names and descriptions

From this view you can:

  • Create a new script — click the create button, provide a name and the script body

  • Edit an existing script — double-click to open the built-in script editor

  • Delete scripts that are no longer needed

  • Import/Export scripts for backup or sharing between servers

Script Editor

The built-in script editor provides:

  • Syntax highlighting for NXSL

  • Error checking and compilation validation

  • Line numbers for easy reference

  • The ability to test scripts before saving

Naming Conventions

Use descriptive, hierarchical names for scripts in the library:

Hook::ConfigurationPoll
Hook::AcceptNewNode
Filter::EventSeverity
Transform::TemperatureConvert
Action::RestartService
DCI::ComputeAvailability

This naming convention makes it clear where each script is used and keeps the library organized.

Referencing Library Scripts

Library scripts can be called from other scripts using the import statement or referenced directly by name in configuration dialogs (EPP rules, actions, hooks, etc.).

Execute Server Script

You can execute scripts from the script library on demand through several methods:

From the Management Client

Right-click on any object and select Execute Script to run a library script in the context of that object. The script receives the selected object as $object and $node (if applicable). $isCluster is always set and indicates whether the object is a cluster; $map is set when the object is a network map, and $dci is set when a DCI is in context.

From the Debug Console

Use the exec command to execute a library script:

exec ScriptName

See Debug Console for more debug console commands.

From Scheduled Tasks

Create a scheduled task with type "Execute Script" and specify the script library name. See Scheduling for task scheduling details.

From NXShell

Execute a script on a node via the Java API. executeScript() takes the object ID, script source code, an optional parameter list, and an output listener; it does not return a value — script output is delivered to the listener:

from org.netxms.client import TextOutputListener

class Output(TextOutputListener):
    def messageReceived(self, text):
        print text
    def setStreamId(self, streamId):
        pass
    def onSuccess(self):
        pass
    def onFailure(self, exception):
        pass

node = session.findObjectByName("server01")
session.executeScript(node.getObjectId(), 'println($node.name);', None, Output())

Execution Security

Ad-hoc script execution initiated from a management client runs on behalf of the invoking user and requires Modify access on the target object, unless the Objects.ScriptExecution.RequireWriteAccess server configuration variable is disabled.

Write Access Restrictions

Scripts that the server evaluates on its own — transformation, filter, predicate, and analysis scripts — run in a read-only security context and cannot change anything in the system. This is controlled by the Scripts.RestrictWriteAccess server configuration variable, which is enabled by default both on new installations and after an upgrade from a version earlier than 6.2.

Restricted scripts may read object properties, alarms, agent data, and SNMP data. Every other operation is denied, including:

  • object modification methods, such as setCustomAttribute(), deleteCustomAttribute(), setComments(), setAlias(), rename(), manage(), unmanage(), enterMaintenance(), leaveMaintenance(), bind(), unbind(), createNode(), createContainer(), setGeoLocation(), setExpectedState(), and the enable*() family

  • active operations on nodes, such as executeAgentCommand(), executeSSHCommand(), openSSHSession(), wakeUp(), and forced polls

  • event generation functions PostEvent() and PostEventEx()

  • functions requiring system access rights, such as SendNotification(), SendMail(), SQLQuery(), GetConfigurationVariable(), LoadEvent(), CreateUserAgentNotification(), and CancelScheduledTasksByKey()

A denied operation does not raise a script error. The call returns false (or a null value, or the supplied default value in the case of GetConfigurationVariable()), the script continues, and nothing is written to the server log at default logging levels. The only trace is a message produced by the nxsl.security debug tag at level 7. If a script that worked before an upgrade to 6.2 silently stopped having any effect, check this first.

The following scripts are restricted:

  • DCI transformation script (both single-value and table DCIs)

  • DCI scripted threshold

  • script: macro in DCI text expansion and %[script] macro in object text expansion

  • Container, collector, template, and cluster auto-bind and auto-apply filter scripts

  • Condition status calculation script

  • Business service scripted check

  • Business service prototype instance discovery script and instance filter script

  • EPP filter script

  • Root cause analysis script (both when an alarm is created by EPP and during background re-evaluation)

  • Asset attribute auto fill script

  • Map object filter script, map link styling script, and map link color provider script

  • SNMP trap transformation script

The following scripts are not restricted and can still modify objects while Scripts.RestrictWriteAccess is enabled:

  • EPP action of type Execute NXSL script

  • Hook scripts (script library entries named Hook::*)

  • Scripts executed by scheduled tasks

  • Object tools of type Server Script

  • Scripts executed manually from the Execute Server Script view or from the server debug console

  • DCI with Script origin (both single-value and table DCIs)

  • DCI instance discovery script of the Script method (the script that produces the instance list)

  • DCI instance discovery filter script

Data collection scripts are exempt because they are stored in the script library, and a user who can edit the script library can already run unrestricted code through hook scripts. The exemption for DCIs with Script origin and for instance discovery scripts applies since 7.0; in 6.2 these scripts are restricted.

If a restricted script has to modify objects, move the modifying part into one of the unrestricted script types — for example, have the DCI generate an event and perform the modification from an EPP Execute NXSL script action.

The restriction can also be disabled entirely by setting Scripts.RestrictWriteAccess to 0 in Configuration > Server Configuration. The change takes effect immediately, without a server restart. Changing the value directly in the config database table bypasses the change notification and does require a server restart.

If the Scripts.RestrictWriteAccess row is missing from the configuration altogether, the server treats the restriction as enabled.

Script DCIs

Script DCIs execute NXSL code on the server to compute metric values. This is useful for derived metrics, aggregations, or metrics that combine data from multiple sources.

To create a script DCI:

  1. Create the script in the script library

  2. Open the DCI editor for a node

  3. Set the data origin to "Script"

  4. In the metric field, enter the name of the library script — optionally with arguments as ScriptName(arg1, arg2), or with a specific entry point as ScriptName.EntryPoint or ScriptName/EntryPoint

Inline script code is not accepted in the metric field; the script must exist in the script library.

Example: library script that computes average CPU across nodes in a container
container = FindObject("Servers");
if (container == null)
    return 0;
total = 0;
count = 0;
for (child : container.children) {
    dciId = FindDCIByDescription(child, "CPU Usage");
    if (dciId != 0) {
        cpu = GetDCIValue(child, dciId);
        if (cpu != null) {
            total += cpu;
            count++;
        }
    }
}
return (count > 0) ? total / count : 0;

Transformation Scripts

Transformation scripts modify DCI values after collection but before storage. They are useful for unit conversion, data normalization, or filtering invalid values.

The collected value is available as $1 in the transformation script. Return the transformed value to store it. 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.

Example: convert Fahrenheit to Celsius
return ($1 - 32) * 5 / 9;
Example: discard outlier values
if ($1 > 10000 || $1 < 0) return DataCollection::ERROR;
return $1;

Offline Script Development

The nxscript command line tool is a standalone NXSL interpreter that can compile and run scripts outside of the server context — useful for syntax checking and quick experiments during script development. It can also convert scripts to NXSL version 5 syntax (-5 option). See nxscript in the CLI tools reference for details.

Best Practices

  • Keep scripts focused on a single task

  • Use the script library for reusable logic instead of duplicating code

  • Test scripts in the editor before deploying to production

  • Use descriptive variable names and consistent naming conventions

  • Add comments only when the logic is not self-evident

  • Handle null values from GetDCIValue() and similar functions

  • Avoid expensive operations (large loops, network calls) in transformation scripts that run on every poll

  • Use trace() for debug output visible in the server log

Related Pages