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.

Notifications

NetXMS can send notifications through multiple channels when events occur or alarms are created. Notification delivery is configured through notification channels and EPP action rules.

Notification Architecture

The notification flow in NetXMS:

  1. An event is generated

  2. The EPP matches the event to a rule

  3. The rule executes an action configured to send a notification

  4. The action specifies the notification channel and recipient

  5. The notification channel delivers the message

Notification Channels

A notification channel defines the delivery method and connection parameters for sending messages.

What a Driver Receives

Every driver receives the same three values for each message: a recipient, a subject, and a message body. They are the Recipient, Subject, and Message text fields of the notification action after macro substitution (see Action Macro Reference). Substitution includes %[script] macros, so each of the three values can be computed by a script from the script library. The Recipient value is then split on semicolons, and the driver receives one recipient per message (see Recipients). When Message contains markdown is set in the action, the SMTP, Telegram, Slack, Mattermost, Matrix, and Microsoft Teams drivers render the Markdown; all other drivers receive a plain-text rendition of the message.

Except for the NXSL driver, the message content is made from these three values only. To put other event data into a message, add macros to the action fields. Drivers with configurable output expose the three values in their own way:

  • Webhook driver — placeholders ${recipient}, ${subject}, and ${body}

  • Shell driver — placeholders ${recipient}, ${subject}, and ${text} (not ${body})

  • NXSL driver — global variables $RECIPIENT, $SUBJECT, and $MESSAGE; the script also gets the event and its source object

Channel Status

Once a notification channel is created, it appears in the channel list with a status indicator:

  • Green — driver initialization was successful

  • Red — driver initialization failed

The channel list has the following columns:

  • Name — channel name

  • Description — channel description

  • Driver — driver used by the channel

  • Messages — number of messages sent through the channel

  • Failures — number of failed send attempts

  • Digested — number of messages combined by message digesting

  • Queue — number of messages currently waiting in the channel’s queue

  • Status — result of the last send attempt

  • Error message — details about initialization or sending failures

Messages waiting in a channel’s queue can be discarded with Clear queue in the channel’s context menu.

A channel provided by a chat bot is registered automatically by the bot and cannot be edited in the channel list; change the chat bot configuration instead.

Configuring Notification Channels

  1. Open Configuration > Notification channels

  2. Click New…​

  3. Select the driver

  4. Configure driver-specific settings in the Driver configuration field

  5. Test the channel with Send notification…​

For driver-specific configuration parameters, see Notification Channel Driver Reference.

Delivery Behavior

Notification channels implement rate limiting (both per channel and per recipient), message digesting (combining multiple messages into a single one), and automatic retry of failed send attempts. The total number of delivery attempts, the first one included, is limited by the NotificationChannels.MaxRetryCount server configuration variable (default 30).

Rate Limiting and Digests

Rate limiting is disabled by default. It is configured with server configuration variables that apply to all notification channels; there is no setting per channel or per event processing rule. Each channel keeps its own limits: a channel limit for all its messages, and a separate limit for each recipient.

Each limit is a token bucket:

  • Burst is the number of messages that can be sent at once.

  • Rate and RateUnit (second, minute, or hour) set how fast the capacity refills.

For example, NotificationChannels.RateLimit.ChannelBurst = 10, NotificationChannels.RateLimit.ChannelRate = 1 and NotificationChannels.RateLimit.ChannelRateUnit = minute let a channel send 10 messages immediately, then one message per minute. A limit is active only when both its burst and its rate are greater than 0. All per-recipient limits of a channel are reset about every 10 minutes, so each recipient then gets its full burst again.

A message that exceeds a limit is not discarded: it stays in the channel queue until the limit allows it. When the queue reaches NotificationChannels.RateLimit.DigestThreshold messages (default 50), throttled messages are collected into a digest for each recipient instead. About every NotificationChannels.RateLimit.DigestInterval seconds (default 300), each recipient with collected messages gets one message with the subject [Digest] Notification summary, queued behind the messages already waiting. Its text is a summary written by the AI assistant when an AI provider is configured, otherwise a list of the subjects of the collected messages. Digest messages are not rate limited. Setting DigestThreshold or DigestInterval to 0 disables digests.

When the channel queue holds NotificationChannels.MaxQueueSize messages (default 500; 0 means no limit), new messages for the channel are discarded. The server then writes a warning to its log and generates a SYS_NC_QUEUE_OVERFLOW event, once each time the queue becomes full. Messages that still fail after all retries are also discarded (see Delivery Behavior).

