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 automation from external programs (for example, Python scripts), use the REST API.

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 Query

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

  • Rename and Delete scripts

To transfer scripts between servers, include them in a server configuration export (Configuration > Export configuration) and import it on the other server (Configuration > Import configuration).

Script Editor

The built-in script editor provides:

  • Syntax highlighting for NXSL

  • Compilation check (Compile) that reports syntax errors without saving

  • Optional line numbers and Go to line navigation

The editor does not run scripts; to test a script, load it in the Execute Script view (see From the Management Client).

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 Tools  Execute script to open the Execute Script view, where you can enter script source or load a script from the library, and run it 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.

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

The nxshell command line tool executes NXSL code on the server through the REST API, in the context of the current object selected in the shell:

nxshell -s netxms.example.com -n server01 -c 'nxsl println($node.name);'

See nxshell in the CLI tools reference for details.

Execution Security

Ad-hoc script execution initiated from a management client, the REST API, or nxshell runs on behalf of the invoking user and requires the Execute scripts access right on the target object (see Permission Reference). Ad-hoc execution without an object context (REST API, nxshell at the top level) requires the _Manage script library system access right.

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(), 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. Scripts started by a user are denied the same silent way when the user lacks the required access rights — see Scripts Started by a User.

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

  • EPP alarm category 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, limited by the access rights of the task owner (see Scripts Started by a User)

  • Object tools of type Server Script, limited by the access rights of the user who runs the tool (see Scripts Started by a User)

  • Scripts executed manually from the Execute Script view, limited by the access rights of the user who runs the script (see Scripts Started by a User)

  • Scripts executed with the exec command of 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.

Scripts Started by a User

Scripts started on behalf of a user run with that user’s security context, regardless of the Scripts.RestrictWriteAccess setting. This applies to:

  • object tools of type Server Script, run from the desktop or web client or through the REST API

  • scripts executed from the Execute Script view or through the REST API

  • dashboard scripted chart elements

  • scripts executed by scheduled tasks — the context is that of the task owner; tasks created by the server itself run as the built-in system user, which has all access rights

  • script library scripts that the AI assistant calls as tools, under the user of the chat session, and AI operator check scripts, under the operator’s owner

Library scripts called from such a script run in the same context.

A script running in a user context can access or modify an object only if the user has the access right that the operation requires on that object — for example, setCustomAttribute() requires the Modify access right. Functions that require system access rights, such as SendNotification() or GetConfigurationVariable(), are allowed only if the user has the corresponding system access right.

Object changes made by a script running in a user context (for example, renaming an object, setting a custom attribute, binding objects, or creating a DCI), as well as agent actions and SSH commands it executes on nodes, are written to the audit log on behalf of that user. Scripts running in other contexts do not write such audit records.

A call denied by the user’s security context behaves the same way as one denied by the read-only context: it returns false (or a null value, or the supplied default value in the case of GetConfigurationVariable()), no script error is raised, and the script continues. Object access denials are logged by the nxsl.security debug tag at level 4. Denials of system access rights are not logged at all.

Scripts executed by scheduled tasks and AI assistant tool scripts run in a user context since 6.2.6; in earlier versions they are not restricted.

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) {
    dci = child.findDCIByDescription("CPU Usage");
    if (dci != null) {
        cpu = dci.cachedValue;
        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::INVALID_DATA, 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 Execute Script view 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 DCI value attributes such as cachedValue and currentValue

  • 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