Upgrading to Joget DX 9

Introduction

Upgrading to the newest version of Joget DX 9 from older versions, such as Joget Workflow v5 and v6 or Joget DX 7 and DX 8, is a streamlined process. There are two recommended upgrade options to choose from:

• Install Joget DX 9 in a new folder with an existing database
• Run a fresh installation of Joget DX 9

This document provides detailed, step-by-step guides on performing the upgrade process using any of the above options. For more information about the newest version of Joget, see What's New in Joget DX 9 and Download Joget DX 9 from https://www.joget.org/download/.

Run Joget DX 9 in a new folder with an existing database

When upgrading from Joget DX 7 or earlier, you can run Joget DX 9 in a new installation folder but using the existing database. Follow these steps:

1. Back up your Joget Workflow v5, v6, or Joget DX 7 database or clone it for Joget DX 9 use (Joget DX 9 will automatically create the new tables and fields it needs).
2. Download Joget DX 9 from Joget's Website and install it in a new folder using the Windows or Linux Installer.
3. Copy all files from your Joget Workflow v5, v6, Joget DX 7, or DX 8 .\wflow\ folder to the same corresponding folder in Joget DX 9.
4. Ensure Joget DX 9 can access your current database (check the database settings in the app_datasource-default.properties file located in the \wflow folder using a text editor.)
   Optionally, edit the .\apache-tomcat-11.x.x\conf\server.xml file if you wish to run Joget DX on a different port instead of 8080.

5. Edit the joget-start.bat or .sh file using a text editor to set a higher -Xmx memory for better performance (for example, -Xmx1024M).

6. Start Joget Apache Tomcat and monitor the joget.log and catalina.log for errors. Refer to Web App Log Viewer for more information.

7. Copy your Joget plugins from the previous instance of Joget to the new Joget folder, if any. The Joget plugins are located in the .\wflow\app_plugins folder.

After these steps, your Joget is upgraded to DX 9 in a new folder while using the previous database and with your apps intact

Run Joget DX 9 in a new folder and use the default new database

This is the fastest upgrade option, especially for a development server. Follow the steps below:

1. Download Joget DX 9 from Joget's Website and install it in a new folder using the Windows or Linux Installer.
2. Run the joget-enterprise-setup-9.0.x.exe installer if you are using Windows or unzip the joget-enterprise-setup-9.0.x.tar.gz if you are using Linux.
   Joget DX comes with MariaDB database by default. However, you can change the default database to MSSQL, Oracle or PostgreSQL.
3. Follow the on-screen installer prompt if you are on Windows.
4. Click on joget-start.bat or joget-start.sh to start Joget DX 9.
5. In your browser, type in the URL address http://localhost:8080/jw to run Joget DX 9.
6. Export all the apps from Joget Workflow v5, v6, Joget DX 7, or DX 8 \wflow\ folder and import them into Joget DX 9.
7. Reimport all plugins to Joget DX 9 by copying the plugins from the previous Joget installation instance to the new instance. The Joget plugins are located in \wflow\app_plugins.

Once finished, your Joget is upgraded to DX 9 with a new database and the apps of your previous Joget installation.

Run Joget DX 9 in my existing Joget Workflow v5, v6, or Joget DX 7, DX 8 folder and upgrading to Joget DX 9 using jw.war

Changes in Joget DX installation files

If you are using Joget v5 or Joget v6, please read the following changes that were introduced in Joget DX 7, 8, and 9:

• Joget DX uses Glowroot for Application Performance Management, thus a new -javaagent argument is needed in the startup joget-start.bat or .sh script. See the example below: 

  set JAVA_OPTS=-Xmx768M -Dwflow.home=./wflow/ -javaagent:./wflow/aspectjweaver-1.8.5.jar -javaagent:./wflow/glowroot/glowroot.jar

• Joget DX has new runtime Glowroot files in .\wflow\glowroot\. The new Application Performance Management feature uses the Glowroot runtime. You can retrieve these files from a fresh install of Joget DX 9.
• Joget DX has a higher default maximum memory allocation pool for the JVM in -Xmx1024M. Joget DX requires more Java heap space, and if your server has additional RAM, allocate more -Xmx@ memory for better performance.
• Joget DX 9 installation is running on apache-tomcat-11.0.2.
• Joget DX installation is running on Java jre21.0.5.

Post installation notes

Use this guide Troubleshooting - Common Errors, to learn how to solve start-up errors in your Joget DX .

Download and install new plugins, especially for Joget DX 7-DX 9 from https://archives.joget.org/addons/ and https://marketplace.joget.com/ to try out:

• Process Enhancement Plugin
• Report Builder
• API Builder

To save time in the initial DX 9 testing, you can delay the copying of the .\wflow\app_formuploads folder (may be too many files) and .\wflow\app_plugins folder (to first test Joget DX with zero custom plugin) until after everything is running smoothly.

Additional documentation

General upgrade flow

1. Prepare a test server that mimics the production server as closely as possible in all possible aspects (e.g., user setup, networking environment, CPU/memory capabilities, database) without cloning the production database server. Start with a fresh new database.
2. Once you are ready with the test server, you may try to start with a fresh database without the data, but just the Apps loaded in. Run through all the functionalities of your apps to see if everything works as expected.
3. If Step 2 goes well, you may then try to clone the existing production database to see how your Apps fare with the existing production data. Run through all the functionalities of your Apps again to see if everything works as expected.
4. If you have integrated Joget Workflow with other solutions, you will also need to test them accordingly.
5. When you are ready, please continue to the next step.

DX 8 and DX 9 database table changes over DX 7

These are the new tables that will be automatically created upon initial start-up of Joget DX 9 over the existing database used by Joget DX 7:

1. wf_history_activity
2. wf_history_process
3. wf_process_link_history

In the unlikely case that you need to create the tables manually, you can locate the CREATE script in exploded jw.war file at \jw\WEB-INF\classes\setup\sql\.

For the MySQL database, if you are setting it over a new database using the Set Up Database wizard, the default collation is now utf8mb4_unicode_ci instead of utf8_unicode_ci in Joget DX 7.

-Dwflow.collationChecking=false

Transitioning from Professional to Enterprise edition

Joget DX Professional Edition will no longer be available starting October 2024. This decision was made to streamline the Joget product lineup and focus Joget's efforts on delivering the best possible solutions to meet the evolving needs of our customers and partners.

This step will guide you to transition from Professional to Enterprise Edition.

Follow these steps:

1. Update Joget.
2. Run the Enterprise version to get the system key, and apply for a new license.
3. Head over here to acquire New License.