This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

How to Create EPP Rules

This page covers how to create, configure, and manage Event Processing Policy (EPP) rules. For an overview of how the EPP works, see Understanding Event Processing Policy. For a complete reference of filters and actions, see EPP Reference.

Creating a Rule

  1. Open Configuration > Event processing policy

  2. Click Add new rule (new rules are added at the bottom by default)

  3. Configure the filter criteria:

    • Select matching events

    • Select source objects (or select Any for all objects)

    • Set severity filter if needed

    • Add time filters if the rule should only apply during specific hours

  4. Configure actions:

    • Create, resolve, or terminate alarms

    • Execute server actions (send notification, execute command or script, etc.)

    • Give the AI assistant instructions to act on the event (see How to Analyze Events with AI Instructions)

  5. Enable Stop event processing on the Action page if subsequent rules should not see the event

  6. Save the chain with Save (Ctrl+S)

A new rule is added to the chain in the active tab — see Managing Rule Chains.

Managing Rule Chains

The editor shows one tab for each rule chain you can read; the main chain’s tab is titled Main. A tab whose chain has unsaved changes is titled *name; a chain you can read but not edit is titled name (read-only). The tooltip of a named chain shows its description and how many rules call it ("called by N rule(s)").

Save (Ctrl+S) saves the chain in the active tab; Save all saves every changed chain and stops at the first conflict.

Creating, Changing, and Deleting a Chain

New chain…​ is next to the last tab; Chain properties…​ and Delete chain are at the right end of the tab row. All three are also in the view menu and require the Edit event processing policy system right. Unlike rule changes, they take effect on the server immediately, without Save.

To create a chain:

  1. Click New chain…​

  2. In the Create Chain dialog, enter a Name (required; names do not have to be unique) and an optional Description

  3. Optionally grant access to users who do not have the Edit event processing policy right (see Chain Access)

  4. Click OK — the chain opens in a new tab

A chain is evaluated only when a rule calls it: add the chain on the calling rule’s Chain Calls page.

Chain properties…​ opens the same dialog (Chain Properties) for the chain in the active tab. The main chain has no properties and cannot be deleted.

Delete chain deletes the chain in the active tab together with all its rules, after a confirmation. If rules in other chains call it, the confirmation names how many rules and which chains; those calls are removed from the calling rules. Unsaved changes in the deleted chain are lost.

Moving Rules to Another Chain

To move rules to another chain, select them and click Move to chain…​ (rule context menu or toolbar). The Move Rules to Another Chain dialog lists the other chains you can edit; pick the Target chain and click OK. The rules keep their order and their GUIDs and are appended to the end of the target chain. If moved rules call the target chain, the dialog warns that these calls become calls of the chain to itself, which the server skips at run time; remove them afterwards.

