Actions

Actions are predefined operations that execute when EPP rules match events. They are the mechanism through which NetXMS sends notifications, executes scripts, forwards data to external systems, and performs automated remediation.

Action Types

NetXMS supports six action types:

Type Description

Execute command on management server

Run a shell command on the NetXMS server

Execute command on remote node via agent

Execute a pre-configured agent action on a node via the NetXMS agent

Execute command on remote node via SSH

Execute a command on a node through its SSH proxy

Execute NXSL script

Run a script from the script library on the server

Send notification

Send a message through a notification channel (email, SMS, Telegram, etc.)

Forward event

Send the event to another server through a pre-configured event forwarder

Managing Actions

Creating an Action

  1. Open Configuration > Actions

  2. Click New…​

  3. Select the action type

  4. Configure the action parameters

  5. Save

Every action type has an Action is disabled checkbox — a disabled action is kept in the configuration but never executes.

Macro Substitution

All action configurations support macro substitution for dynamic content. The same macros can be used in event message templates, alarm messages, alarm keys, and notification templates.

See Action Macro Reference for the complete list of available macros.

Send Notification

Delivers a message through a configured notification channel.

Parameter Description

Channel name

The notification channel to use for delivery

Recipient

Recipient address; interpretation depends on the channel driver (supports macros)

Subject

Message subject (supports macros; ignored by channels without subject support)

Message text

Message body (supports macros)

Message contains markdown

Indicates that the message text uses Markdown formatting

See Notifications for notification channel setup.

Execute NXSL Script

Runs a script from the script library on the server. Inline script code is not supported — the action references a library script by name.

Parameter Description

Script name

Name of the script library script to execute. Arguments can be given in the form script(arg1, arg2), and an alternative entry point in the form script.entry_point or script/entry_point.

The event’s parameters are passed to the script as arguments, after any arguments given in the Script name field.

The script has access to:

Variable Description

$event

The event being processed

$object

Event source object (any type)

$node

Event source node (set when the source object is a node)

$map

Event source network map (set when the source object is a network map)

$isCluster

True when the event source object is a cluster

There is no $alarm variable — the script runs in the context of the event, not an alarm — and no $dci variable, even for threshold-related events.

Example — a library script that restarts a service on the source node when a service-down event occurs:

if ($node == null)
  return;
if (!AgentExecuteCommand($node, "restart.service", "httpd"))
  trace(1, "Failed to restart httpd on " .. $node.name);

Here restart.service is an agent action defined on the target node, for example Action = restart.service:systemctl restart $1 in the agent configuration file.

Execute Command on Management Server

Runs a shell command on the NetXMS server host.

Parameter Description

Command

Shell command to execute (supports macros)

Example command:

/opt/scripts/handle_alert.sh "%n" "%a" "%m"
Commands execute with the privileges of the NetXMS server process. Ensure scripts are secured and validate input parameters.

Execute Command on Remote Node via SSH

Executes a command on a node via SSH.

Parameter Description

Remote host

Target node: a hostname or IP address, @objectName to reference a node by object name, or #objectId to reference it by object ID. Must resolve to an existing node object. Supports macros.

Command

Command to execute on the remote host (supports macros)

The command is executed through the SSH proxy configured for the target node, using the node’s SSH credentials (port, login, password or key configured in node properties).

Execute Command on Remote Node via Agent

Executes a pre-configured agent action on a node via the NetXMS agent.

Parameter Description

Remote host

Target node: a hostname or IP address, @objectName to reference a node by object name, or #objectId to reference it by object ID (supports macros)

Agent’s action

Single command line: the first word is the agent action name, the remaining words are passed to the action as arguments (supports macros)

The agent action must be configured in the agent’s nxagentd.conf on the target node:

Action = restart_service:/usr/bin/systemctl restart $1

The value is split at the first colon: the part before it is the action name, everything after it is the command line to execute.

Agent actions let you predefine on the agent side exactly which commands the server can invoke.

Forward Event

Forwards the event to another system through a pre-configured event forwarder.

Parameter Description

Event forwarder

The event forwarder to use, selected from the list of configured forwarders

Recipient

For the snmptrap forwarder, overrides the destination host (when empty, the hostname from the forwarder configuration is used); ignored by the isc forwarder. Supports macros.

Event forwarders are configured in Configuration > Event Forwarders. Two forwarder drivers are built in:

  • isc — forwards events to another NetXMS server over the inter-server communication (ISC) protocol; the destination hostname is set in the forwarder configuration

  • snmptrap — forwards events as SNMP traps

