Object Tools

Object tools are predefined operations that can be executed on managed objects directly from the NetXMS management client. They provide quick access to common administrative tasks for nodes and other objects.

Configured object tools are available under Tools in the object browser’s context menu or the context menu of an alarm.

Object tools can be executed on containers in the object browser. Depending on the configuration of a specific object tool, it will be executed in the context of that container or for all objects under that container (see Run in Container Context).

Tools are managed in Configuration  Object Tools. There are some predefined object tools available after installation of the system.

If an object tool is not needed for some time, it can be disabled and then re-enabled when required. When an object tool is disabled, it is not shown under the Tools item of the context menu. If an image (16x16 px) is configured for an object tool, it will be displayed next to the object tool name in the menu.

A tool can have input fields, filters depending on execution object, macro substitution, and access control configuration.

Tool Types

Agent Command

Executes a command (action) on the target node’s NetXMS agent and optionally displays the output.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation (e.g., &Info→Agent→Restart).

Description

Description shown in the "Object Tools" configuration view. Should describe the tool’s purpose.

Agent’s command

Name of the agent action to execute. There are built-in agent actions, and additional actions can be defined in the agent configuration file. Parameters are supplied in the format: commandName param1 param2 param3…​

Command generates output

If selected, command execution opens a window displaying the output.

This tool requires confirmation before execution

If selected, a Yes/No confirmation dialog with the configured message is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Commands section of the Object Details view.

Command name

Name of the command shown in Object Details.

Command short name

Short name used when the command name is too long for display.

Suppress notification of successful execution

If selected, no success message is shown after tool execution completes.

Disabled

If selected, tool is not shown in the object browser’s context menu.

SNMP Table

Retrieves an SNMP table from the target node and displays results in tabular form. Columns are configured in the Columns tab.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Title

Title of the view where the table will be displayed.

Use as index: OID suffix of first column

Uses the OID suffix of the first column as the index to match rows across columns.

Use as index: Value of first column

Uses the value of the first column as the index to match rows across columns.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Disabled

If selected, tool is not shown in the context menu.

Agent List

Retrieves an agent list from the target node and displays results in tabular form. A regular expression is used to split each line of the received data into columns defined in the Columns tab.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Title

Title of the view where the table will be displayed.

Parameter

Name of the agent list metric to query.

Regular expression

Regular expression used to parse each line of the list into separate columns. Capture groups correspond to columns defined in the Columns tab.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Disabled

If selected, tool is not shown in the context menu.

Agent Table

Retrieves an agent table from the target node and displays results in tabular form.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Title

Title of the view where the table will be displayed.

Parameter

Name of the agent table metric to query.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Disabled

If selected, tool is not shown in the context menu.

URL

Opens a URL in the web browser. Supports macro substitution in the URL field.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

URL

URL to open in the browser. Supports macro substitution.

TCP tunnel

The TCP tunnel group contains four controls:

  • Setup TCP tunnel to remote port — if enabled, the management client opens a local port and establishes a tunnel through the server and a proxy agent. The proxy agent must have EnableTCPProxy=yes in its configuration. When enabled, additional macros ${local-address} and ${local-port} become available in the URL field.

  • Remote port — number of the remote TCP port the tunnel connects to.

  • Connect to remote host — if enabled, the tunnel is established to a different host instead of the target node itself.

  • Remote host — address of the host the tunnel connects to when Connect to remote host is enabled.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Disabled

If selected, tool is not shown in the context menu.

Run in container context

See Run in Container Context.

Local Command

Executes a command on the machine where the Desktop Management Client is running and optionally displays the output.

This tool type is not available from the Web Management Client, as it is not possible to execute commands on the web client machine.
Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Command

Command to execute on the local machine. Supports macro substitution.

TCP tunnel

The TCP tunnel group contains four controls:

  • Setup TCP tunnel to remote port — if enabled, the management client opens a local port and establishes a tunnel through the server and a proxy agent. The proxy agent must have EnableTCPProxy=yes in its configuration. When enabled, additional macros ${local-address} and ${local-port} become available in the command field.

  • Remote port — number of the remote TCP port the tunnel connects to.

  • Connect to remote host — if enabled, the tunnel is established to a different host instead of the target node itself.

  • Remote host — address of the host the tunnel connects to when Connect to remote host is enabled.

