Breaking Changes Between Releases
Review this page before upgrading to identify changes that may require manual intervention or script updates.
For upgrade procedures, see Upgrading.
7.1
-
NXCP protocol version 1 is no longer supported; the minimum is version 2. Upgrade agents that support only version 1 before upgrading the server. Protocol negotiation now fails if the peer does not answer the capability request or reports an unsupported version. See Agent Upgrades.
-
The object status Testing is removed. An interface whose operational state is testing gets status Minor if its expected state is Up, otherwise Normal; an interface whose administrative state is testing gets status Disabled. Stored status Testing is converted to Unknown during upgrade. The NXSL constants
Status::TESTINGandStatusColor::TESTINGremain for script compatibility, but no object has this status. -
The node option Use ICMP ping on primary IP address to determine node status and the NXSL method
Node::enablePrimaryIPPing()are removed. Before a node is considered down, its primary IP address is always checked with ICMP ping, unless ICMP pings are disabled for the node. Scripts that call the method fail. Interfaces other than pseudo-interfaces and manually created ones no longer get their status from ICMP ping. See ICMP Monitoring. -
After the server loses and regains network connectivity,
SYS_NODE_UPandSYS_AP_UPevents of the nodes and access points that went down because of the loss are correlated to the connectivity events. The shipped rules Terminate node down alarms when node is up and End downtime accept correlated events after upgrade; custom rules that match these events need Accept correlated events. See Beacon Hosts. -
The
IO::file functions in NXSL require the new system access right Access server file system from scripts in scripts running under a user’s security context; the upgrade grants it to the Admins group only. They are denied in scripts that run in the read-only security context (see Write Access Restrictions). -
The DCI unit
Uptimeis renamed toTimeSpan. Existing DCIs are converted during upgrade, and configuration exported by an older server is converted on import (the old name is matched without regard to case), but scripts and API clients that set or compare unit names must use the new name: a DCI created or changed through the API or NXCP with the unitUptimeis not converted, and its values are not displayed as a duration. Event macros with the units format specifier and Grafana summary tables (unless Use multipliers is set to No for the DCI) format these values as[-][n days, ]hh:mm:ss(for example,1 day, 01:01:01instead of1 days, 1:01:01), the same as the management console. The NXSL functionSecondsToUptime()is deprecated and keeps its output format; its replacementFormatTimeSpan()uses the new format. -
The AI server configuration variables
AI.MaxBackgroundIterationsandAI.MaxInteractiveIterationsare renamed toAI.MaxBackgroundStepsandAI.MaxInteractiveSteps(existing values are kept). The scheduled task handlerExecute.AIAgentTaskis renamed toExecute.AIPrompt, and existing tasks are converted. Delegation of skills to sub-requests is replaced by workers. See AI reference. -
The server configuration variable
Server.CommandOutputTimeoutis renamed toClient.ObjectTools.OutputTimeout(the existing value is kept). It now also sets how long the management client waits for output of Agent Command and SSH Command object tools, which used a fixed 60 seconds before. -
AI assistant internal tools (skills, memory, AI tasks, AI messages, approval requests, and AI operator checks) are no longer available to MCP clients.
-
A network device driver set manually with the
snmp.drivercustom attribute is used only if the node supports the transports the driver requires. -
REST API: node communication settings are grouped.
POST /v1/objectsno longer reads the flat fieldsagentPort,agentProxy,snmpPort,snmpProxy,etherNetIpPort,etherNetIpAddress,etherNetIpProxy,modbusTcpPort,modbusUnitId,modbusProxy,icmpProxy,sshLogin,sshPassword,sshPort,sshProxy,vncPassword,vncPort, andvncProxy; use theagent,snmp,etherNetIp,modbus,icmp,ssh, andvncgroups instead (for example,ssh.login). Node object documents return SSH, VNC, Modbus, EtherNet/IP, NETCONF, and ICMP settings in thessh,vnc,modbus,etherNetIp,netconf, andicmpgroups instead of flat fields, andicmp.statCollectionModeis a name (default,on,off) instead of a number. On sensors,modbusUnitIdis replaced bymodbus.unitId. See REST API. -
REST API, AI:
/v1/ai/skills-and-functionsis renamed to/v1/ai/skills-and-tools; in its responsefunctionsis renamed totools, the skill fieldsupportsDelegationtosupportsWorker, and thedefaultModevaluesloaded/delegatedtoload/worker. The disabled item typesS/Fare renamed toskill/tool. The chat status fieldcurrentFunctionis renamed tocurrentTool, the AI operator fielditerationtocycle, and AI message fieldssourceTaskId/sourceTaskTypeare replaced byorigin. In EPP rule documents,aiAgentInstructionsis renamed toaiInstructions(the old name is still accepted as input). The NXSL attributeAIOperator.iterationremains as an alias ofcycle. -
OpenTelemetry export (
otlpmodule):host.nameandhost.idare sent only for nodes; other objects are identified by the newnetxms.object.id,netxms.object.guid, andnetxms.object.classattributes. The custom attributeotel:service.nameon an object overridesServiceName. The log record attributeevent.tagsis an array of strings instead of a comma-separated string. Events without a source object use the management server node as their resource instead ofhost.name=netxms-server. Resource attributes for hardware, location, power domains, and cooling zones, and the DCI tag data point attributes, are new. See OpenTelemetry (OTLP) Export.
7.0.4
-
The SNMP trap receiver, the UDP syslog receiver, and the built-in SNMP agent of the server use
ListenAddressthe same way as the TCP listeners since 7.0.2: they listen on every address in a comma-separated list, ignore an address that cannot be resolved instead of falling back to loopback, and no longer open a loopback socket for the other address family. With no usable address, the receiver stays inactive.
7.0.3
-
SSH key import accepts only unencrypted OpenSSH private keys and derives the public key on the server. Import clients must send
privateKeyin that format; supplying a separate public key does not bypass validation. Keys in other formats or with a passphrase must be converted before import (see Importing a Key). Keys already stored are not changed. Key names longer than 254 characters are rejected instead of being truncated.
7.0.2
-
ContextSizein AI provider configuration now always means the context window size of the model and no longer setsmax_tokensforanthropicproviders. Use the newMaxOutputTokensparameter for that limit (default 32768). See AI reference. -
The REST API returns symbolic names instead of numeric codes for DCI data. In current values,
dataType,status,type, and the thresholdcurrentSeverityare names, andsourceTypeis replaced byorigin. In the performance view,dataTypeis a name. Table results haveorigininstead ofsource, and the columndataTypeis a name. -
The origin name of agent DCIs changed from
nxagenttoagentin REST API responses and in data export files. Requests that sendnxagentasoriginare rejected. -
ListenAddresson the server and the agent, andSNMPTrapListenAddresson the agent, listen only on the configured addresses. An address that cannot be resolved is ignored instead of falling back to loopback, and a single address no longer opens a loopback socket for the other address family. With no usable address, the listener stays inactive. On the server, this applies to the TCP listeners, such as those for client and agent tunnel connections. The SNMP trap receiver, the UDP syslog receiver, and the built-in SNMP agent still take a single address fromListenAddressand listen on the loopback address when it cannot be resolved, which is also the case for a comma-separated list (changed in 7.0.4). -
Existing network maps with automatic layout change their appearance: Spring and Radial use new algorithms, tree layouts start from the center of the graph, and automatic layouts fit the map size or the visible area, except Sparse vertical tree in map views. See Layout Algorithms.
-
The Close other sessions after login user option no longer applies to logins with persistent tokens (as before, it does not apply to logins with service tokens), and now applies to RADIUS challenge-response logins.
7.0
-
The standalone WebAPI service (
nxapisrv) is deprecated and removed; the REST API is now provided by thewebapiserver module loaded into the server process. -
The "internal" object tool type was removed and type 0 is now reserved. The built-in Wakeup node tool is converted to a server script tool (
Tools::WakeUpNode) during upgrade. -
A network mask is no longer accepted when creating nodes. Pseudo-interfaces created for unmanaged nodes get a synthetic mask automatically.
-
The Microsoft Teams notification channel driver was reworked to use Power Automate Workflows webhooks. Legacy Office 365 connectors are no longer supported, and the
UseMessageCardsandThemeColordriver options are ignored. -
DCIs with Script origin and DCI instance discovery scripts no longer run in the read-only security context introduced in 6.2. They can modify objects, post events, and send notifications regardless of the
Scripts.RestrictWriteAccesssetting. Such scripts live in the script library, and write access to the script library already allows unrestricted code to run, for example through hook scripts. All other scripts listed in Write Access Restrictions remain restricted. -
Ad-hoc script execution on an object requires the new Execute scripts object access right instead of Modify, and the
Objects.ScriptExecution.RequireWriteAccessserver configuration variable is removed. During upgrade, the right is granted to every access list entry that has Modify (or Read or Modify, ifObjects.ScriptExecution.RequireWriteAccesswas disabled). -
Opening the data collection configuration of an object requires the new Read data collection configuration access right, and reading device configuration backups requires the new Read device configuration access right. During upgrade, the first is granted to every access list entry that has Read, the second to every entry that has Modify.
-
Helpdesk links are server modules: the
HelpDeskLinkserver configuration variable is removed, and the link is enabled by loadingjiraorredminewith aModuleentry innetxmsd.conf. The Jira webhook is served by the web API listener at/jira-webhook;Jira.Webhook.PortandJira.Webhook.Pathare replaced byJira.Webhook.EnableandJira.Webhook.Secret. See Helpdesk Integration. -
The Python subagent is removed.
-
The Jython-based
nxshellscripting client is removed; Python scripts should use the REST API. The namenxshellnow belongs to a different, interactive command line shell — see NetXMS Shell (nxshell). -
NXSL performs integer arithmetic as signed 64-bit; an operation keeps the unsigned 64-bit domain only when one operand is an unsigned 64-bit value. Scripts that relied on 32-bit wrap-around get different results.
-
NXSL
Alarmmethodsacknowledge(),resolve(),terminate(),setHelpdeskReference(),closeHelpdeskIssue(), andunlinkFromHelpdesk(), andTunnel.bind(), returntrueorfalseinstead of a numeric result code (where0meant success). Scripts that compare the result with0must be updated. -
On Windows, each element of an exec-form command (
["app.exe", "arg1", "arg2"]) is now passed to the executable as exactly one argument, as on other platforms. Previously the elements were joined with spaces and re-split by the started program. Configurations that packed several arguments into one element (for example["app.exe", "-a -b"]) must split them into separate elements, and configurations that wrapped a value in extra quotes to keep it together on Windows (for example["reg.exe", "add", "HKLM\Software\Example", "/v", "Name", "/d", '"some text"']) must drop the extra quotes, because they are now passed to the program as part of the argument. -
On Windows, the server and agent installers no longer include the MySQL database driver
mysql.ddr;mariadb.ddrconnects to both MySQL and MariaDB servers. When upgrading to 7.0.0 to 7.0.2, changeDBDriverinnetxmsd.conffrommysqltomariadbbefore running the installer. Otherwise the database upgrade that the installer runs fails, and the server does not start. To recover, correctDBDriver, runnxdbmgr upgrade, and then start the server. In the same versions, the agent’s MySQL subagent does not initialize when itsDriverismysql; set it tomariadb. Since 7.0.3,mysqlin the configuration loads the MariaDB driver on Windows. Linux packages are not affected. See Database Setup.
6.2
Scripts evaluated automatically by the server — DCI transformation scripts, scripted thresholds, auto-bind filters, conditions, EPP filter and RCA scripts, and others — are now read-only and cannot modify objects, post events, or send notifications.
This is controlled by the new Scripts.RestrictWriteAccess server configuration variable, which is set to 1 both on new installations and during upgrade.
Denied operations do not produce a script error: the call returns false or a null value and the script continues, so affected scripts stop having effect silently.
Using the returned value as though the operation had succeeded can cause a later NXSL error that does not mention the restriction.
See Write Access Restrictions for the list of affected scripts and for ways to keep the modifying logic working.
6.1
-
The server validates the credentials of incoming SNMP traps against the source node and drops traps that do not match. For SNMPv1/v2c, the trap community must match the node’s SNMP community, or the separate trap community if one is configured; for SNMPv3, the user name must match and the security level must not be lower than configured. Earlier versions did not check the community of incoming traps, so a device that sends traps with a community different from the one used for polling stops producing trap events after the upgrade. Dropped traps do not appear in the trap log. Since 6.2.0, the
SYS_SNMP_TRAP_AUTH_FAILUREevent reports them; since 6.2.3 and 7.0, the check can be disabled globally or per node. See Trap Credential Validation.
6.0.0
The web management client requires a servlet container supporting Jakarta Servlet API 6.0 (Tomcat 10.1 or later, Jetty 12 or later). Containers that implement only the older javax.servlet API, such as Tomcat 9, are no longer supported.
Backslash no longer has special meaning in macro expansion and does not need to be escaped.
The input field macro %(name) has been repurposed into a multi-purpose macro supporting:
-
%(nl)— insert new line character -
%(cr)— insert carriage return character -
%(lf)— insert line feed character -
%(tab)— insert tab character -
%(in:name)— insert input field value
During upgrade, existing macros are automatically converted.
5.1
NXSL changes: node attribute ipAddr is deprecated.
Use the ipAddress attribute instead.
The reporting server (nxreportd) and the agent’s Java and JMX subagents require Java 11 or later; version 5.0 and earlier ran on Java 8. On a host with only a Java 8 runtime, they do not start. See Reporting.
5.0
MIB File Changes
Previously loaded additional MIB files will not work after upgrade. They must be re-uploaded via .
-
MIB compilation file extension changed to
.mib -
Compiled MIB file extension changed to
.cmib -
Default MIB file location changed to
$HOME/share/netxms/mibs/ -
Default format of SNMP OIDs changed to a format without leading dot — this can break scripts that use SNMP OID string comparisons
NXSL Syntax Overhaul
The NXSL syntax has changed significantly.
During upgrade, existing scripts are converted automatically.
For manual conversion, use the nxscript command line utility: nxscript -5 script-file.nxsl.
| Description | Old Syntax | New Syntax |
|---|---|---|
String concatenation |
|
|
Object dereference |
|
|
Array initialization |
|
|
Safe dereference (custom attribute access) |
|
|
Library import |
|
|
Function definition |
|
|
NXSL Class and Function Renames
Class TIME was renamed to DateTime.
New modules Math, Base64, Crypto, Net, and IO were created, and functions were moved under them.
The most commonly used functions are left as deprecated aliases, but others were renamed without a deprecated version.
| Old Name | New Name | Type |
|---|---|---|
TIME |
DateTime |
class |
asin |
Math::Asin |
function |
acos |
Math::Acos |
function |
atan |
Math::Atan |
function |
atan2 |
Math::Atan2 |
function |
cosh |
Math::Cosh |
function |
exp |
Math::Exp |
function |
gethostbyaddr |
Net::ResolveAddress |
function |
gethostbyname |
Net::ResolveHostname |
function |
log |
Math::Log |
function |
log10 |
Math::Log10 |
function |
md5 |
Crypto::MD5 |
function |
sha1 |
Crypto::SHA1 |
function |
sha256 |
Crypto::SHA256 |
function |
sinh |
Math::Sinh |
function |
tanh |
Math::Tanh |
function |
weierstrass |
Math::Weierstrass |
function |
decode |
Base64::Decode |
function |
encode |
Base64::Encode |
function |
CopyFile |
IO::CopyFile |
function |
CreateDirectory |
IO::CreateDirectory |
function |
DeleteFile |
IO::DeleteFile |
function |
FileAccess |
IO::FileAccess |
function |
OpenFile |
IO::OpenFile |
function |
RemoveDirectory |
IO::RemoveDirectory |
function |
RenameFile |
IO::RenameFile |
function |
4.4
The minimal JRE (Java Runtime Environment) version for both web and management client is now Java 17.
4.2
The NXSL functions AgentExecuteAction and AgentExecuteActionWithOutput were renamed to AgentExecuteCommand and AgentExecuteCommandWithOutput.
4.1
-
The
CreateDCINXSL method changed: the last two parameters (polling interval and retention time) should be set tonullinstead of0to use default values -
NXSL decimal numbers written with leading zeros are no longer interpreted as octal
4.0
-
Incompatible change in NXSL DCI class:
instanceattribute now refers to the instance value (as in{instance}macro), not instance name. UseinstanceNameto access the instance name. -
Several Web API endpoints were renamed (e.g.,
API_HOME/summaryTable/adHocbecameAPI_HOME/summary-table/ad-hoc)
3.8
The minimal JRE (Java Runtime Environment) version for the management client is Java 11. A Desktop Management Client with bundled JRE is provided for Windows.
3.7
-
Introduced boolean type in NXSL. Comparisons like
func() == 1, wherefuncreturns a boolean, will always evaluate to false because the boolean valuetrueis not equal to integer 1. This may require fixes in NXSL scripts. -
Regexp matching operation in NXSL now returns an array with capture groups or
falseas a result. -
Clusters now have configuration poll. If you have a configuration poll hook script that references
$node, this will produce errors when configuration poll runs on a cluster. Replace$nodewith$objector add a guard:if (classof($object) == "Node").
3.6
The Certificate Manager was removed from the server.
All CA certificates configuration must be manually moved to the TrustedCertificate parameter in the server configuration file.
3.5
External Metrics (ExternalMetric, etc.) now expect UTF-8 encoding on Windows.
Adjust scripts called by external metrics if non-ASCII characters are returned.
3.1
-
Regexp matching operation in NXSL returns array with capture groups or
NULLas result -
NXSL objects and arrays in logical expressions are evaluated to
TRUE— this may require NXSL script adjustments
3.0
-
Notification channels introduced as new functionality. SMS configuration is automatically migrated from server configuration to a notification channel based on the old driver name (AnySMS, DBTable, Dummy, GSM, Kannel, MyMobile, Nexmo, NXAgent, Portech, Slack, SMSEagle, Text2Reach, WebSMS). No manual action required.
-
Flags and dynamic flags moved to the
NetObjectclass. Node flags are separated into user-set flags and system-set capability flags. Numeric values for flags, capabilities, and dynamic flags were changed — this affects NXSL scripts that check those flags directly. -
The 32-bit version of the management client is no longer available.
-
The agent always requires encryption unless the
RequireEncryptionparameter is explicitly set tooff. You may need to add this parameter where encryption is not desired. -
Agent policies were merged with templates. Each policy was converted to a template. No manual changes required.
Java Version Requirements Summary
Starting with version 4.4, Java 17 is the minimum Java version for both the desktop and web management clients. For earlier releases, the release notes stated older minimums for the management client: Java 8 up to version 3.7 and Java 11 from version 3.8.
Starting with version 5.1, the reporting server (nxreportd) and the agent’s Java and JMX subagents require Java 11 or later; up to version 5.0 they ran on Java 8.
| Current versions of the web management client require Tomcat 10.1 or later, or Jetty 12 or later (Jakarta Servlet API 6.0). |