Font Size:
Ask Joget AI

Best Practices for Upgrading Joget Versions

Pre-Upgrade Preparation Checklist

Complete the following preparation tasks prior to initiating an upgrade in production:

  1. System Inventory Audit:
    • Record the exact active Joget build number, Java JDK version, database engine version, and custom Tomcat configurations.
    • Audit all installed plugins in the wflow/app_plugins directory directly on the filesystem rather than relying solely on app exports.
  2. Database Cloning and Strategy:
    • The Joget database schema migration is automatic and irreversible once the newer major version connects to the schema.
    • Always clone the production database to a dedicated staging environment for upgrade rehearsals. Do not point multiple Joget instances to the same database.
  3. Selective File Preservation:
    • Copy application data selectively (such as wflow/app_plugins, wflow/app_datasources*.properties, and form attachment storage paths).
    • Do not bulk-copy the entire old wflow directory over a new installation. Overwriting the new wflow directory carries over legacy Java agents (aspectjweaver.jar, glowroot/), causing major bytecode errors ("Unsupported class file major version") and CPU spikes on Java 17 or 21.
  4. License Management:
    • Major platform upgrades require a new major version license key bound to the system MAC address, database profile, and major version number.
    • Applying an invalid or expired license causes Joget to drop to "Free Mode", restricting login access to the first 3 registered user accounts (by ascending username order). This can lock out administrative accounts if the username is not among the first three accounts.

Upgrade FAQs & Best Practices

Frequently Asked Questions

  1. Can DX 7 or DX 8 run on Tomcat 10 or 11?
    No. Tomcat 10+ requires Jakarta EE (jakarta.servlet.*), whereas DX 7 and DX 8 rely on Java EE (javax.servlet.*). Use Tomcat 9.0.x for DX 7/DX 8, or upgrade to DX 9 for Tomcat 11 support.
  2. Can I upgrade Tomcat myself without upgrading Joget?
    Yes, within the same major Tomcat line (e.g., 9.0.x for DX 7/DX 8, 11.0.x for DX 9). Avoid Tomcat 9.0.81 due to known UI issues. When installing Tomcat ≥ 9.0.106 or 11.0.8, ensure maxPartCount="1000" is set in server.xml.
  3. Which Java versions are supported?
    Joget DX 7 supports Java 8 and 11 (Java 11 requires version ≥ 11.0.4). DX 7.1 supports Java 11 and 21. DX 8 supports Java 11, 17, and 21. DX 9 supports Java 17 and 21. Ensure matching AspectJ and Glowroot agent versions are updated in the wflow folder when upgrading Java.
  4. Do I need to change Java or Tomcat for minor Joget upgrades (e.g., 9.0.3 to 9.0.7)?
    No. Only the jw.war file needs to be updated within the same major line.
  5. Can I replace core JARs (Spring, Log4j, Hibernate) inside jw.war to address security scans?
    No. Replacing JARs inside jw.war will cause application instability or startup failures. Instead, upgrade to the latest patch release of your major version line or proceed with a major version upgrade.
  6. Do DX 7 or DX 8 plugins work on DX 9?
    Marketplace plugins generally work because DX 9 automatically converts javax.servlet packages to jakarta.servlet. Custom plugins embedding Spring/Hibernate or using custom Spring contexts should be rebuilt using the DX 9 SDK archetype.
  7. Why do .original, .lock, and .transformed files appear in app_plugins on DX 9?
    These files are generated during the automated javax to jakarta plugin bytecode transformation process.
  8. Do BeanShell scripts with javax.servlet imports need to be rewritten for DX 9?
    No. Joget DX 9 automatically transforms javax.* imports to jakarta.* in BeanShell scripts at runtime.
  9. Can I install a DX 9 plugin on DX 8?
    No. DX 9 plugins are compiled for jakarta and will not function on DX 8. Use the DX 8-compatible version of the plugin.
  10. Why does DX 9 contain tomcat-jdbc-10.1.x.jar on Tomcat 11, and can it be deleted?
    It is required for monitoring components. Do not delete it.

Best Practice Checklist for Upgrades

Before Upgrading

  • Install the target version into a new folder using its bundled Tomcat and JRE runtime rather than deploying jw.war into an existing installation.
  • Audit installed plugins in wflow/app_plugins and prepare updated Marketplace or recompiled versions.
  • Review custom HQL, Form Data Binders, and BeanShell scripts for case sensitivity, explicit type casting, and proper syntax (especially for Hibernate 6 / DX 9).
  • Document JVM options, custom Tomcat connector configurations in server.xml, context.xml, and log4j2.xml so they can be manually re-applied.
  • Clone the production database to a dedicated staging environment for upgrade rehearsals and request major version license keys in advance.

During Upgrade Execution

  • Selectively copy data files from the old wflow directory (e.g., app_plugins, datasource properties, and form upload paths). Do not bulk-copy Java agent JARs (aspectjweaver, glowroot, wflow-cluster).
  • Re-apply custom JVM parameters on the new installation: -Dwflow.home, heap settings, agent configurations, and (for DX 9) --add-opens=java.base/java.nio=ALL-UNNAMED.
  • Clear temporary work directories (delete webapps/jw and work/) before starting Tomcat.

Post-Upgrade Verification

  • Inspect joget.log for classloader errors, OSGi resolution warnings, or query syntax exceptions.
  • Perform validation testing on large form submissions, file uploads, datalist filtering, report generation, and third-party integrations (SSO/LDAP).
Created by Debanraj Ravindran Last modified by Debanraj Ravindran on Nov 03, 2026