Upgrade to v4

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

September 23rd, 2021

What's new in Mango v4? Important information to know when upgrading.

General upgrade tips

  • Upgrading from 4.0.0-beta.x releases to the 4.0.0 final release is not guaranteed. Please test to make sure it works for you.
  • You should always backup your database and have a recovery plan before upgrading Mango!
    • You should always test upgrades in a development environment before upgrading production instances of Mango
  • When you first upgrade to Mango 4.x, your users may see a cached version of the 3.x UI in their browser.
    • Users should close all their browser tabs which have Mango open and reopen them.
    • Alternatively hold shift and press refresh (Chrome), note that this may not work if you have multiple Mango tabs open.
    • As a last resort, completely clear your browser's cache

You will need a new license for Mango v4

Please contact Radix IoT to purchase a license before you upgrade.

Legacy pages have been removed

Please be aware that the legacy UI (JSP, DWR based pages) have been removed, you must now use our AngularJS UI at /ui/.

Starting Mango as a service

Mango 3.x shipped with a script called ma.sh for use on Linux and macOS. This script is no longer available in 4.x, we now recommend starting Mango using systemd which is widely used across every major modern Linux distribution. If you were previously using an init.d script to start Mango, you should migrate to a systemd service.

The start-mango.sh and stop-mango.sh scripts are still available in Mango 4.x and can be used to manually start/stop Mango. Please be aware that Mango will not automatically restart if you use start-mango.sh.

One new feature is the ability to run ./bin/start-mango.sh wait, this causes the script to wait for Mango to terminate before returning control to the terminal. You can press Ctrl-C to send the SIGINT signal to Mango and shut it down cleanly.

Startup extensions (the ext-available and ext-enabled directories) from Mango 3.x or earlier will no longer work. You should use the new start-options.sh script to enable Java options when using the systemd service or the start-mango.sh script.

Another important consideration is that $MA_HOME/overrides/classes and $MA_HOME/overrides/properties are no longer added to the classpath via the default start up scripts. This should not affect you unless you have customized code.

On Windows, we now recommend starting Mango as a Windows service using WinSW.

Unsupported modules

You must remove any unsupported modules if you are planning to upgrade via the store. You cannot upgrade if you have unsupported modules installed. Below is a list of modules that are no longer supported.

  • abeip
  • abpccc
  • dataImport
  • deviceConfig
  • graphicalViews
  • jsonFileImport
  • loggingConsole
  • pointLinks
  • reports
  • scheduledEvents
  • sstGraphics
  • templateConfig
  • mbus
  • Twilio

Supported Java / JDK versions

Previously we recommended running Mango on Oracle Java 8. With the release of Mango 4.x it is now hardcoded to run on OpenJDK 11, Mango will fail on startup if still using Java 8. You will see the performance benefits from using Java 11 due to improved GC algorithms.

SQL database support

Mango is now capable of running on MySQL 8, previously only MySQL 5.7 was supported.

Configurable data paths

A primary goal of Mango 4.x was to separate the data from the installation files. Mango now supports configuring a separate path in which to store all your configuration, database, and time series data.

You can set the path to where your data should be stored by setting the environment variable mango_paths_data or by setting the property paths.data in your configuration file.

You can also independently configure paths for your H2 database, timeseries database, file store etc if you do not wish to keep it all in one directory.

By default, Mango 4.x will honor the old filesystem structure used by Mango 3.x so upgrading is less of a hassle. However, we do recommend that you separate your data for ease of maintenance down the track.

Configuration file is now named mango.properties

The Mango configuration file previously named env.properties is now named mango.properties by default. Mango 4.x will still try and locate a file named env.properties for backwards compatibility.

The order in which Mango searches for its configuration file is as follows:

  1. $mango_config (environment variable)
  2. $MA_ENV_PROPERTIES (legacy environment variable)
  3. $mango_paths_data/mango.properties
  4. $mango_paths_data/env.properties
  5. ~/mango.properties (~ is the user’s home directory, also supported on Windows)
  6. $mango_paths_home/env.properties (legacy location)
  7. $mango_paths_home/overrides/properties/env.properties (legacy location)

Mango 4.x will create a mango.properties file on startup if it does not exist in any of these locations. This file will be entirely commented out so Mango will use its default settings. This file will be in one of the following locations based on the variables you have set.

  1. $mango_config (if environment variable is set)
  2. $MA_ENV_PROPERTIES (if environment variable is set)
  3. $mango_paths_data/mango.properties (if mango_paths_data environment variable is set)
  4. ~/mango.properties (if user has a home directory)
  5. Finally fail with an error message

A warning will be displayed if configuration file is readable/writable by "others", you should run chmod o-rw on your mango.properties file (Linux, macOS).

Environment variables

Mango 4.x supports setting any configuration property via an environment variable. This is particularly useful for running Mango inside a containerized environment such as Docker or Kubernetes.

In order to set a configuration property via an environment variable, replace the periods/dots with underscores and prefix with mango_ e.g. web.port becomes mango_web_port.

You can set these environment variables in places such as

  • /etc/environment file
  • systemd mango.service file
  • WinSW mango.xml configuration file
  • On the command line e.g. mango_web_port=8081 ./bin/start-mango.sh
  • In the start-options.sh file

