Upgrade to v4

What you need to know about upgrading your mango to v4.

March 15th, 2021


  • You will need a new license for Mango v4, be sure to contact Radix IoT to get a license before you upgrade.
  • You should always backup your database and have a recovery plan before upgrading Mango!
  • Be sure to remove any unsupported modules if you are planning to upgrade via the store, you cannot upgrade if you have unsupported modules installed.
  • The following modules have been removed from Mango 4.0: dataImport, graphicalViews, jsonFileImport, loggingConsole, pointLinks, reports, scheduledEvents, sstGraphics, templateConfig , abeip, abpccc, deviceConfig.
  • The following modules have been added - mapDbPointValueCache, ldapAuthentication, lineProtocolDataSource, mqttSparkplug.
  • You are not guaranteed to be able to upgrade to 4.0.0 from a 4.0.0-beta.x release (the Mango database schema may change).
  • You must thoroughly review and test any Mango scripts which access the Mango Java API as this has significantly changed.
  • Be aware that the legacy UI (JSP, DWR based pages) have been removed, you must now use the AngularJS single page UI at /ui/.
  • Any Mango scripts (e.g. meta data points, scripting data source) that use a DAO via .instance will no longer work. Use Common.getBean(...) See here Mango Java Script.
  • Data point permissions have changed, they now have edit permissions in addition to their read permissions. The data source's edit permission no longer gives you access to its data points. Upon upgrade, the data source's edit permission will be copied to the edit permission for each of its points.
  • Edit permission of an object no longer gives you access to read it, you must explicitly have read permission.
  • To create an event detector on a data point you must have edit permission for that point.
  • To view a generated Excel Report one must either have generated the report or explicitly have read permission.
  • REST v1 and v2 are removed and we now have /rest/v3 The main changes are the permission models but some URLS have been cleaned up too so review any of your code that interfaces with our REST API. /rest/latest is now an alias for that will point to the latest REST version.
  • Maintenance event read permission requires you to have read access to all data points and sources referenced by the event configuration.
  • Maintenance event edit permission requires you to have edit access to all data points and sources referenced by the event configuration.
  • Startup extensions from Mango 3.x or before will no longer work, use the new start-options.sh script.
  • H2 databases will be dumped and re-imported to run on the H2 MV Store engine on upgrade.
  • A warning will be displayed if your env.properties file is readable/writable by "others", you should run "chmod o-rw" on your env.properties file (Linux, macOS).
  • If you have overridden your log4j2.xml file you should ensure you are not using ${sys:ma.logs}, instead use ${mango:paths.logs}.
  • You can now configure the path to store data under for all your databases, overrides, configuration files etc. The old paths however are honored by default.
  • Roles are no longer defined using free-form comma separated strings, you must create a role before you assign it to a user.
  • Permissions are no longer defined using free-form comma separated strings, you can only select existing roles.
  • There is now an "anonymous" role which any unauthenticated person/client holds, even if they are not logged in. This can be used to give permission to public/anonymous users to perform certain actions.
  • The user events table has been removed, you can no longer silence an alarm just for yourself
  • Session cookies are now persisted accross restarts of Mango by default, you can disable this via the sessionCookie.persistent property.
  • $MA_HOME/overrides/classes and $MA_HOME/overrides/properties are no longer added to the classpath via the default start up scripts.
  • We strongly recommend migrating to using the systemd mango.service file to start Mango on supported operating systems.

Copyright © 2020 Radix IoT, LLC.