Command generates output

If selected, command execution opens a window displaying the output.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Suppress notification of successful execution

If selected, no success message is shown after tool execution completes.

Disabled

If selected, tool is not shown in the context menu.

Run in container context

See Run in Container Context.

Server Command

Executes a command on the NetXMS server.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Command

Command to execute on the server. Supports macro substitution.

Command generates output

If selected, command execution opens a window displaying the output.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Suppress notification of successful execution

If selected, no success message is shown after tool execution completes.

Disabled

If selected, tool is not shown in the context menu.

Run in container context

See Run in Container Context.

Download File

Retrieves the contents of a file from the target node’s agent. This tool can be used to monitor agent logs in real-time.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Remote File Name

Path to the file on the remote agent. On Windows, use double backslashes as path separators (e.g., C:\\log\\log.log). Supports strftime(3C) format macros for date/time substitution.

Limit initial download size (in bytes, 0 for unlimited)

Limits the initial download to the last N bytes of the file. If set to 0, the complete file is retrieved.

Follow file changes

If selected, the file view automatically updates as new data is appended to the file (similar to tail -f).

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Disabled

If selected, tool is not shown in the context menu.

Server Script

Executes an NXSL script from the Script Library. This tool type provides the full range of capabilities available through NXSL scripting.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Script

Name of the script from the Script Library to execute.

Command generates output

If selected, a new window opens with the script execution result.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Suppress notification of successful execution

If selected, no success message is shown after tool execution completes.

Disabled

If selected, tool is not shown in the context menu.

Run in container context

See Run in Container Context.

SSH Command

Executes a command on the target node via SSH. The command is executed through the NetXMS server’s SSH subsystem.

Field Description

Name

Name shown in the node menu. Submenus can be created using -> notation.

Description

Description shown in the "Object Tools" configuration view.

Command

Command to execute on the remote node via SSH. Supports macro substitution.

Command generates output

If selected, command execution opens a window displaying the output.

This tool requires confirmation before execution

If selected, a confirmation dialog is shown before execution.

Confirmation message

Message text displayed in the confirmation dialog.

Show this tool in node commands

If selected, this tool appears in the Object Details view.

Command name / Command short name

Names for the command in Object Details.

Suppress notification of successful execution

If selected, no success message is shown after tool execution completes.

Disabled

If selected, tool is not shown in the context menu.

Properties

Filter

Filters control on which objects an object tool is displayed in the context menu.

The Applicable object types group at the top of the page selects the object classes the tool can be used on: Node, Interface, Sensor, and Access point. Only Server Script, URL, and SSH Command tools can target interfaces, sensors, or access points; for all other tool types only Node is available.

Below the object type selection there are 10 filter options that can be combined:

# Filter Description

1

NetXMS agent should be available

Tool is shown only if the NetXMS agent is available on the node.

2

Node should support SNMP

Tool is shown only if the node supports SNMP.

3

Node should support SSH

Tool is shown only if the node has the SSH capability.

4

Node should support EtherNet/IP

Tool is shown only if the node has the EtherNet/IP capability.

5

Node should support Modbus TCP

Tool is shown only if the node has the Modbus TCP capability.

6

Node SNMP OID should match with the following template

Tool is shown only if the node’s SNMP OID matches the provided pattern string.

7

Node platform name should match the following template

Tool is shown only if the node’s platform name matches the provided comma-separated regular expression list.

8

Workstation OS name should match the following template

Only shown for Local Command tools. Tool is shown only if the operating system of the workstation running the management client matches the provided comma-separated regular expression list.

9

Parent template name should match the following template

Tool is shown only if the node has a template applied whose name matches the provided comma-separated regular expression list.

10

The following custom attribute(s) should exist

Tool is shown only if the object has custom attributes whose names match the provided comma-separated regular expression list. Only attribute names are checked — attribute values are never inspected.

Multiple filters can be combined. All selected filter conditions must be satisfied for the tool to be shown.

Access Control

The Access Control tab defines which users or groups can see and execute an object tool. Add users or groups (for example, the Everyone group) to the access list to grant them access.

