Neptune DXP Documentation
Neptune DXP - Open Edition · 25.0 MTS

Upgrade to Neptune DXP - Open Edition 25

Neptune DXP 25 includes a lot of new features and enhancements to make Neptune DXP even more valuable for you. In order to provide the best experience we introduced a few changes you need to be aware of before upgrading to Neptune DXP 25.

Choose your upgrade path

You are currently on What to read

24.15

Changes in 25.0.0 (all paths) and Universal upgrade steps (all paths).

24.10 – 24.14

The above, plus Additional steps when upgrading from 24.10 to 24.14.

23.x or 22.x

Upgrading from 23.x or 22.x first, then the 24.15 path.

Changes in 25.0.0 (all paths)

Upgrading to 25.0.0

The release that follows the June release of 24.15 was originally planned as 24.16. It has instead been designated version 25.0.0, a major version.

Two underlying platform upgrades drive this decision:

  • Node.js moves to version 26.8.1. The version previously in use, Node.js 22, reaches the end of its maintenance window in May 2027.

  • The default UI5 version is upgraded to 1.148.3. The previous default, 1.136, reaches end of maintenance in Q3 2026.

Because both upgrades can introduce breaking changes, the release is treated as a major upgrade rather than a minor one.

As is customary for a major version upgrade, Neptune recommends that you perform full regression testing of your applications in a non-production environment before upgrading your production system. This is particularly relevant here because the Node.js runtime and the default UI5 version both change, either of which can affect application behavior.

License invalidation

The move from what would have been 24.16.0 to 25.0.0 does not affect your existing customer license. The license remains valid across this version change.

A license can, however, be invalidated by changes to the environment it runs in, such as a change to the operating system or the underlying hardware. A major upgrade is often the point at which such changes are made, which is why this is noted here. If a license becomes invalid around the time of the upgrade, the cause is one of these environment changes and not the move to 25.0.0. Plan any such changes with this in mind.

Renewal process

If a license does become invalid, we recommend the following renewal process:

  1. Contact our Support team and request that the existing license be detached from our servers.

  2. Our Support team will then guide you through the steps below.

Do not carry out the following steps unless you are in contact with our Support team. Doing so will leave the system without a license.

  • Remove the existing license from the system by selecting Remove ALL Licenses.

  • Obtain the new online license file.

  • Complete the online setup process using the new license file.

Node.js runtime upgrade to version 26

Neptune DXP - Open Edition is upgrading its runtime environment to Node.js 26.8.1. This update is necessary because Node.js 22 reaches the end of its maintenance window in May 2027 and will no longer receive security patches or maintenance updates.

Node.js 26 introduces several technical changes that may affect application behavior.

Scope of Impact

Most actively maintained npm packages that follow semantic versioning (semver) are expected to work without modification. This has been verified for all npm packages bundled and shipped with Neptune DXP - Open Edition.

However, applications may require changes or testing if they involve:

  • Custom or internally maintained npm modules

  • Native bindings

  • Deprecated or removed Node.js APIs

Migration Checklist

Follow these steps to prepare custom npm packages in your development and deployment environments for Node.js 22:

  1. Upgrade your local Node.js version, i.e. the Node.js version installed on your host machine, to 26.8.1 or later.

    You can check if your local Node.js version, used when installing npm modules, matches at least the minor embedded Node.js version of the Neptune DXP - Open Edition runtime system on the System Info tile of the Cockpit.

  2. Find your npm package installation path as configured in Custom Settings → General → npm Installation Path.

  3. Re-install all custom npm packages:

    npm install

  4. Identify outdated dependencies using:

    npm outdated
npm-check-updates

  5. Update outdated packages, prioritizing those with native components or known compatibility constraints.

  6. Rebuild native modules:

    npm rebuild

  7. Monitor for warnings or errors:

    • Check for deprecation warning messages during application startup

    • Review logs for runtime errors that did not occur under Node.js 22

  8. Now make sure to test all server scripts that use custom npm modules in a QA system before upgrading your production system, focusing on packages that are not officially supported or are custom-built.

Universal upgrade steps (all paths)

Important notice on Git integration and upgrades

As part of our Git integration with development packages, your development package artifacts are exported and committed as versioned files in a Git repository. Each package consists of artifacts stored in the database and mirrored as files in the repository.