Forwarding to another NetXMS server is used in distributed monitoring setups where a central server needs to receive events from remote servers.

Automatic Actions on New Node

NetXMS can automatically execute actions when new nodes are discovered or added to the system. This is configured through EPP rules that match the SYS_NODE_ADDED event.

Common Use Cases

Apply Templates to New Nodes

Automatically apply templates based on node properties:

// Check if node runs Linux
if ($node.platformName ~= "Linux")
{
  t = FindObject("Linux Base Template");
  if (t != null) $node.applyTemplate(t);
  t = FindObject("Linux Monitoring");
  if (t != null) $node.applyTemplate(t);
}

// Check if node is a Windows server
if ($node.platformName ~= "Windows")
{
  t = FindObject("Windows Base Template");
  if (t != null) $node.applyTemplate(t);
}

// Check for specific capabilities
if ($node.isSNMP)
{
  t = FindObject("SNMP Base Template");
  if (t != null) $node.applyTemplate(t);
}

Set Custom Attributes

Assign custom attributes based on discovered information:

// Set location based on IP range
ip = $node.ipAddr;
if (ip ~= "10.1.*")
  $node.setCustomAttribute("location", "datacenter-1");
else if (ip ~= "10.2.*")
  $node.setCustomAttribute("location", "datacenter-2");

// Set responsible team
$node.setCustomAttribute("team", "infrastructure");

Move to Correct Container

Organize new nodes into appropriate containers:

// Move to container based on platform
if ($node.platformName ~= "Linux")
{
  target = FindObject("Linux Servers");
  if (target != null)
    target.bind($node);
}

Set Expected State via Custom Attribute

Record the expected state for critical infrastructure in a custom attribute:

// Mark critical infrastructure as expected to be up
if ($node.ipAddr ~= "10.0.0.*")
{
  $node.setCustomAttribute("expected_state", "up");
}

Setting Up Automatic Actions

  1. Create an NXSL script in the script library with the desired automation logic

  2. Create an action of type Execute NXSL script referencing the script by name

  3. Create an EPP rule:

    • Event filter: SYS_NODE_ADDED

    • Source filter: Any (or restrict to specific containers)

    • Action: the action created in step 2

  4. Position the rule appropriately in the EPP

Test automatic actions with a few manually added nodes before relying on them for network discovery results.

Combining with Auto-Apply Templates

Automatic actions on new nodes complement the auto-apply template feature (see Auto-Apply Rules). Use EPP-based actions for complex logic that depends on event parameters or requires multiple operations, and auto-apply for straightforward template binding based on object properties.

Action Execution

When an EPP rule matches, command execution actions (local command, agent command, SSH command, and NXSL script) are dispatched asynchronously to a thread pool and may run concurrently — there is no guaranteed completion order between actions of the same rule. Notification and event forwarding actions are instead handed directly to the notification channel and event forwarder queues. The failure of one action does not affect the others and does not stop event processing; a failed execution of any action type except notification generates a SYS_ACTION_EXECUTION_FAILURE event.

Action Delays and Timers

Each action within an EPP rule can be configured with a delay. The delay accepts a plain number of seconds or a duration string — for example, 90, 5m, or 2h. The delay timer starts when the rule matches, and the action executes when the timer expires.

A delayed action can be given a timer key (supports macros). The only way to cancel a pending delayed action is through the Timer Cancellations list of another EPP rule that includes the same timer key — typically the rule matching the corresponding recovery event. Alarm resolution or termination does not by itself cancel pending delayed actions.

Each action can also be configured with a snooze time and a snooze/blocking timer key: after the action executes, a blocking timer is set, and the action will not execute again while that timer is active. This suppresses repeated execution when the same rule matches in quick succession.

Troubleshooting Actions

Action Not Executing

  • Verify the EPP rule is matching the expected events (check event log)

  • Verify the rule is enabled (not disabled)

  • Check rule ordering — a higher-priority rule with Stop Processing may be consuming the event

  • Verify the action is properly configured and enabled

Notification Not Delivered

  • Check notification channel configuration and connectivity

  • Test the notification channel with Send Test Message

  • Check server logs for delivery errors

Script Action Failing

  • Check server logs for NXSL error messages

  • Test the script in the NXSL console first

  • Verify variable availability ($node is null for non-node events)

Remote Command Failing

  • Verify SSH connectivity or agent communication

  • Check that the command/action is configured on the target node

  • Verify permissions for command execution

Next Steps