EPP Reference

This page provides a complete reference for Event Processing Policy (EPP) filter criteria, actions, and macros. For an overview of how the EPP works, see Understanding Event Processing Policy. For step-by-step instructions on creating rules, see How to Create EPP Rules.

A rule’s configuration is organized into property pages: Condition (with sub-pages Events, Source Objects, Time Filter, Severity Filter, and Filtering Script), Action (with sub-pages Alarm, Incident, Downtime Control, Persistent Storage, Custom Attributes, Server Actions, Script, Timer Cancellations, and AI Agent Instructions), and Comments.

Filter Criteria

Events

Match rules to events by:

  • Individual event selection — choose specific events from the event list

  • Inverse matching — match all events except selected ones

There is no filter for event tags — to match events by tag, call $event→hasTag() in the filtering script.

Source Objects

Restrict rules to events from specific sources:

  • Individual objects — select specific nodes, interfaces, etc.

  • Parent objects — an event matches if the selected object is anywhere in the source object’s parent hierarchy, so selecting a container, subnet, cluster, template, business service, zone, or any other parent matches events from all objects beneath it

  • Any source — match events from all objects (default)

Source objects and exclusions lists work together to control which objects the rule applies to. If the source objects list is empty, the rule matches any object.

The Exclusions list takes priority over the source objects list. For example, you can specify a container in source objects and one specific node from that container in the exclusions list — the rule would match all nodes from the container except that one excluded node.

The Inverse rule checkbox inverts the matching logic: objects that would normally be matched by the combination of source objects and exclusions will not be matched, and vice versa.

Severity Filter

Check specific severity levels. Multiple levels can be selected (e.g., match Major and Critical only).

Time Filter

Restrict rule evaluation to specific time frames. Time frames support the following filters:

  • Time range — start and end time of day

  • Days of week — select which days the rule is active (Monday through Sunday)

  • Days of month — specified as comma-separated lists of days or ranges (e.g., 1,3,5,20-25); the letter L denotes the last day of the month

  • Months — select which months the rule is active (January through December)

Multiple time frames can be added to a single rule. The Inverse rule (match time that is NOT within time frames listed below) checkbox on the Time Filter page inverts the matching for the whole rule: the rule matches when the current time is outside all listed time frames.

This is useful for different notification routing during business hours vs. off-hours.

Accept Correlated Events

The Accept correlated events checkbox on the rule’s Condition page controls whether events that are correlated to another event should be processed by this rule. For example, when a node is in maintenance mode, all events from that node are correlated to the maintenance event. By default, correlated events are skipped. Enable this checkbox if the rule should process correlated events as well.

Filtering Script

For conditions that cannot be expressed with the standard filters, attach an NXSL filtering script on the Filtering Script page. The script receives the event object and must return true for the rule to match.

Available variables in the filtering script:

Variable Description

$event

The event being processed

$object

Source object (any type)

$node

Source node object (if the source is a node)

$dci

DCI related to the event (if applicable)

CUSTOM_MESSAGE

Writable — set to override alarm/action message

EVENT_CODE

Event code (read-only)

SEVERITY

Event severity as a number (read-only)

SEVERITY_TEXT

Event severity as text (read-only)

OBJECT_ID

Source object ID (read-only)

EVENT_TEXT

Event message text (read-only)

Example filter script — match only events from nodes in a specific zone:

return ($node != null && $node.zoneUIN == 5);

Example — match only during maintenance windows:

if ($node == null)
  return false;
return $node.isInMaintenanceMode;

Actions

When a rule matches, the following property pages control what happens:

Action

The Action page contains general processing options:

  • Stop event processing — when checked and the rule matches, no further rules are evaluated for this event. Use this to prevent catch-all rules from matching events that have already been handled.

  • Event logging — a radio group controlling whether the event is written to the event log: Do not change, Force logging, or Disable logging.

Alarm

Create a new alarm, update an existing one, or resolve/terminate alarms by key. See Alarms for details on alarm configuration.

Alarm creation parameters configured in the rule:

Parameter Description

Message

Text displayed in the alarm list (supports macro substitution)

Alarm key

Unique key for alarm correlation (supports macro substitution)

Alarm severity

Inherit from event or override

Alarm timeout

Time in seconds, counted from the alarm’s last change, after which the timeout event is generated if the alarm is still outstanding; the timeout event is generated at most once (0 = disabled)

Timeout event

Event generated when the alarm timeout expires

Root cause analysis script

Optional NXSL script for root cause analysis

Alarm category

One or more categories assigned to the created alarm (used for category-based access control)

Create helpdesk ticket on alarm creation

Checkbox — automatically create a ticket in the linked helpdesk system

Add AI assistant’s comment on alarm creation

Checkbox — attach an AI assistant comment to the created alarm

When resolving or terminating alarms, the alarm key is matched exactly by default. This exact key match is how recovery events (like SYS_NODE_UP) automatically close alarms created by failure events (like SYS_NODE_DOWN). Check Use regular expression for alarm termination/resolving to treat the key as a regular expression and match multiple related alarms with a single rule.

Server Actions