Some environment variables of note:

  • mango_paths_data sets the data path
  • mango_paths_home sets the path to the Mango installation, this is not usually needed. The Mango 3.x environment variable MA_HOME is also supported for backwards compatibility.
  • mango_config sets the path to the configuration file. The Mango 4.x beta environment variable MA_ENV_PROPERTIES is also supported for backwards compatibility.

Custom Log4J2 configuration

Previously you could place a custom log42.xml file in overrides/classes and it would be used by Mango. In Mango 4.x you must specify its location via the property log4j2.configurationFile in your configuration file. A good place to put this file is in your data directory.

If you have overridden your log4j2.xml file you should ensure you are not using ${sys:ma.logs}, instead use ${mango:paths.logs}.

Roles and permissions changes

Mango 4.x includes significant changes to the way that roles and permissions work.

Roles

A user is assigned a set of "roles", these roles must be manually created before they can be assigned to a user. Previously in Mango 3.x roles were assigned to a user via a free-form comma separated string and were somewhat confusingly labelled as "permissions". The upgrade process will automatically generate roles for you based on your 3.x permissions and users.

There are three built-in roles in Mango 4.x:

  • anonymous every person/device connecting to Mango has this role, even if not authenticated (not logged in)
  • user every authenticated (logged in) user has this role
  • superadmin user's with this role have the highest privileges, they can do anything within Mango

Roles can be configured to inherit other roles. If role_a inherits role_b then a user which is directly assigned role_a will also hold role_b.

Permissions

Permissions are no longer specified using free-form comma separated strings, you must grant access to pre-defined roles. In Mango 4.x you can require two or more roles to be held in order to grant access, i.e. you might require role_a AND role_b to be held for access to be granted. In Mango 3.x you could only specify that role_a OR role_b must be held.

In 4.x you may also combine AND and OR terms to produce complex "expressions". This functionality is accessed via the advanced mode of the new permission editor UI.

New permissions on objects and changed behaviors

  • 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.
  • To create an event detector on a data point you must have edit permission for that point.
  • Edit permission of an object no longer gives you access to read it, you must explicitly have read permission.
  • To view a generated Excel Report one must either have generated the report or explicitly have read permission.
  • Maintenance event read permission requires you to have read access to all data points and sources referenced by the event configuration.
  • Events/alarms now have a read permission which is copied from the event source when the event is raised
    • e.g. data point events are visible to anyone with read permission for the data point, at the point in time the event was raised

REST API changes

The Mango REST API v1 and v2 URLs have been removed, Mango v4 uses /rest/v3 which also has an alias of /rest/latest. The /rest/latest URL will always point to the newest version of the REST API.

We have tried to maintain backwards compatibility where possible however some URLs have changed and may accept/return slightly different JSON models. Please review your third party code/scripts that interfaces with our REST API. As before, REST API documentation can be obtained via Swagger.

A significant change that is wide-spread in the JSON models is that permissions are now expressed differently to accommodate for the new permission system.

Mango 3.x

{
  "readPermission": "role_a,role_b"
}

Mango 4.x

{
  "readPermission": [["role_a"],["role_b"]]
}

Upgrading your scripts

You must thoroughly review and test any Mango scripts (e.g. meta data points, global scripts, scripting data sources, etc.) which access the Mango Java API as this has significantly changed.

Any Mango scripts that use a DAO via .instance will no longer work. Use Common.getBean(...) See here Mango Java Script.

Nashorn scripting engine support

The Nashorn scripting engine used extensively throughout Mango was deprecated in Java 11 and removed in Java 15. In order to continue using Mango scripts (e.g. meta data points, global scripts, scripting data sources, etc.) on Java versions 15 and above you should install the new nashorn module.

New scripting environment

Mango 4.x contains a new script environment which is used when running scripts from the filestore, and for the script event handler. This script environment supports pluggable scripting engines such as:

  • Nashorn Javascript
  • Graal.js Javascript
  • Groovy scripts

Please be aware that the functions available in this scripting environment are not the same as what is available in meta data points, global scripts, scripting data sources, etc.

Session persistence

Session cookies are now persisted across restarts. This means that users will stay logged in when you restart Mango. You can disable this via the sessionCookie.persistent configuration property.

Upgrading your custom dashboards

Many AngularJS components in the UI module have changed in Mango 4.x. You may find that some components behave slightly differently or have different attributes. Please review the documentation under "API docs" built into Mango. You may have to enable this menu item by going to the "Edit menu" page under "Administration".

Common upgrade issues

  • Your images from the file store are not loading
    • Hardcoded URLs in dashboards like /rest/v2/file-stores/default/xyz.png should be changed to /file-stores/default/xyz.png
  • Your browser console displays Error: [$compile:ctreq] Controller 'ngModel', required by directive 'maWatchListParameters', can't be found!
    • Means that ma-watch-list-parameters needs a ng-model attribute, you should make the following modifications:
  • Mango goes into a 90 second restart loop
    • edit the mango.service file and change PIDFile=/opt/mango/bin/ma.pid to PIDFile=/opt/mango/ma.pid

Mango 3.x

<ma-watch-list-parameters watch-list="designer.watchList" parameters-changed="designer.parameters = $parameters"></ma-watch-list-parameters>

Mango 4.x

<ma-watch-list-parameters watch-list="designer.watchList" ng-model="designer.parameters"></ma-watch-list-parameters>

Other note-worthy changes

  • Mango now exits with specific exit codes depending on why it terminated
  • The user events table has been removed, you can no longer silence an alarm just for yourself

Copyright © 2024 Radix IoT, LLC.