Higson Applications Upgrade

This guide describes how to bump Higson to a newer version — both a patch and a minor/LTS upgrade. Read it end to end before you start.

Test first, then production. Always perform the upgrade on a test environment first and confirm it succeeds (Studio and Runtime start with no errors, Liquibase migrations pass, regression tests are green). Only then repeat it on production.

Golden rules#

  • Studio and Runtime must run the exact same version (e.g. 4.3.2 ↔ 4.3.2), whether Runtime is used as a library or as Runtime REST.
  • Higson Studio MUST be started first — Studio owns and migrates the database schema.
  • Higson migrates the schema automatically on start (Liquibase); the migration cannot be rolled back without a database backup.

Supported components#

The table below lists the core components and versions used by the supported Higson LTS lines. Use it to confirm the target stack before upgrading.

Component 4.1 LTS 4.2 LTS 4.3 LTS
Java (JRE) 17 17 17
Apache Tomcat 10.1 10.1 11.0.25
Spring Boot 3.3 3.3 4.1.1

Which variant applies to you?#

The steps depend on how your application consumes Higson Runtime:

  • Variant A — Runtime as a library: Runtime is embedded in your application as a build.gradle / pom.xml dependency.
  • Variant B — Runtime REST as a separate application: a standalone JAR (Spring Boot) or a WAR deployed to a servlet container.

Common notes (both variants)#

Database backup is a critical step. Because Higson migrates the schema on start, the change cannot be undone without a backup. A Studio snapshot is not enough — it does not store users, history, permissions, etc. Take the backup with a database client.

Property compatibility between versions. New configuration keys are added between releases (for example higson.studio.security.token.verification.secret-key appeared in 4.1.0). After the upgrade, review your application.properties and add any new keys — see the properties change table. Pay special attention to database connection properties.

JDBC driver. The bundle does not contain a database driver. Copy it from the previous installation’s tomcat/lib (e.g. db-driver.jar — the PostgreSQL driver) into the new tomcat/lib.

server.xml. If Studio ran on non-default ports, adjust them in conf/server.xml. Carry over all other changes made to that file as well (e.g. HTTPS/TLS configuration).

Variant A — Runtime as a library#

  1. Download Higson Studio from the download page in the right format — Bundle in Zip for Windows, Bundle in Tgz for Linux.

  2. Shut down Higson Studio.

  3. Shut down the applications using higson-runtime.

  4. Back up the database with a database client (see Common notes).

  5. Unpack the zip/tgz and move the JDBC driver into the new tomcat/lib.

  6. Set application.properties (default: {your_tomcat_dir}/conf/application.properties) — carry over the previous settings and add the new keys.

  7. Adjust ports and other server.xml settings (see Common notes).

  8. Bump the Runtime version in your application. Change the higson-runtime dependency in your build script (build.gradle, pom.xml, …) to match the Studio version, then review the Runtime App properties.

  9. Rebuild and deploy your application with the new library version.

  10. Start Higson Studio:

    • Linux/Unix: ./bin/startup.sh
    • Windows: .\bin\startup.bat

    Open Studio in the browser at the configured address (by default https://{serverUrl}/higson/app).

  11. Run regression tests — confirm the business configuration in Studio and the calculations in your application work correctly.

Engine package changes (when moving to 4.3)#

Moving to 4.3 may require adjusting the package names of key Higson engine classes in your application. If your upgrade path involves this change, contact us and we will guide you through the required updates.

Variant B — Runtime REST as a separate application#

Runtime REST is not part of the Studio bundle — it is a separate artifact.

  1. Download both artifacts, in the same version:

    • Higson Studio — Bundle in Zip (Windows) or Bundle in Tgz (Linux),
    • Higson Runtime REST — one of:
      • HIGSON-Runtime-REST-<version>.jar — standalone (embedded server), or
      • HIGSON-Runtime-REST-<version>.war — for a servlet container (Tomcat).

  2. Shut down Higson Studio.

  3. Stop the running Runtime REST. For a standalone JAR stop the process; for a WAR in a separate Tomcat run its shutdown.sh / shutdown.bat. (Not needed if the WAR runs in the same Tomcat as Studio — step 2 already stopped it.)

  4. Back up the database with a database client (see Common notes).

  5. Unpack the Studio bundle and move the JDBC driver into the new tomcat/lib.

  6. Set Studio application.properties — carry over settings and add new keys.

  7. Adjust Studio ports and other server.xml settings (see Common notes).

  8. Configure Runtime REST separately from Studio:

    JAR (standalone) — configure in its own application.properties / application.yml:

    • database connection (higson.database.*),
    • server.port=<port>.

    Do not place the JAR in webapps/; put it in a dedicated directory (e.g. C:\Higson\runtime-rest\).

    WAR (in a container):

    • Clear the target Tomcat’s webapps/ and drop in the Runtime REST WAR (recommended: a separate Tomcat instance from Studio).
    • Rename the WAR if a specific context path is required. The WAR file name defines the deploy context path, and Tomcat maps # in the file name to / in the path — e.g. higson#rest.war deploys under /higson/rest.
    • Set the port in that Tomcat’s server.xml, not Studio’s.
    • Running the WAR in the same Tomcat as Studio is possible but couples the Runtime lifecycle to Studio and shares the port — not recommended in production.

  9. Start Higson Studio (./bin/startup.sh / .\bin\startup.bat) and open it at the configured address (by default https://{serverUrl}/higson/app).

  10. Start the new Runtime REST (only after Studio has started and migrated the schema):

    • JAR: java -jar HIGSON-Runtime-REST-<version>.jar (override the port with --server.port=<port>),
    • WAR: start the Tomcat where the WAR is deployed.

  11. Verify: check the Runtime REST health endpoint (e.g. .../actuator/health) and run regression tests of the calculations through the Runtime REST API and of the business configuration in Studio.

Upgrade checklist#

  • Studio version = Runtime version (library / REST).
  • Database backup taken with a database client (not a snapshot).
  • Applications shut down (Studio + Runtime).
  • application.properties carried over and new keys added.
  • JDBC driver copied from the old tomcat/lib to the new one.
  • Ports and other server.xml changes (HTTPS/TLS, …) applied in the right files.
  • (Variant A, moving to 4.3) Engine package changes handled — contact us if this applies.
  • (Variant A) higson-runtime version bumped and the application rebuilt.
  • (Variant B) Runtime REST configured and started as a separate application.
  • Studio and Runtime started without errors (startup log, Liquibase migrations OK).
  • Regression tests passed.