If you are upgrading your current Joget v5, v6 or DX 7 to Joget DX 8, here are your options and step by step guides. We recommend you follow the steps in Run Joget DX 8 In A New Folder And Use My Existing Database steps below due to the updated Apache Tomcat and JRE files that come with the latest Joget DX 8 installer.
Download Joget DX 8 from https://www.joget.org/download/ or https://www.joget.org/download/
Upgrade to the latest Java 11
If you are running on Java 11 prior to version 11.0.4, you will need to upgrade to the latest Java 11 version (11.0.13) due to a Java bug that causes a JVM crash https://bugs.openjdk.java.net/browse/JDK-8210457. Click here to read the change log.
New feature
Added compatibility for Java 17 and Java 21.
Joget DX version 8.1 onwards can now run on Java 17 and Java 21.
- Upgraded the aspectjweaver to 1.9.22 & Glowroot to 0.42.2
- This is done on installer
- For existing installations, will need to manually copy the aspectjweaver.jar and glowroot folder and update the JAVA_OPTS.
Things To Note In Joget DX Installation Files
The following are new in Joget DX 7 and 8:- Joget DX uses Glowroot for Application Performance Management; thus a new "-javaagent" argument in needed in the startup "joget-start.bat or .sh" script, 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 in Joget DX uses the Glowroot runtime. You can retrieve these files from a fresh install of Joget DX 8.
Joget DX has a higher default maximum memory allocation pool for the JVM in "-Xmx768M". Joget DX requires more Java heap space and if your server has additional RAM, do allocate more -Xmx@ memory for better performance.
Joget DX 8 installation is running on "apache-tomcat-9.0.71".
Joget DX installation is running on Java "jre11.0.18".
Run Joget DX 8 In My Existing v5-v7 Folder
Backup your current Joget installation files and database.
Download and install Joget DX 8 in a new folder using the Windows or Linux Installer. We will copy some files from here to your Joget v5-v7 folders.
Make the above changes in startup script (add new "-javaagent" argument and "-Xmx" value) and copy in the Glowroot files to ".\wflow\glowroot\" (if you are upgrading from v5 or v6).
Delete all the files in ".\work" folder in ".\apache-tomcat-9.x.x" folder. These are cache files and can be safely deleted.
Delete the ".\jw" and ".\jwdesigner" folders in ".\apache-tomcat-9.x.x\webapps" folder. Joget will re-create the "/jw" folder on startup. Note: The old jwdesigner.war process builder has been deprecated and need not be copied to your new Joget installation.
Delete the older "jw.war" and "jwdesigner.war" files.
Copy Joget DX 8 "jw.war" file into ".\apache-tomcat-9.x.x\webapps\" folder. The source "jw.war" file is located in the same path as in v5-v7.
If necessary, edit the database configuration file ".\wflow\app_datasource-default.properties" to point to your existing v5-v7 database.
- In Joget DX 8 folder, go to apache-tomcat-9.x.x\webapps\jw\WEB-INF\classes\setup\sql and open your respective database type (e.g. jwdb-mysql.sql )
- Find and run the 2 following CREATE TABLE statements from the respective .sql script in your current database:
- wf_process_link_history
- wf_history_process
Start Joget Apache Tomcat and monitor the joget.log and catalina.log for errors.
Run Joget DX 8 In A New Folder And Use An Existing Database
A second quicker option where Joget DX 8 is a new installation: We recommend these steps below due to the updated Apache Tomcat and JRE files that come with the latest Joget DX 8 installer.
Backup your Joget v5, v6 or DX 7 database or clone it for Joget DX 8 use (Joget DX 8 will automatically create the new tables and fields it needs).
Download and install Joget DX 8 in a new folder using the Windows or Linux Installer.
Copy over all files from v5, v6, or DX 7 ".\wflow\*" folder to the same folder in Joget DX 8.
Ensure Joget DX 8 can access your current database (check the database settings in "app_datasource-default.properties" file using a text editor).
Optional: Edit the "./apache-tomcat-9.x.x/conf/server.xml" if you wish to run Joget DX on a different port instead of "8080".
Edit the "joget-start.bat or .sh" file using a text editor to set a higher "-Xmx" memory for better performance (for example -Xmx1024M).
Start Joget Apache Tomcat and monitor the joget.log and catalina.log for errors, read Web App Log Viewer for more information.
- Finally, copy your Joget plugins from the "old" Joget to your new Joget folder, if any. The Joget plugins are located in ".\wflow\app_plugins\".
Run Joget DX 8 In A New Folder And Use The Default New Database
Fastest option, especially for a development server:
Download and install the Joget DX Windows or Linux Installer.
Run the joget-enterprise-setup-8.0.x.exe installer if you are on Windows or unzip the "joget-enterprise-setup-8.0.x.tar.gz" if you are on Linux.
Follow the on screen installer prompt if you are on Windows.
Joget DX comes with MariaDB database but you can change the default database to MSSQL, Oracle or PostgreSQL .
Click on "joget-start.bat" or "joget-start.sh" to start Joget DX 8.
In your browser, type in the url address "http://localhost:8080/jw" to run Joget DX 8.
Export all the apps from v5/v6 and import them into Joget DX 8.
- Finally, copy your Joget plugins from the "old" Joget to your new Joget folder, if any. The Joget plugins are located in ".\wflow\app_plugins\".
Post Installation Notes
Use this guide Troubleshooting - Common Errors to learn how to solve start up errors in your Joget DX 8.
Download and install new plugins specially for Joget DX 7-DX 8 from https://archives.joget.org/addons/ and https://marketplace.joget.com/ to try out:
To save time in the initial DX 8 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
Compatibility: The usual precautions apply; perform a full backup of the servers and it is essential to test any upgrade on a staging or development server first.
Licensing: For the Enterprise & Professional Edition, upgrades between major versions (e.g. v5-DX 7) to DX 8 requires re-activation with a new license, so users with an active Enterprise Software Subscription are required to request for a new license.
IMPORTANT: Starting from DX 7, JAVA 11 is required due to fixes for vulnerability issues of a dependent library.
Prepare a test server that mimics the production server as close as possible in all possible aspects (e.g. user setup, networking environment, cpu/memory capabilities, database) without cloning the production's database server. Start with a fresh new database.
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.
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.
If you have integrated Joget Workflow with other solutions, you will also need to test them accordingly.
When you are ready, please continue to the next step.
DX 8 Database Table Changes Over DX 7
These are the new tables that will be automatically created upon initial start-up of Joget DX 8 over the existing database used by Joget DX 7.:-
- wf_history_activity
- wf_history_process
- 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 MySQL database, if you are setting it over a new database using the Setting Up Database wizard, the default collate is now utf8mb4_unicode_ci instead of utf8_unicode_ci in Joget DX 7.
Disabling Auto Collation
From Joget DX 8.0.11 onwards, should you wish to disable the auto collation, you can add the following parameter in the Joget startup batch file, in JAVA_OPTS
-Dwflow.collationChecking=false
Upgrading Joget DX 8 In My Existing DX8 Folder Using jw.war
Do not upgrade directly in a production server without prior testing. The usual precautions apply; perform a full backup of the servers and it is essential to test any upgrade on a staging or development server first.
Locate the new jw.war file from either the:
Downloadable Installers (in the /apache-tomcat-x.x.x/webapps directory); or
The Enterprise Support Site for Enterprise Software Subscribers.
Stop Apache Tomcat / Joget.
Backup the existing installation data (Please refer to Joget Workflow Deployment Best Practices)
Delete the existing jw.war file and jw folder in "[Joget Installation Directory]/apache-tomcat-x.x.x/webapps".
Delete the Apache Tomcat working directories i.e. the "jw" folder in "[Joget Root]/apache-tomcat-x.x.x/work/Catalina/localhost".
Copy the new jw.war file into the Apache Tomcat webapps directory "[Joget Root]/apache-tomcat-x.x.x/webapps/".
- Delete the temp \jw and \work folders before running the new jw.war.
Start Apache Tomcat / Joget Workflow.
Note: The old jwdesigner.war process builder has been deprecated and need not be copied to your new Joget installation.
Note on Upgrading Joget
If in your earlier Joget version you changed the security key and salt hash, remember to edit the customApplicationContext.xml file and add in your original key and salt hash after upgrading your Joget else you will not be able to log in to Joget with your admin account. You may also need to edit the ".\conf\context.xml" file and add in " <Resources cachingAllowed="true" cacheMaxSize="50000" />" to increase the install default "cacheMaxSize".
Transitioning from Professional to Enterprise edition
Joget DX Professional Edition will no longer be available starting October 2024. This decision was made to streamline Joget product lineup and focus Joget 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 through this steps first : Updating Joget
Next,
- Run the Enterprise version to get the system key, and apply for a new license.
- Head over here on acquiring New License
IMPORTANT: Please take note that the license approval SLA is 24 hours. To avoid any delay, please plan your license activation in advance.