Upgrade to Neptune DXP - Open Edition 24

Neptune DXP 24 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 24. Additionally, to focus on the tools most relevant to you, we decided to deprecate a few tools that got little to no adoption.

Node.js runtime upgrade to version 22

Neptune DXP - Open Edition is upgrading its runtime environment from Node.js 18 to Node.js 22. This update is necessary because Node.js 18 has reached end-of-life and will no longer receive security patches or maintenance updates.

Node.js 22 introduces several technical changes that may affect application behavior. See the official release announcement from The Node.js Project here.

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 22.13.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 v18

  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.

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.

Licensing mechanism

To provide more flexible licensing options to our customers we have introduced a new licensing mechanism.

After installing/upgrading to Neptune DXP 24 you need to (re-)activate your license with the new license wizard. This applies to free trial installations as well.

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.

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 have been 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 24 easier we are bundling a few 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

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. We recommend to 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 has been 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.

Protect against brute-force attacks

As part of Neptune DXP - Open Edition 24.11.0, new security settings have been 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.

Deprecated tooling and functions

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

Related topics