If the access list is empty, only the built-in system account (user ID 0) can execute the tool. No other user bypasses the tool’s access list — membership in the Admins group grants no special treatment. Users holding the "Configure object tools" system access right see all tools in the configuration view, but still need to be on a tool’s access list to execute it.

Executing Agent Command, Server Command, and Server Script tools additionally requires the "Control" access right on the target object. Table tools (SNMP Table, Agent List, Agent Table) do not require the "Control" right — read access to the object is sufficient.

Columns

The Columns tab is used for Agent List, SNMP Table, and Agent Table tool types.

Each column has a name and a data format. Depending on the tool type, the column editor shows one additional property:

  • For SNMP Table tools — SNMP Object Identifier (OID): the OID of the SNMP object to retrieve for this column.

  • For Agent List tools — Substring index (starting from 1): the number of the regular expression capture group whose value is placed in this column.

Column data formats:

Format Description

String

Plain text string

Integer

Integer number

Float

Floating point number

IP Address

IP address (v4 or v6)

MAC Address

MAC address (displayed in standard notation)

Interface Index

Network interface index (resolved to interface name when possible)

Translations

The Translations property page allows defining localized versions of the tool’s Name, Description, Confirmation message, Command name, and Command short name for a fixed set of languages: de, en, es, fr, pt_BR, and ru. Clients using a matching interface language display the translated values instead of the base ones.

Input Fields

Object tools can prompt the user for input values before execution. Input fields are defined in the Input Fields tab and referenced in tool commands using the %(in:name) macro format.

Each input field has the following properties:

  • Name — internal field name used in the %(in:name) macro

  • Display name — label shown to the user in the input dialog

  • Type — one of:

    • Text — free-form text input

    • Password — masked text input (value is not displayed)

    • Number — numeric input

    • Date & Time — date and time input

  • Default value — value pre-filled in the input dialog; macro substitution is applied to it before the dialog is shown. Not available for Date & Time fields.

  • Validate password after entry — available for Password fields only. Before the tool runs, the entered value is checked against the current user’s NetXMS password; execution is aborted if it does not match.

For example, to create a tool that pings a specified number of times:

Ping.Ping(%a, %(in:count))

Where count is an input field of type Number that prompts the user for the ping count.

Run in Container Context

When the "Run in container context" option is enabled, the tool executes only in the context of the selected container, rather than being executed for each child node under that container.

This is useful for tools like URLs where you want to open a page related to the container itself, not for each node within it.

Tool types that support this option: URL, Local Command, Server Command, Server Script.

Macro Substitution

Agent Command, Download File, Local Command, Server Command, SSH Command, URL, and Server Script tool types support macro substitution. A percent sign followed by a macro name is expanded to the macro’s value. If the character after the percent sign is not a valid macro name, both the percent sign and that character are silently dropped and produce no output. Use %% to insert a literal percent character.

Object Macros

Macro Description

%a

IP address of the target object.

%C

Comments of the target object.

%g

Globally unique identifier (GUID) of the target object.

%i

Unique ID of the target object in hexadecimal form. Always prefixed with 0x and contains exactly 8 digits (e.g., 0x000029AC).

%I

Unique ID of the target object in decimal form.

%L

Alias of the target object.

%n

Name of the target object.

%t

Timestamp as formatted text. When the tool is invoked from an alarm, the timestamp of the associated event; otherwise the current server time.

%T

Same as %t, but as the number of seconds since epoch (UNIX timestamp).

%u

IP address of the target object formatted for use in URLs. Expands to [addr] for IPv6 addresses and addr for IPv4 addresses.

%U

User name of the user who launched the object tool.

%v

NetXMS server version string.

%z

Zone UIN of the target object.

%Z

Zone name of the target object (expanded only when zoning is enabled).

Script and Custom Attribute Macros

Macro Description

%[name]

Value returned by a script from the Script Library. You can specify a script entry point by separating it with /, e.g., %[scriptName/calculate]. Script parameters can be specified in parentheses: %[scriptName(123,"text param")].

%{name}

Value of a custom attribute on the target object.

%{name:default_value}

Value of a custom attribute. If the attribute does not exist on the target object, default_value is used. If the attribute exists but has an empty value, the empty value is used.

Input and Special Macros

Macro Description

%(in:name)

Value of an input field.

%(nl)

CR/LF pair (carriage return followed by line feed).

