Scripting

NXSL

Overview

In many parts of the system, fine tuning can be done by using NetXMS built-in scripting language called NXSL (stands for NetXMS Scripting Language). NXSL was designed specifically to be used as embedded scripting language within NetXMS, and because of this has some specific features and limitations. Most notable is very limited access to data outside script boundaries – for example, from NXSL script you cannot access files on server, nor call external programs, nor even access data of the node object other than script is running for without explicit permission. NXSL is interpreted language – scripts first compiled into internal representation (similar to byte code in Java), which is then executed inside NXSL Virtual Machine. Language syntax and available functions can be found in NXSL documentation.

List of places where NXSL scripting is used

Script library

DCI transformation scripts

DCI instance filter script

DCI scripted threshold

DCI summary table object filter script

Container, template, cluster auto-bind script

SNMP trap transformation script

EPP filter script

EPP inline script actions

Map object filter script

Map link styling script

Dashboard scripted chart

Dashboard status indicator

Context dashboard auto-bind script

Business service scripted check

Business service DCI auto apply script

Business service object auto apply script

Business service prototype instance filter script

Asset attribute auto fill script

Object query

Agent configuration filter script

Condition status calculation script

Custom housekeeping scripts (see Custom housekeeping scripts)

Scripting library

Script Library is used to store scripts that can be afterwards executed as macros, part of other script or from debug server console. Scripts can be added, deleted and modified in in this view.

Usage

Scripts from Script Library can be accessed as:

a macros %[scriptName]
used in action of type “Execute NXSL script”
executed from DCIs with “Script” source
functions can be called from other scripts either by using “import scriptName” and calling functions by name, or without import, by calling “scriptName::functionName“
executed from server debug console “execute scriptName“
scripts having name starting with “Hook::” are executed automatically, e.g. “Hook::ConfigurationPoll” is being run on each node’s configuration poll

Note

All parameters provided to script are accessible via $ARGS array. The other option to use parameters is to specify main() function in the script and define parameters in it’s definition.

Execute Server Script

This view allows to execute arbitrary script. Script can be manually created just before execution, and afterwards saved, can be taken from the script library, can be used modified script from the script library and afterwards saved or saved as. If this view is opened on a node, then in the script is available $node variable with node object.

Note

All parameters provided to script are accessible via $ARGS array.

NXShell

NxShell is based on Jython and provide access to NetXMS Java API using interactive shell. NxShell is build as single jar file, which includes all required libraries.

Download: http://www.netxms.org/download/nxshell-VERSION.jar (example: http://www.netxms.org/download/nxshell-1.2.13.jar)

Usage

There are two options of this jar usage:

it can be started as interactive shell;

java -jar nxshell-1.2.15.jar

it can be started with the script name as a first parameter. Then it will just execute this script and exit. Example:

java -jar nxshell-1.2.15.jar test.py

When NxShell is started, it tries to get server IP, login and password from Java properties. In interactive mode, user will be asked for details, otherwise default values will be used.

Start as interactive shell, with IP and Login provided (password will be asked):

java -Dnetxms.server=127.0.0.1 -Dnetxms.login=admin -jar nxshell-1.2.15.jar

Properties

These properties should be set with JVM’s “-D” option. Please make sure that all “-D” options are before “-jar”.

Parameter	Default Value
netxms.server	127.0.0.1
netxms.login	admin
netxms.password	netxms
netxms.encryptSession	true

Scripting

For details on API please refer to javadoc at http://www.netxms.org/documentation/javadoc/latest/.

NxShell provide user with already connected and synchronized session to simplify scripting. Most required packages are imported as well to minimize typing.

Global Variables

Variable	Type	Notes
session	org.netxms.client.NXCSession
s	org.netxms.client.NXCSession	Alias for “session”

Helper Functions

Example

More examples can be found on a NetXMS wiki.

parentId = objects.GenericObject.SERVICEROOT # Infrastructure Services root
cd = NXCObjectCreationData(objects.GenericObject.OBJECT_CONTAINER, "Sample Container", parentId);
containerId = session.createObject(cd) # createObject return ID of newly created object
print '"Sample Container" created, id=%d' % (containerId, )

flags = NXCObjectCreationData.CF_DISABLE_ICMP | \
        NXCObjectCreationData.CF_DISABLE_NXCP | \
        NXCObjectCreationData.CF_DISABLE_SNMP
for i in xrange(0, 5):
    name = "Node %d" % (i + 1, )
    cd = NXCObjectCreationData(objects.GenericObject.OBJECT_NODE, name, containerId);
    cd.setCreationFlags(flags);
    cd.setPrimaryName("0.0.0.0") # Create node without IP address
    nodeId = session.createObject(cd)
    print '"%s" created, id=%d' % (name, nodeId)