When you upgrade your application server (major, minor, or patch versions), the underlying definitions of these artifacts may change due to schema updates or internal improvements to how packages are represented in the file system.

There are two key upgrade scenarios:

  • Non-breaking upgrades (for example, artifact schema changes)

  • Breaking changes (for example, artifact file path changes)

Non-breaking upgrades

  1. Before upgrading, ensure your database and Git repository are in sync (i.e. there are no uncommitted changes)

  2. After upgrading, run a full export of all artifacts in your development packages to ensure your Git repository reflects the updated database schema.

Breaking changes

In some releases, we introduce breaking changes to how artifacts are stored in the file system. These changes are not backwards-compatible. When such changes occur, the release notes will clearly indicate that development packages exported from one version are not compatible with previous versions.

After upgrading, you must re-export all artifacts in your development packages from the database to the Git repository to avoid sync issues and potential runtime errors.

Additional steps when upgrading from 24.10 to 24.14

Shared session secret in multi-instance deployments

Starting with Neptune DXP - Open Edition version 24.14.1, a new environment variable SESSION_SECRET may be set. When upgrading from earlier versions (that is to say, versions before 24.14.1), you must explicitly set this environment variable during setup and ensure it is identical across all instances in multi-instance or scaled deployments. If not configured consistently, each instance generates its own secret, which can lead to authentication failures (for example, users being unable to log in due to mismatched session cookies).

Modified AppCache.Load view behavior

From Neptune DXP - Open Edition version 24.12.0, when calling the event AppCache.Load with a configured parent object for loading child views, the behavior of how child views are handled has changed. This change also harmonizes view handling behavior between both Neptune DXP - Open Edition and Neptune DXP - SAP Edition.

Previously, every time you called AppCache.Load, the child view was recreated from scratch each time. This meant:

  • The onInit event handler ran every time once called.

  • The onbeforeDisplay event handler also ran every time once called.

Now, the system reuses the child view after it is created just once. As a result:

  • onInit is called only once, when the child view is first created.

  • onbeforeDisplay runs on every subsequent load of the view.

If you have set up an onInit event handler in your application for tasks that need to happen every time the view is loaded (like resetting form values, fetching updated data, or setting state), after the change, that code will now run only once on the first time. This can result, for example, in real-time data not updating, or broken UI logic. To continue to ensure seamless loading of child views after the change, move any code that should run on every view load into the onbeforeDisplay event, which still runs each time.

For more information about the AppCache.Load load method, see Using the AppCache.Load method to run applications.

i18n version dependency for Neptune DXP - SAP Edition apps in Neptune DXP - Open Edition

Neptune DXP - SAP Edition apps version 24.10 and later require Neptune DXP - Open Edition i18n support to provide application translations.

On Neptune DXP - Open Edition systems where i18n support is absent (version 24.14.0 and earlier), Neptune DXP - SAP Edition apps (version 24.10 and later) can still load when the corresponding SAP Edition hotfix containing this compatibility fix is installed. In this case, translations are silently absent and a non-fatal network error appears in the browser console.

To use i18n, upgrade the Neptune DXP - Open Edition system to a version that includes i18n support.

Offline license invalidation

This notice applies only to customers already running Neptune DXP - Open Edition 24.

If you are using an offline license, and are upgrading from *DXP24.12.1 or earlier*, your current license will be invalidated.

You must complete offline license setup again after upgrading.

Learn more about the updated offline activation process here.

Protect against brute-force attacks

As part of Neptune DXP - Open Edition 24.11.0, new security settings were introduced to mitigate brute-force log-in attacks and enhance account protection. However, existing users must reapply specific settings to ensure continued security coverage.

Ensure active security controls

If you have previously applied neutralLockedMessage and sendNotificationOnLockedAccount, you must reapply these settings in 24.11.0.

While these security controls enhance system resilience, they will not be automatically retained from previous versions.

System artifacts package

