Upgrade Guide


The Mambo Gamification Platform is always evolving to better suit your needs and to fix any bugs which may have slipped through our battery of automated tests.

New versions of the platform will be available to you when released. Each new version may come with a Database update script which should always be executed when upgrading the platform. If you are upgrading multiple Releases in one go, then you should run all the Database update scripts between your current Release and the Release you are upgrading to.

Testing Process

Prior to upgrading we recommend creating a copy of your production environment with at least one Mambo application server and one database server. This copy should be used to test the upgrade process and more specifically to test whether the integrations built are still functioning correctly.

With major upgrades that could cause disruptions we will provide migration paths which show you how to move from the current integration code to the updated version. However, smaller releases may have simple changes or new defaults which could impact the integrations depending on how they are built.

In order to test the integrations you can either: 1) create a test / copy environment for the product you integrated with and point it to the new updated test servers (recommended option!), or; 2) point the live production system to the test environment. Option (2) should only be performed when there are NO users in the system, or by taking an instance of the production system, taking it off the primary network and upgrading only that version (effectively creating a sandbox / test environment from the production environment).

We highly recommend performing the Testing Process step on every upgrade to ensure there are no problems with your integrations.

Update Process

In order to update the Mambo Gamification Platform follow these steps:

  1. Access the servers running the platform
  2. Stop Tomcat from running (example: sudo /etc/init.d/tomcat7 stop)
  3. Make a copy of your file (see the Installation Guide) to have the current properties at hand
  4. Repeat the Deploying the WAR File section of the Installation Guide with the new Release WAR file
  5. Use the you saved to help fill in the new file. Do not copy and paste. Check if there are new fields to fill in before copying and pasting the old file over the new one.
  6. Versions prior to 5.6.0 should also perform the following steps:
    1. Log into the MongoDB shell
    2. Copy the content of the Database update scripts and call the update functions. For example:
      1. Open Release_4.4.0.js in a text editor
      2. Copy the contents
      3. Paste the contents into the MongoDB shell
      4. Type release440() and hit enter
    3. Repeat the process above for each Database update script between the current Release your are running and the release you are upgrading to
    4. Exit the MongoDB shell
  7. Start Tomcat (example: sudo /etc/init.d/tomcat7 start)

Below is a scenario describing the database update process when jumping multiple Releases in one go.

Note: this is only applicable to releases prior to vesion 5.6.0.

Scenario: You are currently on Release 4.3.0 and want to move to the latest one, Release 4.4.2. There are the following database scripts between 4.3.0 and 4.4.2:

  • Release_4.4.0.js
  • Release_4.4.1.js
  • Release_4.4.2.js

You will need to copy the content of each of these files into the MongoDB shell and run each update function individually in the order that the releases were released i.e. smallest number to largest.


Upgrade Process Lock

When an upgrade doesn't run smoothly and you need to retry, you may face the following error:

[2020-07-07 07:42:47,786] INFO  [Mongobee dao] Mongobee did not acquire process lock. Throwing exception.

Or in newer versions of Mambo:

[2020-07-07 07:42:47,786] INFO  [com.github.mongobee.dao.ChangeEntryDao] Upgrade did not acquire process lock. Another upgrade process is already running or an error occurred during a previous upgrade. In the case of an error, please remove the lock document from the database.

This means that the upgrade failed and that the lock was left in the database.

In order to resolve this, we need to log into our MongoDB shell and type the following commands:

> use mambo
> db.engine.upgradedb.lock.remove({})

Once that's done you will need to restart Tomcat.


Article is closed for comments.