%(cr)

Carriage return character.

%(lf)

Line feed character.

%(tab)

Tab character.

%%

Literal % character.

TCP Tunnel Macros

These macros are available when the TCP tunnel option is enabled (for URL and Local Command types):

Macro Description

${local-address}

Local IP address of the TCP tunnel endpoint.

${local-port}

Local port number of the TCP tunnel endpoint.

Alarm Context Macros

When an object tool is invoked from an alarm’s context menu, the following additional macros are available:

Macro Description

%A

Alarm’s text message.

%c

Event code (numeric).

%d

Description of the DCI associated with the event (if any).

%D

Comments of the DCI associated with the event (if any).

%E

Event tags, comma-separated.

%K

Alarm’s key.

%m

Event’s message text.

%M

Custom message (usually set by a filter script in the event processing policy).

%N

Event name.

%s

Event severity as a number: 0 = Normal, 1 = Warning, 2 = Minor, 3 = Major, 4 = Critical.

%S

Event severity as text (e.g., "Warning", "Critical").

%y

Alarm state as a number: 0 = Outstanding, 1 = Acknowledged, 2 = Resolved, 3 = Terminated.

%Y

Alarm ID.

%1 — %99

Positional event parameters.

%<name>

Value of the named event parameter.

%<name:default>

Value of the named event parameter; default is substituted if the parameter does not exist.

%<{modifiers}name>

Value of the named event parameter formatted according to a comma-separated list of format modifiers: m (or multipliers) applies multipliers, u (or units) appends units. Formatting is based on the DCI associated with the event, e.g., %<\{m,u}value>.

Predefined Object Tools

NetXMS is delivered with a number of predefined object tools:

Name Type Description Filter

&Connect  &SSH

Local Command

Run SSH connection to node in Linux terminal

Workstation OS matches .*nix.*,.*nux.*,.*aix.*

&Connect  &SSH

Local Command

Run SSH connection to node in Windows console

Workstation OS matches Win.*

&Connect  &SSH

Local Command

Run SSH connection to node in Mac terminal

Workstation OS matches .*mac.*

&Connect  Open &web browser

URL

Open embedded web browser to node

&Connect  Open &web browser (HTTPS)

URL

Open embedded web browser to node using HTTPS

&Info  &Agent  &Loaded subagents

Agent Table

Show information about loaded subagents

Agent is available

&Info  &Agent  Configured &ICMP targets

Agent Table

Show information about ICMP targets configured on this agent

Agent is available

&Info  &Agent  Running &configuration

Agent List

Show agent running configuration

Agent is available

&Info  &Agent  Supported &actions

Agent List

Show information about actions supported by agent

Agent is available

&Info  &Agent  Supported &lists

Agent List

Show list of lists supported by agent

Agent is available

&Info  &Agent  Supported &parameters

Agent List

Show list of parameters supported by agent

Agent is available

&Info  &Agent  Supported &tables

Agent List

Show list of tables supported by agent

Agent is available

QtechOLTsONT

SNMP Table

Show ONTs on PON ports

SNMP OID matches .1.3.6.1.4.1.27514.1.10.4.1

QtechOLTsSFP

SNMP Table

Show GPON SFP modules in PON ports

SNMP OID matches .1.3.6.1.4.1.27514.1.10.4.1

&Restart system

Agent Command

Restart target node via NetXMS agent

Agent is available

&Shutdown system

Agent Command

Shutdown target node via NetXMS agent

Agent is available

&Wakeup node

Server Script

Wakeup node using Wake-On-LAN magic packet

Restart &agent

Agent Command

Restart NetXMS agent on target node

Agent is available

The three &Connect  &SSH tools are Local Command variants for different client workstation operating systems — only the variant matching the workstation OS is shown. Each prompts for the user name via a username input field and opens an SSH session to the node in a local terminal.

The &Wakeup node tool executes the Tools::WakeUpNode library script, which sends a Wake-On-LAN magic packet to the node.

Predefined object tools are imported from configuration templates shipped with the server when the server starts. The import is controlled by the Server.ImportConfigurationOnStartup server configuration variable.

Dashboard Integration

Object tool buttons can be embedded in dashboards to provide quick-access controls. See Dashboard Elements for configuration details.