Nothing is saved yet: both chains have unsaved changes. Use Save all, which saves the chains that received new or moved rules first. Do not save only one of the two chains: if the other one is then reloaded or closed without saving, the moved rules end up in both chains (and process every matching event twice) or in neither (netxms#4028).

Chain Access

Users with the Edit event processing policy system right have full access to every chain. Other users can be given access to individual named chains; the main chain is never accessible to them.

Access is granted in the chain’s Chain Properties dialog: add users or groups to the Users and Groups list with Add…​ (new entries get Read), then select the Access Rights for each entry:

  • Read — the chain is shown in the editor, and the user can call it from rules in chains they can edit

  • Edit — the user can change and save the chain’s rules. Grant Read as well: a chain the user cannot read is not shown at all.

An entry for the user takes precedence over entries for their groups, even when it grants less; rights from several group entries are combined.

A user without the system right sees only the chains they can read, cannot create, change, or delete chains, and cannot open the policy at all when no chain grants them Read. Calls to chains they cannot read are shown as the chain ID in brackets. Such a user cannot save a chain in which any rule calls a chain they cannot read, even when they did not change that rule.

Reordering Rules

Rules are reordered by dragging them in the policy editor. The rule context menu also provides Explain, Enable, Disable, Insert above, Insert below, Cut, Copy, Paste, Move to chain…​, and Delete operations. Paste inserts the rules after the last selected rule; with no rule selected, it appends them to the end of the chain, which also works in an empty chain. When reordering, consider:

  • More specific rules should come before more general rules

  • Rules with Stop Processing should be positioned carefully — they prevent all subsequent rules from seeing the event

  • Recovery/deactivation rules typically need their own entries

Common EPP Patterns

Node Down / Node Up

Two rules working together:

Rule 1 — Create alarm on node down: * Event filter: SYS_NODE_DOWN, SYS_NODE_UNREACHABLE (for a node without a primary IP address, loss of its agent tunnel generates only the latter, see Root Cause Analysis) * Action: Create new alarm with key NODE_DOWN_%i, severity Critical

Rule 2 — Terminate alarm on node up: * Event filter: SYS_NODE_UP * Action: Terminate alarms with key NODE_DOWN_%i

Do not set Stop event processing on these rules — it would prevent subsequent notification and escalation rules from seeing the same events.

Threshold Alarm

Rule 1 — Create alarm on threshold: * Event filter: SYS_THRESHOLD_REACHED * Action: Create new alarm with key DC_THRESHOLD_%i_%<dciId>_%<instance>, severity from event

Rule 2 — Terminate alarm on threshold recovery: * Event filter: SYS_THRESHOLD_REARMED * Action: Terminate alarms with key DC_THRESHOLD_%i_%<dciId>_%<instance>

Named parameters are used because positional parameters differ between the two events (the DCI ID is %5 in SYS_THRESHOLD_REACHED but %3 in SYS_THRESHOLD_REARMED). This matches the default policy shipped with NetXMS.

Escalation by Severity

Multiple rules with different actions based on severity:

Rule 1 — Critical events: send SMS + email * Event filter: any * Severity filter: Critical * Actions: Send notification via SMS channel, send notification via email channel

Rule 2 — Major events: send email only * Event filter: any * Severity filter: Major * Actions: Send notification via email channel

Escalation via Timed Outstanding

Alarms can be configured to generate a new event if they remain in Outstanding state for too long. This is configured on the rule’s Alarm page by setting Alarm timeout (a duration such as 90, 30m, or 2h) and selecting the Timeout event to generate. Setting the timeout to 0 disables this feature.

Escalation is built on this mechanism. When an alarm is generated but no operator acknowledges it within a predefined time, a new event can be generated, resulting in additional notifications (email, SMS, instant message) to the operator or their manager. This escalation process can have as many steps as needed.

Alternatively, a single EPP rule can contain multiple actions with different delays. Delay timers are cancelled by another rule when the problem is resolved.

Example — multi-level escalation for node down:

Rule 1 (Node Down with escalation): * Event filter: SYS_NODE_DOWN, SYS_NODE_UNREACHABLE * Action: Create new alarm with key NODE_DOWN_%i * Action: Send email to on-call engineer (delay: 60, delay timer key: NODEDOWN_NOTIFY_%i) * Action: Send email to support manager (delay: 30m, delay timer key: NODEDOWN_ESCALATE1_%i) * Action: Send email to IT manager (delay: 1h, delay timer key: NODEDOWN_ESCALATE2_%i)

Rule 2 (Node Up cancels escalation): * Event filter: SYS_NODE_UP * Action: Terminate alarms with key NODE_DOWN_%i * Timer Cancellations: NODEDOWN_NOTIFY_%i, NODEDOWN_ESCALATE1_%i, NODEDOWN_ESCALATE2_%i

With this configuration:

  1. After 1 minute, the on-call engineer is notified if the problem still persists

  2. After 30 minutes, the support manager is notified if the problem still persists

  3. After 1 hour, the IT manager is notified if the problem still persists

If the node comes back up before any timer expires, the corresponding notifications are cancelled.

Maintenance Mode and Correlated Events

No rules are needed to suppress alarms for objects in maintenance mode. Events from an object in maintenance are automatically correlated to its maintenance event, and every EPP rule skips correlated events by default — so by default no alarms are created and no actions run for them.

To deliberately process events from objects in maintenance (for example, to keep a logging or forwarding rule active during maintenance windows), enable Accept correlated events on the rule’s Condition page. Note that this option applies to all correlated events, not only maintenance — events correlated to a node-down event are affected the same way.

A rule that accepts correlated events for another reason, such as a notification on SYS_NODE_UP, therefore also runs for objects in maintenance. To exclude them, add this filtering script on the rule’s Filtering Script page:

return ($object != null) && !$object.isInMaintenanceMode;

Interface and network service events use the node as their source, so the script also covers them.

Delayed Actions and Maintenance Mode

A delayed action is scheduled when its rule matches the event, and it runs when the delay expires. Maintenance mode does not affect actions that are already scheduled:

  • Entering maintenance mode does not cancel pending delayed actions.

  • When the delay expires, the action runs without another check of the rule’s filters, of the Accept correlated events option, or of the source object’s maintenance state.

  • Pending delayed actions are stored in the database, so a server restart does not remove them.

With the multi-level escalation example above, a node that goes down before a maintenance window starts still sends its escalation emails during the window.

The recovery rule of that example also stops cancelling timers during maintenance. If the node comes back up while it is in maintenance, its SYS_NODE_UP event is correlated to the maintenance event, and Rule 2 skips it. The timers stay active, and the escalation emails are sent although the node is up. When maintenance ends, the server restores the node state saved when maintenance started and, because the state has changed, runs a status poll. This poll generates SYS_NODE_UP again, without maintenance correlation, and Rule 2 cancels the timers that have not expired yet.

Use one or more of the following approaches.

Cancel Timers When the Node Recovers During Maintenance

On Rule 2, select Accept correlated events on the Condition page. Rule 2 then also matches a SYS_NODE_UP event that is correlated to maintenance, and it cancels the timers as soon as the node is up. If the rule also sends a notification that is not wanted during maintenance, keep that rule unchanged and put the timer cancellations into a separate rule with Accept correlated events selected.

This approach does not stop the escalation for a node that stays down during maintenance.

Cancel Timers When Maintenance Starts

Add a rule that cancels the escalation timers when the node enters maintenance:

Rule 3 (Maintenance cancels escalation): * Event filter: SYS_MAINTENANCE_MODE_ENTERED * Timer Cancellations: NODEDOWN_NOTIFY_%i, NODEDOWN_ESCALATE1_%i, NODEDOWN_ESCALATE2_%i

SYS_MAINTENANCE_MODE_ENTERED and SYS_MAINTENANCE_MODE_LEFT are never correlated, so this rule does not need Accept correlated events. When maintenance starts on a container or a cluster, each managed node that newly enters maintenance generates its own SYS_MAINTENANCE_MODE_ENTERED event, so %i expands to the ID of each node and the per-node timer keys are cancelled.

The escalation does not resume after maintenance. If the node is still down when maintenance ends, its state has not changed, so no new SYS_NODE_DOWN event is generated. The alarm created by Rule 1 stays open, but no further escalation emails are sent.

Check Maintenance Mode When the Action Runs

The filters of a rule cannot be evaluated again when its delayed action runs. To check the object at that time, use an Execute NXSL script action for the escalation steps instead of a Send notification action. The script runs when the delay expires, and $object is the event source object in its current state.

Example library script NodeDownEscalation, which takes the recipient as its first argument:

if ($object.isInMaintenanceMode)
   return;
SendNotification("SMTP-Text", $1, "Node " .. $object.name .. " is still down", $event.message);

For each escalation step, create an Execute NXSL script action with a Script name such as NodeDownEscalation("[email protected]"). In Rule 1, use these actions in place of the email actions, with the same delays and delay timer keys.

An escalation step that comes due during maintenance is skipped, not postponed. Steps that come due after maintenance ends run as usual while the node is still down.

Management Tips

  • Use the rule comment as a descriptive label — it is displayed as the rule header in the editor, and the policy can grow to dozens of rules

  • Use comments to document the purpose and context of complex rules

  • Test new rules in a staging environment before applying to production

  • Back up the EPP before making significant changes — see Exporting and Importing Rules

  • Use Disable to temporarily deactivate rules without deleting them

  • Check rules marked with an error icon — expand a rule to read its Errors card (see Rule Error Indication)

  • Group related rules together (e.g., all notification rules in sequence)

Exporting and Importing Rules

EPP rules are exported with Configuration > Export configuration and imported with Configuration > Import configuration. For rule chains:

  • Each exported rule records the chain it belongs to and the chains it calls. The export also carries the name and description of those chains, but not their rules: a called chain whose rules were not exported arrives empty on a server that does not have it yet.

  • Chain access lists are not exported.

  • On import, chains are matched by their GUID, not by name. A chain with the same GUID is always reused; its name and description are updated only when Replace EPP rules is selected. If no chain with that GUID exists, a new chain is created, even if a chain with the same name exists.

  • A rule whose chain can be found neither in the file nor on the server is imported into the main chain, with a warning in the import log. A call to a chain that can be found neither in the file nor on the server is dropped from the rule.