How to Create and Use Custom Events

Custom events extend NetXMS beyond built-in events, enabling automation with NXSL scripts, log parsers, SNMP trap processing, and other scenarios.

For the list of built-in events, see Event Types Reference.

Creating Custom Events

  1. Open Configuration > Event Templates in the management client

  2. Click New…​

  3. Configure the event properties:

Property Description

Event code

Unique numeric identifier, allocated automatically by the server from the custom event range (100000 and above) when the template is saved (shown as 0 until then). Read-only.

GUID

Automatically assigned globally unique identifier. Read-only.

Name

Symbolic name. A convention such as PREFIX_DESCRIPTIVE_NAME (e.g., CUSTOM_BACKUP_FAILED) is recommended, but not enforced

Severity

Default severity level

Message

Template with parameter placeholders (%1 through %99 for positional, %<name> for named)

Description

Documentation text; shown in the event template dialog and as a tooltip in event selectors, not in the event log

Tags

Comma-separated tags for filtering

Options

Write to log — write generated events to the event log; Hide from event monitor — do not show generated events in the event monitor

Event Message Templates

Event messages support macro substitution. See Action Macro Reference for the complete macro reference.

Common macros used in event message templates:

  • %1 through %99 — positional event parameters

  • %<name> — named event parameter

  • %n — event source object name

  • %a — event source IP address

  • %i — event source object ID (hexadecimal)

  • %I — event source object ID (decimal)

  • %c — event code

  • %s — severity code as number (0-4)

  • %S — severity code as text

  • %t — event timestamp

  • %{name} — custom attribute of the source object

Example message template:

Interface %1 on node %n changed state to %2 (speed: %3 Mbps)

Generating Events from Scripts

Use PostEvent() or PostEventEx() in NXSL scripts to generate custom events.

PostEvent() accepts positional string parameters (variadic) and accepts any object that can be an event source:

PostEvent($node, "CUSTOM_DISK_WARNING", null, mount, usedPercent);

The parameters are:

  1. Source object (any valid event source)

  2. Event name or code

  3. User tag (optional, can be null)

  4. Zero or more positional string parameters (accessible as %1, %2, etc. in event message template)

PostEventEx() requires a Node object as the event source and supports named parameters via a hash map or positional parameters via an array:

PostEventEx($node, "CUSTOM_DISK_WARNING",
    %{ "mount" : mount, "percent" : usedPercent });

PostEventEx($node, "CUSTOM_DISK_WARNING", [mount, usedPercent]);

PostEventEx() also accepts optional additional arguments to set event tags and the origin timestamp and origin of the event.

Parameter names differ between the two functions: PostEvent() names its positional parameters P1, P2, …​, while PostEventEx() with an array names them parameter1, parameter2, …​. Both are always accessible positionally as %1, %2, but named access (%<P1> vs %<parameter1>) depends on which function generated the event.

Event Forwarding

NetXMS does not support configuration synchronization between two NetXMS servers (distributed monitoring), but it is possible to forward events from one server to another. This allows synchronizing events between servers with some limitations.

Configuring Event Forwarding

Source server configuration:

  1. Open Configuration > Event Forwarders and create a new event forwarder using the isc driver; set the destination server hostname in the forwarder configuration

  2. Create a new action of type "Forward event" and select the forwarder created in the previous step

  3. Create a rule in the Event Processing Policy with a filter for the events you want to forward, and add the forwarding action

Destination server configuration:

  1. Enable EnableISCListener in server configuration and restart the server

  2. Enable Events.ReceiveForwardedEvents in server configuration (applied without restart)

  3. Open port 4702 (the standard ISC listener port) in the firewall; the listener accepts IPv4 connections only

Relevant server configuration variables:

Variable Default Description

EnableISCListener

false

Enable the Inter-Server Communication (ISC) listener for receiving forwarded events. Requires a server restart

Events.ReceiveForwardedEvents

false

Enable processing of forwarded events received via ISC
The built-in isc forwarding driver connects without encryption — event messages, parameters, and tags cross the network in the clear on port 4702. Use a secure network path (VPN, private link) between the servers.

Event Forwarding Limitations

  1. Event template with the same event name must exist on the recipient server — the forwarder always sends the name, and the receiver looks the template up by name; a matching numeric code alone is not sufficient

  2. The event’s source object must be a node — events from other object types (interfaces, containers, the server object) are forwarded without an IP address and silently dropped by the receiver

  3. Node object with the same IP address as the event’s source node must exist on the recipient server

  4. Does not work with zones

Events that do not meet these conditions are discarded. To check if and why incoming events are discarded, enable debug level 5 for the isc.ef debug tag on the receiving server (see Enabling Debug Logging) — but note that the most common discard reason, no matching node found, produces no log output at any level.

If you need to disable polling of sender server nodes on the recipient server, two options are available:

  • Disable all polling protocols — node status will show as "Unknown" unless there are active alarms, in which case the status reflects the most severe alarm

  • Unmanage nodes — node status will always show as "Unmanaged" regardless of active alarms

Event Log

Events whose template has the Write to log flag enabled are stored in the event log, viewed as the Events log in the Logs perspective of the management client.

Event Log Viewer

The log viewer is query-based: build a filter and press Execute query, then use Get more data to fetch additional records. There is no auto-refresh — for watching events in real time as they occur, use the Events view in the Monitors perspective instead.

The viewer supports:

  • Filtering by time range, source, severity, event name, and message content

  • Server-side ordering, configured in the Ordering section of the filter builder (clicking column headers does not sort)

  • Export to CSV

Event Log Retention

Event log retention is controlled by the server configuration variable Events.LogRetentionTime (in days, default: 90). The housekeeping process automatically removes expired event records.

Next Steps