The channel reads changes to these variables about every 10 seconds between messages, without a server restart; a channel busy sending a message picks them up after that message. See Server Configuration Variables for the full list.

Recipients

The Recipient field of a notification action is a plain text string. Macro substitution is applied to it, then the result is split on semicolons (with surrounding whitespace trimmed) and the message is sent once per recipient — the server does not interpret recipients as user or group names and does not look up addresses anywhere. The expected format of each recipient depends on the driver: an email address, a phone number, a Telegram chat ID, and so on.

User Contact Information

User accounts in NetXMS have Email and Phone number fields (open Configuration > Users and groups and edit the user), and additional channel-specific addresses can be stored in custom attributes. Nothing in the notification delivery path reads these fields automatically — they are only accessible from NXSL scripts. To deliver a notification to an address stored in a user’s profile, use a %[script] macro in the Recipient field and return the address from the script.

Notification Actions

Notifications are triggered by EPP actions. To set up notification delivery:

  1. Create a notification channel (as described above)

  2. Create an action of type Send notification (see Actions)

  3. In the action, select the notification channel and specify recipients

  4. Attach the action to an EPP rule

Message Templates

Notification messages use templates with macro substitution. All macros from the Action Macro Reference are available in notification templates.

Commonly used macros:

  • %n — source object name

  • %a — source IP address

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

  • %S — event severity code as text

  • %m — event message text

  • %N — event name

  • %A — alarm message text (when triggered from alarm-generating rule)

  • %t — timestamp

  • %1 through %99 — positional event parameters

  • %<name> — named event parameter

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

Example email template:

Subject: [{product-name}] %S alarm on %n
Body:
Alarm: %A
Event: %N
Source: %n (%a)
Severity: %S
Time: %t

Notification Routing by Schedule

Different notification targets can be used for different times by combining EPP time filters with separate notification actions:

  • Rule 1 (business hours, Mon-Fri 08:00-18:00): send to on-call team email

  • Rule 2 (off-hours): send to on-call SMS + manager email

See Event Processing Policy for details on time filters.

Notification Logging

Each notification message is recorded in the notification log with a success or failure flag — one record per message, written after all retry attempts. The log does not contain error details; delivery errors surface in the channel’s Error message column and through the SYS_NOTIFICATION_FAILURE event. Messages discarded because the channel queue is full (NotificationChannels.MaxQueueSize server configuration variable, default 500) are not logged at all. The log is available at Logs > Notifications; viewing it requires the "View notification log" system access right.

Executions of all action types — including notifications, with channel, recipient, and subject — are also recorded in Logs > Server Action Executions; viewing that log requires the "View action execution log" system access right.

For low-level troubleshooting, enable debug output in the server debug console: the nc tag covers the notification channel framework (debug nc 6), and drivers log under ncd.<driver> tags such as ncd.smtp or ncd.telegram (debug ncd.* 6 enables all driver output).

Troubleshooting Notifications

Email Not Delivered

  • Verify SMTP server address and port

  • Check authentication credentials

  • Test with Send notification…​ in the Notification Channels view

  • Check server logs for SMTP connection errors

  • Verify the sender address is allowed by the SMTP server (SPF, relay restrictions)

SMS Not Delivered

  • Verify GSM modem connection or gateway configuration

  • Check that the phone number format is correct (international format: +1234567890)

  • Verify modem signal strength and SIM card status

  • For gateway drivers (AnySMS, Nexmo, Twilio, etc.): verify API credentials and account balance

Telegram Not Delivered

  • Verify the bot token is correct

  • Ensure the recipient has started a conversation with the bot (bot cannot initiate chats)

  • Check if a proxy is needed for Telegram API access

  • Verify the chat ID is correct (use https://api.telegram.org/bot<TOKEN>/getUpdates to confirm)

Chat Integrations Not Working

  • Verify webhook URLs are correct and active

  • Check that the bot/integration has been added to the channel/room

  • For Microsoft Teams: verify the channel’s Microsoft Teams Workflows (Power Automate) webhook URL — the driver sends messages as Adaptive Cards to Workflows webhooks; legacy Office 365 incoming webhook connectors were retired by Microsoft and are not supported

  • For Slack: verify the webhook URL has not been revoked

Next Steps