The Neptune DXP - Open Edition executable is now delivered with a number of system artifacts that previously have been delivered through the Neptune DXP Marketplace. This will improve maintainability and ensure correct interplay of the system components. To give a clear indication which artifacts belong to the core system they have been renamed and collected in the system development package neptunesoftware-dxp-system-artifacts. This package is read-only for customers. Its content will only be updated by Neptune. The package contains the following artifacts:

  • the Neptune standard launchpad application: neptunedxp_launchpad

  • all adaptive templates:

    • neptunedxp_adaptive_bi

    • neptunedxp_adaptive_calendar

    • neptunedxp_adaptive_edit

    • neptunedxp_adaptive_grid

    • neptunedxp_adaptive_list

    • neptunedxp_adaptive_pivot_table

    • neptunedxp_adaptive_splitter

    • neptunedxp_adaptive_tile_chart

    • neptunedxp_adaptive_tile_table

  • the Neptune standard login application: neptunedxp_login

  • the Neptune standard workflow inbox components:

    • neptunedxp_inbox_f3_v2

    • neptunedxp_inbox_tile

Adaptive templates

The adaptive templates were renamed to reflect their incorporation in the standard delivery.

Configure your adaptive applications to use the new adaptive templates and to benefit from their enhanced functionality.

Bundled packages

To make your start with Neptune DXP 25 easier, in Neptune DXP 24 we bundled a fe of the most useful Neptune DXP Marketplace add-ons with the installation. All the corresponding development packages are still linked to their respective public GitHub repository. The bundled packages are imported when restarting or upgrading your system when your system role in the System Settings tool is set to Local (default setting).

  • neptunesoftware-dxp-abb-adaptivecrm - Open Edition CRM

  • neptunesoftware-dxp-abb-elearning - Package for developing elearning content

  • neptunesoftware-dxp-abb-neptune-forms - Neptune FORMS Solution

  • neptunesoftware-dxp-abb-neptune-survey - Surveys

  • neptunesoftware-dxp-abb-salesorders - Sales orders with PDF generation

  • neptunesoftware-dxp-abb-signaturepad - Signature Pad Building Block

  • neptunesoftware-dxp-abb-universalbarcodescanner - Barcode Scanner Building Block

  • neptunesoftware-dxp-demo-launchpad-appearance - Neptune Software DXP Demo Launchpad Appearance

  • neptunesoftware-dxp-system-artifacts-ai - System artifacts for Naia-based AI capabilities

If you have directly modified content of these Neptune DXP Marketplace add-ons you must back up these modifications before upgrading to Neptune DXP 24 and then Neptune DXP 25.
Neptune recommends that you point the remote git URL of the modified development package to a different repository of your choice and push your actual development there.

Standard launchpad application

Our new standard launchpad application was completely overhauled and is now the only supported launchpad application.

Custom launchpad applications are no longer supported

Thus, references to custom launchpad applications within launchpad configurations will be replaced by a reference to the standard launchpad application.

Before upgrading you should do the following:

  1. Copy all launchpad configurations that reference custom launchpad applications.

  2. Configure the standard launchpad application for these copies.

  3. Map/migrate your custom functionality to enhancement spots to achieve equivalent functionality.

Custom login application

The new systems artifacts package includes the Neptune standard login application. In case you need custom login functionality you can copy this app, modify it, and use it in your launchpad configuration.

As your custom login application will not benefit from enhancements and bug fixes for the standard login application, we recommend to avoid custom login apps whenever possible.

Enable access for new Cockpit tools

New tools, especially in the design area, have been added to the Cockpit.

The initial access level for the new tools will be None. Update the ACL on your user roles to enable access.

Deprecated tooling and functions

In Neptune DXP 24, we removed the following tools:

  • App Editor

  • Test Plan

  • Test Run

  • Test Unit

  • Load Test

  • System Reports

Some private JavaScript functions that might have been used by customers were moved to an official location:

  • _convertFlatToNested → neptune.Utils.convertFlatToNested

  • _convertNestedToFlat → neptune.Utils.convertNestedToFlat

Upgrading from 23.x or 22.x

We fixed an issue where upgrades from Neptune DXP - Open Edition 23.10.x or earlier to Neptune DXP - Open Edition 24.14.x could fail during database migration due to a schema mismatch in the api_authentication table. This issue previously required upgrading via 24.12.x as a workaround.

For earlier releases, Neptune recommends upgrading your Neptune DXP - Open Edition sequentially through each major version to maintain compatibility with intermediate changes and avoid migration issues.

Related topics