The Server Actions page contains a list of predefined actions to execute when the rule matches. The following action types are available (see Actions):

  • Execute command on management server

  • Execute command on remote node via agent

  • Execute command on remote node via SSH

  • Execute NXSL script

  • Send notification

  • Forward event

Email and messenger notifications are sent with the Send notification action type through a configured notification channel — there is no separate email action type.

Action execution can be delayed, and a delayed action can be cancelled before it runs. Execution can also be snoozed for a period of time. Delayed execution and snoozing are controlled by timers referenced by timer keys, which can be cancelled from the Timer Cancellations page or checked from NXSL scripts.

Each action in the list has the following timer fields:

  • Delay (e.g. 90, 5m, 2h) — how long to wait before executing the action, as a duration string (a plain number of seconds, or with s/m/h/d/w suffix); supports macro substitution

  • Delay timer key — key identifying the delay timer (supports macros); cancelling this key prevents the delayed action from executing

  • Snooze time (e.g. 90, 5m, 2h) — duration during which the action will not be re-executed after it runs; has no effect unless the snooze/blocking timer key is set

  • Snooze/blocking timer key (Do not run action if this timer exists) — the action is not executed while a timer with this key exists; the snooze timer is created under this same key

Timer Cancellations

The Timer Cancellations page contains a list of timer keys to cancel. Timer keys support macro substitution.

This allows cancelling:

  • Delayed action executions — timers created under a delay timer key

  • Snooze/blocking timers — timers created under a snooze/blocking timer key

When a delay timer key is cancelled, the corresponding delayed action will not execute. This is commonly used in correlation patterns where a recovery event cancels notifications that were scheduled by a failure event.

Script

An NXSL script on the Script page is executed as part of the rule’s action.

The script can also modify the event being processed — this is the only way to change event severity or tags from the EPP:

  • $event→setSeverity() — change the event’s severity

  • $event→addTag() — add a tag to the event

  • $event→removeTag() — remove a tag from the event

Script execution is a blocking operation — the event processor will wait for the script to complete. Ensure that the script executes quickly. If you need to execute a long-running script, create an "Execute NXSL script" action and execute it from the EPP rule instead.

Persistent Storage

The Persistent Storage action allows setting or deleting key-value pairs in the NetXMS persistent storage. Both keys and values support macro substitution.

Two operations are available:

  • Set — create or update a persistent storage entry with the specified key and value

  • Delete — remove the persistent storage entry with the specified key

Persistent storage values can be read in NXSL scripts using ReadPersistentStorage("key") and written using WritePersistentStorage("key", "value"). Passing null as the value deletes the variable; an empty string is stored as an empty string.

Current persistent storage contents can be viewed in Configuration > Persistent Storage.

Custom Attributes

The Custom Attributes action allows setting or deleting custom attributes on the source object of the event. Both attribute names and values support macro substitution.

Two operations are available:

  • Set — create or update a custom attribute with the specified name and value

  • Delete — remove the custom attribute with the specified name

Downtime Control

The Downtime Control action adds records to the downtime_log database table; the collected data can be used for downtime reporting and analysis.

Configure a downtime tag (up to 15 characters) to distinguish different types of downtime for the same object. If the tag is left empty, the record is stored with tag default. When closing a downtime record, the system searches for an open record with the same downtime tag. Macros are not supported in the downtime tag field.

Two operations are available:

  • Start downtime — creates a new downtime record for the source object

  • End downtime — closes the matching open downtime record for the source object; does nothing if no matching downtime is currently open

Incident

The Incident page contains the Create incident on alarm creation checkbox. An incident is created only when the rule also creates an alarm and that alarm creation succeeds. The page also provides incident creation delay, title, and description fields. Options are available to have the AI assistant analyze the created incident and to automatically assign it.

AI Agent Instructions

The AI Agent Instructions page contains instructions for the AI agent, applied to events matched by this rule.

Alarm Key Macros

Alarm keys support the following macros for correlating related events:

  • %i — source object ID (hexadecimal)

  • %I — source object ID (decimal)

  • %n — source object name

  • %<param> — named event parameter value

  • %1 through %99 — positional event parameters

Other macros from the Action Macro Reference are also expanded, but alarm keys and messages are expanded without alarm context: %Y (alarm ID) and %y (alarm state) expand to empty values, %U is empty, and %A/%K refer to the alarm message and key produced by an earlier rule for the same event, not this rule’s alarm.

Example alarm key patterns:

NODE_DOWN_%i                          -- correlate by source node
IF_DOWN_%i_%5                         -- correlate by node and interface index (as in the shipped policy)
DC_THRESHOLD_%i_%<dciId>_%<instance>  -- correlate by node, DCI, and instance (named parameters)

For SYS_IF_DOWN, %5 is the interface index (named parameter interfaceIndex); the interface object ID is %1.

Prefer named parameters for threshold correlation keys: positional parameters differ between threshold events — the DCI ID is %5 in SYS_THRESHOLD_REACHED but %3 in SYS_THRESHOLD_REARMED. The default policy shipped with NetXMS uses DC_THRESHOLD_%i_%<dciId>_%<instance> for both.